sh-ast 0.3.1 → 0.4.0

package/dist/syntax-errors.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Error adaptation for the upstream syntax interface. Exceptions retain the Go
+ * error's structured information and partial result; JavaScript's display message
+ * is never the only copy of a byte-bearing upstream value.
+ */
+import type { File, GoString, SyntaxPos } from '../generated/syntax-types.js';
+import { ShAstError } from './errors.js';
+/**
+ * A source grammar error reported by mvdan/sh, with the partial parsed file.
+ * @public
+ */
+export declare class ParseError extends ShAstError {
+    readonly Message: GoString;
+    readonly Filename: GoString;
+    readonly Pos: SyntaxPos;
+    readonly Text: GoString;
+    readonly Incomplete: boolean;
+    readonly File: File | null;
+    /** Identifies a source grammar failure independently of its display text. */
+    readonly code = "SH_AST_SYNTAX_PARSE";
+    /**
+     * Keeps the original Go fields. Message is the formatted upstream error;
+     * Text is its unformatted diagnostic, and File is the result returned with it.
+     */
+    constructor(Message: GoString, Filename: GoString, Pos: SyntaxPos, Text: GoString, Incomplete: boolean, File: File | null);
+}
+/**
+ * A syntax feature rejected for the selected upstream language variant.
+ * @public
+ */
+export declare class LangError extends ShAstError {
+    readonly Message: GoString;
+    readonly Filename: GoString;
+    readonly Pos: SyntaxPos;
+    readonly Feature: GoString;
+    readonly Langs: readonly number[];
+    readonly LangUsed: number;
+    readonly File: File | null;
+    /** Identifies a dialect-specific syntax failure. */
+    readonly code = "SH_AST_SYNTAX_LANG";
+    /** Preserves the feature, permitted variants, actual variant and partial tree. */
+    constructor(Message: GoString, Filename: GoString, Pos: SyntaxPos, Feature: GoString, Langs: readonly number[], LangUsed: number, File: File | null);
+}
+/**
+ * An argument cannot be represented by the binding or violates an upstream
+ * operation's input constraint. It is distinct from malformed shell source.
+ * @public
+ */
+export declare class InputError extends ShAstError {
+    readonly Message: GoString;
+    /** Identifies caller input that cannot be passed faithfully to the operation. */
+    readonly code = "SH_AST_SYNTAX_INPUT";
+    /** Retains exact upstream message bytes even when Error.message needs text. */
+    constructor(Message: GoString);
+}
+//# sourceMappingURL=syntax-errors.d.ts.map

package/dist/syntax-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax-errors.d.ts","sourceRoot":"","sources":["../src/syntax-errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;GAGG;AACH,qBAAa,UAAW,SAAQ,UAAU;IAStC,QAAQ,CAAC,OAAO,EAAE,QAAQ;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ;IAC3B,QAAQ,CAAC,GAAG,EAAE,SAAS;IACvB,QAAQ,CAAC,IAAI,EAAE,QAAQ;IACvB,QAAQ,CAAC,UAAU,EAAE,OAAO;IAC5B,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAb5B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,yBAAyB;IAEtC;;;OAGG;gBAEQ,OAAO,EAAE,QAAQ,EACjB,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,QAAQ,EACd,UAAU,EAAE,OAAO,EACnB,IAAI,EAAE,IAAI,GAAG,IAAI;CAK7B;AAED;;;GAGG;AACH,qBAAa,SAAU,SAAQ,UAAU;IAMrC,QAAQ,CAAC,OAAO,EAAE,QAAQ;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ;IAC3B,QAAQ,CAAC,GAAG,EAAE,SAAS;IACvB,QAAQ,CAAC,OAAO,EAAE,QAAQ;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAX5B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,wBAAwB;IAErC,kFAAkF;gBAEvE,OAAO,EAAE,QAAQ,EACjB,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,QAAQ,EACjB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,IAAI,GAAG,IAAI;CAK7B;AAED;;;;GAIG;AACH,qBAAa,UAAW,SAAQ,UAAU;IAK5B,QAAQ,CAAC,OAAO,EAAE,QAAQ;IAJtC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,yBAAyB;IAEtC,+EAA+E;gBAC1D,OAAO,EAAE,QAAQ;CAIvC"}

package/dist/syntax-errors.js

@@ -0,0 +1,80 @@
+import { ShAstError } from './errors.js';
+/**
+ * A source grammar error reported by mvdan/sh, with the partial parsed file.
+ * @public
+ */
+export class ParseError extends ShAstError {
+    Message;
+    Filename;
+    Pos;
+    Text;
+    Incomplete;
+    File;
+    /** Identifies a source grammar failure independently of its display text. */
+    code = 'SH_AST_SYNTAX_PARSE';
+    /**
+     * Keeps the original Go fields. Message is the formatted upstream error;
+     * Text is its unformatted diagnostic, and File is the result returned with it.
+     */
+    constructor(Message, Filename, Pos, Text, Incomplete, File) {
+        super(displayMessage(Message));
+        this.Message = Message;
+        this.Filename = Filename;
+        this.Pos = Pos;
+        this.Text = Text;
+        this.Incomplete = Incomplete;
+        this.File = File;
+        this.name = 'ParseError';
+    }
+}
+/**
+ * A syntax feature rejected for the selected upstream language variant.
+ * @public
+ */
+export class LangError extends ShAstError {
+    Message;
+    Filename;
+    Pos;
+    Feature;
+    Langs;
+    LangUsed;
+    File;
+    /** Identifies a dialect-specific syntax failure. */
+    code = 'SH_AST_SYNTAX_LANG';
+    /** Preserves the feature, permitted variants, actual variant and partial tree. */
+    constructor(Message, Filename, Pos, Feature, Langs, LangUsed, File) {
+        super(displayMessage(Message));
+        this.Message = Message;
+        this.Filename = Filename;
+        this.Pos = Pos;
+        this.Feature = Feature;
+        this.Langs = Langs;
+        this.LangUsed = LangUsed;
+        this.File = File;
+        this.name = 'LangError';
+    }
+}
+/**
+ * An argument cannot be represented by the binding or violates an upstream
+ * operation's input constraint. It is distinct from malformed shell source.
+ * @public
+ */
+export class InputError extends ShAstError {
+    Message;
+    /** Identifies caller input that cannot be passed faithfully to the operation. */
+    code = 'SH_AST_SYNTAX_INPUT';
+    /** Retains exact upstream message bytes even when Error.message needs text. */
+    constructor(Message) {
+        super(displayMessage(Message));
+        this.Message = Message;
+        this.name = 'InputError';
+    }
+}
+/**
+ * Error.message is a human-readable rendering only. The public Message property
+ * retains original bytes when the Go value is not valid UTF-8.
+ */
+function displayMessage(value) {
+    return typeof value === 'string' ? value : new TextDecoder().decode(value);
+}
+//# sourceMappingURL=syntax-errors.js.map

package/dist/syntax-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax-errors.js","sourceRoot":"","sources":["../src/syntax-errors.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;GAGG;AACH,MAAM,OAAO,UAAW,SAAQ,UAAU;IAS7B;IACA;IACA;IACA;IACA;IACA;IAbX,6EAA6E;IACpE,IAAI,GAAG,qBAAqB,CAAC;IAEtC;;;OAGG;IACH,YACW,OAAiB,EACjB,QAAkB,EAClB,GAAc,EACd,IAAc,EACd,UAAmB,EACnB,IAAiB;QAE1B,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;QAPtB,YAAO,GAAP,OAAO,CAAU;QACjB,aAAQ,GAAR,QAAQ,CAAU;QAClB,QAAG,GAAH,GAAG,CAAW;QACd,SAAI,GAAJ,IAAI,CAAU;QACd,eAAU,GAAV,UAAU,CAAS;QACnB,SAAI,GAAJ,IAAI,CAAa;QAG1B,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,SAAU,SAAQ,UAAU;IAM5B;IACA;IACA;IACA;IACA;IACA;IACA;IAXX,oDAAoD;IAC3C,IAAI,GAAG,oBAAoB,CAAC;IAErC,kFAAkF;IAClF,YACW,OAAiB,EACjB,QAAkB,EAClB,GAAc,EACd,OAAiB,EACjB,KAAwB,EACxB,QAAgB,EAChB,IAAiB;QAE1B,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;QARtB,YAAO,GAAP,OAAO,CAAU;QACjB,aAAQ,GAAR,QAAQ,CAAU;QAClB,QAAG,GAAH,GAAG,CAAW;QACd,YAAO,GAAP,OAAO,CAAU;QACjB,UAAK,GAAL,KAAK,CAAmB;QACxB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,SAAI,GAAJ,IAAI,CAAa;QAG1B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,UAAW,SAAQ,UAAU;IAKnB;IAJrB,iFAAiF;IACxE,IAAI,GAAG,qBAAqB,CAAC;IAEtC,+EAA+E;IAC/E,YAAqB,OAAiB;QACpC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;QADZ,YAAO,GAAP,OAAO,CAAU;QAEpC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED;;;GAGG;AACH,SAAS,cAAc,CAAC,KAAe;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC7E,CAAC"}

package/dist/syntax-snapshot.d.ts

@@ -0,0 +1,47 @@
+import type { File, Node, SyntaxPos } from '../generated/syntax-types.js';
+/**
+ * A node's upstream bounds as observed during parsing. These values refer to the
+ * original source, even when the corresponding syntax record is later edited.
+ * @public
+ */
+export interface NodePositions {
+    /** Starting byte position observed for the original parsed node. */
+    readonly Pos: Readonly<SyntaxPos>;
+    /** Exclusive ending byte position observed for the original parsed node. */
+    readonly End: Readonly<SyntaxPos>;
+}
+/**
+ * Identity-based lookup of the original parse's bounds. A new or copied node has
+ * no observation. The index never calls WASM or recalculates edited node bounds.
+ * @public
+ */
+export interface PositionSnapshot {
+    /**
+     * Returns the captured pair for a node from this parse, or undefined for a
+     * foreign node. If either upstream observation failed, throws the captured
+     * InputError without changing the successfully parsed File. Use nodePos or
+     * nodeEnd to request a live, independent bound from current edited fields.
+     */
+    get(node: Node): NodePositions | undefined;
+}
+/**
+ * Mutable upstream syntax together with a separate source-bound position view.
+ * Editing File never updates Positions; source consumers can retain original
+ * spans while transformations query live nodePos/nodeEnd as needed.
+ * @public
+ */
+export interface ParsedFile {
+    /** The complete mutable upstream File; no bounds or consumer fields are added. */
+    readonly File: File;
+    /** Immutable original observations, keyed by this File's node identities. */
+    readonly Positions: PositionSnapshot;
+}
+/**
+ * Validates complete sidecar coverage once, then stores immutable observations in
+ * a weak identity map. Missing or duplicate metadata is a transport defect; no
+ * per-node live-position fallback may disguise it or multiply WASM transfers.
+ * The File must already have passed the full syntax boundary validator.
+ * @internal
+ */
+export declare function createPositionSnapshot(file: File, raw: unknown): PositionSnapshot;
+//# sourceMappingURL=syntax-snapshot.d.ts.map

package/dist/syntax-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax-snapshot.d.ts","sourceRoot":"","sources":["../src/syntax-snapshot.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,IAAI,EAAY,IAAI,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAKpF;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,aAAa,GAAG,SAAS,CAAC;CAC5C;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;CACtC;AAgED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAmDjF"}

package/dist/syntax-snapshot.js

@@ -0,0 +1,121 @@
+/**
+ * Correlates parse-time upstream position observations with the decoded syntax
+ * records. Snapshots belong to one parse and never track later edits; live
+ * nodePos/nodeEnd remain a separate responsibility. No traversal order or
+ * visitor-control protocol is exposed by this lookup-only view.
+ */
+import { SYNTAX_INTERFACES, SYNTAX_SCHEMA } from '../generated/syntax-schema.js';
+import { ShInternalError } from './errors.js';
+import { InputError } from './syntax-errors.js';
+import { isGoString, isRecord, isSyntaxPos } from './syntax-wire.js';
+/**
+ * Checks only node identity within an already fully validated File. Revalidating
+ * each subtree here would reintroduce work proportional to all descendant sizes.
+ */
+function isNodeIdentity(value) {
+    return ((typeof value.Type === 'string' && SYNTAX_INTERFACES.Node.includes(value.Type)) ||
+        (value.Type === 'TypedNil' &&
+            typeof value.Kind === 'string' &&
+            SYNTAX_INTERFACES.Node.includes(value.Kind)));
+}
+/**
+ * Indexes child-bearing fields once, including paths through auxiliary records.
+ * Metadata order is irrelevant: paths correlate observations without inventing a
+ * Walk order or equating auxiliary records with syntax.Node values.
+ */
+function nodesByPath(file) {
+    const nodes = new Map();
+    const visit = (value, path) => {
+        if (!isRecord(value) || typeof value.Type !== 'string')
+            return;
+        if (isNodeIdentity(value))
+            nodes.set(JSON.stringify(path), value);
+        if (!Object.hasOwn(SYNTAX_SCHEMA, value.Type))
+            return;
+        for (const [name, field] of Object.entries(SYNTAX_SCHEMA[value.Type].fields)) {
+            if (field.kind !== 'struct' && field.kind !== 'interface')
+                continue;
+            const child = value[name];
+            if (Array.isArray(child)) {
+                child.forEach((item, index) => {
+                    visit(item, [...path, name, index]);
+                });
+            }
+            else {
+                visit(child, [...path, name]);
+            }
+        }
+    };
+    visit(file, []);
+    return nodes;
+}
+/** Accepts the exact field/index domain used by the upstream observation sidecar. */
+function isPath(value) {
+    return (Array.isArray(value) &&
+        value.every((component) => typeof component === 'string' ||
+            (typeof component === 'number' && Number.isSafeInteger(component) && component >= 0)));
+}
+/** An upstream method produced exactly one position or one preserved failure. */
+function isObservation(position, error) {
+    return (isSyntaxPos(position) && error === null) || (position === null && isGoString(error));
+}
+/**
+ * Validates complete sidecar coverage once, then stores immutable observations in
+ * a weak identity map. Missing or duplicate metadata is a transport defect; no
+ * per-node live-position fallback may disguise it or multiply WASM transfers.
+ * The File must already have passed the full syntax boundary validator.
+ * @internal
+ */
+export function createPositionSnapshot(file, raw) {
+    const nodes = nodesByPath(file);
+    if (!Array.isArray(raw) || raw.length !== nodes.size)
+        throw new ShInternalError('The syntax snapshot does not cover every parsed node');
+    const observations = new WeakMap();
+    const remaining = new Map(nodes);
+    for (const entry of raw) {
+        if (!isRecord(entry) ||
+            Object.keys(entry).length !== 5 ||
+            !isPath(entry.Path) ||
+            !isObservation(entry.Pos, entry.PosError) ||
+            !isObservation(entry.End, entry.EndError)) {
+            throw new ShInternalError('The syntax snapshot contains an invalid position observation');
+        }
+        const path = JSON.stringify(entry.Path);
+        const node = remaining.get(path);
+        if (node === undefined)
+            throw new ShInternalError('The syntax snapshot contains an unknown or duplicate node path');
+        remaining.delete(path);
+        if (isGoString(entry.PosError)) {
+            observations.set(node, { error: entry.PosError });
+        }
+        else if (isGoString(entry.EndError)) {
+            observations.set(node, { error: entry.EndError });
+        }
+        else if (isSyntaxPos(entry.Pos) && isSyntaxPos(entry.End)) {
+            observations.set(node, {
+                positions: Object.freeze({
+                    Pos: Object.freeze({ ...entry.Pos }),
+                    End: Object.freeze({ ...entry.End }),
+                }),
+            });
+        }
+        else {
+            throw new ShInternalError('The syntax snapshot dropped an upstream method outcome');
+        }
+    }
+    if (remaining.size !== 0)
+        throw new ShInternalError('The syntax snapshot omitted parsed node observations');
+    return Object.freeze({
+        get(node) {
+            const observation = observations.get(node);
+            if (observation === undefined)
+                return undefined;
+            if ('error' in observation) {
+                // An exception may be edited by its catcher; retain the captured bytes.
+                throw new InputError(typeof observation.error === 'string' ? observation.error : observation.error.slice());
+            }
+            return observation.positions;
+        },
+    });
+}
+//# sourceMappingURL=syntax-snapshot.js.map

package/dist/syntax-snapshot.js.map

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

package/dist/syntax-wire.d.ts

@@ -0,0 +1,31 @@
+import type { File, GoString, Node, SyntaxPos } from '../generated/syntax-types.js';
+/** Values after JSON parsing have no inherited application behavior. @internal */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Rejects unpaired UTF-16 surrogates before TextEncoder can replace them. Callers
+ * with source bytes use Uint8Array and receive the upstream byte-input behavior.
+ * @internal
+ */
+export declare function assertUnicodeString(value: string): void;
+/**
+ * Encodes bytes and exact integers without relying on JSON's number precision or
+ * Uint8Array property enumeration. Circular input is a caller error, not a stack
+ * overflow or a partially transferred request.
+ * @internal
+ */
+export declare function encodeWire(value: unknown): string;
+/**
+ * Restores byte-bearing Go values. Ordinary syntax fields retain their spelling,
+ * nulls, defaults, and ordering; no source location or synthetic node is added.
+ * @internal
+ */
+export declare function decodeWire(text: string): unknown;
+/** A Go string is text only when every original byte is valid UTF-8. @internal */
+export declare function isGoString(value: unknown): value is GoString;
+/** Checks the observable uint32-backed position shape without inventing bounds. @internal */
+export declare function isSyntaxPos(value: unknown): value is SyntaxPos;
+/** Narrows complete syntax.Nodes or typed nil Node interfaces; auxiliaries are excluded. @internal */
+export declare function isSyntaxNode(value: unknown): value is Node;
+/** The public parser's root is the precise upstream File representation. @internal */
+export declare function isSyntaxFile(value: unknown): value is File;
+//# sourceMappingURL=syntax-wire.d.ts.map

package/dist/syntax-wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax-wire.d.ts","sourceRoot":"","sources":["../src/syntax-wire.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAEpF,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CASvD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAgCjD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAmBhD;AAED,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED,6FAA6F;AAC7F,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAwB9D;AA4ED,sGAAsG;AACtG,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,CAS1D;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,CAE1D"}

package/dist/syntax-wire.js

@@ -0,0 +1,202 @@
+/**
+ * Lossless JSON adaptation at the JS/Go boundary. Go strings are byte sequences;
+ * integer arguments may span 64 bits. Tagged encodings preserve those domains
+ * without changing the public syntax records into a second tree model.
+ */
+import { InputError } from './syntax-errors.js';
+import { ShInternalError } from './errors.js';
+import { SYNTAX_INTERFACES, SYNTAX_SCHEMA, } from '../generated/syntax-schema.js';
+/** Values after JSON parsing have no inherited application behavior. @internal */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Rejects unpaired UTF-16 surrogates before TextEncoder can replace them. Callers
+ * with source bytes use Uint8Array and receive the upstream byte-input behavior.
+ * @internal
+ */
+export function assertUnicodeString(value) {
+    for (const character of value) {
+        const point = character.codePointAt(0);
+        if (point !== undefined && point >= 0xd800 && point <= 0xdfff) {
+            throw new InputError('A string contains an unpaired UTF-16 surrogate; supply exact bytes instead');
+        }
+    }
+}
+/**
+ * Encodes bytes and exact integers without relying on JSON's number precision or
+ * Uint8Array property enumeration. Circular input is a caller error, not a stack
+ * overflow or a partially transferred request.
+ * @internal
+ */
+export function encodeWire(value) {
+    const ancestors = new Set();
+    const visit = (item) => {
+        if (typeof item === 'string') {
+            assertUnicodeString(item);
+            return item;
+        }
+        if (typeof item === 'bigint')
+            return { Int: item.toString() };
+        if (item instanceof Uint8Array)
+            return { Bytes: Buffer.from(item).toString('base64') };
+        if (item === null || typeof item === 'boolean')
+            return item;
+        if (typeof item === 'number') {
+            if (!Number.isSafeInteger(item))
+                throw new InputError('Numeric values must be safe integers; use bigint for 64-bit arguments');
+            return item;
+        }
+        if (typeof item !== 'object')
+            throw new InputError('Syntax wire values must be data records, arrays, bytes, or scalar values');
+        if (ancestors.has(item))
+            throw new InputError('Syntax records cannot contain cycles');
+        ancestors.add(item);
+        try {
+            if (Array.isArray(item))
+                return item.map(visit);
+            if (!isRecord(item))
+                throw new InputError('Expected a syntax data record');
+            return Object.fromEntries(Object.entries(item).map(([key, child]) => [key, visit(child)]));
+        }
+        finally {
+            ancestors.delete(item);
+        }
+    };
+    return JSON.stringify(visit(value));
+}
+/**
+ * Restores byte-bearing Go values. Ordinary syntax fields retain their spelling,
+ * nulls, defaults, and ordering; no source location or synthetic node is added.
+ * @internal
+ */
+export function decodeWire(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (cause) {
+        throw new ShInternalError(`Invalid syntax bridge JSON: ${String(cause)}`);
+    }
+    const visit = (item) => {
+        if (Array.isArray(item))
+            return item.map(visit);
+        if (!isRecord(item))
+            return item;
+        if (Object.keys(item).length === 1 && typeof item.Bytes === 'string') {
+            const bytes = Buffer.from(item.Bytes, 'base64');
+            if (bytes.toString('base64') !== item.Bytes)
+                throw new ShInternalError('Invalid base64 in syntax bridge response');
+            return new Uint8Array(bytes);
+        }
+        return Object.fromEntries(Object.entries(item).map(([key, child]) => [key, visit(child)]));
+    };
+    return visit(parsed);
+}
+/** A Go string is text only when every original byte is valid UTF-8. @internal */
+export function isGoString(value) {
+    return typeof value === 'string' || value instanceof Uint8Array;
+}
+/** Checks the observable uint32-backed position shape without inventing bounds. @internal */
+export function isSyntaxPos(value) {
+    if (!isRecord(value))
+        return false;
+    const uint = (item, maximum) => typeof item === 'number' && Number.isInteger(item) && item >= 0 && item <= maximum;
+    const shape = Object.keys(value).length === 6 &&
+        uint(value.Offset, 0xffff_ffff - 11) &&
+        uint(value.Line, 0x3_ffff) &&
+        uint(value.Col, 0x3fff) &&
+        typeof value.IsValid === 'boolean' &&
+        typeof value.IsRecovered === 'boolean' &&
+        typeof value.OffsetOverflow === 'boolean';
+    if (!shape)
+        return false;
+    if (value.IsRecovered) {
+        return (value.OffsetOverflow === true &&
+            value.IsValid === false &&
+            value.Offset === 0 &&
+            value.Line === 0 &&
+            value.Col === 0);
+    }
+    if (value.OffsetOverflow)
+        return value.IsValid === false && value.Offset === 0;
+    return value.IsValid === (value.Line !== 0 || value.Col !== 0);
+}
+/**
+ * A Go interface can hold a nil pointer with a concrete dynamic type. Its tag
+ * preserves that type without inventing fields for a nonexistent record.
+ */
+function isTypedNil(value, implementers) {
+    return (isRecord(value) &&
+        value.Type === 'TypedNil' &&
+        typeof value.Kind === 'string' &&
+        Object.keys(value).length === 2 &&
+        implementers.includes(value.Kind));
+}
+/**
+ * Validates complete records against the pinned schema, including nil-bearing
+ * boundaries. This is a boundary check, not a semantic shell interpretation.
+ */
+function matchesRecord(value, active) {
+    if (!isRecord(value) || typeof value.Type !== 'string' || active.has(value))
+        return false;
+    if (!Object.hasOwn(SYNTAX_SCHEMA, value.Type))
+        return false;
+    const descriptor = SYNTAX_SCHEMA[value.Type];
+    if (Object.keys(value).length !== Object.keys(descriptor.fields).length + 1)
+        return false;
+    active.add(value);
+    try {
+        return Object.entries(descriptor.fields).every(([name, field]) => Object.hasOwn(value, name) && matchesField(value[name], field, active));
+    }
+    finally {
+        active.delete(value);
+    }
+}
+/** Checks one upstream field without conflating a nil slice with an empty one. */
+function matchesField(value, field, active) {
+    if (value === null)
+        return field.nullable;
+    if (field.slice) {
+        return (Array.isArray(value) &&
+            value.every((item) => item === null ? field.elementNullable : matchesScalar(item, field, active)));
+    }
+    return matchesScalar(value, field, active);
+}
+/** Each scalar category retains its upstream domain rather than JS coercions. */
+function matchesScalar(value, field, active) {
+    switch (field.kind) {
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'string':
+            return isGoString(value);
+        case 'position':
+            return isSyntaxPos(value);
+        case 'operator':
+            return (typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 0xffff_ffff);
+        case 'struct':
+            return isRecord(value) && value.Type === field.type && matchesRecord(value, active);
+        case 'interface':
+            return (isRecord(value) &&
+                typeof value.Type === 'string' &&
+                field.type !== null &&
+                Object.hasOwn(SYNTAX_INTERFACES, field.type) &&
+                (isTypedNil(value, SYNTAX_INTERFACES[field.type]) ||
+                    (SYNTAX_INTERFACES[field.type].includes(value.Type) && matchesRecord(value, active))));
+    }
+}
+/** Narrows complete syntax.Nodes or typed nil Node interfaces; auxiliaries are excluded. @internal */
+export function isSyntaxNode(value) {
+    if (isTypedNil(value, SYNTAX_INTERFACES.Node))
+        return true;
+    return (isRecord(value) &&
+        typeof value.Type === 'string' &&
+        Object.hasOwn(SYNTAX_SCHEMA, value.Type) &&
+        SYNTAX_SCHEMA[value.Type].node &&
+        matchesRecord(value, new Set()));
+}
+/** The public parser's root is the precise upstream File representation. @internal */
+export function isSyntaxFile(value) {
+    return isSyntaxNode(value) && value.Type === 'File';
+}
+//# sourceMappingURL=syntax-wire.js.map

package/dist/syntax-wire.js.map

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

package/dist/syntax.d.ts

@@ -0,0 +1,65 @@
+import type { OperatorFamily, RawOperator } from '../generated/syntax-constants.js';
+import type { File, GoString, Node, SyntaxPos } from '../generated/syntax-types.js';
+import { type ParsedFile } from './syntax-snapshot.js';
+export type { ParsedFile, PositionSnapshot, NodePositions } from './syntax-snapshot.js';
+export { InputError, LangError, ParseError } from './syntax-errors.js';
+/**
+ * Whole-file parser inputs corresponding to upstream controls. Defaults match
+ * NewParser; in particular comments are retained only when KeepComments is true.
+ * Numeric int arguments accept bigint because Go's WASM int is signed 64-bit.
+ * @public
+ */
+export interface ParseOptions {
+    /** Source identity carried by File/errors; no file is opened by the binding. */
+    Filename?: GoString;
+    /** Retains comment nodes when true; upstream defaults to false. */
+    KeepComments?: boolean;
+    /** Upstream LangVariant value. Variant rejects unsupported values, including LangAuto. */
+    Variant?: number | bigint;
+    /** Lexer delimiter with upstream byte-length, whitespace and prefix semantics. */
+    StopAt?: GoString;
+    /** Maximum number of recoverable missing grammar tokens, using upstream behavior. */
+    RecoverErrors?: number | bigint;
+}
+/**
+ * Parses exact source bytes, or well-formed Unicode text encoded as UTF-8. First
+ * use synchronously initializes WASM. The existing conservative nesting guard is
+ * an explicit binding resource limit, not an upstream grammar restriction.
+ * @public
+ */
+export declare function parseSync(source: string | Uint8Array, options?: ParseOptions): File;
+/**
+ * Parses once while observing every real node's upstream bounds in Go. The
+ * separate immutable lookup describes this original parse; it never replaces
+ * live nodePos/nodeEnd or tracks edits. Source adapters avoid reconstructing
+ * each descendant subtree just to display the original source locations.
+ * @public
+ */
+export declare function parseWithPositionsSync(source: string | Uint8Array, options?: ParseOptions): ParsedFile;
+/**
+ * Computes a node's starting position from its current fields using upstream's
+ * Pos method. No cached parse-time position can override subsequent tree edits.
+ * @public
+ */
+export declare function nodePos(node: Node): SyntaxPos;
+/**
+ * Computes a node's ending position using upstream's End method, including
+ * recovered/invalid behavior and changes to text or child nodes.
+ * @public
+ */
+export declare function nodeEnd(node: Node): SyntaxPos;
+/**
+ * Constructs an upstream position. uint64 arguments use bigint when outside the
+ * safe-number range; upstream clamps offsets and zeroes overflowing line/column
+ * values. The binding does not replace those rules with its own range policy.
+ * @public
+ */
+export declare function newPos(offset: number | bigint, line: number | bigint, column: number | bigint): SyntaxPos;
+/**
+ * Represents an unnamed value in an upstream uint32 operator family. Named
+ * constants remain precise literal unions; this explicit path preserves other Go
+ * values without claiming an operation such as Print accepts them.
+ * @public
+ */
+export declare function rawOperator<Family extends OperatorFamily>(family: Family, value: number): RawOperator<Family>;
+//# sourceMappingURL=syntax.d.ts.map

package/dist/syntax.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax.d.ts","sourceRoot":"","sources":["../src/syntax.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACpF,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAepF,OAAO,EAA0B,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAC/E,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAExF,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,mEAAmE;IACnE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,kFAAkF;IAClF,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,qFAAqF;IACrF,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE,OAAO,GAAE,YAAiB,GAAG,IAAI,CAEvF;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,GAAG,UAAU,EAC3B,OAAO,GAAE,YAAiB,GACzB,UAAU,CAGZ;AAwBD;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CACpB,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,MAAM,EAAE,MAAM,GAAG,MAAM,GACtB,SAAS,CAQX;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,SAAS,cAAc,EACvD,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,WAAW,CAAC,MAAM,CAAC,CAarB"}