sh-ast 0.7.0 → 0.9.0

package/dist/analyze.d.ts

@@ -210,7 +210,10 @@ export declare interface Argv0Resolution {
  * - `'embedded-command'` — a wrapper flag whose value structurally embeds
  *   the real command rather than naming it as a separate word (e.g.
  *   `env -S 'rm -rf /'` — see {@link WrapperSpec.unresolvableFlags}'s doc
- *   comment).
+ *   comment), or a shell interpreter's `-c` option (`bash -c 'rm x'`, see
+ *   {@link EmbeddedCommandInterpreterSpec}). In both cases the chain's
+ *   second-to-last element is the wrapper or interpreter word, so its name
+ *   stays available.
  * - `'ambiguous-assignment'` — a statically known assignment operand whose
  *   acceptance differs across supported utility implementations, such as
  *   `env =value cmd` (GNU/glibc accepts an empty name; BSD rejects it).
@@ -1292,6 +1295,38 @@ export declare interface DeclClause {
     Variant: Lit | null;
 }
 
+/**
+ * `sh-ast/analyze`'s default {@link EmbeddedCommandInterpreterSpec} table:
+ * the shells whose `-c` option makes {@link resolveArgv0} report
+ * `'embedded-command'`. Each entry's option grammar is hand-derived from the
+ * cited manual. Basic clusters and required operands were cross-checked on
+ * Linux bash 5.2.21, dash 0.5.12, zsh 5.9, ksh93u+m 1.0.8 and mksh R59.
+ * Long-option, termination and omitted-operand cases were checked on macOS
+ * bash 5.3.9 and 3.2.57 (also `/bin/sh`), Apple dash-16, zsh 5.9 and ksh93u+
+ * AJM 2012-08-01. Omitted `-o`/`+o` operands before another signed option
+ * were confirmed only on that ksh93u+ build, not ksh93u+m or mksh. Builds can
+ * differ: macOS's ksh93u+ differs from the cited 93u+m for `ksh -o c "echo X"`.
+ * The `sh` entry also models bash's long options because `sh` can be bash.
+ * Named options that change the option grammar itself (such as zsh's
+ * `shoptionletters`) are not interpreted; a custom table is needed for that
+ * grammar. It is data, not policy:
+ * it names no dangerous commands and a caller can replace or extend it via
+ * {@link ResolveArgv0Options.embeddedCommandInterpreters}; an empty array
+ * restores the behavior in which an interpreter is an ordinary effective
+ * command.
+ *
+ * Frozen, including each entry and its arrays.
+ *
+ * @see https://www.gnu.org/software/bash/manual/bash.html#Invoking-Bash — bash
+ * @see https://pubs.opengroup.org/onlinepubs/9699919799/utilities/sh.html — POSIX `sh`
+ * @see https://man7.org/linux/man-pages/man1/dash.1.html — dash(1)
+ * @see https://zsh.sourceforge.io/Doc/Release/Invocation-and-Startup.html — zsh
+ * @see https://github.com/ksh93/ksh — ksh93u+m `sh(1)`
+ * @see https://man.mirbsd.org/mksh.1 — mksh(1)
+ * @public
+ */
+export declare const DEFAULT_EMBEDDED_COMMAND_INTERPRETERS: readonly EmbeddedCommandInterpreterSpec[];
+
 /**
  * `sh-ast/analyze`'s default {@link WrapperSpec} table — every entry's
  * flag/operand handling is hand-derived from that wrapper's own manual
@@ -1374,6 +1409,115 @@ export declare const DplIn: 67;
  */
 export declare const DplOut: 68;
 
+/**
+ * A data-only description of one shell interpreter whose `-c` option makes the
+ * next operand a command string run by that shell (`bash -c 'rm x'`). Like
+ * `env -S`, the command that runs lives *inside* an operand, so
+ * {@link resolveArgv0} reports `'embedded-command'` instead of the
+ * interpreter's own name as the effective command.
+ * The selector `c` is reserved: exact-token fields (`noOperandLongOptions`,
+ * `operandLongOptions`, `optionTerminatorWords`) cannot contain `-c`.
+ *
+ * Only the option grammar needed to decide *whether `-c` is an option* is
+ * described: which options consume an operand word (so that `-o c` or
+ * `-o pipefail -c` are not misread) and where option parsing ends. Everything
+ * else about the interpreter — what its other options mean, whether a given
+ * option name is valid — is irrelevant to that decision and unmodeled; an
+ * invalid invocation that a real shell would reject is still reported
+ * conservatively, since nothing is guessed about what it would run.
+ *
+ * Option parsing ends at the first statically known word that is not an
+ * option, at `--`, at a lone `-`, or at a table-defined terminator; afterwards
+ * a word shaped like `-c` is an ordinary script operand. A dynamic word in
+ * option position leaves the question undecidable, so scanning stops and the interpreter is reported
+ * exactly as before (its own static name). In that case `static: true` means
+ * only that the interpreter's name is known; it does not mean the command is a
+ * plain shell invocation, because `bash "$f" -c x` runs `x` when `$f` is `-x`.
+ *
+ * This shape may grow new optional fields in a **minor** release; existing
+ * fields' meaning never changes.
+ *
+ * @public
+ */
+export declare interface EmbeddedCommandInterpreterSpec {
+    /**
+     * The interpreter's name, matched against a static command word's final
+     * path segment: `bash`, `/bin/bash` and `/usr/local/bin/bash` all match
+     * `['bash']`. Only the command word is reduced to its final segment;
+     * entries containing `/` (such as `['/bin/bash']`) are rejected with
+     * {@link ShAnalyzeInvalidWrapperSpecError}. Use `['bash']` to recognize
+     * path-qualified invocations. The first entry containing the segment wins.
+     *
+     * Unlike {@link WrapperSpec.names}, which tries exact names first and
+     * falls back to the final segment only for absolute paths, interpreter
+     * matching uses only the final segment, including for relative paths
+     * such as `./bash`. The question here is whether a command string is
+     * embedded, not which executable would be located.
+     */
+    readonly names: readonly string[];
+    /**
+     * Single option letters (without a sign) that take a name or value operand
+     * under both `-` and `+`, e.g. `['o']` for `-o pipefail` / `+o pipefail`.
+     * A letter listed here never selects the command string itself, so
+     * `bash -o c script` keeps `c` as an option *name*.
+     * The selector `c` is reserved and cannot be listed as an operand option;
+     * conflicting entries throw {@link ShAnalyzeInvalidWrapperSpecError}.
+     */
+    readonly operandOptions: readonly string[];
+    /**
+     * How an {@link EmbeddedCommandInterpreterSpec.operandOptions} letter
+     * receives its operand inside a clustered word:
+     *
+     * - `'separate-word'` — always the next word; remaining letters in the
+     *   cluster are still options (`bash -oc errexit 'cmd'` is `-o errexit -c`).
+     * - `'rest-of-cluster'` — the remainder of the word if any, else the next
+     *   word; later letters in the same word are part of the operand
+     *   (`zsh -oc` names an option `c`).
+     */
+    readonly operandAttachment: 'separate-word' | 'rest-of-cluster';
+    /**
+     * Letters from {@link EmbeddedCommandInterpreterSpec.operandOptions} whose
+     * separate operand may be omitted before a word beginning with `-` or `+`.
+     * An attached operand still belongs to the option. For example, ksh93u+
+     * treats `-o -c cmd` and `+o -c cmd` as an operand-free option listing
+     * followed by `-c`; bash, dash and zsh consume `-c` as the option name.
+     * A dynamic potential operand makes this distinction undecidable.
+     */
+    readonly optionalOperandOptions?: readonly string[];
+    /**
+     * No-operand letters that end option scanning after the current cluster,
+     * under either sign. Remaining letters in that cluster still take effect:
+     * zsh's `-b -c script` runs the file `-c`, but `-bc cmd` selects a string.
+     * These letters must not include `c` or an operand-taking letter.
+     */
+    readonly optionTerminatorLetters?: readonly string[];
+    /**
+     * Additional whole words that end option scanning, like zsh's `+` and `+-`.
+     * The terminator is not a command string; an already-selected `-c` needs
+     * a following word. `--` and a lone `-` are always terminators.
+     */
+    readonly optionTerminatorWords?: readonly string[];
+    /**
+     * Exact long-option words that take a separate operand, recognized before
+     * short-option clusters regardless of prefix: bash's `--rcfile FILE` and
+     * `-rcfile FILE`, or zsh's `--emulate sh`. A dynamic operand stops scanning
+     * because its expansion may produce multiple actual arguments.
+     */
+    readonly operandLongOptions?: readonly string[];
+    /**
+     * Exact long-option words with no operand, recognized before short-option
+     * clusters. Bash's `-restricted` and `-noprofile` are whole long options,
+     * not clusters containing `c` or `o`. Unlisted `--name` / `+-name` words
+     * are also treated as operand-free; option validity is not checked.
+     */
+    readonly noOperandLongOptions?: readonly string[];
+    /**
+     * `true` if the interpreter also treats `+c` as selecting the command
+     * string. Other shells do not select command mode with `+c`.
+     */
+    readonly plusCSelectsCommand?: boolean;
+}
+
 /**
  * Enumerates every command invocation (`CallExpr`) reachable from `root`,
  * with its resolved words ({@link resolveWord}) and the path used to reach
@@ -2705,7 +2849,7 @@ export declare const DplOut: 68;
   * command) or add their own (e.g. a project's `with-retry` helper) and
   * both directions are followed identically to any built-in entry.
   *
-  * **A statically-unknowable word is never guessed through** — three
+  * **A statically-unknowable word is never guessed through** — four
   * distinct cases all stop the chain immediately at that word rather than
   * falling back to any other guess:
   *
@@ -2726,6 +2870,30 @@ export declare const DplOut: 68;
   *    reports `effective: { static: false, reason: 'embedded-command' }`
   *    (see {@link WrapperSpec.unresolvableFlags}'s doc comment).
   *
+  * 4. The effective command is a shell interpreter
+  *    ({@link DEFAULT_EMBEDDED_COMMAND_INTERPRETERS}) invoked with `-c` —
+  *    `bash -c "$x"`, `sudo sh -ec ls` — and the command that runs is
+  *    inside the string operand. The result is the same
+  *    `'embedded-command'` shape `env -S` produces: the interpreter word is
+  *    `chain.at(-2)` and `chainIndices.at(-1)` is the option word that
+  *    selected `-c`. `bash script.sh`, `bash -e script.sh`, `bash -- -c`
+  *    and `bash -o c` are not `-c` invocations and resolve to `bash` as
+  *    before. A dynamic word in option position (`bash "$f" -c x`,
+  *    `bash -c"$y" x`) is undecidable, so the interpreter stays a static
+  *    `bash`: `static: true` then means only that the name is known, not that
+  *    the command is a plain shell invocation. The `-c` string itself is never
+  *    parsed.
+  *
+  * Known limits: the table models common option spellings, not a full
+  * emulation of each shell's option parser. Unusual spellings can be
+  * misclassified in either direction:
+  *
+  * - Bash/sh single-dash long options after a short option, e.g. `bash -e -rcfile M`.
+  * - `ksh -c +c M`, or a dynamic word after `-c` that expands to an option.
+  * - mksh's selector-bearing operands in `mksh -o -c M` and `mksh -o +c M`.
+  * - A lone `+` before `-c`, e.g. `bash + -c M`.
+  * - Zsh grammar switches, e.g. `zsh -o shoptionletters -b -c M`.
+  *
   * `VAR=val` shell-assignment prefixes on the `CallExpr` itself
   * (`CommandSite.node.Assigns`, e.g. `FOO=bar rm x`) are always skipped and
   * counted in {@link Argv0Resolution.assignmentsSkipped} — a mechanism
@@ -2740,7 +2908,8 @@ export declare const DplOut: 68;
   * least one argv word; see its doc comment), not a "malformed shell
   * source" case.
   * @throws {@link ShAnalyzeInvalidWrapperSpecError} if
-      * `options.transparentWrappers` contains a malformed entry (see
+      * `options.transparentWrappers` or `options.embeddedCommandInterpreters`
+      * contains a malformed entry (see
       * {@link ResolveArgv0Options.transparentWrappers}'s doc comment).
       * @public
       */
@@ -2767,6 +2936,19 @@ export declare const DplOut: 68;
        * flag matching.
        */
       readonly transparentWrappers?: readonly WrapperSpec[];
+      /**
+       * The shell interpreters whose `-c` operand is reported as an
+       * `'embedded-command'`. Defaults to
+       * {@link DEFAULT_EMBEDDED_COMMAND_INTERPRETERS}. Pass a replacement array to
+       * add or drop interpreters; an empty array disables the behavior, so every
+       * interpreter resolves as an ordinary effective command.
+       *
+       * Validated at the {@link resolveArgv0} boundary like
+       * {@link ResolveArgv0Options.transparentWrappers}: the table must be an
+       * array. A non-array value (including `null`) or malformed entry throws
+       * {@link ShAnalyzeInvalidWrapperSpecError}; only `undefined` uses defaults.
+       */
+      readonly embeddedCommandInterpreters?: readonly EmbeddedCommandInterpreterSpec[];
   }
 
   /**
@@ -4068,22 +4250,47 @@ export declare const DplOut: 68;
    */
   export declare interface WrapperSpec {
       /**
-       * The literal, exact argv0 text (after quote/escape removal) that
-       * identifies this wrapper — e.g. `['env']`. Matched only against a
-       * `static: true` word; see {@link WrapperSpec}'s doc comment.
+       * The command name that identifies this wrapper — e.g. `['env']`.
+       * Matched only against a `static: true` word; see {@link WrapperSpec}'s
+       * doc comment.
+       *
+       * Matching first searches the entire table for an exact name. Only when
+       * no exact entry exists does it try an absolute path's final segment:
        *
-       * Matching is **exact-name-only** — never basename matching. `sudo` does
-       * not match `/usr/bin/sudo` or `./sudo`; only a word whose *entire*
-       * resolved text equals one of `names` is recognized. This is a
-       * deliberate, narrower-than-real-world policy choice (a real shell would
-       * happily run `/usr/bin/sudo`), not an oversight: silently treating any
-       * path *ending in* a known wrapper name as that wrapper would be a
-       * different, broader matching policy this package isn't making on a
-       * caller's behalf. A caller who wants path-aware matching can express it
-       * explicitly via a custom {@link ResolveArgv0Options.transparentWrappers}
-       * table (e.g. `names: ['sudo', '/usr/bin/sudo']`).
+       * 1. Its entire resolved text (after quote/escape removal) equals one of
+       *    `names`: `env`, or a path a caller listed verbatim. An exact path
+       *    entry takes precedence over a plain-name entry even if listed later.
+       * 2. The spec does not declare {@link WrapperSpec.shellBuiltin | shellBuiltin: true},
+       *    and the word is an **absolute path** (starts with `/`) whose final segment
+       *    equals one of `names`: `/usr/bin/env`, `/usr/bin/sudo`, `/opt/x/nice`
+       *    and `/usr//bin/env` resolve as `env`, `sudo` and `nice`. The chain
+       *    keeps the word as written, so a consumer still sees the path.
+       *
+       * Relative paths and paths with a trailing slash do not use the
+       * final-segment fallback. They can still match an explicitly listed name,
+       * such as `./with-retry` or `/opt/with-retry/`. Custom plain names also
+       * acquire absolute-path aliases unless `shellBuiltin: true`; a path-only
+       * name does not acquire aliases for other paths with the same final segment.
+       *
+       * This is a lexical analysis assumption, not executable identity:
+       * `PATH` is not consulted and the filesystem is not read. Without an
+       * exact override, an unrelated executable named `/opt/mytools/env` uses
+       * the `env` entry's grammar. The chain preserves the original path so
+       * callers can apply their own policy. A word with an expansion
+       * (`"$dir/env"`) is not `static` and is never matched.
        */
       readonly names: readonly string[];
+      /**
+       * Whether this wrapper represents a shell builtin rather than an external
+       * utility. A path cannot reach a builtin: `/tmp/command` names an external
+       * executable, so its arguments must not be interpreted as builtin operands.
+       * When true, only exact entries in {@link WrapperSpec.names} match; the
+       * absolute-path final-segment fallback is disabled. Explicitly listed path
+       * entries still match exactly. False or omitted preserves utility matching.
+       * The defaults mark `command` and `exec`; custom tables may mark their own
+       * builtins, such as `builtin`.
+       */
+      readonly shellBuiltin?: boolean;
       /**
        * Legacy shorthand for {@link WrapperSpec.assignmentOperands}'s
        * `'shell-identifier'` grammar: skip statically resolved `NAME=value`

package/dist/errors.d.ts

@@ -50,41 +50,28 @@ export declare class ShAnalyzeMaxDepthError extends ShAstError {
     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.
+ * A whole-file parse operation exceeded the binding's native node-nesting budget.
+ * The maintained parser counts statement, word, and expression work, including
+ * iterative construction of deep operator trees. A refusal returns no partial
+ * File or position snapshot and leaves subsequent parse calls available.
  *
- * 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.
+ * This is a binding resource constraint, not an upstream grammar restriction.
+ * The fixed 128-unit policy can refuse valid deeply nested input. Units describe
+ * native node work, not actual Go/JavaScript frames or necessarily final AST
+ * depth. The empirical margin assumes an ordinary caller stack; arbitrary
+ * pre-existing JavaScript recursion can exhaust it. This does not establish
+ * safety for arbitrary caller-constructed trees or other recursive operations.
  *
  * @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). */
+    /** Fixed maximum native node-nesting units; 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`.
+     * Native node work at the rejected entry, greater than {@link ShParseMaxDepthError.maxDepth}.
+     * The historical field name is retained for compatibility; the value is no
+     * longer a lexical estimate and is not a count of runtime stack frames.
      */
     readonly estimatedDepth: number;
     constructor(maxDepth: number, estimatedDepth: number);

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAE9F;;;;;GAKG;AACH,8BAAsB,UAAW,SAAQ,KAAK;IAC5C,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CAChC;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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAE9F;;;;;GAKG;AACH,8BAAsB,UAAW,SAAQ,KAAK;IAC5C,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CAChC;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;;;;;;;;;;;;;;GAcG;AACH,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,QAAQ,CAAC,IAAI,4BAA4B;IACzC,wEAAwE;IACxE,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

@@ -55,45 +55,32 @@ export class ShAnalyzeMaxDepthError extends ShAstError {
     }
 }
 /**
- * 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.
+ * A whole-file parse operation exceeded the binding's native node-nesting budget.
+ * The maintained parser counts statement, word, and expression work, including
+ * iterative construction of deep operator trees. A refusal returns no partial
+ * File or position snapshot and leaves subsequent parse calls available.
  *
- * 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.
+ * This is a binding resource constraint, not an upstream grammar restriction.
+ * The fixed 128-unit policy can refuse valid deeply nested input. Units describe
+ * native node work, not actual Go/JavaScript frames or necessarily final AST
+ * depth. The empirical margin assumes an ordinary caller stack; arbitrary
+ * pre-existing JavaScript recursion can exhaust it. This does not establish
+ * safety for arbitrary caller-constructed trees or other recursive operations.
  *
  * @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). */
+    /** Fixed maximum native node-nesting units; 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`.
+     * Native node work at the rejected entry, greater than {@link ShParseMaxDepthError.maxDepth}.
+     * The historical field name is retained for compatibility; the value is no
+     * longer a lexical estimate and is not a count of runtime stack frames.
      */
     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".`);
+        super(`parseSync: native parser node work (${String(estimatedDepth)} units) exceeds the maximum this bridge accepts (${String(maxDepth)}) — refusing this input without a partial result.`);
         this.name = 'ShParseMaxDepthError';
         this.maxDepth = maxDepth;
         this.estimatedDepth = estimatedDepth;

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAE9F;;;;;GAKG;AACH,MAAM,OAAgB,UAAW,SAAQ,KAAK;CAG7C;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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAE9F;;;;;GAKG;AACH,MAAM,OAAgB,UAAW,SAAQ,KAAK;CAG7C;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;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,oBAAqB,SAAQ,UAAU;IACzC,IAAI,GAAG,wBAAwB,CAAC;IACzC,wEAAwE;IAC/D,QAAQ,CAAS;IAC1B;;;;OAIG;IACM,cAAc,CAAS;IAEhC,YAAY,QAAgB,EAAE,cAAsB;QAClD,KAAK,CACH,uCAAuC,MAAM,CAAC,cAAc,CAAC,oDAAoD,MAAM,CAAC,QAAQ,CAAC,mDAAmD,CACrL,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/sh-ast.d.ts

@@ -2263,8 +2263,9 @@ export declare interface ParseOptions {
 
 /**
  * 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.
+ * use synchronously initializes WASM. Native node-nesting work has a fixed binding
+ * resource budget; exceeding it throws {@link ShParseMaxDepthError}. Subsequent
+ * parse calls remain usable after that refusal.
  * The returned File and its Node subtrees are plain syntax data: ordinary
  * structuredClone(node), without transfers, makes an independent editable copy
  * while retaining position values, byte strings, typed nils and internal aliases.
@@ -2835,41 +2836,28 @@ export declare const Shl: 71;
 export declare const ShlAssgn: 57;
 
 /**
- * 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.
+ * A whole-file parse operation exceeded the binding's native node-nesting budget.
+ * The maintained parser counts statement, word, and expression work, including
+ * iterative construction of deep operator trees. A refusal returns no partial
+ * File or position snapshot and leaves subsequent parse calls available.
+ *
+ * This is a binding resource constraint, not an upstream grammar restriction.
+ * The fixed 128-unit policy can refuse valid deeply nested input. Units describe
+ * native node work, not actual Go/JavaScript frames or necessarily final AST
+ * depth. The empirical margin assumes an ordinary caller stack; arbitrary
+ * pre-existing JavaScript recursion can exhaust it. This does not establish
+ * safety for arbitrary caller-constructed trees or other recursive operations.
  *
  * @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). */
+    /** Fixed maximum native node-nesting units; 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`.
+     * Native node work at the rejected entry, greater than {@link ShParseMaxDepthError.maxDepth}.
+     * The historical field name is retained for compatibility; the value is no
+     * longer a lexical estimate and is not a count of runtime stack frames.
      */
     readonly estimatedDepth: number;
     constructor(maxDepth: number, estimatedDepth: number);

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

@@ -1 +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;;;;;;;GAOG;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;AAuED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,OAAO,GACjB,gBAAgB,CA4DlB"}
+{"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;;;;;;;GAOG;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;AAyFD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,OAAO,GACjB,gBAAgB,CA4DlB"}

package/dist/syntax-snapshot.js

@@ -31,9 +31,7 @@ function visitNodes(file, observe) {
             observe(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;
+        for (const name of childFields(value.Type)) {
             const child = value[name];
             if (Array.isArray(child))
                 child.forEach(visit);
@@ -43,6 +41,23 @@ function visitNodes(file, observe) {
     };
     visit(file);
 }
+/**
+ * Child-bearing (struct or interface) field names per record type, in schema
+ * order. The generated schema is immutable, so each list is derived once rather
+ * than re-filtering every field of every visited record.
+ */
+const CHILD_FIELDS = new Map();
+/** Returns the cached child field names for a type known to be in the schema. */
+function childFields(type) {
+    let names = CHILD_FIELDS.get(type);
+    if (names === undefined) {
+        names = Object.entries(SYNTAX_SCHEMA[type].fields)
+            .filter(([, field]) => field.kind === 'struct' || field.kind === 'interface')
+            .map(([name]) => name);
+        CHILD_FIELDS.set(type, names);
+    }
+    return names;
+}
 /** Own byte-bearing failures so neither transport holders nor catchers can alter captures. */
 function copyError(error) {
     return typeof error === 'string' ? error : error.slice();

package/dist/syntax-snapshot.js.map

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

package/dist/syntax-wire.d.ts

@@ -30,4 +30,16 @@ export declare function isSyntaxPos(value: unknown): value is SyntaxPos;
 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;
+/**
+ * Validates a parse response's File exactly as isSyntaxFile does while rebuilding
+ * its positions. The bridge spells each File position as a compact
+ * [Offset, Line, Col, Flags] tuple (flags: bit 0 IsValid, bit 1 IsRecovered,
+ * bit 2 OffsetOverflow) because positions are most of a parse response. Each
+ * tuple is replaced in place by the identical six-member SyntaxPos record, in
+ * its usual member order, and then checked like any other position. Only a
+ * freshly decoded response may be passed: the graph is mutated, and a false
+ * result can leave it partly restored, so callers must discard it.
+ * @internal
+ */
+export declare function restoreSyntaxFile(value: unknown): value is File;
 //# sourceMappingURL=syntax-wire.d.ts.map

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

@@ -1 +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;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAyChD;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"}
+{"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;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CA0ChD;AAsCD,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;AA+GD,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;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,CAE/D"}