parseman 0.1.0

package/dist/combinators/recover.d.ts

@@ -0,0 +1,20 @@
+import type { Combinator, ParseError } from '../types.ts';
+export type { ParseError };
+/**
+ * Error-recovery combinator. Tries `parser`; on success returns normally.
+ * On failure, scans forward one character at a time until `sentinel` matches
+ * (or EOF), then returns a ParseError node spanning the skipped range.
+ * The sentinel is NOT consumed — the caller's grammar continues from there.
+ *
+ * Intended for IDE/incremental parsers that must produce a result even on
+ * broken input. The error path is not optimized; use only where recovery
+ * is genuinely needed, not on hot paths.
+ *
+ *   const stmt = choice(
+ *     ifStmt, whileStmt,
+ *     recover(exprStmt, literal(';'))
+ *   )
+ */
+export declare function recover<T>(parser: Combinator<T>, sentinel: Combinator<unknown>): Combinator<T | ParseError>;
+export declare function isParseError(value: unknown): value is ParseError;
+//# sourceMappingURL=recover.d.ts.map

package/dist/combinators/recover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recover.d.ts","sourceRoot":"","sources":["../../src/combinators/recover.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,UAAU,EAAE,MAAM,aAAa,CAAA;AAEhG,YAAY,EAAE,UAAU,EAAE,CAAA;AAE1B;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,EACrB,QAAQ,EAAE,UAAU,CAAC,OAAO,CAAC,GAC5B,UAAU,CAAC,CAAC,GAAG,UAAU,CAAC,CA4B5B;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE"}

package/dist/combinators/ref.d.ts

@@ -0,0 +1,18 @@
+import type { Combinator } from '../types.ts';
+/**
+ * Create a forward-declared parser slot for mutually recursive grammars.
+ *
+ * Because JS evaluates arguments eagerly, you can't reference a variable
+ * before it's declared. ref() creates a placeholder you fill in later:
+ *
+ *   const value = ref<JSONValue>()
+ *   const array  = transform(sequence(literal('['), sepBy(value, literal(',')), literal(']')), ...)
+ *   const object = transform(sequence(literal('{'), sepBy(pair, literal(',')), literal('}')), ...)
+ *   value.define(choice(object, array, string, number, bool, nullVal))
+ *
+ * Unlike lazy(() => x), you use the ref directly — no wrapping at each call site.
+ */
+export declare function ref<T>(): Combinator<T> & {
+    define(p: Combinator<T>): void;
+};
+//# sourceMappingURL=ref.d.ts.map

package/dist/combinators/ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../../src/combinators/ref.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,MAAM,aAAa,CAAA;AAGpF;;;;;;;;;;;;GAYG;AACH,wBAAgB,GAAG,CAAC,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG;IAAE,MAAM,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;CAAE,CA8B3E"}

package/dist/combinators/regex.d.ts

@@ -0,0 +1,3 @@
+import type { Combinator } from '../types.ts';
+export declare function regex(pattern: string | RegExp, flags?: string): Combinator<string>;
+//# sourceMappingURL=regex.d.ts.map

package/dist/combinators/regex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regex.d.ts","sourceRoot":"","sources":["../../src/combinators/regex.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAmD,MAAM,aAAa,CAAA;AA2H9F,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,SAAK,GAAG,UAAU,CAAC,MAAM,CAAC,CA2B9E"}

package/dist/combinators/repeat.d.ts

@@ -0,0 +1,6 @@
+import type { Combinator } from '../types.ts';
+export declare function many<T>(parser: Combinator<T>): Combinator<T[]>;
+export declare function oneOrMore<T>(parser: Combinator<T>): Combinator<T[]>;
+export declare function optional<T>(parser: Combinator<T>): Combinator<T | null>;
+export declare function sepBy<T, S>(parser: Combinator<T>, separator: Combinator<S>): Combinator<T[]>;
+//# sourceMappingURL=repeat.d.ts.map

package/dist/combinators/repeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repeat.d.ts","sourceRoot":"","sources":["../../src/combinators/repeat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,MAAM,aAAa,CAAA;AAEpF,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CAwB9D;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CA0BnE;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,CAiBvE;AAED,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CA+B5F"}

package/dist/combinators/scanTo.d.ts

@@ -0,0 +1,30 @@
+import type { Combinator } from '../types.ts';
+export type ScanToOptions = {
+    /** Parsers that match "container" regions to skip over intact (balanced parens, strings, comments…) */
+    skip?: Combinator<unknown>[];
+    /**
+     * If true, reaching EOF without finding the sentinel is a success — returns
+     * everything consumed so far. Default false (fail at EOF).
+     */
+    orEOF?: boolean;
+};
+/**
+ * Consume input up to (but not including) the sentinel, skipping over any
+ * "hole" patterns in order so their contents are never mistaken for the sentinel.
+ *
+ * Returns the consumed text as a string. The sentinel is NOT consumed.
+ * Fails if the sentinel is never found (unless orEOF is true).
+ *
+ *   const selector = scanTo(literal('{'), {
+ *     skip: [cssComment, stringLit, balanced('(', ')'), balanced('[', ']')],
+ *   })
+ */
+export declare function scanTo(sentinel: Combinator<unknown>, { skip, orEOF }?: ScanToOptions): Combinator<string>;
+/**
+ * Match a balanced open/close pair, skipping over any holes inside.
+ * Returns the full matched text including delimiters.
+ *
+ *   const parenGroup = balanced('(', ')', { skip: [comment, stringLit] })
+ */
+export declare function balanced(open: string, close: string, options?: ScanToOptions): Combinator<string>;
+//# sourceMappingURL=scanTo.d.ts.map

package/dist/combinators/scanTo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanTo.d.ts","sourceRoot":"","sources":["../../src/combinators/scanTo.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,MAAM,aAAa,CAAA;AAMpF,MAAM,MAAM,aAAa,GAAG;IAC1B,uGAAuG;IACvG,IAAI,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,CAAA;IAC5B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CACpB,QAAQ,EAAE,UAAU,CAAC,OAAO,CAAC,EAC7B,EAAE,IAAS,EAAE,KAAa,EAAE,GAAE,aAAkB,GAC/C,UAAU,CAAC,MAAM,CAAC,CA6CpB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,UAAU,CAAC,MAAM,CAAC,CAMpB"}

package/dist/combinators/sequence.d.ts

@@ -0,0 +1,7 @@
+import type { Combinator } from '../types.ts';
+type UnwrapParsers<T extends Combinator<unknown>[]> = {
+    [K in keyof T]: T[K] extends Combinator<infer U> ? U : never;
+};
+export declare function sequence<T extends [Combinator<unknown>, ...Combinator<unknown>[]]>(...parsers: T): Combinator<UnwrapParsers<T>>;
+export {};
+//# sourceMappingURL=sequence.d.ts.map

package/dist/combinators/sequence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence.d.ts","sourceRoot":"","sources":["../../src/combinators/sequence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAoD,MAAM,aAAa,CAAA;AAG/F,KAAK,aAAa,CAAC,CAAC,SAAS,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI;KACnD,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK;CAC7D,CAAA;AAED,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,GAAG,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,EAChF,GAAG,OAAO,EAAE,CAAC,GACZ,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAuC9B"}

package/dist/combinators/withCtx.d.ts

@@ -0,0 +1,13 @@
+import type { Combinator } from '../types.ts';
+/**
+ * Runs `parser` with `ctx.user` set to `extra` for the duration of the parse.
+ * The outer user context is restored on exit (lexical scoping).
+ *
+ *   const functionBody = withCtx({ inFn: true },
+ *     sequence(literal('{'), many(statement), literal('}'))
+ *   )
+ *
+ * Read back with guard() or from within a transform's span argument.
+ */
+export declare function withCtx<U, T>(extra: U, parser: Combinator<T>): Combinator<T>;
+//# sourceMappingURL=withCtx.d.ts.map

package/dist/combinators/withCtx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withCtx.d.ts","sourceRoot":"","sources":["../../src/combinators/withCtx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,MAAM,aAAa,CAAA;AAEpF;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAc5E"}

package/dist/compiler/codegen.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Compile a Combinator<T> definition tree into an optimized JavaScript function.
+ *
+ * Design: every sub-emitter uses early-return on failure. Fallible contexts
+ * (many loops, non-disjoint choice arms) wrap inner code in IIFEs so
+ * early-return keeps working uniformly throughout.
+ */
+import type { Combinator, ParseResult } from '../types.ts';
+export type CompiledParser<T> = {
+    parse(input: string, pos?: number): ParseResult<T>;
+    /** The generated source (for inspection / future source maps) */
+    source: string;
+    /**
+     * A self-contained JS expression (IIFE) that evaluates to a parse function.
+     * Safe to inline directly into transformed source — no external references
+     * except for runtime-fallback parsers embedded via closures.
+     * Returns null if the parser cannot be fully inlined (e.g. contains user
+     * closures that can't be serialized).
+     */
+    inlineExpression: string | null;
+};
+export declare function compile<T>(parser: Combinator<T>): CompiledParser<T>;
+//# sourceMappingURL=codegen.d.ts.map

package/dist/compiler/codegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/compiler/codegen.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,UAAU,EAAuB,WAAW,EAAgC,MAAM,aAAa,CAAA;AAowB7G,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;IAC9B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;IAClD,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;OAMG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;CAChC,CAAA;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CA0DnE"}

package/dist/compiler/line-index.d.ts

@@ -0,0 +1,16 @@
+import type { Span } from '../types.ts';
+/**
+ * Precomputed index of newline positions for O(log n) offset→line/col lookup.
+ * lineStarts[i] is the byte offset of the first character on line i+1.
+ */
+export type LineIndex = {
+    lineStarts: number[];
+};
+export declare function buildLineIndex(input: string): LineIndex;
+export declare function offsetToLineCol(index: LineIndex, offset: number): {
+    line: number;
+    col: number;
+};
+/** Fills startLine/startColumn/endLine/endColumn on a span in-place. */
+export declare function annotateSpan(span: Span, index: LineIndex): Span;
+//# sourceMappingURL=line-index.d.ts.map

package/dist/compiler/line-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"line-index.d.ts","sourceRoot":"","sources":["../../src/compiler/line-index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAEvC;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAEhD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAMvD;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,MAAM,GACb;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAU/B;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAU/D"}

package/dist/cst/grammar.d.ts

@@ -0,0 +1,84 @@
+import type { Combinator, Span } from '../types.ts';
+import type { CSTNode, CSTLeaf, CSTError, CSTRawChild, NodeLike } from './types.ts';
+import type { ParseDoc } from './incremental.ts';
+type Capital = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
+/** Keys of T whose names start with a capital letter (CST parser). */
+export type RuleKeys<T> = {
+    [K in keyof T & string]: K extends `${Capital}${string}` ? K : never;
+}[keyof T & string];
+/**
+ * Maps each grammar property to its resolved Combinator type.
+ *
+ * Use as the parameter type in rule thunks — gives `g.*` the correct
+ * Combinator type instead of the raw function type:
+ *
+ *   Expr = (g: Refs<this>) => choice(g.Atom, sequence(g.Expr, literal('+'), g.Atom))
+ */
+export type Refs<T> = {
+    [K in keyof T as K extends `_${string}` ? never : T[K] extends Combinator<any> ? K : T[K] extends (g: any) => Combinator<any> ? K : never]: T[K] extends Combinator<infer V> ? Combinator<V> : T[K] extends (g: any) => Combinator<infer V> ? Combinator<V> : never;
+};
+/**
+ * Base class for grammars that automatically produce a CST (or a custom AST
+ * if you override `buildNode`).
+ *
+ * Rules are declared as class properties:
+ *   - Plain Combinator  (no cross-references needed):
+ *       digits = regex(/[0-9]+/)
+ *   - Thunk  (references other parser via `g`):
+ *       Expr = (g: Refs<this>) => choice(g.Atom, sequence(g.Expr, literal('+')))
+ *
+ * Convention:
+ *   Capital letter → CSTNode-producing rule (span + savedContext + children)
+ *   lowercase      → transparent helper (terminals bubble up as CSTLeaf in the
+ *                    nearest enclosing capital rule)
+ *
+ * Mutual recursion works because thunks are collected first, ref() placeholders
+ * installed for each one, then all thunks are called with `g` (a map of refs).
+ * Initialization is lazy — triggered on the first call to rule().
+ *
+ * Grammar inheritance: subclass property initializers naturally override parent
+ * ones (they run last in construction order), so extending a grammar means only
+ * re-declaring the parser you want to change.
+ *
+ *   class JSONCParser extends JSONParser {
+ *     ws = jsoncWs  // override just this one rule
+ *   }
+ */
+export declare class Parser<N extends NodeLike = CSTNode> {
+    private _built;
+    private _build;
+    /**
+     * Override to produce a custom AST node instead of a plain CSTNode.
+     * The returned object must satisfy NodeLike for IncrementalParser to work.
+     *
+     * `rawChildren` is `children` plus any trivia tokens (whitespace/comments)
+     * consumed between terms, in parse order. Use it to inspect trivia when the
+     * grammar is whitespace-sensitive (e.g. CSS descendant vs adjacent combinators).
+     * The default implementation ignores `rawChildren`.
+     */
+    protected buildNode(type: string, span: Span, children: ReadonlyArray<N | CSTLeaf | CSTError>, savedContext: unknown, _rawChildren: ReadonlyArray<CSTRawChild>): N;
+    /** Wrap an inner combinator so it produces a CSTNode on each match. */
+    private _makeNodeParser;
+    /** Reconstruct a node with a new children array (used by IncrementalParser). */
+    rebuild(node: N, newChildren: ReadonlyArray<N | CSTLeaf | CSTError>): N;
+    /**
+     * Parse input starting from a named rule, returning a ParseDoc.
+     * The doc carries the tree, any parse errors, and an edit() method
+     * for incremental re-parsing on subsequent changes.
+     *
+     *   const doc = css.parse('Stylesheet', src)
+     *   doc.tree    // the CST root, or null on failure
+     *   doc.errors  // ParseFail[], empty on success
+     *
+     *   // In an editor — just keep calling edit():
+     *   const doc2 = doc.edit(newSrc, changeStart, changeEnd)
+     */
+    parse(ruleName: RuleKeys<this>, input: string): ParseDoc<N>;
+    /**
+     * Get the compiled Combinator for a named rule.
+     * Triggers lazy initialization on first call.
+     */
+    rule(name: RuleKeys<this>): Combinator<N>;
+}
+export {};
+//# sourceMappingURL=grammar.d.ts.map

package/dist/cst/grammar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../../src/cst/grammar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,IAAI,EAAE,MAAM,aAAa,CAAA;AAE1F,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAa,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE9F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAMhD,KAAK,OAAO,GAAG,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GACvD,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,CAAA;AAE9D,sEAAsE;AACtE,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KACvB,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,SAAS,GAAG,OAAO,GAAG,MAAM,EAAE,GAAG,CAAC,GAAG,KAAK;CACrE,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAA;AAEnB;;;;;;;GAOG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI;KACnB,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,IAAI,MAAM,EAAE,GAAG,KAAK,GAC3C,CAAC,CAAC,CAAC,CAAC,SAAS,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,GAChC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,KAAK,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,GAC5C,KAAK,GACN,CAAC,CAAC,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GAChD,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,KAAK,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GAC5D,KAAK;CACT,CAAA;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,MAAM,CAAC,CAAC,SAAS,QAAQ,GAAG,OAAO;IAC9C,OAAO,CAAC,MAAM,CAAQ;IAEtB,OAAO,CAAC,MAAM;IA2Cd;;;;;;;;OAQG;IACH,SAAS,CAAC,SAAS,CACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,aAAa,CAAC,CAAC,GAAG,OAAO,GAAG,QAAQ,CAAC,EAC/C,YAAY,EAAE,OAAO,EACrB,YAAY,EAAE,aAAa,CAAC,WAAW,CAAC,GACvC,CAAC,CAEH;IAED,uEAAuE;IACvE,OAAO,CAAC,eAAe;IAoCvB,gFAAgF;IAChF,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC,GAAG,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,CAEtE;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAE1D;IAED;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAKxC;CACF"}

package/dist/cst/incremental.d.ts

@@ -0,0 +1,34 @@
+import type { ParseFail } from '../types.ts';
+import type { Parser } from './grammar.ts';
+import type { NodeLike } from './types.ts';
+/**
+ * The result of Parser.parse() — holds the current tree and supports
+ * incremental re-parsing via edit().
+ *
+ *   const doc = css.parse('Stylesheet', src)
+ *   doc.tree    // CSTNode (or your N), null if parse failed
+ *   doc.errors  // ParseFail[], empty on success
+ *   doc.input   // the source string that produced this tree
+ *
+ *   const doc2 = doc.edit(newSrc, changeStart, changeEnd)
+ */
+export interface ParseDoc<N extends NodeLike = NodeLike> {
+    readonly tree: N | null;
+    readonly errors: ParseFail[];
+    readonly input: string;
+    /**
+     * Incrementally re-parse after a text change.
+     *
+     * @param changeStart  Byte offset where the change begins (same in old and new text).
+     * @param oldChangeEnd Byte offset where the replaced region ends in the OLD text (exclusive).
+     * @param newText      The replacement text (may be empty for a pure deletion).
+     *
+     * Maps directly to editor change events:
+     *   VSCode:     doc.edit(change.rangeOffset, change.rangeOffset + change.rangeLength, change.text)
+     *   CodeMirror: doc.edit(change.from, change.to, change.insert)
+     *   LSP:        doc.edit(startByte, endByte, change.text)  // after line/col → byte conversion
+     */
+    edit(changeStart: number, oldChangeEnd: number, newText: string): ParseDoc<N>;
+}
+export declare function makeParseDoc<N extends NodeLike>(parser: Parser<N>, ruleName: string, input: string): ParseDoc<N>;
+//# sourceMappingURL=incremental.d.ts.map

package/dist/cst/incremental.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"incremental.d.ts","sourceRoot":"","sources":["../../src/cst/incremental.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,SAAS,EAAE,MAAM,aAAa,CAAA;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAY,MAAM,cAAc,CAAA;AACpD,OAAO,KAAK,EAAqB,QAAQ,EAAE,MAAM,YAAY,CAAA;AAM7D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ;IACrD,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,CAAA;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;CAC9E;AA+GD,wBAAgB,YAAY,CAAC,CAAC,SAAS,QAAQ,EAC7C,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,QAAQ,CAAC,CAAC,CAAC,CAOb"}

package/dist/cst/types.d.ts

@@ -0,0 +1,74 @@
+import type { Span } from '../types.ts';
+/**
+ * Minimal interface a node must satisfy for IncrementalParser to navigate and
+ * re-parse the tree. Satisfying this is all that's required for a custom AST
+ * produced by overriding GrammarParser.buildNode().
+ *
+ * `children` only needs to be iterable with items that have `_tag` so the
+ * traversal code can distinguish sub-nodes from leaves. For incremental
+ * replacement, nodes are reconstructed via object spread — so plain objects
+ * work naturally; class instances with non-enumerable properties do not.
+ */
+export type NodeLike = {
+    readonly _tag: 'node';
+    readonly type: string;
+    readonly span: Span;
+    readonly savedContext: unknown;
+    readonly children: ReadonlyArray<{
+        readonly _tag: string;
+    }>;
+};
+/**
+ * A named CST node produced by a capital-letter rule method in GrammarParser.
+ * Children are in parse order: CSTNode children from named sub-parser interspersed
+ * with CSTLeaf terminals from literal() / regex() calls inside lowercase helpers.
+ */
+export type CSTNode = {
+    readonly _tag: 'node';
+    /** Rule name — the method name that produced this node. */
+    readonly type: string;
+    readonly span: Span;
+    readonly children: CSTChild[];
+    /**
+     * Shallow clone of ctx.user at the moment this node's parse began.
+     * Used as the re-entry point for incremental re-parsing.
+     * Only meaningful when ctx.user is primitives-only (no mutable objects).
+     */
+    readonly savedContext: unknown;
+};
+/**
+ * A terminal token — the result of a literal() or regex() match inside a CST rule.
+ * Lowercase helpers are transparent: their terminals surface as leaves of the
+ * nearest enclosing capital-letter rule.
+ */
+export type CSTLeaf = {
+    readonly _tag: 'leaf';
+    readonly value: string;
+    readonly span: Span;
+};
+/**
+ * A record of a failed rule parse — produced when error recovery is active.
+ * Carries what was successfully parsed before the failure (partial children)
+ * and the expected tokens at the failure point.
+ */
+export type CSTError = {
+    readonly _tag: 'error';
+    readonly type: string;
+    readonly span: Span;
+    readonly expected: string[];
+    readonly children: CSTChild[];
+    readonly savedContext: unknown;
+};
+export type CSTChild = CSTNode | CSTLeaf | CSTError;
+/**
+ * A trivia token — whitespace or comment consumed between terms during parsing.
+ * Only present in `rawChildren`; never in the structural `children` array.
+ */
+export type CSTTrivia = {
+    readonly _tag: 'trivia';
+    readonly value: string;
+    readonly span: Span;
+};
+/** Full child union including trivia — used in the `rawChildren` arg of `buildNode`. */
+export type CSTRawChild = CSTNode | CSTLeaf | CSTTrivia | CSTError;
+//# sourceMappingURL=types.d.ts.map

package/dist/cst/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cst/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAEvC;;;;;;;;;GASG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC5D,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,CAAA;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;CAC/B,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;CACpB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,CAAA;IAC7B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;CAC/B,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEnD;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;CACpB,CAAA;AAED,wFAAwF;AACxF,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAA"}