The Open Standard for Generative UI
Nested Schema Validation & Type mismatch check (#729)
AB0d021ef9da71
diff --git a/packages/lang-core/package.json b/packages/lang-core/package.jsonindex 2b59f93b2..8bc00d1ca 100644--- a/packages/lang-core/package.json+++ b/packages/lang-core/package.json@@ -1,6 +1,6 @@{"name": "@openuidev/lang-core",- "version": "0.2.12",+ "version": "0.2.13","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/index.ts b/packages/lang-core/src/index.tsindex a0843435c..cc10b3933 100644--- a/packages/lang-core/src/index.ts+++ b/packages/lang-core/src/index.ts@@ -15,8 +15,10 @@ export type {// ── Parser ──export { createParser, createStreamingParser, parse } from "./parser";export type { Parser, StreamParser } from "./parser";-export { isASTNode, isRuntimeExpr } from "./parser/ast";+export { isASTNode, isRuntimeExpr, walkAST } from "./parser/ast";export type { ASTNode, CallNode, RuntimeExprNode, Statement } from "./parser/ast";+// Low-level parsing pipeline (tokenize → split → parseExpression) for consumers+// that walk partial/streaming openui-lang source without a full parser.export {ACTION_NAMES,ACTION_STEPS,@@ -28,6 +30,8 @@ export {} from "./parser/builtins";export type { BuiltinDef } from "./parser/builtins";export { enrichErrors } from "./parser/enrich-errors";+export { parseExpression } from "./parser/expressions";+export { tokenize } from "./parser/lexer";export { mergeStatements } from "./parser/merge";export { generatePrompt, generateSystemPrompt } from "./parser/prompt";export type {@@ -40,6 +44,8 @@ export type {} from "./parser/prompt";export { jsonToOpenUI } from "./parser/serialize";export type { SerializeOptions } from "./parser/serialize";+export { autoClose, split } from "./parser/statements";+export type { Token } from "./parser/tokens";export { BuiltinActionType } from "./parser/types";export type {ActionEvent,diff --git a/packages/lang-core/src/parser/__tests__/materialize.validation.test.ts b/packages/lang-core/src/parser/__tests__/materialize.validation.test.tsnew file mode 100644index 000000000..5309bb0dc--- /dev/null+++ b/packages/lang-core/src/parser/__tests__/materialize.validation.test.ts@@ -0,0 +1,361 @@+import { describe, expect, it } from "vitest";+import { createParser, createStreamingParser } from "../parser";+import type { LibraryJSONSchema, MaterializeCtx, ValidationError } from "../types";+import { validateSchemaValue } from "../validation";++/**+ * Significant cases for the recursive validator (validateSchemaValue) and the+ * resolveInvalidValue edge rule — one test per behavior family:+ *+ * 1. recursive descent + error reporting (JSON-pointer paths, attribution)+ * 2. the edge rule — default → substitute; required → propagate; optional →+ * prune; array items always pruned+ * 3. component elements in data slots+ * 4. conservative skips (composites, dynamic values, malformed schemas)+ * 5. streaming gates (required + enum deferred; scalar checks stay on)+ *+ * Each component below exposes the schema-under-test as its FIRST positional+ * arg, so `Comp(<value>)` maps `<value>` straight onto the interesting prop.+ */+const schema: LibraryJSONSchema = {+ $defs: {+ // arg0 → `info`: an object with a required key + typed leaves+ ObjBox: {+ properties: {+ info: {+ type: "object",+ properties: {+ author: { type: "string" },+ views: { type: "number" },+ },+ required: ["author"],+ },+ },+ required: [],+ },+ // arg0 → `rows`: an array whose items are objects with a required key+ ArrBox: {+ properties: {+ rows: {+ type: "array",+ items: {+ type: "object",+ properties: {+ label: { type: "string" },+ value: { type: "number" },+ },+ required: ["label"],+ },+ },+ },+ required: [],+ },+ // arg0 → `tags`: an array of scalar strings+ TagBox: {+ properties: {+ tags: { type: "array", items: { type: "string" } },+ },+ required: [],+ },+ // arg0 → `status`: an enum leaf+ EnumBox: {+ properties: {+ status: { enum: ["active", "inactive"] },+ },+ required: [],+ },+ // arg0 → `combo`: a composite (anyOf) that must be left unchecked+ AnyBox: {+ properties: {+ combo: { anyOf: [{ type: "string" }, { type: "number" }] },+ },+ required: [],+ },+ // arg0..2 → scalar params for top-level leaf checks+ ScalarBox: {+ properties: {+ title: { type: "string" },+ count: { type: "number" },+ flag: { type: "boolean" },+ },+ required: [],+ },+ // arg0 → `children`: array without `items` — elements are unchecked+ ListBox: {+ properties: { children: { type: "array" } },+ required: [],+ },+ // arg0 → `text`: a plain catalog component used as a nested prop value+ CardBox: {+ properties: { text: { type: "string" } },+ required: [],+ },+ // arg0 → `title`: REQUIRED scalar param — a type mismatch drops the component+ ReqScalar: {+ properties: { title: { type: "string" } },+ required: ["title"],+ },+ // arg0 → `theme`: REQUIRED param with a default — invalid/missing values fall back to it+ DefBox: {+ properties: { theme: { type: "string", default: "dark" } },+ required: ["theme"],+ },+ // arg0 → `children`: a component slot (anyOf of $refs) — membership unchecked+ SlotBox: {+ properties: {+ children: { type: "array", items: { anyOf: [{ $ref: "#/$defs/CardBox" }] } },+ },+ required: [],+ },+ // args → `labels` (REQUIRED data array), `variant` (enum) — mirrors chart signatures+ ChartBox: {+ properties: {+ labels: { type: "array", items: { type: "string" } },+ variant: { enum: ["grouped", "stacked"] },+ },+ required: ["labels"],+ },+ // arg0 → `cfg`: nested keys with defaults at both required and optional edges+ NestDefBox: {+ properties: {+ cfg: {+ type: "object",+ properties: {+ mode: { enum: ["fast", "slow"], default: "fast" },+ retries: { type: "number", default: 3 },+ },+ required: ["mode"],+ },+ },+ required: [],+ },+ },+};++const parser = createParser(schema);++function errorsFor(src: string): ValidationError[] {+ return parser.parse(src).meta.errors;+}++/** Run validateSchemaValue directly against a raw schema fragment. */+function directErrors(value: unknown, s: unknown, partial = false): ValidationError[] {+ const ctx: MaterializeCtx = {+ syms: new Map(),+ cat: undefined,+ errors: [],+ unres: [],+ visited: new Set(),+ partial,+ };+ validateSchemaValue(value, s, "X", "/p", ctx);+ return ctx.errors;+}++describe("recursive descent & error reporting", () => {+ it("accepts valid values and reports violations with JSON-pointer paths + distinct codes", () => {+ expect(errorsFor('root = ObjBox({ author: "ann", views: 3 })')).toEqual([]);+ // wrong leaf type inside an object+ expect(errorsFor('root = ObjBox({ author: "ann", views: "lots" })')[0]).toMatchObject({+ code: "type-mismatch",+ component: "ObjBox",+ path: "/info/views",+ });+ // array item leaf, with element index+ expect(errorsFor('root = ArrBox([{ label: "a", value: "x" }])')[0]).toMatchObject({+ path: "/rows/0/value",+ });+ // missing vs null required keys carry distinct codes+ expect(errorsFor("root = ObjBox({ views: 3 })")[0]).toMatchObject({+ code: "missing-required",+ path: "/info/author",+ });+ expect(errorsFor("root = ObjBox({ author: null, views: 3 })")[0]).toMatchObject({+ code: "null-required",+ path: "/info/author",+ });+ });++ it("reports container-shape mismatches and accumulates independent errors", () => {+ expect(errorsFor('root = ObjBox("hello")')[0].message).toContain(+ "expects object but got string",+ );+ expect(errorsFor("root = TagBox(42)")[0].message).toContain("expects array but got number");+ // an object with dynamic parts is still an object at runtime — flagged+ expect(errorsFor("root = ScalarBox({ a: $x })")[0].message).toContain(+ "expects string but got object",+ );+ // three violations spread over two array elements+ const byPath = errorsFor('root = ArrBox([{ label: 1 }, { value: "x" }])')+ .map((e) => `${e.code}:${e.path}`)+ .sort();+ expect(byPath).toEqual([+ "missing-required:/rows/1/label",+ "type-mismatch:/rows/0/label",+ "type-mismatch:/rows/1/value",+ ]);+ // arg validation and excess-args reporting are independent+ expect(+ errorsFor('root = ScalarBox(1, 1, true, "extra")')+ .map((e) => e.code)+ .sort(),+ ).toEqual(["excess-args", "type-mismatch"]);+ });++ it("messages are self-sufficient and attributed to the defining statement", () => {+ // top-level required violations carry the typed component signature+ expect(errorsFor("root = ReqScalar()")[0].message).toBe(+ 'missing required field "/title" — signature: ReqScalar(title*: string)',+ );+ expect(errorsFor('root = ChartBox(null, "grouped")')[0].message).toBe(+ 'required field "/labels" cannot be null — signature: ChartBox(labels*: array, variant: "grouped"|"stacked")',+ );+ // unknown components list the catalog+ expect(errorsFor("root = Nope()")[0].message).toContain("Available components: ObjBox, ArrBox");+ // errors point at the statement that defines the component+ expect(+ errorsFor('root = ListBox([inner])\ninner = ObjBox({ author: "ann", views: "lots" })')[0],+ ).toMatchObject({ component: "ObjBox", statementId: "inner" });+ });+});++describe("resolveInvalidValue — the edge rule (default → required → prune)", () => {+ it("prunes invalid values on OPTIONAL edges and ARRAY ITEMS — component survives", () => {+ // nested optional key+ expect(+ parser.parse('root = ObjBox({ author: "ann", views: "lots" })').root?.props.info,+ ).toEqual({ author: "ann" });+ // optional top-level param+ const top = parser.parse("root = ScalarBox(5)");+ expect(top.root).not.toBeNull();+ expect(top.root?.props).not.toHaveProperty("title");+ // optional param holding an unrepairable object (missing required key)+ expect(parser.parse("root = ObjBox({ views: 3 })").root?.props).not.toHaveProperty("info");+ // array items: siblings survive, a required-key violation is absorbed by the item edge+ expect(parser.parse('root = TagBox(["a", 2, "c"])').root?.props.tags).toEqual(["a", "c"]);+ expect(+ parser.parse('root = ArrBox([{ label: "a", value: 1 }, { value: 2 }])').root?.props.rows,+ ).toEqual([{ label: "a", value: 1 }]);+ });++ it("propagates through REQUIRED edges: parent pruned at an optional edge, or component dropped", () => {+ // info.author (required) invalid → info invalid → info optional → pruned+ const nested = parser.parse('root = ObjBox({ author: { first: "a" }, views: 3 })');+ expect(nested.root).not.toBeNull();+ expect(nested.root?.props).not.toHaveProperty("info");+ // required param invalid with no default → component drops+ expect(parser.parse("root = ReqScalar(5)").root).toBeNull();+ });++ it("substitutes schema defaults at every edge; absent/null required keys fill silently", () => {+ // top-level required param: default rescues an invalid value (error kept) and a missing one (silent)+ const def = parser.parse("root = DefBox(5)");+ expect(def.root?.props.theme).toBe("dark");+ expect(def.meta.errors).toHaveLength(1);+ expect(parser.parse("root = DefBox()").meta.errors).toEqual([]);+ // top-level optional param: default wins over pruning (error kept)+ const opt = parser.parse('root = NestDefBox({ mode: "warp", retries: 1 })');+ expect(opt.root?.props.cfg).toEqual({ mode: "fast", retries: 1 });+ expect(opt.meta.errors[0]).toMatchObject({ code: "type-mismatch", path: "/cfg/mode" });+ // nested optional key with default+ expect(+ parser.parse('root = NestDefBox({ mode: "slow", retries: "many" })').root?.props.cfg,+ ).toEqual({ mode: "slow", retries: 3 });+ // absent and null required keys fill from defaults without an error+ const absent = parser.parse("root = NestDefBox({ retries: 2 })");+ expect(absent.root?.props.cfg).toEqual({ mode: "fast", retries: 2 });+ expect(absent.meta.errors).toEqual([]);+ const nulled = parser.parse("root = NestDefBox({ mode: null, retries: 2 })");+ expect(nulled.root?.props.cfg).toEqual({ mode: "fast", retries: 2 });+ expect(nulled.meta.errors).toEqual([]);+ });+});++describe("components in data slots", () => {+ it("elements in data slots follow the edge rule: drop on required, prune on optional/items", () => {+ // hbc = HorizontalBarChart(Card([]), [], "grouped") — the motivating case.+ const dropped = parser.parse('root = ChartBox(CardBox("x"), "grouped")');+ expect(dropped.root).toBeNull();+ expect(dropped.meta.errors[0].message).toContain('expects array but got component "CardBox"');+ // optional enum leaf → prop pruned+ const pruned = parser.parse('root = ChartBox(["a"], CardBox("x"))');+ expect(pruned.root?.props).not.toHaveProperty("variant");+ expect(pruned.meta.errors[0].message).toContain("expects a literal value but got component");+ // data-array item → item pruned, siblings survive+ expect(parser.parse('root = TagBox(["a", CardBox("x"), "b"])').root?.props.tags).toEqual([+ "a",+ "b",+ ]);+ });++ it("component slots ($ref/anyOf) stay unchecked; a misplaced component's own args still validate", () => {+ const slot = parser.parse('root = SlotBox([CardBox("hi"), EnumBox("active")])');+ expect(slot.meta.errors).toEqual([]);+ expect((slot.root?.props.children as unknown[]).length).toBe(2);+ // both the position error and the component's own arg error surface+ const errors = errorsFor("root = ObjBox({ author: CardBox(9) })");+ expect(errors).toHaveLength(2);+ expect(errors.find((e) => e.component === "CardBox")).toMatchObject({ path: "/text" });+ expect(errors.find((e) => e.component === "ObjBox")).toMatchObject({ path: "/info/author" });+ });+});++describe("conservative skips", () => {+ it("skips dynamic values, composites, null/omitted args, and extra keys", () => {+ expect(errorsFor('root = TagBox(["a", $x])')).toEqual([]); // $var resolves at runtime+ expect(errorsFor('root = ObjBox({ author: "a", views: Sum([1, 2]) })')).toEqual([]); // builtin+ expect(errorsFor("root = AnyBox({ anything: true })")).toEqual([]); // anyOf composite+ expect(errorsFor("root = ObjBox(null)")).toEqual([]); // absence is the parent's concern+ expect(errorsFor("root = ObjBox()")).toEqual([]);+ expect(errorsFor('root = ObjBox({ author: "a", bonus: 99 })')).toEqual([]); // undeclared keys+ expect(errorsFor('root = ListBox([1, "a", true])')).toEqual([]); // array without `items`+ });++ it("skips malformed/uncheckable schemas and applies documented leaf edges (direct)", () => {+ expect(directErrors(5, undefined)).toEqual([]);+ expect(directErrors(5, "string")).toEqual([]);+ expect(directErrors(5, { $ref: "#/$defs/Thing" })).toEqual([]);+ expect(directErrors(5, { oneOf: [{ type: "string" }] })).toEqual([]);+ expect(directErrors([5], { type: "array", items: [{ type: "string" }] })).toEqual([]); // tuple+ expect(directErrors("x", { type: "date" })).toEqual([]); // unknown type keyword+ expect(directErrors({}, { type: "object", required: "author" })).toEqual([]); // non-array required+ // ...but `required` works even without `properties`+ expect(directErrors({}, { type: "object", required: ["a"] })[0]).toMatchObject({+ code: "missing-required",+ });+ // leaf edges: integer ≈ number (floats pass), const ≈ single-value enum,+ // non-scalar values never judged against enums+ expect(directErrors(1.5, { type: "integer" })).toEqual([]);+ expect(directErrors("3", { type: "integer" })).toHaveLength(1);+ expect(directErrors("loose", { const: "fixed" })[0].message).toContain('one of ["fixed"]');+ expect(directErrors({ a: 1 }, { enum: ["active"] })).toEqual([]);+ });+});++describe("streaming gates", () => {+ it("defers required-key and enum checks while partial, then reports them on completion", () => {+ const req = createStreamingParser(schema);+ expect(req.push("root = ObjBox({ views: 3 ").meta.errors).toEqual([]);+ expect(req.push("})\n").meta.errors[0]).toMatchObject({+ code: "missing-required",+ path: "/info/author",+ statementId: "root",+ });+ const en = createStreamingParser(schema);+ expect(en.push('root = EnumBox("bogus" ').meta.errors).toEqual([]);+ expect(en.push(")\n").meta.errors[0]).toMatchObject({ path: "/status" });+ });++ it("keeps scalar type checks on mid-stream (only structure and enums defer)", () => {+ const sp = createStreamingParser(schema);+ const res = sp.push('root = ObjBox({ author: "a", views: "lots" ');+ expect(res.meta.incomplete).toBe(true);+ expect(res.meta.errors.find((e) => e.code === "type-mismatch")).toMatchObject({+ path: "/info/views",+ });+ // same gating verified directly on a partial ctx+ expect(directErrors({}, { type: "object", required: ["a"] }, true)).toEqual([]);+ expect(directErrors("act", { enum: ["active"] }, true)).toEqual([]);+ expect(directErrors(5, { type: "string" }, true)).toHaveLength(1);+ });+});diff --git a/packages/lang-core/src/parser/enrich-errors.ts b/packages/lang-core/src/parser/enrich-errors.tsindex 65fef725d..9677da56d 100644--- a/packages/lang-core/src/parser/enrich-errors.ts+++ b/packages/lang-core/src/parser/enrich-errors.ts@@ -17,6 +17,10 @@ function buildSignatureHint(* Convert parser ValidationErrors into enriched OpenUIErrors with hints.** Framework-agnostic — usable by React, Svelte, Vue, or standalone.+ *+ * @deprecated ValidationError.message is already humanized and self-sufficient+ * (signatures, available components, expected types are inlined) — read+ * `result.meta.errors` directly. Will be removed in a future major release.*/export function enrichErrors(validationErrors: ValidationError[],diff --git a/packages/lang-core/src/parser/materialize.ts b/packages/lang-core/src/parser/materialize.tsindex f97bab3f2..310e2eab8 100644--- a/packages/lang-core/src/parser/materialize.ts+++ b/packages/lang-core/src/parser/materialize.ts@@ -5,7 +5,13 @@import type { ASTNode } from "./ast";import { isASTNode, isRuntimeExpr } from "./ast";import { isBuiltin, isReservedCall, LAZY_BUILTINS, RESERVED_CALLS } from "./builtins";-import { isElementNode, type ParamMap, type ValidationError } from "./types";+import { isElementNode, type MaterializeCtx } from "./types";+import {+ buildParamsSignature,+ pushValidationIssue,+ resolveInvalidValue,+ validateSchemaValue,+} from "./validation";/*** Recursively check if a prop value contains any AST nodes that need runtime@@ -22,19 +28,6 @@ export function containsDynamicValue(v: unknown): boolean {return Object.values(obj).some(containsDynamicValue);}-export interface MaterializeCtx {- syms: Map<string, ASTNode>;- cat: ParamMap | undefined;- errors: ValidationError[];- unres: string[];- visited: Set<string>;- 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>;-}-/*** Resolve a Ref node: inline from symbol table, detect cycles, emit RuntimeRef* for Query/Mutation declarations. Shared by materializeValue and materializeExpr.@@ -126,12 +119,9 @@ function materializeExprInternal(return { ...node, args: recursedArgs, mappedProps };}// Unknown component in expression: push error (same as value path)- ctx.errors.push({+ pushValidationIssue(ctx, node.name, "", {code: "unknown-component",- component: node.name,- path: "",- message: `Unknown component "${node.name}" — not found in catalog or builtins`,- statementId: ctx.currentStatementId,+ available: ctx.cat && [...ctx.cat.keys()],});return { ...node, args: recursedArgs };}@@ -248,13 +238,7 @@ export function materializeValue(node: ASTNode, ctx: MaterializeCtx): unknown {// Inline Query/Mutation (not from a statement-level declaration) → validation errorif (isReservedCall(name)) {- ctx.errors.push({- code: "inline-reserved",- component: name,- path: "",- message: `${name}() must be declared as a top-level statement, not used inline as a value`,- statementId: ctx.currentStatementId,- });+ pushValidationIssue(ctx, name, "", { code: "inline-reserved" });return null;}@@ -262,20 +246,34 @@ export function materializeValue(node: ASTNode, ctx: MaterializeCtx): unknown {const props: Record<string, unknown> = {};if (def) {+ // Set when a REQUIRED prop holds invalid data with no default to fall+ // back on — the only case where invalidity reaches the component itself.+ let dropComponent = false;// Catalog component: map positional args → named propsfor (let i = 0; i < def.params.length && i < args.length; i++) {- props[def.params[i].name] = materializeValue(args[i], ctx);+ const param = def.params[i];+ const value = materializeValue(args[i], ctx);+ props[param.name] = value;+ // Single validation entry point: scalar leaf type/enum for simple+ // props, recursive key/type checks (with pruning) for nested shapes.+ if (+ param.schema !== undefined &&+ validateSchemaValue(value, param.schema, name, `/${param.name}`, ctx)+ ) {+ // Invalid prop value (error already reported). Same resolution rule as+ // every nested edge; propagation here means dropping the component.+ if (resolveInvalidValue(props, param.name, param.required, param.defaultValue)) {+ dropComponent = true;+ }+ }}// 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({+ pushValidationIssue(ctx, name, "", {code: "excess-args",- component: name,- path: "",- message: `${name} takes ${def.params.length} arg(s), got ${args.length} (${excessCount} excess dropped)`,- statementId: ctx.currentStatementId,+ declared: def.params.length,+ got: args.length,});}@@ -293,28 +291,23 @@ export function materializeValue(node: ASTNode, ctx: MaterializeCtx): unknown {});if (stillInvalid.length) {for (const p of stillInvalid) {- const isNull = p.name in props;- ctx.errors.push({- code: isNull ? "null-required" : "missing-required",- component: name,- path: `/${p.name}`,- message: isNull- ? `required field "${p.name}" cannot be null`- : `missing required field "${p.name}"`,- statementId: ctx.currentStatementId,+ pushValidationIssue(ctx, name, `/${p.name}`, {+ code: p.name in props ? "null-required" : "missing-required",+ signature: buildParamsSignature(name, def.params),});}return null;}}++ // A required prop with unsalvageable data (no default) drops the+ // component — its error was already reported during validation.+ if (dropComponent) return null;} else if (!isBuiltin(name) && !isReservedCall(name)) {// Unknown component: error and drop from tree- ctx.errors.push({+ pushValidationIssue(ctx, name, "", {code: "unknown-component",- component: name,- path: "",- message: `Unknown component "${name}" — not found in catalog or builtins`,- statementId: ctx.currentStatementId,+ available: ctx.cat && [...ctx.cat.keys()],});return null;}diff --git a/packages/lang-core/src/parser/parser.ts b/packages/lang-core/src/parser/parser.tsindex 32b443aca..41bd2e7bc 100644--- a/packages/lang-core/src/parser/parser.ts+++ b/packages/lang-core/src/parser/parser.ts@@ -3,18 +3,20 @@ import { isASTNode, walkAST } from "./ast";import { isBuiltin, RESERVED_CALLS } from "./builtins";import { parseExpression } from "./expressions";import { tokenize } from "./lexer";-import { materializeValue, type MaterializeCtx } from "./materialize";+import { materializeValue } from "./materialize";import { autoClose, split, type RawStmt } from "./statements";import { T } from "./tokens";import {isElementNode,type LibraryJSONSchema,+ type MaterializeCtx,type MutationStatementInfo,type ParamMap,type ParseResult,type QueryStatementInfo,type ValidationError,} from "./types";+import { getSchemaDefaultValue } from "./validation";// ─────────────────────────────────────────────────────────────────────────────// Result building@@ -630,13 +632,6 @@ export interface Parser {parse(input: string): ParseResult;}-function getSchemaDefaultValue(property: unknown): unknown {- if (!property || typeof property !== "object" || Array.isArray(property)) {- return undefined;- }- return (property as { default?: unknown }).default;-}-export function compileSchema(schema: LibraryJSONSchema): ParamMap {const map: ParamMap = new Map();const defs = schema.$defs ?? {};@@ -648,6 +643,7 @@ export function compileSchema(schema: LibraryJSONSchema): ParamMap {name: key,required: required.includes(key),defaultValue: getSchemaDefaultValue(properties[key]),+ schema: properties[key],}));map.set(name, { params });}diff --git a/packages/lang-core/src/parser/prompt.ts b/packages/lang-core/src/parser/prompt.tsindex 069eddadb..7c4372746 100644--- a/packages/lang-core/src/parser/prompt.ts+++ b/packages/lang-core/src/parser/prompt.ts@@ -439,6 +439,9 @@ function importantRules(`${flags.toolCalls ? "4" : "3"}. Every $binding appears in at least one component or expression.`,);}+ if (flags.toolCalls && flags.bindings) {+ verifyLines.push("5. Every visible filter $binding appears in at least one Query args object.");+ }return `## Important Rules- When asked about data, generate realistic/plausible datadiff --git a/packages/lang-core/src/parser/types.ts b/packages/lang-core/src/parser/types.tsindex 573331c31..2a378972f 100644--- a/packages/lang-core/src/parser/types.ts+++ b/packages/lang-core/src/parser/types.ts@@ -1,20 +1,23 @@import type { ASTNode } from "./ast";+export type JSONSchemaProperty = Record<string, unknown>;+export type JSONSchemaDef = {+ properties?: JSONSchemaProperty;+ required?: string[];+ description?: string;+};+/*** The JSON Schema document produced by `library.toJSONSchema()`.* All component schemas live in `$defs`, keyed by component name.*/export interface LibraryJSONSchema {- $defs?: Record<- string,- {- properties?: Record<string, unknown>;- required?: string[];- description?: string;- }- >;+ $defs?: Record<string, JSONSchemaDef>;}+/** Scalar JSON Schema types we can reliably check a positional literal against. */+export type ScalarParamType = "string" | "number" | "boolean";+export interface ParamDef {/** Parameter name, e.g. "title", "columns". */name: string;@@ -22,6 +25,8 @@ export interface ParamDef {required: boolean;/** Default value from JSON Schema — used when the required field is missing/null. */defaultValue?: unknown;+ /** The raw JSON Schema fragment for this param. */+ schema?: unknown;}/** Internal parameter map for positional-arg to named-prop mapping. */@@ -70,7 +75,12 @@ export function isElementNode(value: unknown): value is ElementNode {* Validation error codes for schema-related issues.*/export type ValidationErrorCode =- "missing-required" | "null-required" | "unknown-component" | "inline-reserved" | "excess-args";+ | "missing-required"+ | "null-required"+ | "unknown-component"+ | "inline-reserved"+ | "excess-args"+ | "type-mismatch";/*** A prop validation error. Components with missing required props are@@ -89,6 +99,19 @@ export interface ValidationError {statementId?: string;}+export interface MaterializeCtx {+ syms: Map<string, ASTNode>;+ cat: ParamMap | undefined;+ errors: ValidationError[];+ unres: string[];+ visited: Set<string>;+ 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>;+}+/*** Error sources across the openui-lang pipeline.*/diff --git a/packages/lang-core/src/parser/validation.ts b/packages/lang-core/src/parser/validation.tsnew file mode 100644index 000000000..77458972b--- /dev/null+++ b/packages/lang-core/src/parser/validation.ts@@ -0,0 +1,370 @@+import { isASTNode } from "./ast";+import {+ isElementNode,+ type ElementNode,+ type MaterializeCtx,+ type ParamDef,+ type ScalarParamType,+} from "./types";++// ─────────────────────────────────────────────────────────────────────────────+// Schema & value introspection+// ─────────────────────────────────────────────────────────────────────────────++/** `typeof` results a scalar/enum leaf can be checked against. */+const SCALAR_TYPEOFS: readonly string[] = ["string", "number", "boolean"];++const NO_PROPS: Record<string, unknown> = {};+const NO_REQUIRED: readonly string[] = [];++function jsType(value: unknown): string {+ return Array.isArray(value) ? "array" : typeof value;+}++/** Composite shapes can't be reliably matched to a single plain value. */+function isCompositeSchema(s: Record<string, unknown>): boolean {+ return "$ref" in s || "anyOf" in s || "oneOf" in s || "allOf" in s;+}++/** Scalar type/enum info extracted from a JSON Schema leaf, for describeTypeMismatch. */+interface ScalarTypeInfo {+ /** Scalar leaf type, when the property is a plain string/number/boolean. */+ expectedType?: ScalarParamType;+ /** Allowed literal values from `enum`/`const`. */+ enumValues?: readonly unknown[];+}++/** Extract the scalar leaf type/enum from an already-narrowed JSON Schema object. */+export function getScalarTypeInfo(s: Record<string, unknown>): ScalarTypeInfo {+ if (Array.isArray(s["enum"])) return { enumValues: s["enum"] };+ if ("const" in s) return { enumValues: [s["const"]] };+ switch (s["type"]) {+ case "string":+ return { expectedType: "string" };+ case "number":+ case "integer":+ return { expectedType: "number" };+ case "boolean":+ return { expectedType: "boolean" };+ default:+ return {};+ }+}++/** Read a JSON Schema fragment's `default`, if it carries one. */+export function getSchemaDefaultValue(property: unknown): unknown {+ if (!property || typeof property !== "object" || Array.isArray(property)) {+ return undefined;+ }+ return (property as { default?: unknown }).default;+}++/** Returns the expected type for a param from its schema properties */+export function getTypeFromSchema(property: unknown): string | undefined {+ if (!property || typeof property !== "object" || Array.isArray(property)) {+ return undefined;+ }+ const p = property as Record<string, unknown>;+ // $refs and compound types aren't validator-checkable but still make useful hints.+ if (typeof p.$ref === "string") {+ return p.$ref.split("/").pop();+ }+ // Scalar/enum leaves: share the validator's schema-leaf interpretation so+ // signatures and type-mismatch messages never disagree.+ const leaf = getScalarTypeInfo(p);+ if (leaf.enumValues) {+ return leaf.enumValues.map((v) => JSON.stringify(v)).join("|");+ }+ if (leaf.expectedType) {+ return leaf.expectedType;+ }+ return typeof p.type === "string" ? p.type : undefined;+}++/**+ * Build a typed signature like `Header(title*: string, variant: "a"|"b")` from+ * compiled params — * marks required. Positional order is preserved so an LLM+ * can fix swapped args.+ */+export function buildParamsSignature(component: string, params: ParamDef[]): string {+ const rendered = params+ .map((p) => {+ const type = getTypeFromSchema(p.schema);+ const marked = p.required ? `${p.name}*` : p.name;+ return type ? `${marked}: ${type}` : marked;+ })+ .join(", ");+ return `${component}(${rendered})`;+}++/** Checks a param's returned value against its expected value */+function checkTypeMismatch(+ value: unknown,+ info: ScalarTypeInfo,+): { expected: string; actual: string } | null {+ const actual = typeof value;+ if (info.enumValues) {+ if (!SCALAR_TYPEOFS.includes(actual)) return null;+ if (info.enumValues.includes(value)) return null;+ return {+ expected: `one of [${info.enumValues.map((v) => JSON.stringify(v)).join(", ")}]`,+ actual: JSON.stringify(value),+ };+ }+ if (info.expectedType && info.expectedType !== actual) {+ return { expected: info.expectedType, actual: jsType(value) };+ }+ return null;+}++// ─────────────────────────────────────────────────────────────────────────────+// Errors+// ─────────────────────────────────────────────────────────────────────────────++/**+ * A structured validation issue. Every error of a kind reads identically+ * because its message template lives in validationMessage — call sites only+ * supply the varying parts.+ */+export type ValidationIssue =+ | { code: "type-mismatch"; expected: string; actual: string }+ | { code: "missing-required"; signature?: string }+ | { code: "null-required"; signature?: string }+ | { code: "unknown-component"; available?: string[] }+ | { code: "inline-reserved" }+ | { code: "excess-args"; declared: number; got: number };++function validationMessage(component: string, path: string, issue: ValidationIssue): string {+ switch (issue.code) {+ case "type-mismatch":+ return `field "${path}" expects ${issue.expected} but got ${issue.actual}`;+ case "missing-required":+ return `missing required field "${path}"${issue.signature ? ` — signature: ${issue.signature}` : ""}`;+ case "null-required":+ return `required field "${path}" cannot be null${issue.signature ? ` — signature: ${issue.signature}` : ""}`;+ case "unknown-component":+ return `Unknown component "${component}" — not found in catalog or builtins${issue.available?.length ? `. Available components: ${issue.available.join(", ")}` : ""}`;+ case "inline-reserved":+ return `${component}() must be declared as a top-level statement, not used inline as a value`;+ case "excess-args":+ return `${component} takes ${issue.declared} arg(s), got ${issue.got} (${issue.got - issue.declared} excess dropped)`;+ }+}++/** Append a validation error, deriving its message from the structured issue. */+export function pushValidationIssue(+ ctx: MaterializeCtx,+ component: string,+ path: string,+ issue: ValidationIssue,+): void {+ ctx.errors.push({+ code: issue.code,+ component,+ path,+ message: validationMessage(component, path, issue),+ statementId: ctx.currentStatementId,+ });+}++// ─────────────────────────────────────────────────────────────────────────────+// Invalid-value resolution — the edge rule+// ─────────────────────────────────────────────────────────────────────────────++/**+ * Override invalid value with a default one if present.+ * Propagate upwards if it's a required key.+ * Else, delete the key.+ */+export function resolveInvalidValue(+ container: Record<string, unknown>,+ key: string,+ required: boolean,+ defaultValue: unknown,+): boolean {+ if (defaultValue !== undefined) {+ container[key] = defaultValue;+ return false;+ }+ if (required) return true;+ delete container[key];+ return false;+}++// ─────────────────────────────────────────────────────────────────────────────+// Validators — one per schema shape, dispatched by validateSchemaValue+// ─────────────────────────────────────────────────────────────────────────────++/**+ * Position check for a component element in a data slot: slots that admit+ * components ($ref / anyOf / oneOf members) are left unchecked, a slot+ * declaring a plain-data shape can never be satisfied by a component, and+ * unconstrained slots stay conservative.+ */+function validateElementPosition(+ element: ElementNode,+ s: Record<string, unknown>,+ component: string,+ path: string,+ ctx: MaterializeCtx,+): boolean {+ if (isCompositeSchema(s)) return false;+ if (typeof s["type"] === "string" || Array.isArray(s["enum"]) || "const" in s) {+ pushValidationIssue(ctx, component, path, {+ code: "type-mismatch",+ expected: typeof s["type"] === "string" ? s["type"] : "a literal value",+ actual: `component "${element.typeName}"`,+ });+ return true;+ }+ return false;+}++/**+ * Validate an object-shaped slot: container type, required keys (absent/null+ * ones fill silently from their schema default), then each declared property+ * recursively, resolving invalid children via the edge rule.+ */+function validateObjectValue(+ value: unknown,+ s: Record<string, unknown>,+ component: string,+ path: string,+ ctx: MaterializeCtx,+): boolean {+ if (typeof value !== "object" || Array.isArray(value)) {+ pushValidationIssue(ctx, component, path, {+ code: "type-mismatch",+ expected: "object",+ actual: jsType(value),+ });+ return true;+ }+ const obj = value as Record<string, unknown>;+ const props =+ s["properties"] && typeof s["properties"] === "object"+ ? (s["properties"] as Record<string, unknown>)+ : NO_PROPS;+ const required = Array.isArray(s["required"]) ? (s["required"] as string[]) : NO_REQUIRED;+ let invalid = false;+ // Structural checks are streaming-sensitive — only run on complete input.+ if (!ctx.partial) {+ for (const key of required) {+ const present = key in obj;+ if (!present || obj[key] == null) {+ const fallback = getSchemaDefaultValue(props[key]);+ if (fallback !== undefined) {+ obj[key] = fallback;+ continue;+ }+ pushValidationIssue(ctx, component, `${path}/${key}`, {+ code: present ? "null-required" : "missing-required",+ });+ invalid = true;+ }+ }+ }+ for (const key of Object.keys(props)) {+ if (key in obj) {+ const sub = props[key];+ if (validateSchemaValue(obj[key], sub, component, `${path}/${key}`, ctx)) {+ if (resolveInvalidValue(obj, key, required.includes(key), getSchemaDefaultValue(sub))) {+ invalid = true;+ }+ }+ }+ }+ return invalid;+}++/**+ * Validate an array slot: Invalid items are pruned in+ * place: validated first so error paths keep original indices+ */+function validateArrayValue(+ value: unknown,+ s: Record<string, unknown>,+ component: string,+ path: string,+ ctx: MaterializeCtx,+): boolean {+ if (!Array.isArray(value)) {+ pushValidationIssue(ctx, component, path, {+ code: "type-mismatch",+ expected: "array",+ actual: jsType(value),+ });+ return true;+ }+ const items = s["items"];+ if (!items || typeof items !== "object" || Array.isArray(items)) return false;+ let invalid: number[] | undefined;+ for (let i = 0; i < value.length; i++) {+ if (validateSchemaValue(value[i], items, component, `${path}/${i}`, ctx)) {+ (invalid ??= []).push(i);+ }+ }+ if (invalid) {+ for (let i = invalid.length - 1; i >= 0; i--) value.splice(invalid[i], 1); // prune the array+ }+ return false;+}++/**+ * Validate a scalar/enum leaf. Enum membership defers while streaming — a+ * partial literal may still complete toward a valid member; scalar type+ * checks stay on (a wrong type won't become right with more input).+ */+function validateLeafValue(+ value: unknown,+ s: Record<string, unknown>,+ component: string,+ path: string,+ ctx: MaterializeCtx,+): boolean {+ const leaf = getScalarTypeInfo(s);+ if (leaf.expectedType == null && leaf.enumValues == null) return false;+ if (leaf.enumValues && ctx.partial) return false;+ const mismatch = checkTypeMismatch(value, leaf);+ if (mismatch) {+ pushValidationIssue(ctx, component, path, { code: "type-mismatch", ...mismatch });+ return true;+ }+ return false;+}++/**+ * Recursively validate a materialized value against a JSON Schema fragment,+ * pruning unsalvageable data along the way. Dispatches on the schema shape:+ * objects and arrays descend recursively (reporting nested errors with+ * JSON-pointer paths), leaf scalars check type/enum, and component elements+ * get a position check only (their own args validate separately).+ *+ * Every violation is reported, then the same rule (resolveInvalidValue)+ * applies at each recursion edge: schema default → substitute; REQUIRED edge →+ * parent invalid, caller repeats one level up; OPTIONAL edge → prune. ARRAY+ * ITEMS are always pruned. Absent/null required keys fill silently from their+ * schema default; reported violations keep their error even when a default steps in.+ */+export function validateSchemaValue(+ value: unknown,+ schema: unknown,+ component: string,+ path: string,+ ctx: MaterializeCtx,+): boolean {+ if (!schema || typeof schema !== "object" || Array.isArray(schema)) return false;+ const s = schema as Record<string, unknown>;+ // Absence is handled by required checks on the parent; skip null/undefined.+ if (value == null) return false;+ // Dynamic runtime expressions ($var, builtins) resolve later — don't flag.+ if (isASTNode(value)) return false;+ // Child components: only their position is checked here.+ if (isElementNode(value)) return validateElementPosition(value, s, component, path, ctx);+ if (isCompositeSchema(s)) return false;++ const type = s["type"];+ if (type === "object") return validateObjectValue(value, s, component, path, ctx);+ if (type === "array") return validateArrayValue(value, s, component, path, ctx);+ return validateLeafValue(value, s, component, path, ctx);+}diff --git a/packages/vue-lang/package.json b/packages/vue-lang/package.jsonindex da294173e..883b29667 100644--- a/packages/vue-lang/package.json+++ b/packages/vue-lang/package.json@@ -1,6 +1,6 @@{"name": "@openuidev/vue-lang",- "version": "0.1.3",+ "version": "0.1.4","description": "Define component libraries, generate LLM system prompts, and render streaming OpenUI Lang output in Vue 3 — the Vue runtime for OpenUI generative UI","license": "MIT","type": "module",diff --git a/packages/vue-lang/src/state.ts b/packages/vue-lang/src/state.tsindex e41a9d8c6..239046d1e 100644--- a/packages/vue-lang/src/state.ts+++ b/packages/vue-lang/src/state.ts@@ -4,7 +4,6 @@ import {createQueryManager,createStore,createStreamingParser,- enrichErrors,evaluate,evaluateElementProps,type ActionEvent,@@ -16,6 +15,7 @@ import {type QueryManager,type QuerySnapshot,type ToolProvider,+ type ValidationError,} from "@openuidev/lang-core";import {computed,@@ -462,14 +462,18 @@ export function useOpenUIState(});}- // Parser validation errors+ // Parser validation errors → tag source; ValidationError.message is already+ // humanized (signatures/available components/expected types inlined).if (res?.meta?.errors?.length) {errors.push(- ...enrichErrors(- res.meta.errors,- options.library.toJSONSchema(),- Object.keys(options.library.components),- ),+ ...res.meta.errors.map((e: ValidationError) => ({+ source: "parser" as const,+ code: e.code,+ message: e.message,+ component: e.component,+ path: e.path || undefined,+ statementId: e.statementId,+ })),);}