sh-ast 0.0.0 → 0.2.0

package/dist/deep-freeze.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Recursively freezes `value` and every object/array it (transitively)
+ * contains, so a frozen shared table's immutability holds at every level —
+ * not just its own top-level keys — rather than relying on every caller to
+ * treat it as read-only by convention.
+ *
+ * Generic, structural recursion over an unknown shape needs a cast to index
+ * into `value`'s own properties; contained to this one small, well-tested
+ * utility rather than spread across every table that uses it.
+ *
+ * @internal
+ */
+export declare function deepFreeze<T>(value: T): Readonly<T>;
+//# sourceMappingURL=deep-freeze.d.ts.map

package/dist/deep-freeze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-freeze.d.ts","sourceRoot":"","sources":["../src/deep-freeze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAWnD"}

package/dist/deep-freeze.js

@@ -0,0 +1,25 @@
+/**
+ * Recursively freezes `value` and every object/array it (transitively)
+ * contains, so a frozen shared table's immutability holds at every level —
+ * not just its own top-level keys — rather than relying on every caller to
+ * treat it as read-only by convention.
+ *
+ * Generic, structural recursion over an unknown shape needs a cast to index
+ * into `value`'s own properties; contained to this one small, well-tested
+ * utility rather than spread across every table that uses it.
+ *
+ * @internal
+ */
+export function deepFreeze(value) {
+    if (value !== null && (typeof value === 'object' || typeof value === 'function')) {
+        for (const key of Object.getOwnPropertyNames(value)) {
+            const prop = value[key];
+            if (prop !== null && typeof prop === 'object') {
+                deepFreeze(prop);
+            }
+        }
+        Object.freeze(value);
+    }
+    return value;
+}
+//# sourceMappingURL=deep-freeze.js.map

package/dist/deep-freeze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-freeze.js","sourceRoot":"","sources":["../src/deep-freeze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CAAI,KAAQ;IACpC,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,UAAU,CAAC,EAAE,CAAC;QACjF,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,GAAI,KAAiC,CAAC,GAAG,CAAC,CAAC;YACrD,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC9C,UAAU,CAAC,IAAI,CAAC,CAAC;YACnB,CAAC;QACH,CAAC;QACD,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,180 @@
+import type { ShellDialect } from './types.js';
+/**
+ * Common base class for every error this package throws — originally just
+ * {@link sh-ast#parseSync | parseSync}'s errors, now also the
+ * `sh-ast/analyze` layer's (see {@link ShAnalyzeMaxDepthError},
+ * {@link ShAnalyzeInvalidWrapperSpecError}). Provides a stable, documented
+ * `code` discriminator (e.g. `"SH_AST_PARSE_ERROR"`) alongside the usual
+ * `instanceof` narrowing, so consumers can branch on failure kind
+ * programmatically without parsing `.message` strings. Never thrown directly
+ * — only via its concrete subclasses
+ * ({@link sh-ast#ShParseError | ShParseError},
+ * {@link sh-ast#ShInvalidDialectError | ShInvalidDialectError},
+ * {@link sh-ast#ShInternalError | ShInternalError},
+ * {@link ShAnalyzeMaxDepthError},
+ * {@link sh-ast#ShParseMaxDepthError | ShParseMaxDepthError},
+ * {@link ShAnalyzeInvalidWrapperSpecError}).
+ *
+ * Re-exported from `sh-ast/analyze` as well as the root `sh-ast` entry
+ * point (see #23) — every subclass thrown by `sh-ast/analyze`'s own
+ * functions extends this, so a consumer of that subpath alone can
+ * `catch`/reference the base without also importing from root.
+ *
+ * @public
+ */
+export declare abstract class ShAstError extends Error {
+    /**
+     * Stable, machine-readable discriminator for this error kind. Distinct
+     * per subclass and will not change once published.
+     */
+    abstract readonly code: string;
+}
+/**
+ * Position info attached to a {@link ShParseError}.
+ *
+ * @public
+ */
+export interface ShParseErrorInfo {
+    /** 1-based line number, exactly as reported by mvdan/sh. */
+    line: number;
+    /**
+     * 1-based column number, in **UTF-16 code units** — converted from
+     * mvdan/sh's own byte-counting column so it agrees with
+     * {@link ShNode.loc}'s columns (mvdan/sh reports `column` as a byte count
+     * on the source line, not a UTF-16 code unit count; see
+     * design/ARCHITECTURE.md's "Byte→UTF-16 conversion"). For ASCII-only
+     * source text this is numerically identical to mvdan/sh's own column.
+     */
+    column: number;
+    /** The filename used for the parse (see {@link ParseOptions.filename}). */
+    filename: string;
+}
+/**
+ * Thrown by {@link parseSync} when shell source fails to parse. Carries the
+ * real position mvdan/sh reported — never 1:1 placeholders: `.line` is
+ * 1-based exactly as mvdan/sh reports it, and `.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 on the source line — see
+ * {@link ShParseErrorInfo.column}). The unconverted, raw byte-column
+ * position appears only inside `.message`, mvdan/sh's own formatted string,
+ * verbatim.
+ *
+ * @public
+ */
+export declare class ShParseError extends ShAstError {
+    readonly code = "SH_AST_PARSE_ERROR";
+    readonly line: number;
+    readonly column: number;
+    readonly filename: string;
+    constructor(message: string, info: ShParseErrorInfo);
+}
+/**
+ * Thrown by {@link parseSync} when {@link ParseOptions.dialect} is not one
+ * of the supported {@link ShellDialect} values. Carries the rejected value
+ * as `.dialect`; `.message` lists the supported dialects. A foreseeable,
+ * actionable user mistake — never an instance of {@link ShParseError}.
+ *
+ * @public
+ */
+export declare class ShInvalidDialectError extends ShAstError {
+    readonly code = "SH_AST_INVALID_DIALECT";
+    /** The rejected dialect value, exactly as passed to {@link parseSync}. */
+    readonly dialect: string;
+    constructor(dialect: string, supportedDialects: readonly ShellDialect[]);
+}
+/**
+ * Thrown by {@link parseSync} for failures that should never happen given a
+ * correctly-behaving WASM shim: a malformed result envelope, an unexpected
+ * root node type, or any other shim contract violation. Distinct from
+ * {@link ShInvalidDialectError} and {@link ShParseError}, both of which
+ * indicate a foreseeable, actionable user mistake rather than an internal
+ * defect.
+ *
+ * @public
+ */
+export declare class ShInternalError extends ShAstError {
+    readonly code = "SH_AST_INTERNAL";
+    constructor(message: string);
+}
+/**
+ * Thrown by `sh-ast/analyze`'s `enumerateCommands` when a tree's genuinely
+ * nested structure — subshells within subshells, chained command/process
+ * substitutions, deeply nested `if`/`case`/loop/function/`time`/`{ }`
+ * bodies, deeply chained `elif` — exceeds its defensive recursion-depth
+ * guard. **Not** thrown for a long *linear* chain (`|`/`|&`/`&&`/`||` of
+ * any realistic length): `enumerateCommands` traverses those iteratively,
+ * so chain length alone never grows this guard's depth counter — only
+ * genuine tree nesting does.
+ *
+ * `enumerateCommands` deliberately fails closed here rather than returning
+ * a truncated, partial result: a partial `CommandSite[]` silently omits
+ * real command sites, which is a false negative for a permission-hook-style
+ * consumer that treats "command not found in the enumeration" as "nothing
+ * to worry about" — an explicit, documented throw is safer than a silent
+ * under-report. Gate-style consumers should treat this error as `deny`,
+ * not fall back to "no commands found, so allow".
+ *
+ * @public
+ */
+export declare class ShAnalyzeMaxDepthError extends ShAstError {
+    readonly code = "SH_AST_ANALYZE_MAX_DEPTH";
+    /** The maximum nesting depth `enumerateCommands` supports; the same value every time (not caller-configurable). */
+    readonly maxDepth: number;
+    constructor(maxDepth: number);
+}
+/**
+ * Thrown by {@link parseSync} when `text`'s conservatively estimated
+ * structural nesting depth (subshells, command/process substitutions,
+ * `if`/`case`/loop/function bodies, `{ }` blocks, backtick or `$(...)`
+ * command substitution, `$((...))` arithmetic — see
+ * `parse-depth-guard.ts`'s module doc for the exact heuristic) exceeds the
+ * limit `parseSync` accepts. Thrown *before* `text` is ever handed to the
+ * WASM shim: mvdan/sh's own recursive-descent parser has no recovery path
+ * for exhausting its call stack on pathologically deep input (a stack
+ * overflow deep inside the shared WASM instance is not a normal, catchable
+ * JS error the way a parse syntax error is), so this bridge estimates the
+ * risk up front and fails closed with a typed error instead of ever making
+ * that call — the shared WASM instance is therefore never put at risk of
+ * wedging on this class of input; a `parseSync` call right after catching
+ * this error works exactly as it would if this input had never been
+ * attempted.
+ *
+ * Like {@link ShAnalyzeMaxDepthError}, this is pathological-input
+ * protection, not a normal-usage ceiling: a legitimately deep (but
+ * realistic) script parses fine. The estimate can *over*-count relative to
+ * mvdan/sh's real grammar (rejecting some legitimate-but-unusually-deep
+ * input) but is designed to never *under*-count relative to it — see
+ * `parse-depth-guard.ts` for the documented false-positive sources this
+ * trades off against ever letting a genuinely crash-inducing input
+ * through.
+ *
+ * @public
+ */
+export declare class ShParseMaxDepthError extends ShAstError {
+    readonly code = "SH_AST_PARSE_MAX_DEPTH";
+    /** The maximum structural nesting depth `parseSync` accepts; the same value every time (not caller-configurable). */
+    readonly maxDepth: number;
+    /**
+     * The conservatively estimated nesting depth that tripped the guard.
+     * Not necessarily `text`'s "true" nesting depth under a real parse — see
+     * {@link ShParseMaxDepthError}'s doc comment — only ever `> maxDepth`.
+     */
+    readonly estimatedDepth: number;
+    constructor(maxDepth: number, estimatedDepth: number);
+}
+/**
+ * Thrown by `sh-ast/analyze`'s `resolveArgv0` when a caller-supplied
+ * `options.transparentWrappers` array contains a malformed `WrapperSpec`
+ * entry — e.g. a non-array or empty `names`, or a flag field that isn't an
+ * array of strings. Fails closed with a clear, specific message at the
+ * point the malformed table is supplied, rather than letting the bad shape
+ * reach flag-matching logic and surface as a confusing native `TypeError`
+ * (or, worse, a silently wrong match) far from its actual cause.
+ *
+ * @public
+ */
+export declare class ShAnalyzeInvalidWrapperSpecError extends ShAstError {
+    readonly code = "SH_AST_ANALYZE_INVALID_WRAPPER_SPEC";
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8BAAsB,UAAW,SAAQ,KAAK;IAC5C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,YAAa,SAAQ,UAAU;IAC1C,QAAQ,CAAC,IAAI,wBAAwB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB;CAOpD;AAED;;;;;;;GAOG;AACH,qBAAa,qBAAsB,SAAQ,UAAU;IACnD,QAAQ,CAAC,IAAI,4BAA4B;IACzC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,SAAS,YAAY,EAAE;CAOxE;AAED;;;;;;;;;GASG;AACH,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,QAAQ,CAAC,IAAI,qBAAqB;gBAEtB,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,sBAAuB,SAAQ,UAAU;IACpD,QAAQ,CAAC,IAAI,8BAA8B;IAC3C,mHAAmH;IACnH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM;CAO7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,QAAQ,CAAC,IAAI,4BAA4B;IACzC,qHAAqH;IACrH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;gBAEpB,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM;CAQrD;AAED;;;;;;;;;;GAUG;AACH,qBAAa,gCAAiC,SAAQ,UAAU;IAC9D,QAAQ,CAAC,IAAI,yCAAyC;gBAE1C,OAAO,EAAE,MAAM;CAI5B"}

package/dist/errors.js

@@ -0,0 +1,179 @@
+/**
+ * Common base class for every error this package throws — originally just
+ * {@link sh-ast#parseSync | parseSync}'s errors, now also the
+ * `sh-ast/analyze` layer's (see {@link ShAnalyzeMaxDepthError},
+ * {@link ShAnalyzeInvalidWrapperSpecError}). Provides a stable, documented
+ * `code` discriminator (e.g. `"SH_AST_PARSE_ERROR"`) alongside the usual
+ * `instanceof` narrowing, so consumers can branch on failure kind
+ * programmatically without parsing `.message` strings. Never thrown directly
+ * — only via its concrete subclasses
+ * ({@link sh-ast#ShParseError | ShParseError},
+ * {@link sh-ast#ShInvalidDialectError | ShInvalidDialectError},
+ * {@link sh-ast#ShInternalError | ShInternalError},
+ * {@link ShAnalyzeMaxDepthError},
+ * {@link sh-ast#ShParseMaxDepthError | ShParseMaxDepthError},
+ * {@link ShAnalyzeInvalidWrapperSpecError}).
+ *
+ * Re-exported from `sh-ast/analyze` as well as the root `sh-ast` entry
+ * point (see #23) — every subclass thrown by `sh-ast/analyze`'s own
+ * functions extends this, so a consumer of that subpath alone can
+ * `catch`/reference the base without also importing from root.
+ *
+ * @public
+ */
+export class ShAstError extends Error {
+}
+/**
+ * Thrown by {@link parseSync} when shell source fails to parse. Carries the
+ * real position mvdan/sh reported — never 1:1 placeholders: `.line` is
+ * 1-based exactly as mvdan/sh reports it, and `.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 on the source line — see
+ * {@link ShParseErrorInfo.column}). The unconverted, raw byte-column
+ * position appears only inside `.message`, mvdan/sh's own formatted string,
+ * verbatim.
+ *
+ * @public
+ */
+export class ShParseError extends ShAstError {
+    code = 'SH_AST_PARSE_ERROR';
+    line;
+    column;
+    filename;
+    constructor(message, info) {
+        super(message);
+        this.name = 'ShParseError';
+        this.line = info.line;
+        this.column = info.column;
+        this.filename = info.filename;
+    }
+}
+/**
+ * Thrown by {@link parseSync} when {@link ParseOptions.dialect} is not one
+ * of the supported {@link ShellDialect} values. Carries the rejected value
+ * as `.dialect`; `.message` lists the supported dialects. A foreseeable,
+ * actionable user mistake — never an instance of {@link ShParseError}.
+ *
+ * @public
+ */
+export class ShInvalidDialectError extends ShAstError {
+    code = 'SH_AST_INVALID_DIALECT';
+    /** The rejected dialect value, exactly as passed to {@link parseSync}. */
+    dialect;
+    constructor(dialect, supportedDialects) {
+        super(`bridge: unrecognized shell dialect "${dialect}"; supported dialects are: ${supportedDialects.join(', ')}`);
+        this.name = 'ShInvalidDialectError';
+        this.dialect = dialect;
+    }
+}
+/**
+ * Thrown by {@link parseSync} for failures that should never happen given a
+ * correctly-behaving WASM shim: a malformed result envelope, an unexpected
+ * root node type, or any other shim contract violation. Distinct from
+ * {@link ShInvalidDialectError} and {@link ShParseError}, both of which
+ * indicate a foreseeable, actionable user mistake rather than an internal
+ * defect.
+ *
+ * @public
+ */
+export class ShInternalError extends ShAstError {
+    code = 'SH_AST_INTERNAL';
+    constructor(message) {
+        super(message);
+        this.name = 'ShInternalError';
+    }
+}
+/**
+ * Thrown by `sh-ast/analyze`'s `enumerateCommands` when a tree's genuinely
+ * nested structure — subshells within subshells, chained command/process
+ * substitutions, deeply nested `if`/`case`/loop/function/`time`/`{ }`
+ * bodies, deeply chained `elif` — exceeds its defensive recursion-depth
+ * guard. **Not** thrown for a long *linear* chain (`|`/`|&`/`&&`/`||` of
+ * any realistic length): `enumerateCommands` traverses those iteratively,
+ * so chain length alone never grows this guard's depth counter — only
+ * genuine tree nesting does.
+ *
+ * `enumerateCommands` deliberately fails closed here rather than returning
+ * a truncated, partial result: a partial `CommandSite[]` silently omits
+ * real command sites, which is a false negative for a permission-hook-style
+ * consumer that treats "command not found in the enumeration" as "nothing
+ * to worry about" — an explicit, documented throw is safer than a silent
+ * under-report. Gate-style consumers should treat this error as `deny`,
+ * not fall back to "no commands found, so allow".
+ *
+ * @public
+ */
+export class ShAnalyzeMaxDepthError extends ShAstError {
+    code = 'SH_AST_ANALYZE_MAX_DEPTH';
+    /** The maximum nesting depth `enumerateCommands` supports; the same value every time (not caller-configurable). */
+    maxDepth;
+    constructor(maxDepth) {
+        super(`enumerateCommands: exceeded the maximum supported structural nesting depth (${String(maxDepth)} frames) — refusing to return a partial result. Treat this as a deny signal, not "no commands found".`);
+        this.name = 'ShAnalyzeMaxDepthError';
+        this.maxDepth = maxDepth;
+    }
+}
+/**
+ * Thrown by {@link parseSync} when `text`'s conservatively estimated
+ * structural nesting depth (subshells, command/process substitutions,
+ * `if`/`case`/loop/function bodies, `{ }` blocks, backtick or `$(...)`
+ * command substitution, `$((...))` arithmetic — see
+ * `parse-depth-guard.ts`'s module doc for the exact heuristic) exceeds the
+ * limit `parseSync` accepts. Thrown *before* `text` is ever handed to the
+ * WASM shim: mvdan/sh's own recursive-descent parser has no recovery path
+ * for exhausting its call stack on pathologically deep input (a stack
+ * overflow deep inside the shared WASM instance is not a normal, catchable
+ * JS error the way a parse syntax error is), so this bridge estimates the
+ * risk up front and fails closed with a typed error instead of ever making
+ * that call — the shared WASM instance is therefore never put at risk of
+ * wedging on this class of input; a `parseSync` call right after catching
+ * this error works exactly as it would if this input had never been
+ * attempted.
+ *
+ * Like {@link ShAnalyzeMaxDepthError}, this is pathological-input
+ * protection, not a normal-usage ceiling: a legitimately deep (but
+ * realistic) script parses fine. The estimate can *over*-count relative to
+ * mvdan/sh's real grammar (rejecting some legitimate-but-unusually-deep
+ * input) but is designed to never *under*-count relative to it — see
+ * `parse-depth-guard.ts` for the documented false-positive sources this
+ * trades off against ever letting a genuinely crash-inducing input
+ * through.
+ *
+ * @public
+ */
+export class ShParseMaxDepthError extends ShAstError {
+    code = 'SH_AST_PARSE_MAX_DEPTH';
+    /** The maximum structural nesting depth `parseSync` accepts; the same value every time (not caller-configurable). */
+    maxDepth;
+    /**
+     * The conservatively estimated nesting depth that tripped the guard.
+     * Not necessarily `text`'s "true" nesting depth under a real parse — see
+     * {@link ShParseMaxDepthError}'s doc comment — only ever `> maxDepth`.
+     */
+    estimatedDepth;
+    constructor(maxDepth, estimatedDepth) {
+        super(`parseSync: input's estimated structural nesting depth (${String(estimatedDepth)}+ frames) exceeds the maximum this bridge accepts (${String(maxDepth)}) — refusing to hand this input to the WASM parser, which would risk exhausting its call stack uncatchably. Treat this as a deny signal, not "input looks fine".`);
+        this.name = 'ShParseMaxDepthError';
+        this.maxDepth = maxDepth;
+        this.estimatedDepth = estimatedDepth;
+    }
+}
+/**
+ * Thrown by `sh-ast/analyze`'s `resolveArgv0` when a caller-supplied
+ * `options.transparentWrappers` array contains a malformed `WrapperSpec`
+ * entry — e.g. a non-array or empty `names`, or a flag field that isn't an
+ * array of strings. Fails closed with a clear, specific message at the
+ * point the malformed table is supplied, rather than letting the bad shape
+ * reach flag-matching logic and surface as a confusing native `TypeError`
+ * (or, worse, a silently wrong match) far from its actual cause.
+ *
+ * @public
+ */
+export class ShAnalyzeInvalidWrapperSpecError extends ShAstError {
+    code = 'SH_AST_ANALYZE_INVALID_WRAPPER_SPEC';
+    constructor(message) {
+        super(`resolveArgv0: invalid transparentWrappers entry — ${message}`);
+        this.name = 'ShAnalyzeInvalidWrapperSpecError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAgB,UAAW,SAAQ,KAAK;CAM7C;AAuBD;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,YAAa,SAAQ,UAAU;IACjC,IAAI,GAAG,oBAAoB,CAAC;IAC5B,IAAI,CAAS;IACb,MAAM,CAAS;IACf,QAAQ,CAAS;IAE1B,YAAY,OAAe,EAAE,IAAsB;QACjD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAChC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,qBAAsB,SAAQ,UAAU;IAC1C,IAAI,GAAG,wBAAwB,CAAC;IACzC,0EAA0E;IACjE,OAAO,CAAS;IAEzB,YAAY,OAAe,EAAE,iBAA0C;QACrE,KAAK,CACH,uCAAuC,OAAO,8BAA8B,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3G,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,eAAgB,SAAQ,UAAU;IACpC,IAAI,GAAG,iBAAiB,CAAC;IAElC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,sBAAuB,SAAQ,UAAU;IAC3C,IAAI,GAAG,0BAA0B,CAAC;IAC3C,mHAAmH;IAC1G,QAAQ,CAAS;IAE1B,YAAY,QAAgB;QAC1B,KAAK,CACH,+EAA+E,MAAM,CAAC,QAAQ,CAAC,uGAAuG,CACvM,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,oBAAqB,SAAQ,UAAU;IACzC,IAAI,GAAG,wBAAwB,CAAC;IACzC,qHAAqH;IAC5G,QAAQ,CAAS;IAC1B;;;;OAIG;IACM,cAAc,CAAS;IAEhC,YAAY,QAAgB,EAAE,cAAsB;QAClD,KAAK,CACH,0DAA0D,MAAM,CAAC,cAAc,CAAC,sDAAsD,MAAM,CAAC,QAAQ,CAAC,kKAAkK,CACzT,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;IACvC,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,gCAAiC,SAAQ,UAAU;IACrD,IAAI,GAAG,qCAAqC,CAAC;IAEtD,YAAY,OAAe;QACzB,KAAK,CAAC,qDAAqD,OAAO,EAAE,CAAC,CAAC;QACtE,IAAI,CAAC,IAAI,GAAG,kCAAkC,CAAC;IACjD,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { parseSync } from './parse.js';
+export { ShAnalyzeInvalidWrapperSpecError, ShAnalyzeMaxDepthError, ShAstError, ShInternalError, ShInvalidDialectError, ShParseError, ShParseMaxDepthError, } from './errors.js';
+export type { ShParseErrorInfo } from './errors.js';
+export type { ParseOptions, Position, ShellDialect, ShFile, ShNode } from './types.js';
+export { visitorKeys } from './visitor-keys.js';
+export { walk } from './walk.js';
+/**
+ * Strongly-typed `ShNode` subtypes for every mvdan/sh node type — generated
+ * by `tools/gen-visitor-keys` alongside {@link visitorKeys} (see
+ * design/ARCHITECTURE.md, "The schema table is generated, not
+ * hand-written"). {@link ShNode}'s index signature remains the base
+ * contract; these are an additive, opt-in stronger typing for consumers
+ * that want e.g. `ShNodes.ShCallExprNode` instead of a generic `ShNode`.
+ *
+ * @public
+ */
+export type * as ShNodes from '../generated/node-types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EACL,gCAAgC,EAChC,sBAAsB,EACtB,UAAU,EACV,eAAe,EACf,qBAAqB,EACrB,YAAY,EACZ,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;;;;;GASG;AACH,YAAY,KAAK,OAAO,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { parseSync } from './parse.js';
+export { ShAnalyzeInvalidWrapperSpecError, ShAnalyzeMaxDepthError, ShAstError, ShInternalError, ShInvalidDialectError, ShParseError, ShParseMaxDepthError, } from './errors.js';
+export { visitorKeys } from './visitor-keys.js';
+export { walk } from './walk.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EACL,gCAAgC,EAChC,sBAAsB,EACtB,UAAU,EACV,eAAe,EACf,qBAAqB,EACrB,YAAY,EACZ,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC"}

package/dist/normalize.d.ts

@@ -0,0 +1,52 @@
+import type { ShNode } from './types.js';
+/**
+ * A JSON value as produced by `JSON.parse`.
+ *
+ * @internal
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Builds a byte-offset -> UTF-16-index lookup for `text`. mvdan/sh reports
+ * byte offsets; ESLint (and JavaScript strings generally) index by UTF-16
+ * code unit, so every position needs this conversion. Throws if asked to
+ * convert an offset that does not fall on a UTF-8 code-point boundary — an
+ * invariant every offset the parser emits must satisfy (see
+ * design/ARCHITECTURE.md's "Serialization contract").
+ *
+ * @internal
+ */
+export declare function makeByteToUtf16(text: string): (byteOffset: number) => number;
+/**
+ * Converts a byte offset and the 1-based line mvdan/sh already computed for
+ * it into a 1-based, UTF-16-code-unit column — the same conversion
+ * `normalize` applies to every node's `loc.start`/`loc.end` below, extracted
+ * so a parse error's reported position (see `errors.ts`'s
+ * `ShParseErrorInfo`) can use the identical algorithm instead of the raw
+ * byte-counting column mvdan/sh itself reports. See design/ARCHITECTURE.md's
+ * "Byte→UTF-16 conversion".
+ *
+ * @internal
+ */
+export declare function toUtf16Column(text: string, byteOffset: number, line: number): number;
+/**
+ * Normalizes mvdan/sh's typedjson tree into the shape ESLint expects: every
+ * node gets `type`, `range` (UTF-16), `loc` (1-based, UTF-16 columns), and
+ * every other field copied over with its name lowercased. See
+ * design/ARCHITECTURE.md's "Normalized node shape".
+ *
+ * Three of mvdan/sh's struct types — `Slice`, `Replace`, `Expansion`, all
+ * reachable only via `ParamExp.Slice`/`.Repl`/`.Exp` — do not implement
+ * `syntax.Node` (no `Pos()`/`End()`), so typedjson never gives them a `Pos`/
+ * `End` pair, let alone a `Type` discriminator. They still hold real child
+ * nodes (`Slice.Offset`/`.Length`, `Replace.Orig`/`.With`,
+ * `Expansion.Word`), so dropping them would silently lose that subtree (see
+ * issue #13 — `${USER:-nobody}`'s `nobody` literal). This function
+ * synthesizes a `type`/`range`/`loc` for these from their own children's
+ * already-computed positions instead, via `walkSynthetic` below.
+ *
+ * @internal
+ */
+export declare function normalize(root: JsonValue, text: string): ShNode;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAY,MAAM,EAAE,MAAM,YAAY,CAAC;AAkBnD;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACnB,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAoEhF;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAsB5E;AAkBD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIpF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAsI/D"}