The Open Standard for Generative UI
add orphaned statements tracking, excess-args validation (#437)
Aditya-thesys28890cca9bb6
diff --git a/docs/content/docs/api-reference/react-lang.mdx b/docs/content/docs/api-reference/react-lang.mdxindex e81820893..560aa625f 100644--- a/docs/content/docs/api-reference/react-lang.mdx+++ b/docs/content/docs/api-reference/react-lang.mdx@@ -238,8 +238,19 @@ interface ParseResult {root: ElementNode | null;meta: {incomplete: boolean;+ /** References used but not yet defined (dropped as null in output). */unresolved: string[];+ /** Value statements defined but not reachable from root. Excludes $state, Query, and Mutation. */+ orphaned: string[];statementCount: number;+ /**+ * Validation errors:+ * - "missing-required" — required prop not provided+ * - "null-required" — required prop explicitly null+ * - "unknown-component" — component not in library schema+ * - "inline-reserved" — Query/Mutation used inline instead of top-level+ * - "excess-args" — more positional args than schema params (extras dropped, component still renders)+ */errors: ValidationError[];};/** Extracted Query() statements with tool name, args AST, defaults AST */diff --git a/docs/content/docs/openui-lang/renderer.mdx b/docs/content/docs/openui-lang/renderer.mdxindex b2c23e3af..28fa0b439 100644--- a/docs/content/docs/openui-lang/renderer.mdx+++ b/docs/content/docs/openui-lang/renderer.mdx@@ -89,17 +89,18 @@ These examples are simplified for demonstration. In production, you'll need to hError codes:-| Code | Source | Description |-| :------------------ | :------------- | :---------------------------------------------- |-| `unknown-component` | parser | Component name not in the library |-| `missing-required` | parser | Required prop not provided |-| `null-required` | parser | Required prop explicitly null |-| `inline-reserved` | parser | Query/Mutation used inline instead of top-level |-| `parse-failed` | parser | Response produced no renderable root |-| `parse-exception` | parser | Parser crashed on malformed input |-| `tool-not-found` | query/mutation | Tool name not found in toolProvider |-| `runtime-error` | runtime | Expression evaluation failed on a prop |-| `render-error` | runtime | React component threw during render |+| Code | Source | Description |+| :------------------ | :------------- | :----------------------------------------------------------------------- |+| `unknown-component` | parser | Component name not in the library |+| `missing-required` | parser | Required prop not provided |+| `null-required` | parser | Required prop explicitly null |+| `excess-args` | parser | More positional args than schema params (extras dropped, still renders) |+| `inline-reserved` | parser | Query/Mutation used inline instead of top-level |+| `parse-failed` | parser | Response produced no renderable root |+| `parse-exception` | parser | Parser crashed on malformed input |+| `tool-not-found` | query/mutation | Tool name not found in toolProvider |+| `runtime-error` | runtime | Expression evaluation failed on a prop |+| `render-error` | runtime | React component threw during render |If no `onError` callback is provided, errors are logged to `console.warn` instead of being silently swallowed.@@ -107,7 +108,8 @@ If no `onError` callback is provided, errors are logged to `console.warn` instea- Parser re-runs as chunks arrive.- Forward references resolve when their statements arrive.-- Missing unresolved references are omitted/null in parsed output until available.+- Unresolved references and invalid components are dropped from arrays (not left as null holes).+- `meta.orphaned` lists defined-but-unreachable statements on every chunk — useful for real-time debugging.- There is no `nodePlaceholder` prop in the current renderer API.## Actionsdiff --git a/docs/content/docs/openui-lang/troubleshooting.mdx b/docs/content/docs/openui-lang/troubleshooting.mdxindex 4bfe5545f..a565c60d1 100644--- a/docs/content/docs/openui-lang/troubleshooting.mdx+++ b/docs/content/docs/openui-lang/troubleshooting.mdx@@ -122,7 +122,7 @@ Error codes:`onError` is for error handling. It collects errors from all layers (parser, runtime, queries) into a single callback.-`onParseResult` is for inspection. It gives you the raw parse tree: the AST, statement count, unresolved references. Use it when you need to see what the parser produced, not just what went wrong.+`onParseResult` is for inspection. It gives you the raw parse tree: the AST, statement count, unresolved references, and orphaned statements. Use it when you need to see what the parser produced, not just what went wrong.```tsx<Renderer@@ -130,6 +130,8 @@ Error codes:if (result) {console.log("Statements:", result.meta.statementCount);console.log("Unresolved:", result.meta.unresolved);+ console.log("Orphaned:", result.meta.orphaned);+ console.log("Errors:", result.meta.errors);}}}/>diff --git a/packages/lang-core/package.json b/packages/lang-core/package.jsonindex 0ce854ca4..ae6775712 100644--- a/packages/lang-core/package.json+++ b/packages/lang-core/package.json@@ -1,6 +1,6 @@{"name": "@openuidev/lang-core",- "version": "0.1.2",+ "version": "0.1.3","description": "Framework-agnostic core for OpenUI Lang: parser, prompt generation, validation, and type definitions","license": "MIT","type": "module",diff --git a/packages/lang-core/src/parser/__tests__/parser.test.ts b/packages/lang-core/src/parser/__tests__/parser.test.tsindex 4c2f5498e..2bd339aa3 100644--- a/packages/lang-core/src/parser/__tests__/parser.test.ts+++ b/packages/lang-core/src/parser/__tests__/parser.test.ts@@ -61,14 +61,21 @@ describe("unknown-component", () => {// ── excess-args ───────────────────────────────────────────────────────────────describe("excess-args", () => {- it("silently accepts extra args (no excess-args error emitted)", () => {+ it("reports excess-args error but still renders with valid args", () => {const result = parse('root = Title("hello", "extra")', schema);- expect(codes('root = Title("hello", "extra")')).not.toContain("excess-args");- // Extra args are ignored; first arg maps to the defined param+ expect(codes('root = Title("hello", "extra")')).toContain("excess-args");+ // Extra args dropped, first arg maps correctlyexpect(result.root).not.toBeNull();expect(result.root?.props.text).toBe("hello");});+ it("excess-args message lists count", () => {+ const errs = errors('root = Title("hello", "extra", "more")');+ const excess = errs.find((e: { code: string }) => e.code === "excess-args");+ expect(excess).toBeDefined();+ expect(excess!.message).toContain("2 excess dropped");+ });+it("does not report when arg count matches param count", () => {expect(codes('root = Title("hello")')).not.toContain("excess-args");});@@ -144,3 +151,87 @@ describe("existing errors carry type and code", () => {});});});++// ── array null-dropping ─────────────────────────────────────────────────────++describe("array null-dropping", () => {+ it("drops unresolved refs from children arrays", () => {+ const result = parse('root = Stack([missing, t1])\nt1 = Title("ok")', schema);+ const children = result.root?.props?.children as any[];+ expect(children).toHaveLength(1);+ expect(children[0].typeName).toBe("Title");+ });++ it("drops invalid components (missing required props) from arrays", () => {+ const result = parse('root = Stack([bad, good])\nbad = Title()\ngood = Title("ok")', schema);+ const children = result.root?.props?.children as any[];+ expect(children).toHaveLength(1);+ expect(children[0].props.text).toBe("ok");+ });++ it("drops unknown components from arrays", () => {+ const result = parse('root = Stack([u, t1])\nu = Ghost("x")\nt1 = Title("ok")', schema);+ const children = result.root?.props?.children as any[];+ expect(children).toHaveLength(1);+ expect(children[0].typeName).toBe("Title");+ });++ it("preserves null literals in arrays", () => {+ const result = parse("root = Stack([null, null])", schema);+ const children = result.root?.props?.children as any[];+ expect(children).toEqual([null, null]);+ });++ it("streaming: unresolved refs fill in when defined later", () => {+ const sp = createStreamParser(schema);+ const p1 = sp.push('root = Stack([t1, t2])\nt1 = Title("first")\n');+ expect((p1.root?.props?.children as any[]).length).toBe(1);+ const p2 = sp.push('t2 = Title("second")\n');+ expect((p2.root?.props?.children as any[]).length).toBe(2);+ });+});++// ── orphaned statements ─────────────────────────────────────────────────────++describe("orphaned statements", () => {+ it("detects unreachable statements on complete parse", () => {+ const result = parse(+ 'root = Stack([t1])\nt1 = Title("used")\norphan = Title("unused")',+ schema,+ );+ expect(result.meta.orphaned).toContain("orphan");+ expect(result.meta.orphaned).not.toContain("t1");+ expect(result.meta.orphaned).not.toContain("root");+ });++ it("no orphans when all statements are reachable", () => {+ const result = parse('root = Stack([t1, t2])\nt1 = Title("a")\nt2 = Title("b")', schema);+ expect(result.meta.orphaned).toHaveLength(0);+ });++ it("orphaned computed during streaming too", () => {+ const sp = createStreamParser(schema);+ // orphan is defined but not referenced from root+ const p1 = sp.push('root = Stack([t1])\nt1 = Title("a")\norphan = Title("stray")\n');+ expect(p1.meta.orphaned).toContain("orphan");+ expect(p1.meta.orphaned).not.toContain("t1");+ });++ it("detects multiple orphaned statements", () => {+ const result = parse(+ 'root = Stack([t1])\nt1 = Title("used")\na = Title("x")\nb = Title("y")',+ schema,+ );+ expect(result.meta.orphaned).toContain("a");+ expect(result.meta.orphaned).toContain("b");+ expect(result.meta.orphaned).toHaveLength(2);+ });++ it("deeply nested refs are not orphaned", () => {+ const result = parse(+ 'root = Stack([t1])\nt1 = Table([col], rows)\ncol = Title("Name")\nrows = [["Alice"]]',+ schema,+ );+ expect(result.meta.orphaned).toHaveLength(0);+ });+});diff --git a/packages/lang-core/src/parser/materialize.ts b/packages/lang-core/src/parser/materialize.tsindex c9cd95a6a..f97bab3f2 100644--- a/packages/lang-core/src/parser/materialize.ts+++ b/packages/lang-core/src/parser/materialize.ts@@ -31,6 +31,8 @@ export interface MaterializeCtx {partial: boolean;/** Tracks which statement is currently being materialized (for error attribution). */currentStatementId?: string;+ /** Statement IDs not yet reached — delete as they're touched. Remaining = orphaned. */+ unreached?: Set<string>;}/**@@ -47,6 +49,7 @@ function resolveRef(name: string, ctx: MaterializeCtx, mode: "value" | "expr"):return mode === "expr" ? { k: "Ph", n: name } : null;}const target = ctx.syms.get(name)!;+ ctx.unreached?.delete(name);// Query/Mutation declarations → RuntimeRef (resolved at runtime by evaluator)if (target.k === "Comp" && isReservedCall(target.name)) {const refType =@@ -264,6 +267,18 @@ export function materializeValue(node: ASTNode, ctx: MaterializeCtx): unknown {props[def.params[i].name] = materializeValue(args[i], ctx);}+ // Report excess positional args (extra args are silently dropped)+ if (args.length > def.params.length) {+ const excessCount = args.length - def.params.length;+ ctx.errors.push({+ code: "excess-args",+ component: name,+ path: "",+ message: `${name} takes ${def.params.length} arg(s), got ${args.length} (${excessCount} excess dropped)`,+ statementId: ctx.currentStatementId,+ });+ }+// Validate required props — try defaultValue first before droppingconst missingRequired = def.params.filter((p) => p.required && (!(p.name in props) || props[p.name] === null),diff --git a/packages/lang-core/src/parser/parser.ts b/packages/lang-core/src/parser/parser.tsindex 1e9f914c2..beae85b57 100644--- a/packages/lang-core/src/parser/parser.ts+++ b/packages/lang-core/src/parser/parser.ts@@ -26,6 +26,7 @@ function emptyResult(incomplete = true): ParseResult {meta: {incomplete,unresolved: [],+ orphaned: [],statementCount: 0,errors: [],},@@ -196,6 +197,14 @@ function buildResult(}const unres: string[] = [];const errors: ValidationError[] = [];+ // Track orphaned: start with value statement IDs, delete as they're reached.+ // Exclude root, state ($var), query, and mutation declarations — they're consumed separately.+ const unreached = new Set<string>();+ for (const [id, stmt] of stmtMap) {+ if (id === entryId) continue;+ if (stmt.kind === "state" || stmt.kind === "query" || stmt.kind === "mutation") continue;+ unreached.add(id);+ }const ctx: MaterializeCtx = {syms,cat,@@ -204,6 +213,7 @@ function buildResult(visited: new Set(),partial: wasIncomplete,currentStatementId: entryId,+ unreached,};const materialized = materializeValue(syms.get(entryId)!, ctx);@@ -215,11 +225,14 @@ function buildResult(ctx,);+ const orphaned = [...unreached];+return {root,meta: {incomplete: wasIncomplete,unresolved: unres,+ orphaned,statementCount: stmtCount,errors: errors,},diff --git a/packages/lang-core/src/parser/types.ts b/packages/lang-core/src/parser/types.tsindex 236b47e24..dbe32229c 100644--- a/packages/lang-core/src/parser/types.ts+++ b/packages/lang-core/src/parser/types.ts@@ -72,7 +72,8 @@ export type ValidationErrorCode =| "missing-required"| "null-required"| "unknown-component"- | "inline-reserved";+ | "inline-reserved"+ | "excess-args";/*** A prop validation error. Components with missing required props are@@ -231,6 +232,8 @@ export interface ParseResult {incomplete: boolean;/** Names of references used but not yet defined (dropped as null in output). */unresolved: string[];+ /** Names of value statements defined but not reachable from root. Excludes $state, Query, and Mutation declarations. */+ orphaned: string[];/** Total number of `identifier = Expression` statements parsed. */statementCount: number;/**