stringent 0.0.1 → 0.0.2

package/dist/parse/index.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Parse Type - Type-Level Parsing with Grammar Support
+ *
+ * Parse<Grammar, Input, Context> computes the exact result type of parsing
+ * an input string against a grammar.
+ *
+ * The grammar is a flat tuple of precedence levels:
+ *   [[Level0Ops], [Level1Ops], ..., [Atoms]]
+ *
+ * Parsing proceeds:
+ * 1. Try operators at current level (index 0, lowest precedence)
+ * 2. Fall back to next level (index 1, higher precedence)
+ * 3. Continue until atoms (last element)
+ */
+import type { Token } from "@sinclair/parsebox";
+import type { Context } from "../context.js";
+import type { Grammar } from "../grammar/index.js";
+import type { NodeSchema, PatternSchema, PatternSchemaBase, NamedSchema, NumberSchema, StringSchema, IdentSchema, ConstSchema, ExprSchema } from "../schema/index.js";
+import type { NumberNode, StringNode, IdentNode, ConstNode } from "../primitive/index.js";
+/** Base parse error */
+export interface ParseError<TMessage extends string = string> {
+    readonly __error: true;
+    readonly message: TMessage;
+}
+/** Type mismatch error (expression has wrong type) */
+export type TypeMismatchError<TExpected extends string, TActual extends string> = ParseError<`Type mismatch: expected ${TExpected}, got ${TActual}`>;
+/** No match error (no grammar rule matched) */
+export type NoMatchError = ParseError<"No grammar rule matched">;
+/** Binary operator node */
+export interface BinaryNode<TName extends string = string, TLeft = unknown, TRight = unknown, TOutputSchema extends string = string> {
+    readonly node: TName;
+    readonly outputSchema: TOutputSchema;
+    readonly left: TLeft;
+    readonly right: TRight;
+}
+type ParseNumberPrimitive<TInput extends string> = Token.TNumber<TInput> extends [infer V extends string, infer R extends string] ? [NumberNode<V>, R] : [];
+type ParseStringPrimitive<TQuotes extends readonly string[], TInput extends string> = Token.TString<[...TQuotes], TInput> extends [
+    infer V extends string,
+    infer R extends string
+] ? [StringNode<V>, R] : [];
+type ParseIdentPrimitive<TInput extends string, TContext extends Context> = Token.TIdent<TInput> extends [
+    infer V extends string,
+    infer R extends string
+] ? V extends keyof TContext["data"] ? [IdentNode<V, TContext["data"][V] & string>, R] : [IdentNode<V, "unknown">, R] : [];
+type ParseConstPrimitive<TValue extends string, TInput extends string> = Token.TConst<TValue, TInput> extends [
+    infer _V extends string,
+    infer R extends string
+] ? [ConstNode<TValue>, R] : [];
+/**
+ * Parse a single pattern element (non-Expr).
+ * Works with both plain schemas and NamedSchema (intersection type).
+ */
+type ParseElement<TElement extends PatternSchema, TInput extends string, TContext extends Context> = TElement extends NumberSchema ? ParseNumberPrimitive<TInput> : TElement extends StringSchema<infer Q> ? ParseStringPrimitive<Q, TInput> : TElement extends IdentSchema ? ParseIdentPrimitive<TInput, TContext> : TElement extends ConstSchema<infer V> ? ParseConstPrimitive<V, TInput> : never;
+/**
+ * Parse a tuple of pattern elements.
+ *
+ * TCurrentLevels - grammar from current level onward (for rhs)
+ * TNextLevels - grammar from next level onward (for lhs, avoids left-recursion)
+ * TFullGrammar - complete grammar (for expr role, full reset)
+ */
+type ParsePatternTuple<TPattern extends readonly PatternSchema[], TInput extends string, TContext extends Context, TCurrentLevels extends Grammar, TNextLevels extends Grammar, TFullGrammar extends Grammar, TAcc extends unknown[] = []> = TPattern extends readonly [
+    infer First extends PatternSchema,
+    ...infer Rest extends readonly PatternSchema[]
+] ? ParseElementWithLevel<First, TInput, TContext, TCurrentLevels, TNextLevels, TFullGrammar> extends [infer R, infer Remaining extends string] ? ParsePatternTuple<Rest, Remaining, TContext, TCurrentLevels, TNextLevels, TFullGrammar, [
+    ...TAcc,
+    R
+]> : [] : [TAcc, TInput];
+/**
+ * Parse an expression element based on its role.
+ * Works with both plain schemas and NamedSchema (intersection type).
+ *
+ * Role determines which grammar slice is used:
+ * - "lhs": TNextLevels (avoids left-recursion)
+ * - "rhs": TCurrentLevels (maintains precedence, enables right-associativity)
+ * - "expr": TFullGrammar (full reset for delimited contexts)
+ */
+type ParseElementWithLevel<TElement extends PatternSchema, TInput extends string, TContext extends Context, TCurrentLevels extends Grammar, TNextLevels extends Grammar, TFullGrammar extends Grammar> = TElement extends ExprSchema<infer C, infer Role> ? Role extends "lhs" ? ParseExprWithConstraint<TNextLevels, TInput, TContext, C, TFullGrammar> : Role extends "rhs" ? ParseExprWithConstraint<TCurrentLevels, TInput, TContext, C, TFullGrammar> : ParseExprWithConstraint<TFullGrammar, TInput, TContext, C, TFullGrammar> : ParseElement<TElement, TInput, TContext>;
+/**
+ * Parse a node's pattern and build the result node.
+ */
+type ParseNodePattern<TNode extends NodeSchema, TInput extends string, TContext extends Context, TCurrentLevels extends Grammar, TNextLevels extends Grammar, TFullGrammar extends Grammar> = ParsePatternTuple<TNode["pattern"], TInput, TContext, TCurrentLevels, TNextLevels, TFullGrammar> extends [infer Children extends unknown[], infer Rest extends string] ? [BuildNodeResult<TNode, Children>, Rest] : [];
+type ExtractBindings<TPattern extends readonly PatternSchema[], TChildren extends unknown[], TAcc extends {} = {}> = TPattern extends readonly [
+    infer First extends PatternSchema,
+    ...infer RestPattern extends readonly PatternSchema[]
+] ? TChildren extends [infer Child, ...infer RestChildren] ? First extends NamedSchema<PatternSchemaBase, infer Name> ? ExtractBindings<RestPattern, RestChildren, {
+    [P in keyof TAcc | Name]: P extends Name ? Child : P extends keyof TAcc ? TAcc[P] : never;
+}> : ExtractBindings<RestPattern, RestChildren, TAcc> : TAcc : TAcc;
+/**
+ * Build the result node from parsed children.
+ *
+ * Uses named bindings from .as() to determine node fields.
+ * - Single unnamed child: passthrough (atom behavior)
+ * - Otherwise: bindings become node fields
+ */
+type BuildNodeResult<TNode extends NodeSchema, TChildren extends unknown[]> = ExtractBindings<TNode["pattern"], TChildren> extends infer Bindings ? keyof Bindings extends never ? TChildren extends [infer Only] ? Only : never : {
+    readonly node: TNode["name"];
+    readonly outputSchema: TNode["resultType"];
+} & Bindings : never;
+/**
+ * Parse an expression with optional type constraint.
+ */
+type ParseExprWithConstraint<TStartLevels extends Grammar, TInput extends string, TContext extends Context, TConstraint extends string | undefined, TFullGrammar extends Grammar> = ParseLevels<TStartLevels, TInput, TContext, TFullGrammar> extends [
+    infer Node extends {
+        outputSchema: string;
+    },
+    infer Rest extends string
+] ? TConstraint extends string ? Node["outputSchema"] extends TConstraint ? [Node, Rest] : [] : [Node, Rest] : [];
+/**
+ * Try parsing each node in a level.
+ */
+type ParseNodes<TNodes extends readonly NodeSchema[], TInput extends string, TContext extends Context, TCurrentLevels extends Grammar, TNextLevels extends Grammar, TFullGrammar extends Grammar> = TNodes extends readonly [
+    infer First extends NodeSchema,
+    ...infer Rest extends readonly NodeSchema[]
+] ? ParseNodePattern<First, TInput, TContext, TCurrentLevels, TNextLevels, TFullGrammar> extends [infer R, infer Remaining extends string] ? [R, Remaining] : ParseNodes<Rest, TInput, TContext, TCurrentLevels, TNextLevels, TFullGrammar> : [];
+/**
+ * Parse using grammar levels (flat tuple).
+ *
+ * TLevels is the remaining levels to try, starting from current.
+ * - Try nodes at first level (TLevels[0])
+ * - If no match, fall back to rest of levels
+ * - Base case: single level (atoms) - just try those nodes
+ */
+type ParseLevels<TLevels extends Grammar, TInput extends string, TContext extends Context, TFullGrammar extends Grammar> = TLevels extends readonly [
+    infer CurrentNodes extends readonly NodeSchema[],
+    ...infer NextNodes extends Grammar
+] ? ParseNodes<CurrentNodes, TInput, TContext, TLevels, NextNodes, TFullGrammar> extends [infer R, infer Remaining extends string] ? [R, Remaining] : ParseLevels<NextNodes, TInput, TContext, TFullGrammar> : TLevels extends readonly [infer LastNodes extends readonly NodeSchema[]] ? ParseNodes<LastNodes, TInput, TContext, TLevels, TLevels, TFullGrammar> : [];
+/**
+ * Parse<Grammar, Input, Context>
+ *
+ * Main entry point for type-level parsing.
+ *
+ * @example
+ * type Result = Parse<MyGrammar, "1+2", Context>;
+ * // [BinaryNode<"add", NumberNode<"1">, NumberNode<"2">, "number">, ""]
+ */
+export type Parse<TGrammar extends Grammar, TInput extends string, TContext extends Context> = ParseLevels<TGrammar, TInput, TContext, TGrammar>;
+export {};

package/dist/parse/index.js

@@ -0,0 +1,15 @@
+/**
+ * Parse Type - Type-Level Parsing with Grammar Support
+ *
+ * Parse<Grammar, Input, Context> computes the exact result type of parsing
+ * an input string against a grammar.
+ *
+ * The grammar is a flat tuple of precedence levels:
+ *   [[Level0Ops], [Level1Ops], ..., [Atoms]]
+ *
+ * Parsing proceeds:
+ * 1. Try operators at current level (index 0, lowest precedence)
+ * 2. Fall back to next level (index 1, higher precedence)
+ * 3. Continue until atoms (last element)
+ */
+export {};

package/dist/primitive/index.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Primitive Factory System
+ *
+ * Creates context-aware parser primitives using Parsebox Token API.
+ * Parse methods are generic - return types computed from input literals.
+ *
+ * IMPORTANT: All parse methods MUST be generic in context:
+ *   parse<TInput extends string, $ extends Context>(input: TInput, $: $)
+ *
+ * DO NOT remove the $ generic parameter - it ensures schema type information
+ * flows through the parser chain. See CLAUDE.md for details.
+ */
+import { Token } from "@sinclair/parsebox";
+import type { Context } from "../context.js";
+import type { ToNumber } from "hotscript/dist/internals/numbers/impl/utils.js";
+export type { Context } from "../context.js";
+/** Parse result: empty = no match, [value, rest] = matched */
+export type ParseResult<T, R extends string = string> = [] | [T, R];
+export interface ASTNode<TType extends string = string, TOutputSchema = unknown> {
+    node: TType;
+    outputSchema: TOutputSchema;
+}
+export interface IdentNode<TName extends string = string, TOutputSchema = "unknown"> extends ASTNode<"identifier", TOutputSchema> {
+    name: TName;
+}
+export type NumberNode<TValue extends string = string> = ASTNode<"literal", "number"> & {
+    raw: TValue;
+    value: ToNumber<TValue>;
+};
+export type StringNode<TValue extends string = string> = ASTNode<"literal", "string"> & {
+    raw: TValue;
+    value: TValue;
+};
+export type NullNode = ASTNode<"literal", "null"> & {
+    raw: "null";
+    value: null;
+};
+export type UndefinedNode = ASTNode<"literal", "undefined"> & {
+    raw: "undefined";
+    value: undefined;
+};
+export type BooleanNode<TValue extends string = string> = ASTNode<"boolean", TValue> & {
+    raw: TValue;
+    value: TValue extends "true" ? true : false;
+};
+export type LiteralNode = NumberNode | StringNode | NullNode | UndefinedNode | BooleanNode;
+export type ConstNode<TValue extends string = string> = ASTNode<"const", TValue>;
+/** Computed parse result for Number */
+export type ParseNumber<TInput extends string> = Token.TNumber<TInput> extends [
+    infer V extends string,
+    infer R extends string
+] ? [NumberNode<V>, R] : [];
+/** Computed parse result for String */
+export type ParseString<TQuotes extends string[], TInput extends string> = Token.TString<TQuotes, TInput> extends [
+    infer V extends string,
+    infer R extends string
+] ? [StringNode<V>, R] : [];
+/** Computed parse result for Ident - looks up value type from schema */
+export type ParseIdent<TInput extends string, $ extends Context> = Token.TIdent<TInput> extends [
+    infer V extends string,
+    infer R extends string
+] ? V extends keyof $["data"] ? [IdentNode<V, $["data"][V]>, R] : [IdentNode<V>, R] : [];
+/** Computed parse result for Const */
+export type ParseConst<TValue extends string, TInput extends string> = Token.TConst<TValue, TInput> extends [
+    infer _V extends string,
+    infer R extends string
+] ? [ConstNode<TValue>, R] : [];
+/**
+ * Base parser interface. All parsers implement this.
+ * Context is generic to preserve type information.
+ */
+export interface IParser {
+    parse<TInput extends string, $ extends Context>(input: TInput, $: $): [] | [unknown, string];
+}
+/** Number primitive - parses numeric literals using Token.Number */
+declare class _Number {
+    readonly __primitive: "number";
+    parse<TInput extends string, $ extends Context>(input: TInput, _$: $): ParseNumber<TInput>;
+}
+/** String primitive - parses quoted string literals using Token.String */
+declare class _String<TQuotes extends string[]> {
+    readonly __primitive: "string";
+    readonly quotes: TQuotes;
+    constructor(quotes: TQuotes);
+    parse<TInput extends string, $ extends Context>(input: TInput, _$: $): ParseString<TQuotes, TInput>;
+}
+/** Identifier primitive - parses identifiers using Token.Ident */
+declare class _Ident {
+    readonly __primitive: "ident";
+    parse<TInput extends string, $ extends Context>(input: TInput, $: $): ParseIdent<TInput, $>;
+}
+/** Const primitive - parses exact string matches using Token.Const */
+declare class _Const<TValue extends string> {
+    readonly __primitive: "const";
+    readonly value: TValue;
+    constructor(value: TValue);
+    parse<TInput extends string, $ extends Context>(input: TInput, _$: $): ParseConst<TValue, TInput>;
+}
+export declare const Number: () => _Number;
+export declare const String: <TQuotes extends string[]>(quotes: [...TQuotes]) => _String<TQuotes>;
+export declare const Ident: () => _Ident;
+export declare const Const: <TValue extends string>(value: TValue) => _Const<TValue>;
+export type { _Number, _String, _Ident, _Const };
+export { type IParser as Primitive };

package/dist/primitive/index.js

@@ -0,0 +1,97 @@
+/**
+ * Primitive Factory System
+ *
+ * Creates context-aware parser primitives using Parsebox Token API.
+ * Parse methods are generic - return types computed from input literals.
+ *
+ * IMPORTANT: All parse methods MUST be generic in context:
+ *   parse<TInput extends string, $ extends Context>(input: TInput, $: $)
+ *
+ * DO NOT remove the $ generic parameter - it ensures schema type information
+ * flows through the parser chain. See CLAUDE.md for details.
+ */
+import { Token } from "@sinclair/parsebox";
+// =============================================================================
+// Primitive Implementations
+// =============================================================================
+/** Number primitive - parses numeric literals using Token.Number */
+class _Number {
+    __primitive = "number";
+    parse(input, _$) {
+        // Runtime type is [] | [string, string], but TypeScript computes exact type
+        const result = Token.Number(input);
+        if (result.length !== 2)
+            return [];
+        return [
+            {
+                node: "literal",
+                raw: result[0],
+                value: +result[0],
+                outputSchema: "number",
+            },
+            result[1],
+        ];
+    }
+}
+/** String primitive - parses quoted string literals using Token.String */
+class _String {
+    __primitive = "string";
+    quotes;
+    constructor(quotes) {
+        this.quotes = quotes;
+    }
+    parse(input, _$) {
+        const result = Token.String(this.quotes, input);
+        if (result.length !== 2)
+            return [];
+        return [
+            {
+                node: "literal",
+                raw: result[0],
+                value: result[0],
+                outputSchema: "string",
+            },
+            result[1],
+        ];
+    }
+}
+/** Identifier primitive - parses identifiers using Token.Ident */
+class _Ident {
+    __primitive = "ident";
+    parse(input, $) {
+        const result = Token.Ident(input);
+        if (result.length !== 2)
+            return [];
+        const name = result[0];
+        const data = $.data;
+        const valueType = name in data ? data[name] : "unknown";
+        return [
+            { node: "identifier", name, outputSchema: valueType },
+            result[1],
+        ];
+    }
+}
+/** Const primitive - parses exact string matches using Token.Const */
+class _Const {
+    __primitive = "const";
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+    parse(input, _$) {
+        const result = Token.Const(this.value, input);
+        if (result.length !== 2)
+            return [];
+        return [
+            { node: "const", outputSchema: JSON.stringify(this.value) },
+            result[1],
+        ];
+    }
+}
+// =============================================================================
+// Exported Factories
+// =============================================================================
+export const Number = () => new _Number();
+export const String = (quotes) => new _String(quotes);
+export const Ident = () => new _Ident();
+export const Const = (value) => new _Const(value);

package/dist/runtime/infer.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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;

package/dist/runtime/infer.js

@@ -0,0 +1,34 @@
+/**
+ * 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)}`);
+}

package/dist/runtime/parser.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 } from "../schema/index.js";
+import { ASTNode } from "../primitive/index.js";
+/** Parse result: empty = no match, [node, rest] = matched */
+export type ParseResult<T extends ASTNode<any, any> = ASTNode<any, any>> = [] | [T & {}, string];
+/**
+ * Build runtime grammar from node schemas.
+ *
+ * Returns a flat tuple of levels:
+ *   [[ops@prec1], [ops@prec2], ..., [atoms]]
+ *
+ * Levels are sorted by precedence ascending (lowest first).
+ * Atoms are always the last level.
+ */
+export declare function buildGrammar(nodes: 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>;