stringent 0.0.1 → 0.0.4

package/dist/runtime/eval.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Runtime Expression Evaluation
+ *
+ * Evaluates parsed AST nodes to produce runtime values.
+ * Uses the eval functions defined in NodeSchema to compute results.
+ *
+ * The evaluator:
+ * 1. Recursively evaluates child nodes first
+ * 2. Passes evaluated values to the node's eval function
+ * 3. Returns the computed result
+ * 4. Validates values against arktype constraints at runtime
+ */
+import type { NodeSchema, SchemaToType } from '../schema/index.js';
+/**
+ * Extract the outputSchema from an AST node type.
+ * Returns the literal schema string if present, otherwise 'unknown'.
+ */
+type ExtractOutputSchema<T> = T extends {
+    outputSchema: infer S extends string;
+} ? S : 'unknown';
+/**
+ * A type that represents any AST node with an outputSchema field.
+ * This is used as a constraint for the evaluate() function.
+ */
+export type ASTNodeWithSchema<TSchema extends string = string> = {
+    readonly node: string;
+    readonly outputSchema: TSchema;
+};
+/**
+ * Recursively extract all identifier nodes from an AST.
+ * Returns a union of { name: string, outputSchema: string } tuples.
+ *
+ * This is used to determine what variables are used in an expression
+ * and what types they expect.
+ */
+type ExtractIdentifiers<T> = T extends {
+    node: 'identifier';
+    name: infer N;
+    outputSchema: infer S;
+} ? {
+    name: N;
+    outputSchema: S;
+} : T extends object ? {
+    [K in keyof T]: ExtractIdentifiers<T[K]>;
+}[keyof T] : never;
+/**
+ * Convert a union of identifier tuples to a data object type.
+ *
+ * @example
+ * type Ids = { name: 'x'; outputSchema: 'number' } | { name: 'y'; outputSchema: 'string' };
+ * type Data = IdentifiersToData<Ids>;
+ * // { x: number; y: string }
+ */
+type IdentifiersToData<T> = T extends {
+    name: infer N extends string;
+    outputSchema: infer S;
+} ? {
+    [K in N]: SchemaToType<S>;
+} : never;
+/**
+ * Merge a union of single-key objects into a single object type.
+ *
+ * @example
+ * type Union = { x: number } | { y: string };
+ * type Merged = UnionToIntersection<Union>;
+ * // { x: number } & { y: string }
+ */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Extract required data types from an AST based on its identifier nodes.
+ * Returns Record<string, never> if no identifiers are found (empty object is allowed).
+ *
+ * @example
+ * type AST = { node: 'add'; left: { node: 'identifier'; name: 'x'; outputSchema: 'number' }; ... };
+ * type Data = ExtractRequiredData<AST>;
+ * // { x: number }
+ */
+export type ExtractRequiredData<T> = ExtractIdentifiers<T> extends never ? Record<string, never> : UnionToIntersection<IdentifiersToData<ExtractIdentifiers<T>>>;
+/**
+ * Evaluation context that includes both the parse context and node schemas.
+ * When AST type is provided, the data is type-checked against the AST's variables.
+ */
+export interface EvalContext<TData = Record<string, unknown>> {
+    /** The data context (variable name → value mapping) */
+    data: TData;
+    /** The node schemas (for looking up eval functions) */
+    nodes: readonly NodeSchema[];
+}
+/**
+ * Evaluate an AST node to produce a runtime value.
+ *
+ * The return type is inferred from the AST node's `outputSchema` field:
+ * - `outputSchema: "number"` → returns `number`
+ * - `outputSchema: "string"` → returns `string`
+ * - `outputSchema: "boolean"` → returns `boolean`
+ * - `outputSchema: "null"` → returns `null`
+ * - `outputSchema: "undefined"` → returns `undefined`
+ * - Other/unknown → returns `unknown`
+ *
+ * @param ast - The parsed AST node to evaluate
+ * @param ctx - The evaluation context containing variable values and node schemas
+ * @returns The evaluated value with the type derived from the AST's outputSchema
+ *
+ * @example
+ * ```ts
+ * import { createParser, defineNode, lhs, rhs, constVal } from "stringent";
+ * import { evaluate } from "stringent/runtime/eval";
+ *
+ * const add = defineNode({
+ *   name: "add",
+ *   pattern: [lhs("number").as("left"), constVal("+"), rhs("number").as("right")],
+ *   precedence: 1,
+ *   resultType: "number",
+ *   eval: ({ left, right }) => left + right,
+ * });
+ *
+ * const parser = createParser([add] as const);
+ * const result = parser.parse("1+2", {});
+ *
+ * if (result.length === 2) {
+ *   const value = evaluate(result[0], { data: {}, nodes: [add] });
+ *   // value has type: number (not unknown!)
+ *   // value === 3
+ * }
+ * ```
+ */
+export declare function evaluate<T, TData extends ExtractRequiredData<T>>(ast: T, ctx: EvalContext<TData>): SchemaToType<ExtractOutputSchema<T>>;
+/**
+ * Create a bound evaluator function for a specific set of node schemas.
+ *
+ * This is a convenience function that pre-binds the node schemas,
+ * so you only need to pass the AST and variable values when evaluating.
+ *
+ * The returned evaluator function preserves type inference:
+ * - The return type is derived from the AST's `outputSchema` field
+ * - `outputSchema: "number"` → returns `number`
+ * - `outputSchema: "string"` → returns `string`
+ * - etc.
+ *
+ * @param nodes - The node schemas with eval functions
+ * @returns An evaluator function with type inference
+ *
+ * @example
+ * ```ts
+ * const evaluator = createEvaluator([add, mul]);
+ *
+ * const result = parser.parse("1+2*3", {});
+ * if (result.length === 2) {
+ *   const value = evaluator(result[0], {});
+ *   // value has type: number (inferred from AST's outputSchema)
+ *   // value === 7
+ * }
+ * ```
+ */
+export declare function createEvaluator(nodes: readonly NodeSchema[]): <T, TData extends ExtractRequiredData<T>>(ast: T, data: TData) => SchemaToType<ExtractOutputSchema<T>>;
+export {};
+//# sourceMappingURL=eval.d.ts.map

package/dist/runtime/eval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval.d.ts","sourceRoot":"","sources":["../../src/runtime/eval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAMnE;;;GAGG;AACH,KAAK,mBAAmB,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,YAAY,EAAE,MAAM,CAAC,SAAS,MAAM,CAAA;CAAE,GAAG,CAAC,GAAG,SAAS,CAAC;AAEjG;;;GAGG;AACH,MAAM,MAAM,iBAAiB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,IAAI;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC,CAAC;AAMF;;;;;;GAMG;AACH,KAAK,kBAAkB,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC,CAAA;CAAE,GAC/F;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,YAAY,EAAE,CAAC,CAAA;CAAE,GAC5B,CAAC,SAAS,MAAM,GACd;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC,MAAM,CAAC,CAAC,GACrD,KAAK,CAAC;AAEZ;;;;;;;GAOG;AACH,KAAK,iBAAiB,CAAC,CAAC,IAAI,CAAC,SAAS;IACpC,IAAI,EAAE,MAAM,CAAC,SAAS,MAAM,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC,CAAC;CACvB,GACG;KAAG,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC;CAAE,GAC7B,KAAK,CAAC;AAEV;;;;;;;GAOG;AACH,KAAK,mBAAmB,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,GAAG,KAAK,CAAC,SAAS,CACjF,CAAC,EAAE,MAAM,CAAC,KACP,IAAI,GACL,CAAC,GACD,KAAK,CAAC;AAEV;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAC/B,kBAAkB,CAAC,CAAC,CAAC,SAAS,KAAK,GAC/B,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GACrB,mBAAmB,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEpE;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC1D,uDAAuD;IACvD,IAAI,EAAE,KAAK,CAAC;IACZ,uDAAuD;IACvD,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;CAC9B;AA0DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,SAAS,mBAAmB,CAAC,CAAC,CAAC,EAC9D,GAAG,EAAE,CAAC,EACN,GAAG,EAAE,WAAW,CAAC,KAAK,CAAC,GACtB,YAAY,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAgGtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,IAChC,CAAC,EAAE,KAAK,SAAS,mBAAmB,CAAC,CAAC,CAAC,EAC/D,KAAK,CAAC,EACN,MAAM,KAAK,KACV,YAAY,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAGxC"}

package/dist/runtime/eval.js

@@ -0,0 +1,206 @@
+/**
+ * Runtime Expression Evaluation
+ *
+ * Evaluates parsed AST nodes to produce runtime values.
+ * Uses the eval functions defined in NodeSchema to compute results.
+ *
+ * The evaluator:
+ * 1. Recursively evaluates child nodes first
+ * 2. Passes evaluated values to the node's eval function
+ * 3. Returns the computed result
+ * 4. Validates values against arktype constraints at runtime
+ */
+import { type } from 'arktype';
+// =============================================================================
+// Runtime ArkType Validation
+// =============================================================================
+/**
+ * Cache for arktype validators to avoid re-creating them for each evaluation.
+ * Maps schema strings to their compiled validators.
+ */
+const validatorCache = new Map();
+/**
+ * Get or create an arktype validator for a given schema string.
+ * Uses a cache to avoid re-creating validators for frequently used schemas.
+ *
+ * @param schema - The arktype schema string (e.g., 'number >= 0', 'string.email')
+ * @returns The compiled arktype validator
+ */
+function getValidator(schema) {
+    let validator = validatorCache.get(schema);
+    if (!validator) {
+        // Create and cache the validator
+        // Note: Invalid schemas will cause arktype to throw at compile time
+        // At runtime, we trust the schema was validated at parse time
+        validator = type(schema);
+        validatorCache.set(schema, validator);
+    }
+    return validator;
+}
+/**
+ * Validate a value against an arktype schema at runtime.
+ * Throws an error if the value doesn't match the schema constraints.
+ *
+ * @param value - The value to validate
+ * @param schema - The arktype schema string (e.g., 'number >= 0', 'string.email')
+ * @param variableName - The name of the variable (for error messages)
+ * @throws Error if the value doesn't match the schema constraints
+ */
+function validateValue(value, schema, variableName) {
+    // Skip validation for generic schemas that don't have runtime constraints
+    // These basic types are handled by TypeScript's compile-time checking
+    if (schema === 'unknown' || schema === 'never') {
+        return;
+    }
+    const validator = getValidator(schema);
+    const result = validator(value);
+    // arktype returns the value if valid, or an ArkErrors object if invalid
+    if (result instanceof type.errors) {
+        throw new Error(`Variable '${variableName}' failed validation for schema '${schema}': ${result.summary}`);
+    }
+}
+/**
+ * Evaluate an AST node to produce a runtime value.
+ *
+ * The return type is inferred from the AST node's `outputSchema` field:
+ * - `outputSchema: "number"` → returns `number`
+ * - `outputSchema: "string"` → returns `string`
+ * - `outputSchema: "boolean"` → returns `boolean`
+ * - `outputSchema: "null"` → returns `null`
+ * - `outputSchema: "undefined"` → returns `undefined`
+ * - Other/unknown → returns `unknown`
+ *
+ * @param ast - The parsed AST node to evaluate
+ * @param ctx - The evaluation context containing variable values and node schemas
+ * @returns The evaluated value with the type derived from the AST's outputSchema
+ *
+ * @example
+ * ```ts
+ * import { createParser, defineNode, lhs, rhs, constVal } from "stringent";
+ * import { evaluate } from "stringent/runtime/eval";
+ *
+ * const add = defineNode({
+ *   name: "add",
+ *   pattern: [lhs("number").as("left"), constVal("+"), rhs("number").as("right")],
+ *   precedence: 1,
+ *   resultType: "number",
+ *   eval: ({ left, right }) => left + right,
+ * });
+ *
+ * const parser = createParser([add] as const);
+ * const result = parser.parse("1+2", {});
+ *
+ * if (result.length === 2) {
+ *   const value = evaluate(result[0], { data: {}, nodes: [add] });
+ *   // value has type: number (not unknown!)
+ *   // value === 3
+ * }
+ * ```
+ */
+export function evaluate(ast, ctx) {
+    if (typeof ast !== 'object' || ast === null) {
+        throw new Error(`Invalid AST node: expected object, got ${typeof ast}`);
+    }
+    const node = ast;
+    // Check for the 'node' property that indicates the node type
+    if (!('node' in node) || typeof node.node !== 'string') {
+        throw new Error(`Invalid AST node: missing 'node' property`);
+    }
+    const nodeType = node.node;
+    // Handle literal nodes (number, string, boolean, null, undefined)
+    if (nodeType === 'literal') {
+        if ('value' in node) {
+            return node.value;
+        }
+        throw new Error(`Literal node missing 'value' property`);
+    }
+    // Internal eval context for recursive calls (typed at runtime level)
+    const internalCtx = ctx;
+    // Handle identifier nodes - look up value in context and validate against schema
+    if (nodeType === 'identifier') {
+        if (!('name' in node) || typeof node.name !== 'string') {
+            throw new Error(`Identifier node missing 'name' property`);
+        }
+        const name = node.name;
+        if (!(name in internalCtx.data)) {
+            throw new Error(`Undefined variable: ${name}`);
+        }
+        const value = internalCtx.data[name];
+        // Validate value against arktype schema at runtime
+        if ('outputSchema' in node && typeof node.outputSchema === 'string') {
+            validateValue(value, node.outputSchema, name);
+        }
+        return value;
+    }
+    // Handle const nodes (operators, keywords) - these shouldn't be evaluated directly
+    if (nodeType === 'const') {
+        throw new Error(`Cannot evaluate const node directly`);
+    }
+    // Handle parentheses - just evaluate the inner expression
+    if (nodeType === 'parentheses') {
+        if (!('inner' in node)) {
+            throw new Error(`Parentheses node missing 'inner' property`);
+        }
+        // Use type assertion for recursive call (data constraint already validated at entry)
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+        return evaluate(node.inner, internalCtx);
+    }
+    // Look up the node schema for this node type
+    const nodeSchema = internalCtx.nodes.find((n) => n.name === nodeType);
+    if (!nodeSchema) {
+        throw new Error(`Unknown node type: ${nodeType}. Make sure to pass all node schemas to evaluate().`);
+    }
+    if (!nodeSchema.eval) {
+        throw new Error(`Node type '${nodeType}' has no eval function defined`);
+    }
+    // Extract and evaluate all named bindings from the node
+    const evaluatedBindings = {};
+    // Get the pattern to determine which fields are named bindings
+    for (const element of nodeSchema.pattern) {
+        // Check if this is a named schema (has __named and name)
+        if ('__named' in element && element.__named === true && 'name' in element) {
+            const bindingName = element.name;
+            if (bindingName in node) {
+                // Recursively evaluate the child node
+                // Use type assertion for recursive call (data constraint already validated at entry)
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+                evaluatedBindings[bindingName] = evaluate(node[bindingName], internalCtx);
+            }
+        }
+    }
+    // Call the eval function with evaluated bindings
+    return nodeSchema.eval(evaluatedBindings, internalCtx.data);
+}
+/**
+ * Create a bound evaluator function for a specific set of node schemas.
+ *
+ * This is a convenience function that pre-binds the node schemas,
+ * so you only need to pass the AST and variable values when evaluating.
+ *
+ * The returned evaluator function preserves type inference:
+ * - The return type is derived from the AST's `outputSchema` field
+ * - `outputSchema: "number"` → returns `number`
+ * - `outputSchema: "string"` → returns `string`
+ * - etc.
+ *
+ * @param nodes - The node schemas with eval functions
+ * @returns An evaluator function with type inference
+ *
+ * @example
+ * ```ts
+ * const evaluator = createEvaluator([add, mul]);
+ *
+ * const result = parser.parse("1+2*3", {});
+ * if (result.length === 2) {
+ *   const value = evaluator(result[0], {});
+ *   // value has type: number (inferred from AST's outputSchema)
+ *   // value === 7
+ * }
+ * ```
+ */
+export function createEvaluator(nodes) {
+    return function evaluator(ast, data) {
+        return evaluate(ast, { data, nodes });
+    };
+}
+//# sourceMappingURL=eval.js.map

package/dist/runtime/eval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval.js","sourceRoot":"","sources":["../../src/runtime/eval.ts"],"names":[],"mappings":"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"}

package/dist/runtime/infer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Runtime Type Inference
+ *
+ * Infers the result type of a parsed AST at runtime.
+ *
+ * With the new architecture, nodes carry their outputSchema directly,
+ * so inference is simpler - just extract the outputSchema field.
+ */
+import type { Context } from '../context.js';
+export type InferredType = string;
+/**
+ * Runtime inference - extracts outputSchema from parsed AST nodes.
+ *
+ * @param ast - The parsed AST node
+ * @param context - Parse context (unused, kept for API compatibility)
+ * @returns The result type of the AST node
+ *
+ * @example
+ * ```ts
+ * const result = parser.parse("1+2", {});
+ * if (result.length === 2) {
+ *   const type = infer(result[0], {}); // "number"
+ * }
+ * ```
+ */
+export declare function infer(ast: unknown, _context: Context): InferredType;
+//# sourceMappingURL=infer.d.ts.map

package/dist/runtime/infer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"infer.d.ts","sourceRoot":"","sources":["../../src/runtime/infer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,YAAY,CAanE"}

package/dist/runtime/infer.js

@@ -0,0 +1,35 @@
+/**
+ * Runtime Type Inference
+ *
+ * Infers the result type of a parsed AST at runtime.
+ *
+ * With the new architecture, nodes carry their outputSchema directly,
+ * so inference is simpler - just extract the outputSchema field.
+ */
+/**
+ * Runtime inference - extracts outputSchema from parsed AST nodes.
+ *
+ * @param ast - The parsed AST node
+ * @param context - Parse context (unused, kept for API compatibility)
+ * @returns The result type of the AST node
+ *
+ * @example
+ * ```ts
+ * const result = parser.parse("1+2", {});
+ * if (result.length === 2) {
+ *   const type = infer(result[0], {}); // "number"
+ * }
+ * ```
+ */
+export function infer(ast, _context) {
+    if (typeof ast !== 'object' || ast === null) {
+        throw new Error(`Invalid AST node: ${ast}`);
+    }
+    const node = ast;
+    // Nodes with outputSchema (new architecture)
+    if ('outputSchema' in node && typeof node.outputSchema === 'string') {
+        return node.outputSchema;
+    }
+    throw new Error(`AST node has no outputSchema: ${JSON.stringify(ast)}`);
+}
+//# sourceMappingURL=infer.js.map

package/dist/runtime/infer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"infer.js","sourceRoot":"","sources":["../../src/runtime/infer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,KAAK,CAAC,GAAY,EAAE,QAAiB;IACnD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,qBAAqB,GAAG,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM,IAAI,GAAG,GAA8B,CAAC;IAE5C,6CAA6C;IAC7C,IAAI,cAAc,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,YAAY,KAAK,QAAQ,EAAE,CAAC;QACpE,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,iCAAiC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAC1E,CAAC"}

package/dist/runtime/parser.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Runtime Parser
+ *
+ * Mirrors the type-level Parse<Grammar, Input, Context> at runtime.
+ * Uses the same precedence-based parsing strategy:
+ *   1. Try operators at current level (lowest precedence first)
+ *   2. Fall back to next level (higher precedence)
+ *   3. Base case: try atoms (last level)
+ */
+import type { Context } from '../context.js';
+import type { ComputeGrammar, Grammar } from '../grammar/index.js';
+import type { Parse } from '../parse/index.js';
+import type { NodeSchema, StringSchema, ConstSchema, ExprSchema } from '../schema/index.js';
+import { ASTNode } from '../primitive/index.js';
+/** All built-in atoms, used as the last level of the grammar */
+export declare const BUILT_IN_ATOMS: readonly [NodeSchema<"numberLiteral", readonly [import("../schema/index.js").NumberSchema & {
+    as<TName extends string>(name: TName): import("../schema/index.js").NamedSchema<import("../schema/index.js").NumberSchema, TName>;
+}], 0, "number">, NodeSchema<"stringLiteral", readonly [StringSchema<readonly ["\"", "'"]> & {
+    as<TName extends string>(name: TName): import("../schema/index.js").NamedSchema<StringSchema<readonly ["\"", "'"]>, TName>;
+}], 0, "string">, NodeSchema<"nullLiteral", readonly [import("../schema/index.js").NullSchema & {
+    as<TName extends string>(name: TName): import("../schema/index.js").NamedSchema<import("../schema/index.js").NullSchema, TName>;
+}], 0, "null">, NodeSchema<"booleanLiteral", readonly [import("../schema/index.js").BooleanSchema & {
+    as<TName extends string>(name: TName): import("../schema/index.js").NamedSchema<import("../schema/index.js").BooleanSchema, TName>;
+}], 0, "boolean">, NodeSchema<"undefinedLiteral", readonly [import("../schema/index.js").UndefinedSchema & {
+    as<TName extends string>(name: TName): import("../schema/index.js").NamedSchema<import("../schema/index.js").UndefinedSchema, TName>;
+}], 0, "undefined">, NodeSchema<"identifier", readonly [import("../schema/index.js").IdentSchema & {
+    as<TName extends string>(name: TName): import("../schema/index.js").NamedSchema<import("../schema/index.js").IdentSchema, TName>;
+}], 0, "unknown">, NodeSchema<"parentheses", readonly [ConstSchema<"("> & {
+    as<TName extends string>(name: TName): import("../schema/index.js").NamedSchema<ConstSchema<"(">, TName>;
+}, import("../schema/index.js").NamedSchema<ExprSchema<string, "expr">, "inner">, ConstSchema<")"> & {
+    as<TName extends string>(name: TName): import("../schema/index.js").NamedSchema<ConstSchema<")">, TName>;
+}], 0, "unknown">];
+/** Parse result: empty = no match, [node, rest] = matched */
+export type ParseResult<T extends ASTNode<string, unknown> = ASTNode<string, unknown>> = [] | [T & {}, string];
+/**
+ * Process escape sequences in a string.
+ * Supports: \n, \t, \r, \\, \", \', \0, \b, \f, \v, \xHH, \uHHHH
+ *
+ * @param str - The raw string with escape sequences
+ * @returns The processed string with escape sequences converted
+ */
+export declare function processEscapeSequences(str: string): string;
+/**
+ * Build runtime grammar from operator schemas.
+ *
+ * Returns a flat tuple of levels:
+ *   [[ops@prec1], [ops@prec2], ..., [builtInAtoms]]
+ *
+ * Operators are sorted by precedence ascending (lowest first).
+ * Built-in atoms are always appended as the last level.
+ */
+export declare function buildGrammar(operators: readonly NodeSchema[]): Grammar;
+/**
+ * Parse input string using node schemas.
+ *
+ * The return type is computed from the input types using the type-level
+ * Parse<Grammar, Input, Context> type, ensuring runtime and type-level
+ * parsing stay in sync.
+ */
+export declare function parse<const TNodes extends readonly NodeSchema[], const TInput extends string, const TContext extends Context>(nodes: TNodes, input: TInput, context: TContext): Parse<ComputeGrammar<TNodes>, TInput, TContext>;
+import { type RichParseError, type ParseResultWithErrors } from '../errors.js';
+export type { RichParseError, ParseResultWithErrors };
+/**
+ * Result from parseWithErrors - includes rich error information on failure.
+ */
+export interface ParseWithErrorsResult<T extends ASTNode<string, unknown> = ASTNode<string, unknown>> {
+    /** Whether parsing was successful */
+    readonly success: boolean;
+    /** The parsed AST node (only present if success is true) */
+    readonly ast?: T;
+    /** Remaining unparsed input (only present if success is true) */
+    readonly remaining?: string;
+    /** Parse error information (only present if success is false) */
+    readonly error?: RichParseError;
+    /** Original input string */
+    readonly input: string;
+}
+/**
+ * Parse input with rich error information.
+ *
+ * Unlike `parse()` which returns an empty array on failure, this function
+ * returns detailed error information including:
+ * - Position (line, column, offset)
+ * - Error message
+ * - Source snippet showing where the error occurred
+ *
+ * @example
+ * ```ts
+ * const result = parseWithErrors([add], "1 + ", context);
+ * if (!result.success) {
+ *   console.log(result.error.message);
+ *   // "No grammar rule matched at position 1:5: """
+ *   console.log(result.error.snippet);
+ *   // "1 + →"
+ * }
+ * ```
+ */
+export declare function parseWithErrors<const TNodes extends readonly NodeSchema[], const TInput extends string, const TContext extends Context>(nodes: TNodes, input: TInput, context: TContext): ParseWithErrorsResult;
+/**
+ * Format a parse error for display.
+ *
+ * @example
+ * ```ts
+ * const result = parseWithErrors([add], "1 + ", context);
+ * if (!result.success) {
+ *   console.log(formatParseError(result.error));
+ *   // Error at line 1, column 5:
+ *   //   No grammar rule matched at position 1:5: ""
+ *   //
+ *   //   1 + →
+ * }
+ * ```
+ */
+export declare function formatParseError(error: RichParseError): string;
+//# sourceMappingURL=parser.d.ts.map

package/dist/runtime/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/runtime/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EACV,UAAU,EAEV,YAAY,EACZ,WAAW,EACX,UAAU,EAEX,MAAM,oBAAoB,CAAC;AAa5B,OAAO,EACL,OAAO,EAOR,MAAM,uBAAuB,CAAC;AA2E/B,gEAAgE;AAGhE,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;kBAQjB,CAAC;AAEX,6DAA6D;AAC7D,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,IACjF,EAAE,GACF,CAAC,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,CAAC;AAoBrB;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA+F1D;AA6KD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,CAuBtE;AA4TD;;;;;;GAMG;AACH,wBAAgB,KAAK,CACnB,KAAK,CAAC,MAAM,SAAS,SAAS,UAAU,EAAE,EAC1C,KAAK,CAAC,MAAM,SAAS,MAAM,EAC3B,KAAK,CAAC,QAAQ,SAAS,OAAO,EAE9B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,QAAQ,GAChB,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAOjD;AAMD,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAG3B,MAAM,cAAc,CAAC;AAEtB,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,qBAAqB,CACpC,CAAC,SAAS,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC;IAE7D,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACjB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC,4BAA4B;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAC7B,KAAK,CAAC,MAAM,SAAS,SAAS,UAAU,EAAE,EAC1C,KAAK,CAAC,MAAM,SAAS,MAAM,EAC3B,KAAK,CAAC,QAAQ,SAAS,OAAO,EAC9B,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAG,qBAAqB,CA+BxE;AAsCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAmB9D"}