sh-ast 0.3.0 → 0.4.0

package/dist/syntax.js

@@ -0,0 +1,152 @@
+/**
+ * Synchronous access to the pinned upstream syntax model. Parsing and derived
+ * node bounds run in Go; this module transports exact data and adapts errors,
+ * leaving ESLint locations, traversal, and policy to consumers.
+ */
+import { SYNTAX_SCHEMA } from '../generated/syntax-schema.js';
+import { ShInternalError } from './errors.js';
+import { assertParseDepthWithinLimit } from './parse-depth-guard.js';
+import { InputError, LangError, ParseError } from './syntax-errors.js';
+import { assertUnicodeString, decodeWire, encodeWire, isGoString, isRecord, isSyntaxFile, isSyntaxNode, isSyntaxPos, } from './syntax-wire.js';
+import { callSyntax } from './wasm-instance.js';
+import { createPositionSnapshot } from './syntax-snapshot.js';
+export { InputError, LangError, ParseError } from './syntax-errors.js';
+/**
+ * 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 function parseSync(source, options = {}) {
+    return invokeParse('parse', source, options).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 function parseWithPositionsSync(source, options = {}) {
+    const { file, response } = invokeParse('parse-with-positions', source, options);
+    return Object.freeze({ File: file, Positions: createPositionSnapshot(file, response.Positions) });
+}
+/** Shared source/options/error semantics for both whole-file parsing operations. */
+function invokeParse(operation, source, options) {
+    if (typeof source !== 'string' && !(source instanceof Uint8Array))
+        throw new InputError('Source must be a string or Uint8Array');
+    if (typeof source === 'string')
+        assertUnicodeString(source);
+    const bytes = typeof source === 'string' ? new TextEncoder().encode(source) : source;
+    // Decoding here supplies only an ASCII-structure risk estimate. The original
+    // bytes, including malformed UTF-8, are always sent unchanged to the parser.
+    assertParseDepthWithinLimit(typeof source === 'string' ? source : new TextDecoder().decode(source));
+    validateOptions(options);
+    const result = invoke(operation, bytes, encodeWire(options));
+    if (!isSyntaxFile(result.File))
+        throw new ShInternalError('The syntax parser returned an incomplete or invalid File record');
+    return { file: result.File, response: result };
+}
+/**
+ * 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 function nodePos(node) {
+    return positionOf('pos', node);
+}
+/**
+ * Computes a node's ending position using upstream's End method, including
+ * recovered/invalid behavior and changes to text or child nodes.
+ * @public
+ */
+export function nodeEnd(node) {
+    return positionOf('end', node);
+}
+/**
+ * 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 function newPos(offset, line, column) {
+    const result = invoke('newpos', new TextEncoder().encode(encodeWire({ Offset: offset, Line: line, Col: column })));
+    if (!isSyntaxPos(result.Position))
+        throw new ShInternalError('The syntax constructor returned an invalid position record');
+    return result.Position;
+}
+/**
+ * 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 function rawOperator(family, value) {
+    const knownFamily = Object.values(SYNTAX_SCHEMA).some((record) => Object.values(record.fields).some((field) => field.kind === 'operator' && field.type === family));
+    if (!knownFamily || !Number.isInteger(value) || value < 0 || value > 0xffff_ffff) {
+        throw new InputError('An operator value must belong to a known family and be an integral uint32');
+    }
+    // The runtime check establishes the opaque numeric brand; no value is changed.
+    return value;
+}
+/** Exact Go options are validated without silently ignoring misspelled keys. */
+function validateOptions(options) {
+    if (!isRecord(options))
+        throw new InputError('Parser options must be a data record');
+    const allowed = new Set(['Filename', 'KeepComments', 'Variant', 'StopAt', 'RecoverErrors']);
+    for (const [name, value] of Object.entries(options)) {
+        if (!allowed.has(name))
+            throw new InputError(`Unknown parser option: ${name}`);
+        if ((name === 'Filename' || name === 'StopAt') && !isGoString(value))
+            throw new InputError(`${name} must be a string or byte array`);
+        if (name === 'KeepComments' && typeof value !== 'boolean')
+            throw new InputError('KeepComments must be boolean');
+        if ((name === 'Variant' || name === 'RecoverErrors') &&
+            typeof value !== 'bigint' &&
+            (typeof value !== 'number' || !Number.isSafeInteger(value))) {
+            throw new InputError(`${name} must be a safe integer or bigint`);
+        }
+    }
+}
+/** Only the requested upstream method runs; partial nodes can support one bound. */
+function positionOf(operation, node) {
+    if (!isSyntaxNode(node))
+        throw new InputError('Expected a complete, acyclic upstream Node record');
+    const result = invoke(operation, new TextEncoder().encode(encodeWire(node)));
+    if (!isSyntaxPos(result.Position))
+        throw new ShInternalError('The syntax bridge returned an invalid derived position');
+    return result.Position;
+}
+/** Decodes one complete response before translating its upstream failure kind. */
+function invoke(operation, payload, options = '{}') {
+    const result = decodeWire(callSyntax(operation, payload, options));
+    if (!isRecord(result))
+        throw new ShInternalError('The syntax bridge returned a non-record response');
+    if (result.Error !== undefined) {
+        const error = result.Error;
+        if (!isRecord(error) || !isGoString(error.Message))
+            throw new ShInternalError('The syntax bridge returned a malformed error');
+        if (error.Kind === 'InputError')
+            throw new InputError(error.Message);
+        if (error.Kind === 'InternalError')
+            throw new ShInternalError(typeof error.Message === 'string' ? error.Message : new TextDecoder().decode(error.Message));
+        const file = result.File === null ? null : isSyntaxFile(result.File) ? result.File : undefined;
+        if (file === undefined || !isGoString(error.Filename) || !isSyntaxPos(error.Pos))
+            throw new ShInternalError('The syntax bridge dropped a partial result or error position');
+        if (error.Kind === 'ParseError' &&
+            isGoString(error.Text) &&
+            typeof error.Incomplete === 'boolean') {
+            throw new ParseError(error.Message, error.Filename, error.Pos, error.Text, error.Incomplete, file);
+        }
+        if (error.Kind === 'LangError' &&
+            isGoString(error.Feature) &&
+            Array.isArray(error.Langs) &&
+            error.Langs.every((lang) => typeof lang === 'number' && Number.isSafeInteger(lang)) &&
+            typeof error.LangUsed === 'number') {
+            throw new LangError(error.Message, error.Filename, error.Pos, error.Feature, error.Langs, error.LangUsed, file);
+        }
+        throw new ShInternalError('The syntax bridge returned an unknown or incomplete upstream error');
+    }
+    return result;
+}
+//# sourceMappingURL=syntax.js.map

package/dist/syntax.js.map

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

package/dist/wasm-instance.d.ts

@@ -1,13 +1,10 @@
 import '../shim/wasm_exec.js';
 /**
- * Calls into the WASM shim's `process` export, instantiating the shim on
- * first use. Encodes `text`/`dialect`/`filename` into shim-owned linear
- * memory, reads the NUL-terminated JSON result back via `TextDecoder`
- * (rather than syscall/js's `js.ValueOf(string)`, which dominated the parse
- * cost — see design/ARCHITECTURE.md's "Performance"), and frees every buffer
- * the call allocated.
- *
+ * Calls the lossless syntax protocol synchronously with byte-exact payloads.
+ * Every returned allocation is released even when a later allocation, exported
+ * operation, or response validation fails. Views are recreated after each call
+ * because Go allocation can grow and detach linear memory.
  * @internal
  */
-export declare function callParse(text: string, dialect: string, filename: string): string;
+export declare function callSyntax(operation: string, payload: Uint8Array, options?: string): string;
 //# sourceMappingURL=wasm-instance.d.ts.map

package/dist/wasm-instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wasm-instance.d.ts","sourceRoot":"","sources":["../src/wasm-instance.ts"],"names":[],"mappings":"AAGA,OAAO,sBAAsB,CAAC;AA2F9B;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAuBjF"}
+{"version":3,"file":"wasm-instance.d.ts","sourceRoot":"","sources":["../src/wasm-instance.ts"],"names":[],"mappings":"AAIA,OAAO,sBAAsB,CAAC;AAsE9B;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,SAAO,GAAG,MAAM,CAkCzF"}

package/dist/wasm-instance.js

@@ -1,3 +1,4 @@
+/** Synchronous singleton WASM ownership and byte-exact syntax protocol transport. */
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -6,19 +7,18 @@ import { ShInternalError } from './errors.js';
 const here = path.dirname(fileURLToPath(import.meta.url));
 // `shim/` is a sibling of both `src/` (test-time) and `dist/` (build-time).
 const wasmPath = path.join(here, '..', 'shim', 'sh-ast.wasm');
+/** Validates shared memory ownership primitives before any buffer crosses the bridge. */
 function isShimExports(value) {
     const candidate = value;
     return (candidate.mem instanceof WebAssembly.Memory &&
         typeof candidate.alloc === 'function' &&
-        typeof candidate.free === 'function' &&
-        typeof candidate.process === 'function');
+        typeof candidate.free === 'function');
 }
 let wasmModule;
 let shimExports;
 /**
  * Instantiates the WASM shim synchronously in Node, exactly once, and
- * reuses the instance across parses (see design/ARCHITECTURE.md,
- * "Synchronous parse: solved, two mechanisms"). Node imposes no size limit
+ * reuses the instance across parses and position operations. Node imposes no size limit
  * on synchronous `WebAssembly.Module` compilation — that restriction is
  * browser-main-thread-only.
  */
@@ -30,7 +30,7 @@ function ensureInstance() {
     const instance = new WebAssembly.Instance(wasmModule, go.importObject);
     void go.run(instance);
     if (!isShimExports(instance.exports)) {
-        throw new ShInternalError('bridge: WASM shim did not export the expected alloc/process/free/mem linear-memory ABI');
+        throw new ShInternalError('bridge: WASM shim did not export the expected alloc/free/mem linear-memory ABI');
     }
     shimExports = instance.exports;
     return shimExports;
@@ -38,51 +38,48 @@ function ensureInstance() {
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 /**
- * Writes `text` (UTF-8 encoded) into a freshly `alloc`ed buffer and returns
- * its (pointer, length). The caller owns the buffer and must `free` it once
- * `process` has consumed it.
- */
-function writeString(exports, text) {
-    const bytes = encoder.encode(text);
-    const ptr = exports.alloc(bytes.length);
-    // `exports.mem.buffer` is re-read here rather than cached across calls:
-    // a Go-side allocation can grow WASM linear memory, which detaches any
-    // previously created `ArrayBuffer` view (see `callParse` below for the
-    // same reasoning on the read side).
-    new Uint8Array(exports.mem.buffer, ptr, bytes.length).set(bytes);
-    return { ptr, len: bytes.length };
-}
-/**
- * Calls into the WASM shim's `process` export, instantiating the shim on
- * first use. Encodes `text`/`dialect`/`filename` into shim-owned linear
- * memory, reads the NUL-terminated JSON result back via `TextDecoder`
- * (rather than syscall/js's `js.ValueOf(string)`, which dominated the parse
- * cost — see design/ARCHITECTURE.md's "Performance"), and frees every buffer
- * the call allocated.
- *
+ * Calls the lossless syntax protocol synchronously with byte-exact payloads.
+ * Every returned allocation is released even when a later allocation, exported
+ * operation, or response validation fails. Views are recreated after each call
+ * because Go allocation can grow and detach linear memory.
  * @internal
  */
-export function callParse(text, dialect, filename) {
+export function callSyntax(operation, payload, options = '{}') {
     const exports = ensureInstance();
-    const t = writeString(exports, text);
-    const d = writeString(exports, dialect);
-    const f = writeString(exports, filename);
-    const resultPtr = exports.process(t.ptr, t.len, d.ptr, d.len, f.ptr, f.len);
-    exports.free(t.ptr);
-    exports.free(d.ptr);
-    exports.free(f.ptr);
-    if (resultPtr === 0) {
-        throw new ShInternalError('bridge: WASM shim returned a null result pointer');
+    const process = exports.syntaxProcess;
+    if (typeof process !== 'function') {
+        throw new ShInternalError('The installed WASM asset does not export the lossless syntax protocol');
+    }
+    const allocations = [];
+    const write = (bytes) => {
+        const ptr = exports.alloc(bytes.length);
+        allocations.push(ptr);
+        if (ptr === 0)
+            throw new ShInternalError('The syntax bridge returned a null input allocation');
+        new Uint8Array(exports.mem.buffer, ptr, bytes.length).set(bytes);
+        return { ptr, len: bytes.length };
+    };
+    try {
+        const op = write(encoder.encode(operation));
+        const input = write(payload);
+        const opts = write(encoder.encode(options));
+        const result = process(op.ptr, op.len, input.ptr, input.len, opts.ptr, opts.len);
+        if (result === 0)
+            throw new ShInternalError('The syntax bridge returned a null result');
+        allocations.push(result);
+        const memory = new Uint8Array(exports.mem.buffer);
+        if (result >= memory.length)
+            throw new ShInternalError('The syntax bridge returned an out-of-bounds result');
+        let end = result;
+        while (end < memory.length && memory[end] !== 0)
+            end++;
+        if (end === memory.length)
+            throw new ShInternalError('The syntax bridge result has no terminator');
+        return decoder.decode(memory.subarray(result, end));
+    }
+    finally {
+        for (const ptr of allocations)
+            exports.free(ptr);
     }
-    // Re-read `mem.buffer` fresh (see `writeString`'s comment) and scan for the
-    // shim's NUL sentinel — valid JSON from Go's encoding/json never contains
-    // a raw 0x00 byte, since every control character is \u-escaped.
-    const memory = new Uint8Array(exports.mem.buffer);
-    let end = resultPtr;
-    while (memory[end] !== 0)
-        end++;
-    const json = decoder.decode(memory.subarray(resultPtr, end));
-    exports.free(resultPtr);
-    return json;
 }
 //# sourceMappingURL=wasm-instance.js.map

package/dist/wasm-instance.js.map

@@ -1 +1 @@
-{"version":3,"file":"wasm-instance.js","sourceRoot":"","sources":["../src/wasm-instance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,sBAAsB,CAAC;AAM9B,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,4EAA4E;AAC5E,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;AA2B9D,SAAS,aAAa,CAAC,KAA0B;IAC/C,MAAM,SAAS,GAAG,KAA6B,CAAC;IAChD,OAAO,CACL,SAAS,CAAC,GAAG,YAAY,WAAW,CAAC,MAAM;QAC3C,OAAO,SAAS,CAAC,KAAK,KAAK,UAAU;QACrC,OAAO,SAAS,CAAC,IAAI,KAAK,UAAU;QACpC,OAAO,SAAS,CAAC,OAAO,KAAK,UAAU,CACxC,CAAC;AACJ,CAAC;AAED,IAAI,UAA0C,CAAC;AAC/C,IAAI,WAAoC,CAAC;AAEzC;;;;;;GAMG;AACH,SAAS,cAAc;IACrB,IAAI,WAAW;QAAE,OAAO,WAAW,CAAC;IACpC,UAAU,KAAK,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC;IACjE,MAAM,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC;IACpB,MAAM,QAAQ,GAAG,IAAI,WAAW,CAAC,QAAQ,CAAC,UAAU,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC;IACvE,KAAK,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACtB,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,eAAe,CACvB,wFAAwF,CACzF,CAAC;IACJ,CAAC;IACD,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC;IAC/B,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAClC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAElC;;;;GAIG;AACH,SAAS,WAAW,CAAC,OAAoB,EAAE,IAAY;IACrD,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACxC,wEAAwE;IACxE,uEAAuE;IACvE,uEAAuE;IACvE,oCAAoC;IACpC,IAAI,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACjE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;AACpC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,OAAe,EAAE,QAAgB;IACvE,MAAM,OAAO,GAAG,cAAc,EAAE,CAAC;IACjC,MAAM,CAAC,GAAG,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACrC,MAAM,CAAC,GAAG,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACxC,MAAM,CAAC,GAAG,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACzC,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IAC5E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACpB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACpB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAEpB,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,eAAe,CAAC,kDAAkD,CAAC,CAAC;IAChF,CAAC;IAED,4EAA4E;IAC5E,0EAA0E;IAC1E,gEAAgE;IAChE,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAClD,IAAI,GAAG,GAAG,SAAS,CAAC;IACpB,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,GAAG,EAAE,CAAC;IAChC,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC;IAC7D,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACxB,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"wasm-instance.js","sourceRoot":"","sources":["../src/wasm-instance.ts"],"names":[],"mappings":"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"}