Skip to content

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.mdx
index 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.mdx
index 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 h
Error 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.
## Actions
diff --git a/docs/content/docs/openui-lang/troubleshooting.mdx b/docs/content/docs/openui-lang/troubleshooting.mdx
index 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.json
index 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.ts
index 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 correctly
expect(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.ts
index 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 dropping
const 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.ts
index 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.ts
index 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;
/**