sh-ast 0.0.0 → 0.2.0

package/dist/parse.d.ts

@@ -0,0 +1,50 @@
+import { type JsonValue } from './normalize.js';
+import type { ParseOptions, ShFile } from './types.js';
+interface ParseErrorPayload {
+    message: string;
+    filename: string;
+    line: number;
+    column: number;
+    offset: number;
+}
+interface ErrorPayload {
+    message: string;
+}
+interface ResultEnvelope {
+    file?: JsonValue;
+    parseError?: ParseErrorPayload;
+    error?: ErrorPayload;
+}
+/**
+ * @internal
+ */
+export declare function isResultEnvelope(value: unknown): value is ResultEnvelope;
+/**
+ * Synchronously parses shell source into a normalized AST.
+ *
+ * The first call instantiates the WASM shim synchronously (Node-only); the
+ * instance is reused across subsequent calls, so repeated calls do not
+ * re-instantiate (see design/ARCHITECTURE.md).
+ *
+ * Throws {@link ShParseError} on a shell syntax error, carrying the position
+ * mvdan/sh reported: `.line` is 1-based exactly as mvdan/sh reports it;
+ * `.column` is converted to UTF-16 code units so it agrees with
+ * {@link ShNode.loc}'s columns (mvdan/sh itself reports `column` as a byte
+ * count — see {@link ShParseErrorInfo.column}). That unconverted, raw
+ * position appears only inside `.message`, which is mvdan/sh's own
+ * formatted string, verbatim. Throws {@link ShInvalidDialectError} when
+ * {@link ParseOptions.dialect} is not a supported dialect. Throws
+ * {@link ShInternalError} for failures that should never happen given
+ * a correctly-behaving shim (malformed envelope, unexpected root node
+ * type, shim contract violations). Throws {@link ShParseMaxDepthError} if
+ * `text`'s conservatively estimated structural nesting depth exceeds the
+ * limit this bridge accepts — checked, and thrown, *before* `text` is ever
+ * handed to the WASM shim, since mvdan/sh's own parser has no recovery path
+ * for exhausting its stack on pathological nesting (see that error's doc
+ * comment and `parse-depth-guard.ts`).
+ *
+ * @public
+ */
+export declare function parseSync(text: string, options?: ParseOptions): ShFile;
+export {};
+//# sourceMappingURL=parse.d.ts.map

package/dist/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AACA,OAAO,EAA4B,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG1E,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,EAAE,MAAM,YAAY,CAAC;AAcrE,UAAU,iBAAiB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,YAAY;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,cAAc;IACtB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAoCD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAKxE;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,MAAM,CAsCtE"}

package/dist/parse.js

@@ -0,0 +1,125 @@
+import { ShInternalError, ShInvalidDialectError, ShParseError } from './errors.js';
+import { normalize, toUtf16Column } from './normalize.js';
+import { assertParseDepthWithinLimit } from './parse-depth-guard.js';
+import { callParse } from './wasm-instance.js';
+/**
+ * The full set of dialects {@link parseSync} accepts, in the order surfaced
+ * by {@link ShInvalidDialectError}'s message. Kept as a runtime value
+ * distinct from the {@link ShellDialect} union so `parseSync` can validate
+ * `options.dialect` before ever calling into the WASM shim.
+ */
+const SUPPORTED_SHELL_DIALECTS = ['bash', 'posix', 'mksh', 'bats', 'zsh'];
+function isSupportedShellDialect(value) {
+    return SUPPORTED_SHELL_DIALECTS.includes(value);
+}
+/**
+ * Checks that `value` is a plain object — rejects arrays, `null`, wrapped
+ * primitives, class instances, and symbol-keyed objects. `isResultEnvelope`
+ * and its field-level helpers below all validate `unknown` input coming
+ * straight out of `JSON.parse`, so this is the full-rigor check, not just
+ * `typeof value === 'object'`.
+ *
+ * @internal
+ */
+function isPlainObject(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.getPrototypeOf(value) === Object.prototype &&
+        Object.getOwnPropertySymbols(value).length === 0);
+}
+function isParseErrorPayload(value) {
+    return (isPlainObject(value) &&
+        typeof value.message === 'string' &&
+        typeof value.filename === 'string' &&
+        typeof value.line === 'number' &&
+        typeof value.column === 'number' &&
+        typeof value.offset === 'number');
+}
+function isErrorPayload(value) {
+    return isPlainObject(value) && typeof value.message === 'string';
+}
+/**
+ * @internal
+ */
+export function isResultEnvelope(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (value.parseError !== undefined && !isParseErrorPayload(value.parseError))
+        return false;
+    if (value.error !== undefined && !isErrorPayload(value.error))
+        return false;
+    return true;
+}
+function asShFile(node) {
+    if (node.type !== 'File') {
+        throw new ShInternalError(`bridge: expected root node of type "File", got "${node.type}"`);
+    }
+    if (!Array.isArray(node.stmts)) {
+        throw new ShInternalError('bridge: expected root node to have an array "stmts" field');
+    }
+    return node;
+}
+/**
+ * Synchronously parses shell source into a normalized AST.
+ *
+ * The first call instantiates the WASM shim synchronously (Node-only); the
+ * instance is reused across subsequent calls, so repeated calls do not
+ * re-instantiate (see design/ARCHITECTURE.md).
+ *
+ * Throws {@link ShParseError} on a shell syntax error, carrying the position
+ * mvdan/sh reported: `.line` is 1-based exactly as mvdan/sh reports it;
+ * `.column` is converted to UTF-16 code units so it agrees with
+ * {@link ShNode.loc}'s columns (mvdan/sh itself reports `column` as a byte
+ * count — see {@link ShParseErrorInfo.column}). That unconverted, raw
+ * position appears only inside `.message`, which is mvdan/sh's own
+ * formatted string, verbatim. Throws {@link ShInvalidDialectError} when
+ * {@link ParseOptions.dialect} is not a supported dialect. Throws
+ * {@link ShInternalError} for failures that should never happen given
+ * a correctly-behaving shim (malformed envelope, unexpected root node
+ * type, shim contract violations). Throws {@link ShParseMaxDepthError} if
+ * `text`'s conservatively estimated structural nesting depth exceeds the
+ * limit this bridge accepts — checked, and thrown, *before* `text` is ever
+ * handed to the WASM shim, since mvdan/sh's own parser has no recovery path
+ * for exhausting its stack on pathological nesting (see that error's doc
+ * comment and `parse-depth-guard.ts`).
+ *
+ * @public
+ */
+export function parseSync(text, options) {
+    const dialect = options?.dialect ?? 'bash';
+    const filename = options?.filename ?? 'input.sh';
+    if (!isSupportedShellDialect(dialect)) {
+        throw new ShInvalidDialectError(dialect, SUPPORTED_SHELL_DIALECTS);
+    }
+    assertParseDepthWithinLimit(text);
+    const raw = callParse(text, dialect, filename);
+    const result = JSON.parse(raw);
+    if (!isResultEnvelope(result)) {
+        throw new ShInternalError('bridge: WASM shim returned an unexpected payload shape');
+    }
+    if (result.parseError) {
+        // mvdan/sh reports `column` as a byte count on the source line, not a
+        // UTF-16 code unit count — inconsistent with ShNode.loc.column, which is
+        // always UTF-16 (see design/ARCHITECTURE.md's "Byte→UTF-16 conversion").
+        // Recompute it from `offset` (a byte offset from the start of the file,
+        // which every position mvdan/sh reports carries) via the same
+        // conversion `normalize` applies to every node, so a thrown
+        // ShParseError's column always agrees with the column a ShNode at that
+        // position would report.
+        const column = toUtf16Column(text, result.parseError.offset, result.parseError.line);
+        throw new ShParseError(result.parseError.message, {
+            line: result.parseError.line,
+            column,
+            filename: result.parseError.filename,
+        });
+    }
+    if (result.error) {
+        throw new ShInternalError(result.error.message);
+    }
+    if (result.file === undefined) {
+        throw new ShInternalError('bridge: WASM shim returned neither a file nor an error');
+    }
+    return asShFile(normalize(result.file, text));
+}
+//# sourceMappingURL=parse.js.map

package/dist/parse.js.map

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