@sanbus/galley-core 0.0.1

package/dist/port.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Neutral FFI port: the single seam between the runtime-neutral core
+ * (`session.ts`, `node.ts`, `procedures.ts`) and each runtime adapter
+ * (Node/koffi, Bun/`bun:ffi`, Deno/`Deno.dlopen`).
+ *
+ * The port mirrors `bindings/c/galley.h`, but with structured returns
+ * instead of C out-parameters: adapters own all memory copying (bytes are
+ * already-copied `Uint8Array`s here, valid after the next parse) and all
+ * integer normalization (addresses are `bigint`, counts and statuses are
+ * `number`). Opaque native pointers (sessions, walkers, procedure args)
+ * cross the seam as `Handle` and are never inspected by the core.
+ */
+export type Handle = unknown;
+/** `GalleyCOptions` fields as plain data; null selects library defaults. */
+export interface SessionCOptions {
+    maxErrors: number;
+    recoveryWindow: number;
+    stackOverflowRecovery: number;
+    syntaxErrorStackDepth: number;
+    verbosity: number;
+    astPreallocationRatio: number;
+    astPreallocationCap: bigint;
+}
+/** One pre-order walker step. */
+export interface WalkedStep {
+    node: bigint;
+    depth: number;
+    isSemanticError: boolean;
+}
+/**
+ * Flat bulk read of the most recent successful parse, one slot per node
+ * address. `parent` holds `INVALID_NODE` for the root, `firstChild`/`next`
+ * hold `INVALID_NODE` where the link does not exist, `variable` holds -1
+ * for nodes without a variable, and `spanStart`/`spanLen` are byte
+ * offsets into the parsed input. Parent, firstChild, and next alone
+ * describe the whole tree with no further calls.
+ */
+export interface TreeSnapshot {
+    count: number;
+    parent: BigUint64Array;
+    firstChild: BigUint64Array;
+    next: BigUint64Array;
+    childCount: Uint32Array;
+    variable: BigInt64Array;
+    spanStart: BigUint64Array;
+    spanLen: BigUint64Array;
+}
+/** Native dispatch callback installed by the adapter; receives a decoded hook name. */
+export type DispatchHandler = (name: string, args: Handle) => void;
+export interface FfiPort {
+    version(): string;
+    parserType(): number;
+    errorRecoveryMode(): number;
+    hasAst(): boolean;
+    hasProcedures(): boolean;
+    allowsNoAstTreeProcedures(): boolean;
+    sourceRetentionEnabled(): boolean;
+    hasPositionTracking(): boolean;
+    hasInputStreaming(): boolean;
+    usesVerbatim(): boolean;
+    stackOverflowRecoveryAvailable(): boolean;
+    symbolCount(): number;
+    variableCount(): number;
+    statusString(status: number): string | null;
+    /** Null handle on initialization failure (most commonly allocation failure). */
+    createSession(options: SessionCOptions | null): Handle;
+    destroySession(handle: Handle): void;
+    /** Negative status on failure. */
+    setMessageOverride(handle: Handle, name: Uint8Array, message: Uint8Array): number;
+    /** Bytes parsed, or a negative status code. */
+    parse(handle: Handle, data: Uint8Array): number;
+    /** Bytes parsed, or a negative status code. */
+    parseFile(handle: Handle, path: string): number;
+    /** End position of the most recent successful parse; null on failure. */
+    lastPosition(handle: Handle): [number, number] | null;
+    nodeCount(handle: Handle): number;
+    /** Negative status on failure (e.g. capacity exceeded). */
+    reserveNodes(handle: Handle, capacity: bigint): number;
+    nodeCapacity(handle: Handle): number;
+    rootNode(handle: Handle): bigint;
+    nodeValid(handle: Handle, node: bigint): boolean;
+    childCount(handle: Handle, node: bigint): number;
+    firstChild(handle: Handle, node: bigint): bigint;
+    lastChild(handle: Handle, node: bigint): bigint;
+    nextSibling(handle: Handle, node: bigint): bigint;
+    priorSibling(handle: Handle, node: bigint): bigint;
+    parent(handle: Handle, node: bigint): bigint;
+    /** Flat bulk read of the most recent successful parse (see `TreeSnapshot`). */
+    treeSnapshot(handle: Handle): TreeSnapshot;
+    /** Null without AST construction or on invalid arguments. */
+    walkerCreate(handle: Handle, node: bigint, skipSemanticErrors: boolean): Handle | null;
+    /** Null when the walk is done. */
+    walkerNext(walker: Handle): WalkedStep | null;
+    walkerSkipChildren(walker: Handle): void;
+    walkerDestroy(walker: Handle): void;
+    nodeSymbolName(handle: Handle, node: bigint): Uint8Array | null;
+    nodeText(handle: Handle, node: bigint): Uint8Array | null;
+    nodeSpan(handle: Handle, node: bigint): [bigint, bigint] | null;
+    nodeLineColumn(handle: Handle, node: bigint): [number, number] | null;
+    /** Raw variable index; -1 when the node has no variable. */
+    nodeVariableIndex(handle: Handle, node: bigint): number;
+    symbolNameAt(handle: Handle, index: number): Uint8Array | null;
+    symbolIsTerminal(handle: Handle, index: number): boolean;
+    variableNameAt(handle: Handle, index: number): Uint8Array | null;
+    hasDiagnostic(handle: Handle): boolean;
+    diagnosticKind(handle: Handle): number;
+    diagnosticMessage(handle: Handle): string | null;
+    diagnosticMessageAnsi(handle: Handle): string | null;
+    diagnosticPosition(handle: Handle): [number, number] | null;
+    diagnosticUnexpectedToken(handle: Handle): Uint8Array | null;
+    diagnosticExpectedCount(handle: Handle): number;
+    diagnosticExpectedAt(handle: Handle, index: number): Uint8Array | null;
+    diagnosticContextCount(handle: Handle): number;
+    diagnosticContextAt(handle: Handle, index: number): Uint8Array | null;
+    syntaxErrorCount(handle: Handle): number;
+    semanticErrorCount(handle: Handle): number;
+    /** (variable, message); null when there is no semantic diagnostic. */
+    diagnosticSemantic(handle: Handle): [string, string] | null;
+    /** (spaces, width); null when not an indentation diagnostic. */
+    diagnosticIndentation(handle: Handle): [number, number] | null;
+    diagnosticRecoveryKind(handle: Handle): number;
+    diagnosticRecoveryTerminal(handle: Handle): Uint8Array | null;
+    diagnosticRecoveryResume(handle: Handle): number | null;
+    diagnosticRecoveryLhsVariable(handle: Handle): string | null;
+    diagnosticRecoveryProduction(handle: Handle): [string, number] | null;
+    diagnosticRecoveryOccurrence(handle: Handle): [string, number, number, string] | null;
+    recordedDiagnosticCount(handle: Handle): number;
+    recordedDiagnosticKind(handle: Handle, diagIndex: number): number;
+    recordedDiagnosticPosition(handle: Handle, diagIndex: number): [number, number] | null;
+    recordedUnexpectedToken(handle: Handle, diagIndex: number): Uint8Array | null;
+    recordedDiagnosticMessage(handle: Handle, diagIndex: number): string | null;
+    recordedIndentation(handle: Handle, diagIndex: number): [number, number] | null;
+    recordedSemantic(handle: Handle, diagIndex: number): [string, string] | null;
+    recordedExpectedCount(handle: Handle, diagIndex: number): number;
+    recordedExpectedToken(handle: Handle, diagIndex: number, tokenIndex: number): Uint8Array | null;
+    recordedContextCount(handle: Handle, diagIndex: number): number;
+    recordedContextName(handle: Handle, diagIndex: number, contextIndex: number): Uint8Array | null;
+    recordedRecoveryKind(handle: Handle, diagIndex: number): number;
+    recordedRecoveryTerminal(handle: Handle, diagIndex: number): Uint8Array | null;
+    recordedRecoveryResume(handle: Handle, diagIndex: number): number | null;
+    recordedRecoveryLhsVariable(handle: Handle, diagIndex: number): string | null;
+    recordedRecoveryProduction(handle: Handle, diagIndex: number): [string, number] | null;
+    recordedRecoveryOccurrence(handle: Handle, diagIndex: number): [string, number, number, string] | null;
+    treeAppendChildren(handle: Handle, parent: bigint, first: bigint): number;
+    treeInsertBefore(handle: Handle, target: bigint, first: bigint): number;
+    treeInsertAfter(handle: Handle, target: bigint, first: bigint): number;
+    treeRemoveSiblings(handle: Handle, node: bigint, count: number): {
+        status: number;
+        head: bigint;
+    };
+    treeRemoveSelf(handle: Handle, node: bigint): {
+        status: number;
+        head: bigint;
+    };
+    treePromoteChildrenOverWrapper(handle: Handle, wrapper: bigint): {
+        status: number;
+        head: bigint;
+    };
+    treeCleanChildren(handle: Handle, node: bigint): {
+        status: number;
+        head: bigint;
+    };
+    treeUnlinkWrapper(handle: Handle, wrapper: bigint): number;
+    treeInsertChildrenAt(handle: Handle, parent: bigint, index: number, first: bigint): number;
+    treeRemoveChildrenAt(handle: Handle, parent: bigint, index: number, count: number): {
+        status: number;
+        head: bigint;
+    };
+    procCurrentNode(args: Handle): bigint;
+    procSetCurrentNode(args: Handle, node: bigint): void;
+    procDropSelf(args: Handle): number;
+    procDropChildren(args: Handle): number;
+    procDropIfEmpty(args: Handle): number;
+    procReplaceWithChildren(args: Handle): number;
+    procContextLine(args: Handle): number;
+    procContextColumn(args: Handle): number;
+    /** Running semantic-error total, or a negative status code. */
+    procReportSemanticError(args: Handle, message: Uint8Array): number;
+    /**
+     * Enables exactly `names` in the native procedure gates before a parse
+     * (selective dispatch): the adapter clears all gates, then enables each
+     * name. Missing symbols (C-procedure or stale libraries) are no-ops.
+     */
+    syncProcedures(names: string[]): void;
+    /**
+     * Hook names in integer-ID order for the ID dispatch path. Queried once
+     * from the library (`galley_js_procedure_count` /
+     * `galley_js_procedure_name_ptr` / `galley_js_procedure_name_len`) and
+     * cached; empty when the library predates the query exports (C-procedure
+     * or stale libraries use the name-carrying dispatch instead).
+     */
+    procedureNames(): string[];
+}

package/dist/port.js

@@ -0,0 +1,14 @@
+/**
+ * Neutral FFI port: the single seam between the runtime-neutral core
+ * (`session.ts`, `node.ts`, `procedures.ts`) and each runtime adapter
+ * (Node/koffi, Bun/`bun:ffi`, Deno/`Deno.dlopen`).
+ *
+ * The port mirrors `bindings/c/galley.h`, but with structured returns
+ * instead of C out-parameters: adapters own all memory copying (bytes are
+ * already-copied `Uint8Array`s here, valid after the next parse) and all
+ * integer normalization (addresses are `bigint`, counts and statuses are
+ * `number`). Opaque native pointers (sessions, walkers, procedure args)
+ * cross the seam as `Handle` and are never inspected by the core.
+ */
+export {};
+//# sourceMappingURL=port.js.map

package/dist/port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.js","sourceRoot":"","sources":["../src/port.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/procedures.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Host-language procedure registry for the JavaScript bindings.
+ *
+ * Runtime-neutral: the registry, `ProcedureArguments`, and the dispatcher
+ * live here. Each adapter installs the dispatcher into its shared library
+ * through its own native callback (`galley_install_*_dispatch`) and calls
+ * {@link dispatchProcedure} with the decoded hook name.
+ *
+ * Hooks receive a `ProcedureArguments` object. Tree queries use
+ * `currentNode()` plus the ordinary `Node` methods (which call the port's
+ * node accessors on the parsing session).
+ */
+import type { Handle, FfiPort } from "./port.ts";
+import { Node } from "./node.ts";
+import type { Session } from "./session.ts";
+export declare class ProcedureArguments {
+    #private;
+    constructor(args: Handle, session: Session | null, port: FfiPort);
+    get session(): Session | null;
+    currentNode(): Node | null;
+    setCurrentNode(node: Node | bigint): void;
+    dropSelf(): void;
+    dropChildren(): void;
+    dropIfEmpty(): void;
+    replaceWithChildren(): void;
+    currentLine(): number;
+    currentColumn(): number;
+    /**
+     * Record a semantic error on the current node and return the running
+     * total. Parsing continues; a syntax-clean parse with any semantic
+     * error fails with status -12.
+     */
+    reportSemanticError(message: string): number;
+}
+export type HookFn = (args: ProcedureArguments) => void;
+/** Records the Session whose parse is in flight so hooks can wrap Nodes. */
+export declare function setParsingSession(session: Session | null): Session | null;
+/** Session of the parse currently in flight, if any. */
+export declare function getParsingSession(): Session | null;
+/**
+ * Runs the registered hook for `name` (silent no-op when unregistered).
+ * Called by each adapter's native dispatch callback. Hook exceptions are
+ * logged and swallowed so a throwing hook never aborts the parse (mirrors
+ * Python's PyErr_Print behavior).
+ */
+export declare function dispatchProcedure(name: string, args: Handle, port: FfiPort): void;
+/**
+ * Installs a single procedure hook. `fn` may be
+ * `(args: ProcedureArguments)=>void` or `()=>void`.
+ * Overwrites any existing entry for `name`.
+ */
+export declare function installProcedure(name: string, fn: HookFn | (() => void)): void;
+/**
+ * Scans `module` for exported procedure hooks (`reduction`, `reduction_*`,
+ * `hook_*`) and registers each function. Returns the number installed.
+ * Mirrors `bindings/python/_galley.c:2339` `install_procedures`.
+ */
+export declare function installProcedures(module: Record<string, unknown>): number;
+/** Removes all registered hooks; subsequent parses will be no-ops. */
+export declare function clearProcedures(): void;
+/** Returns currently registered procedure names. */
+export declare function listProcedures(): string[];

package/dist/procedures.js

@@ -0,0 +1,154 @@
+/**
+ * Host-language procedure registry for the JavaScript bindings.
+ *
+ * Runtime-neutral: the registry, `ProcedureArguments`, and the dispatcher
+ * live here. Each adapter installs the dispatcher into its shared library
+ * through its own native callback (`galley_install_*_dispatch`) and calls
+ * {@link dispatchProcedure} with the decoded hook name.
+ *
+ * Hooks receive a `ProcedureArguments` object. Tree queries use
+ * `currentNode()` plus the ordinary `Node` methods (which call the port's
+ * node accessors on the parsing session).
+ */
+import { INVALID_NODE } from "./constants.js";
+import { encodeUtf8 } from "./text.js";
+import { Node } from "./node.js";
+export class ProcedureArguments {
+    #args;
+    #session;
+    #port;
+    constructor(args, session, port) {
+        this.#args = args;
+        this.#session = session;
+        this.#port = port;
+    }
+    get session() {
+        return this.#session;
+    }
+    currentNode() {
+        if (this.#session === null || this.#session.isClosed)
+            return null;
+        const address = this.#port.procCurrentNode(this.#args);
+        if (address === INVALID_NODE)
+            return null;
+        return new Node(this.#session, address);
+    }
+    setCurrentNode(node) {
+        const address = typeof node === "bigint" ? node : node.address;
+        this.#port.procSetCurrentNode(this.#args, address);
+    }
+    dropSelf() {
+        if (this.#port.procDropSelf(this.#args) < 0) {
+            throw new Error("galley_procedure_drop_self failed");
+        }
+    }
+    dropChildren() {
+        if (this.#port.procDropChildren(this.#args) < 0) {
+            throw new Error("galley_procedure_drop_children failed");
+        }
+    }
+    dropIfEmpty() {
+        if (this.#port.procDropIfEmpty(this.#args) < 0) {
+            throw new Error("galley_procedure_drop_if_empty failed");
+        }
+    }
+    replaceWithChildren() {
+        if (this.#port.procReplaceWithChildren(this.#args) < 0) {
+            throw new Error("galley_procedure_replace_with_children failed");
+        }
+    }
+    currentLine() {
+        return this.#port.procContextLine(this.#args);
+    }
+    currentColumn() {
+        return this.#port.procContextColumn(this.#args);
+    }
+    /**
+     * Record a semantic error on the current node and return the running
+     * total. Parsing continues; a syntax-clean parse with any semantic
+     * error fails with status -12.
+     */
+    reportSemanticError(message) {
+        const status = this.#port.procReportSemanticError(this.#args, encodeUtf8(message));
+        if (status < 0)
+            throw new Error("galley_procedure_report_semantic_error failed");
+        return status;
+    }
+}
+let currentSession = null;
+/** Records the Session whose parse is in flight so hooks can wrap Nodes. */
+export function setParsingSession(session) {
+    const previous = currentSession;
+    currentSession = session;
+    return previous;
+}
+/** Session of the parse currently in flight, if any. */
+export function getParsingSession() {
+    return currentSession;
+}
+const registry = new Map();
+function isProcedureName(name) {
+    return name === "reduction" || name.startsWith("reduction_") || name.startsWith("hook_");
+}
+/**
+ * Runs the registered hook for `name` (silent no-op when unregistered).
+ * Called by each adapter's native dispatch callback. Hook exceptions are
+ * logged and swallowed so a throwing hook never aborts the parse (mirrors
+ * Python's PyErr_Print behavior).
+ */
+export function dispatchProcedure(name, args, port) {
+    const fn = registry.get(name);
+    if (!fn)
+        return;
+    try {
+        if (fn.length === 0) {
+            fn();
+        }
+        else {
+            fn(new ProcedureArguments(args, currentSession, port));
+        }
+    }
+    catch (err) {
+        console.error(`galley procedure ${name} threw:`, err);
+    }
+}
+/**
+ * Installs a single procedure hook. `fn` may be
+ * `(args: ProcedureArguments)=>void` or `()=>void`.
+ * Overwrites any existing entry for `name`.
+ */
+export function installProcedure(name, fn) {
+    if (typeof name !== "string" || name.length === 0)
+        throw new TypeError("procedure name must be non-empty string");
+    if (typeof fn !== "function")
+        throw new TypeError("procedure must be a function");
+    registry.set(name, fn);
+}
+/**
+ * Scans `module` for exported procedure hooks (`reduction`, `reduction_*`,
+ * `hook_*`) and registers each function. Returns the number installed.
+ * Mirrors `bindings/python/_galley.c:2339` `install_procedures`.
+ */
+export function installProcedures(module) {
+    if (module === null || typeof module !== "object")
+        throw new TypeError("module must be an object");
+    let count = 0;
+    for (const [name, value] of Object.entries(module)) {
+        if (typeof value !== "function")
+            continue;
+        if (!isProcedureName(name))
+            continue;
+        registry.set(name, value);
+        count++;
+    }
+    return count;
+}
+/** Removes all registered hooks; subsequent parses will be no-ops. */
+export function clearProcedures() {
+    registry.clear();
+}
+/** Returns currently registered procedure names. */
+export function listProcedures() {
+    return [...registry.keys()];
+}
+//# sourceMappingURL=procedures.js.map

package/dist/procedures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"procedures.js","sourceRoot":"","sources":["../src/procedures.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,MAAM,OAAO,kBAAkB;IACpB,KAAK,CAAS;IACd,QAAQ,CAAiB;IACzB,KAAK,CAAU;IAExB,YAAY,IAAY,EAAE,OAAuB,EAAE,IAAa;QAC9D,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,WAAW;QACT,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC;QAClE,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvD,IAAI,OAAO,KAAK,YAAY;YAAE,OAAO,IAAI,CAAC;QAC1C,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED,cAAc,CAAC,IAAmB;QAChC,MAAM,OAAO,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;QAC/D,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACrD,CAAC;IAED,QAAQ;QACN,IAAI,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,YAAY;QACV,IAAI,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAED,WAAW;QACT,IAAI,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/C,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAED,mBAAmB;QACjB,IAAI,IAAI,CAAC,KAAK,CAAC,uBAAuB,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YACvD,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC;IAED,aAAa;QACX,OAAO,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClD,CAAC;IAED;;;;OAIG;IACH,mBAAmB,CAAC,OAAe;QACjC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,uBAAuB,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC;QACnF,IAAI,MAAM,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACjF,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAID,IAAI,cAAc,GAAmB,IAAI,CAAC;AAE1C,4EAA4E;AAC5E,MAAM,UAAU,iBAAiB,CAAC,OAAuB;IACvD,MAAM,QAAQ,GAAG,cAAc,CAAC;IAChC,cAAc,GAAG,OAAO,CAAC;IACzB,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,iBAAiB;IAC/B,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;AAE3C,SAAS,eAAe,CAAC,IAAY;IACnC,OAAO,IAAI,KAAK,WAAW,IAAI,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;AAC3F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,IAAY,EAAE,IAAa;IACzE,MAAM,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,EAAE;QAAE,OAAO;IAChB,IAAI,CAAC;QACH,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnB,EAAiB,EAAE,CAAC;QACvB,CAAC;aAAM,CAAC;YACL,EAAa,CAAC,IAAI,kBAAkB,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,oBAAoB,IAAI,SAAS,EAAE,GAAG,CAAC,CAAC;IACxD,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,EAAyB;IACtE,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,yCAAyC,CAAC,CAAC;IAClH,IAAI,OAAO,EAAE,KAAK,UAAU;QAAE,MAAM,IAAI,SAAS,CAAC,8BAA8B,CAAC,CAAC;IAClF,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,EAAY,CAAC,CAAC;AACnC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAA+B;IAC/D,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,MAAM,IAAI,SAAS,CAAC,0BAA0B,CAAC,CAAC;IACnG,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,IAAI,OAAO,KAAK,KAAK,UAAU;YAAE,SAAS;QAC1C,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;YAAE,SAAS;QACrC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,KAAe,CAAC,CAAC;QACpC,KAAK,EAAE,CAAC;IACV,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,eAAe;IAC7B,QAAQ,CAAC,KAAK,EAAE,CAAC;AACnB,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,cAAc;IAC5B,OAAO,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;AAC9B,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Parsing session bound to this library's parser.
+ * Mirrors Python/Rust/Go sessions over `bindings/c/galley.h`.
+ *
+ * Runtime-neutral: all native calls go through the injected {@link FfiPort}.
+ * Each adapter (`bindings/js/node`, `../bun`, `../deno`) subclasses `Session`
+ * to supply its port from `SessionOptions.libraryPath`.
+ */
+import type { Diagnostic } from "./diagnostic.ts";
+import type { FfiPort, Handle, TreeSnapshot } from "./port.ts";
+import { Node } from "./node.ts";
+export interface SessionOptions {
+    maxErrors?: number;
+    recoveryWindow?: number;
+    stackOverflowRecovery?: boolean;
+    syntaxErrorStackDepth?: number;
+    verbosity?: number;
+    astPreallocationRatio?: number;
+    astPreallocationCap?: number | bigint;
+    messageOverrides?: Record<string, string>;
+    libraryPath?: string;
+}
+export declare class Session {
+    #private;
+    constructor(port: FfiPort, options?: SessionOptions);
+    get isClosed(): boolean;
+    version(): string;
+    parserType(): number;
+    errorRecoveryMode(): number;
+    hasAst(): boolean;
+    hasProcedures(): boolean;
+    allowsNoAstTreeProcedures(): boolean;
+    sourceRetentionEnabled(): boolean;
+    hasPositionTracking(): boolean;
+    hasInputStreaming(): boolean;
+    usesVerbatim(): boolean;
+    stackOverflowRecoveryAvailable(): boolean;
+    symbolCount(): number;
+    variableCount(): number;
+    statusString(status: number): string | null;
+    close(): void;
+    /** For `using session = new Session()` (Explicit Resource Management). */
+    [Symbol.dispose](): void;
+    parse(input: string | Uint8Array): number;
+    parseSentinel(input: string | Uint8Array): number;
+    parseFile(filePath: string): number;
+    nodeCount(): number;
+    reserveNodes(capacity: number | bigint): void;
+    nodeCapacity(): number;
+    rootNode(): Node | null;
+    nodeValid(node: Node | bigint | number): boolean;
+    childCount(node: Node | bigint | number): number;
+    children(node: Node | bigint | number): Node[];
+    firstChild(node: Node | bigint | number): Node | null;
+    lastChild(node: Node | bigint | number): Node | null;
+    nextSibling(node: Node | bigint | number): Node | null;
+    priorSibling(node: Node | bigint | number): Node | null;
+    parent(node: Node | bigint | number): Node | null;
+    /**
+     * Flat bulk read of the most recent successful parse in a single FFI
+     * crossing: one array slot per node address. Walk `parent`/`firstChild`/
+     * `next` directly instead of one call per node.
+     */
+    snapshot(): TreeSnapshot;
+    /**
+     * Pre-order walker over the subtree rooted at `root`, with the root at
+     * depth 0. Pass true to prune subtrees rooted at semantic-error nodes.
+     * Returns null for invalid roots and builds without AST construction.
+     * Close the walker (or use `using`) before closing the session or
+     * parsing again.
+     */
+    walk(root: Node | bigint | number, skipSemanticErrors?: boolean): Walker | null;
+    symbolNameBytes(node: Node | bigint | number): Uint8Array | null;
+    symbolName(node: Node | bigint | number): string | null;
+    text(node: Node | bigint | number): Uint8Array | null;
+    span(node: Node | bigint | number): [bigint, bigint] | null;
+    lineColumn(node: Node | bigint | number): [number, number] | null;
+    variableIndex(node: Node | bigint | number): number | null;
+    lastPosition(): [number, number] | null;
+    hasDiagnostic(): boolean;
+    setMessageOverride(name: string, message: string): void;
+    diagnostic(): Diagnostic | null;
+    diagnostics(): Diagnostic[];
+    appendChildren(parent: Node | bigint, chain: Node | bigint): void;
+    insertBefore(target: Node | bigint, chain: Node | bigint): void;
+    insertAfter(target: Node | bigint, chain: Node | bigint): void;
+    removeSiblings(node: Node | bigint, count: number): Node | null;
+    removeSelf(node: Node | bigint): Node | null;
+    promoteChildrenOverWrapper(wrapper: Node | bigint): Node | null;
+    cleanChildren(node: Node | bigint): Node | null;
+    unlinkWrapper(wrapper: Node | bigint): void;
+    insertChildrenAt(parent: Node | bigint, index: number, chain: Node | bigint): void;
+    removeChildrenAt(parent: Node | bigint, index: number, count: number): Node | null;
+    symbolNameAt(index: number): Uint8Array | null;
+    symbolIsTerminal(index: number): boolean;
+    variableNameAt(index: number): Uint8Array | null;
+}
+/** One pre-order step of a {@link Walker}. */
+export interface WalkStep {
+    node: Node;
+    depth: number;
+    isSemanticError: boolean;
+}
+/**
+ * Pre-order tree walker over the last successful parse, yielding one
+ * {@link WalkStep} per node. Shares the session's node storage: close the
+ * walker (or use `using`) before closing the session or parsing again.
+ * Created by {@link Session.walk}.
+ */
+export declare class Walker implements IterableIterator<WalkStep> {
+    #private;
+    constructor(session: Session, port: FfiPort, handle: Handle);
+    next(): IteratorResult<WalkStep>;
+    [Symbol.iterator](): IterableIterator<WalkStep>;
+    /**
+     * Prunes the children of the last yielded step; iteration continues with
+     * its next sibling. No effect without a last step.
+     */
+    skipChildren(): void;
+    close(): void;
+    /** For `using walker = session.walk(...)`. */
+    [Symbol.dispose](): void;
+}