feat(react-lang): expand parser validation with rule-tagged errors (#350)

* feat(react-lang): expand parser validation with rule-tagged errors

Adds three new validation checks to ParseResult.meta.validationErrors:
- unknown-component: PascalCase name not found in the library schema
- excess-args: more positional args passed than the schema defines
- unresolved-ref: identifier referenced but never assigned (one-shot and
  stream-end only — forward refs are valid mid-stream)

Also adds:
- ValidationError.rule discriminant field for consumer-side filtering
- ValidationRule type exported from the parser index
- StreamParser.finalize() to signal stream completion and trigger
  unresolved-ref promotion

Existing missing-required and null-required errors now carry rule tags.
Rendering behavior is unchanged — the parser stays permissive.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(react-lang): add parser validation unit tests

Adds vitest and 17 tests covering the three new validation checks:
- unknown-component: unknown PascalCase names are reported, element still renders
- excess-args: extra positional args reported, component still renders
- unresolved-ref: promoted to validationErrors in one-shot and on finalize(),
  but not mid-stream (forward refs are valid during streaming)

Also tests that existing missing-required and null-required errors carry
the new rule field.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(react-lang): document new parser validation checks and finalize()

- Add StreamParser.finalize() docs with usage note about when to call it
- Add ValidationRule type and table of all rule values
- Add ValidationError.rule field to type signatures
- Add filtering example showing consumer-side rule usage
- Update README types import list to include ValidationError, ValidationRule

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* refactor(react-lang): replace ValidationError with discriminated OpenUIError type

Remove finalize() and unresolved-ref error promotion per reviewer feedback.
Rename validationErrors → errors, use type+code discriminated union for
forward-compatible error taxonomy. Update tests and api-reference docs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(react-lang): fix eslint and prettier CI errors

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Aditya-thesys <aditya@thesys.dev>

Author: 3 people

docs/content/docs/api-reference/react-lang.mdx

@@ -152,19 +152,42 @@ interface ElementNode {
   partial: boolean;
 }
 
-interface ValidationError {
+/**
+ * Validation error codes for schema-related issues.
+ *
+ * - missing-required  — required prop absent with no default
+ * - null-required     — required prop explicitly null with no default
+ * - unknown-component — PascalCase name not in the library schema
+ * - excess-args       — more positional args than the schema defines
+ */
+type ValidationErrorCode =
+  | "missing-required"
+  | "null-required"
+  | "unknown-component"
+  | "excess-args";
+
+/**
+ * Structured error from the parser.
+ * Use `type` to distinguish error categories and `code` to filter
+ * or categorize errors on the consumer side.
+ */
+type OpenUIError = {
+  type: "validation";
+  code: ValidationErrorCode;
   component: string;
+  /** JSON Pointer path within props, e.g. "/title". Empty string for structural errors. */
   path: string;
   message: string;
-}
+};
 
 interface ParseResult {
   root: ElementNode | null;
   meta: {
     incomplete: boolean;
+    /** Identifiers referenced but not yet defined. Check after streaming completes. */
     unresolved: string[];
     statementCount: number;
-    validationErrors: ValidationError[];
+    errors: OpenUIError[];
   };
 }
 ```

packages/react-lang/README.md

@@ -119,6 +119,43 @@ function AssistantMessage({ response, isStreaming }) {
 | `createParser(library)` | Create a one-shot parser for complete OpenUI Lang text |
 | `createStreamingParser(library)` | Create an incremental parser for streaming input |
 
+The streaming parser exposes two methods:
+
+| Method | Description |
+| :--- | :--- |
+| `push(chunk)` | Feed the next chunk; returns the latest `ParseResult` |
+| `getResult()` | Get the latest result without consuming new data |
+
+After the stream ends, check `meta.unresolved` for any identifiers that were referenced but never defined. During streaming these are expected (forward refs) and are not treated as errors.
+
+#### Errors
+
+`ParseResult.meta.errors` contains structured `OpenUIError` objects. Each error has a `type` discriminant (currently always `"validation"`) and a `code` for consumer-side filtering:
+
+| Code | Meaning |
+| :--- | :--- |
+| `missing-required` | Required prop absent with no default |
+| `null-required` | Required prop explicitly null with no default |
+| `unknown-component` | Component name not found in the library schema |
+| `excess-args` | More positional args passed than the schema defines |
+
+Errors do not affect rendering — the parser stays permissive and renders what it can. Use `code` to decide how to surface or log errors:
+
+```ts
+const result = parser.parse(output);
+const critical = result.meta.errors.filter(
+  (e) => e.code === "unknown-component"
+);
+```
+
+To check for unresolved references after streaming, inspect `meta.unresolved`:
+
+```ts
+if (result.meta.unresolved.length > 0) {
+  console.warn("Unresolved refs:", result.meta.unresolved);
+}
+```
+
 ### Context Hooks
 
 Use these inside component renderers to interact with the rendering context:
@@ -157,6 +194,8 @@ import type {
   ActionEvent,
   ElementNode,
   ParseResult,
+  OpenUIError,
+  ValidationErrorCode,
   LibraryJSONSchema,
 } from "@openuidev/react-lang";
 ```

packages/react-lang/eslint.config.cjs

@@ -6,9 +6,24 @@ const unusedImports = require("eslint-plugin-unused-imports");
 const eslintPluginPrettier = require("eslint-plugin-prettier");
 
 module.exports = [
+  {
+    files: ["**/__tests__/**/*.{ts,tsx}", "**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],
+    languageOptions: {
+      parser: typescript,
+      parserOptions: {
+        project: "./tsconfig.test.json",
+        sourceType: "module",
+      },
+    },
+  },
   {
     files: ["**/*.{ts,tsx}"],
-    ignores: ["**/*.stories.tsx"],
+    ignores: [
+      "**/*.stories.tsx",
+      "**/__tests__/**/*.{ts,tsx}",
+      "**/*.test.{ts,tsx}",
+      "**/*.spec.{ts,tsx}",
+    ],
     languageOptions: {
       parser: typescript,
       parserOptions: {

packages/react-lang/package.json

@@ -18,6 +18,7 @@
     }
   },
   "scripts": {
+    "test": "vitest run",
     "build": "tsc -p .",
     "watch": "tsc -p . --watch",
     "lint:check": "eslint ./src",
@@ -60,6 +61,7 @@
     "react": ">=19.0.0"
   },
   "devDependencies": {
-    "@types/react": "^19.0.0"
+    "@types/react": "^19.0.0",
+    "vitest": "^4.0.18"
   }
 }

packages/react-lang/src/parser/__tests__/parser.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, it } from "vitest";
+import type { ParamMap } from "../parser";
+import { createStreamParser, parse } from "../parser";
+
+// ── Test schema ──────────────────────────────────────────────────────────────
+
+/**
+ * Minimal schema used across tests.
+ *
+ * Stack takes one param (children), Title takes one (text),
+ * Table takes two (columns, rows). These cover the common test cases.
+ */
+const schema: ParamMap = new Map([
+  ["Stack", { params: [{ name: "children", required: true }] }],
+  ["Title", { params: [{ name: "text", required: true }] }],
+  [
+    "Table",
+    {
+      params: [
+        { name: "columns", required: true },
+        { name: "rows", required: true },
+      ],
+    },
+  ],
+]);
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const errors = (input: string) => parse(input, schema).meta.errors;
+const codes = (input: string) => errors(input).map((e) => e.code);
+
+// ── unknown-component ────────────────────────────────────────────────────────
+
+describe("unknown-component", () => {
+  it("reports when component name is not in schema", () => {
+    const result = parse('root = DataTable("col")', schema);
+    expect(result.meta.errors).toHaveLength(1);
+    expect(result.meta.errors[0]).toMatchObject({
+      type: "validation",
+      code: "unknown-component",
+      component: "DataTable",
+      path: "",
+    });
+  });
+
+  it("still renders the element with _args when unknown", () => {
+    const result = parse('root = DataTable("col")', schema);
+    expect(result.root).not.toBeNull();
+    expect(result.root?.typeName).toBe("DataTable");
+    expect((result.root?.props as any)._args).toEqual(["col"]);
+  });
+
+  it("reports all unknown components in a tree", () => {
+    const r = codes('root = Stack([Ghost("a")])\n');
+    expect(r).toContain("unknown-component");
+  });
+
+  it("does not report for known component names", () => {
+    const result = parse('root = Stack(["hello"])', schema);
+    expect(codes('root = Stack(["hello"])')).not.toContain("unknown-component");
+    expect(result.meta.errors).toHaveLength(0);
+  });
+});
+
+// ── excess-args ───────────────────────────────────────────────────────────────
+
+describe("excess-args", () => {
+  it("reports when more args are passed than params", () => {
+    const result = parse('root = Title("hello", "extra")', schema);
+    expect(result.meta.errors).toHaveLength(1);
+    expect(result.meta.errors[0]).toMatchObject({
+      type: "validation",
+      code: "excess-args",
+      component: "Title",
+      path: "",
+    });
+    expect(result.meta.errors[0].message).toMatch(/takes 1 arg/);
+  });
+
+  it("still renders the component despite excess args", () => {
+    const result = parse('root = Title("hello", "extra")', schema);
+    expect(result.root).not.toBeNull();
+    expect(result.root?.props.text).toBe("hello");
+  });
+
+  it("does not report when arg count matches param count", () => {
+    expect(codes('root = Title("hello")')).not.toContain("excess-args");
+  });
+
+  it("does not report when fewer args than params (handled by missing-required)", () => {
+    expect(codes("root = Table([], [])")).not.toContain("excess-args");
+  });
+});
+
+// ── unresolved references ────────────────────────────────────────────────────
+
+describe("unresolved references", () => {
+  it("tracks unresolved refs in meta.unresolved (one-shot)", () => {
+    const result = parse("root = Stack([tbl])", schema);
+    expect(result.meta.unresolved).toContain("tbl");
+  });
+
+  it("does not produce errors for unresolved refs", () => {
+    const result = parse("root = Stack([tbl])", schema);
+    expect(result.meta.errors).toHaveLength(0);
+  });
+
+  it("clears unresolved when ref is defined", () => {
+    const result = parse('root = Stack([tbl])\ntbl = Title("hello")', schema);
+    expect(result.meta.unresolved).toHaveLength(0);
+  });
+});
+
+// ── unresolved references (streaming) ─────────────────────────────────────────
+
+describe("unresolved references (streaming)", () => {
+  it("tracks unresolved refs mid-stream without errors", () => {
+    const parser = createStreamParser(schema);
+    const midResult = parser.push("root = Stack([tbl])\n");
+    expect(midResult.meta.unresolved).toContain("tbl");
+    expect(midResult.meta.errors).toHaveLength(0);
+  });
+
+  it("resolves automatically when ref is defined in a later chunk", () => {
+    const parser = createStreamParser(schema);
+    parser.push("root = Stack([tbl])\n");
+    const result = parser.push('tbl = Title("hello")\n');
+    expect(result.meta.unresolved).toHaveLength(0);
+  });
+
+  it("keeps unresolved refs in meta.unresolved at end of stream", () => {
+    const parser = createStreamParser(schema);
+    parser.push("root = Stack([tbl])\n");
+    const result = parser.getResult();
+    expect(result.meta.unresolved).toContain("tbl");
+    expect(result.meta.errors).toHaveLength(0);
+  });
+});
+
+// ── existing error rules ──────────────────────────────────────────────────────
+
+describe("existing errors carry type and code", () => {
+  it("missing-required has correct shape", () => {
+    const result = parse("root = Stack()", schema);
+    expect(result.meta.errors).toHaveLength(1);
+    expect(result.meta.errors[0]).toMatchObject({
+      type: "validation",
+      code: "missing-required",
+    });
+  });
+
+  it("null-required has correct shape", () => {
+    const result = parse("root = Stack(null)", schema);
+    expect(result.meta.errors).toHaveLength(1);
+    expect(result.meta.errors[0]).toMatchObject({
+      type: "validation",
+      code: "null-required",
+    });
+  });
+});

packages/react-lang/src/parser/index.ts

@@ -1,5 +1,11 @@
 export { BuiltinActionType } from "./types";
-export type { ActionEvent, ElementNode, ParseResult, ValidationError } from "./types";
+export type {
+  ActionEvent,
+  ElementNode,
+  OpenUIError,
+  ParseResult,
+  ValidationErrorCode,
+} from "./types";
 
 export { createParser, createStreamingParser, parse } from "./parser";
 export type { LibraryJSONSchema, Parser, StreamParser } from "./parser";