sh-ast 0.1.0 → 0.2.0

package/dist/analyze.d.ts

@@ -1,3 +1,100 @@
+/**
+ * The result of statically resolving one position in an
+ * {@link Argv0Resolution.chain}: either an ordinary {@link WordResolution}
+ * (from `resolveWord`) or an {@link Argv0UnresolvedWord} (a `resolveArgv0`-
+ * level "we don't know", distinct from any reason `resolveWord` itself
+ * would report).
+ *
+ * @public
+ */
+export declare type Argv0ChainWord = WordResolution | Argv0UnresolvedWord;
+
+/**
+ * The result of following a {@link CommandSite}'s argv0 through zero or
+ * more transparent wrappers to the effective command actually invoked.
+ * Facts only — no safety verdict; see {@link resolveArgv0}'s doc comment.
+ *
+ * @public
+ */
+export declare interface Argv0Resolution {
+    /**
+     * Every word resolved along the way, outermost wrapper first, ending
+     * with {@link Argv0Resolution.effective} — e.g. for
+     * `nohup env A=1 command rm x` this is the four resolutions for
+     * `nohup`, `env`, `command`, `rm`, in that order. Always has at least
+     * one element.
+     */
+    readonly chain: readonly Argv0ChainWord[];
+    /**
+     * The last element of {@link Argv0Resolution.chain} — the effective
+     * command, or, if resolution hit a statically-unknowable word anywhere
+     * along the chain (an expansion, a glob, an unrecognized flag, an
+     * embedded-command operand, …), that unknowable result itself.
+     * **A `static: false` word is never guessed through**: the moment one is
+     * reached (whether at argv0, several wrappers deep, or synthesized by
+     * `resolveArgv0` itself for an unrecognized flag), it becomes
+     * `effective` and the chain stops — this is the security-relevant
+     * guarantee that makes `sudo -u x "$prog"` report an unknowable
+     * effective command rather than silently treating `sudo` itself as the
+     * answer, and makes `sudo -D /tmp rm x` (an unrecognized `sudo` flag)
+     * report `'unknown-flag'` rather than misreporting `rm` — or, worse,
+     * `/tmp` — as the effective command.
+     */
+    readonly effective: Argv0ChainWord;
+    /**
+     * The number of `VAR=val` shell-assignment prefixes on the `CallExpr`
+     * itself (`CommandSite.node.assigns`, e.g. the `FOO=bar` in
+     * `FOO=bar rm x`) that were skipped to reach argv0. This is a distinct
+     * mechanism from a wrapper's own `VAR=val` *operands* (e.g. `env`'s or
+     * `sudo`'s, see {@link WrapperSpec.skipAssignmentOperands}) — always
+     * exactly `CommandSite.node.assigns`'s length, independent of the
+     * wrapper chain found afterward.
+     */
+    readonly assignmentsSkipped: number;
+}
+
+/**
+ * Why {@link resolveArgv0} couldn't identify a single, definite effective
+ * command — distinct from {@link WordResolutionReason}, which is about why
+ * one *word*'s text is unknowable at the shell-syntax level (an expansion,
+ * a glob, …). `Argv0UnresolvedReason` instead reflects `resolveArgv0`'s own
+ * wrapper-table-driven analysis of an otherwise statically-known word:
+ *
+ * - `'unknown-flag'` — a statically known word shaped like a flag (starts
+ *   with `-`, isn't exactly `--`) for the wrapper currently being
+ *   followed, but that doesn't match any flag/operand shape
+ *   {@link WrapperSpec} recognizes for it. Never guessed through as the
+ *   wrapped command — see {@link resolveArgv0}'s doc comment.
+ * - `'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).
+ *
+ * This union may grow in a **minor** release (mirroring
+ * `WordResolutionReason`'s and `CommandContext`'s semver policy in
+ * `resolve-word.ts`/`enumerate-commands.ts`) — a reason this version
+ * doesn't yet know about only ever accompanies `static: false`; an
+ * exhaustive `switch` should still include a `default` case.
+ *
+ * @public
+ */
+export declare type Argv0UnresolvedReason = 'unknown-flag' | 'embedded-command';
+
+/**
+ * A word position {@link resolveArgv0} could not resolve to either a known
+ * static text or one of {@link WordResolution}'s own `static: false`
+ * reasons — see {@link Argv0UnresolvedReason}'s doc comment. Shares
+ * `WordResolution`'s `static: false` discriminant shape by design, so a
+ * consumer that only branches on `.static` treats it identically to any
+ * other unresolvable word.
+ *
+ * @public
+ */
+export declare interface Argv0UnresolvedWord {
+    readonly static: false;
+    readonly reason: Argv0UnresolvedReason;
+}
+
 /**
  * A single frame of the path from the root of the tree down to a
  * {@link CommandSite}, describing *how* the command is reached — never
@@ -115,6 +212,52 @@ export declare interface CommandSite {
     readonly context: readonly CommandContext[];
 }
 
+/**
+ * `sh-ast/analyze`'s default {@link WrapperSpec} table — every entry's
+ * flag/operand handling is hand-derived from that wrapper's own manual
+ * page (or, for shell builtins, the Bash Reference Manual/POSIX Shell &
+ * Utilities volume), cited per entry below, and cross-checked empirically
+ * against the real utility where one was locally available (GNU coreutils
+ * `env`/`nice` directly; `sudo` via `sudo -h`'s usage/option summary only
+ * — never executed, per this package's "facts only" posture and basic
+ * safety hygiene). This table is *data*, not policy: it names no
+ * "dangerous" commands, makes no safety judgment, and a caller can freely
+ * replace or extend it via {@link ResolveArgv0Options.transparentWrappers}
+ * (see {@link resolveArgv0}'s criterion-4-style configurability guarantee).
+ *
+ * Frozen (including each entry object and its own array/regexp fields) so
+ * immutability of this shared, module-scoped table is a contract, not just
+ * a convention any importer happens to honor — mirrors `visitorKeys`'s and
+ * `CHILD_TYPE_SCHEMA`'s freezing in `visitor-keys.ts`/`normalize.ts`.
+ *
+ * `xargs` is deliberately **excluded**: unlike every entry here, `xargs`
+ * doesn't simply re-exec a single wrapped command word it can point to
+ * statically — it invokes `command [initial-arguments]` once per *batch*
+ * of additional arguments assembled from its own stdin at run time
+ * (batched per `-n`/`-L`/line-splitting rules, GNU xargs(1)). Treating it
+ * as transparent would misrepresent what's actually invoked: the "wrapped
+ * command" is only ever a syntactic *prefix* of the real, stdin-dependent
+ * argv, and that prefix can itself be entirely absent (bare `xargs` reruns
+ * each stdin-derived line as its own command). No `WrapperSpec` shape here
+ * can honestly express that, so `xargs` is left for a caller to model
+ * explicitly if their use case calls for it, rather than shipped as a
+ * silently-wrong default.
+ *
+ * @see https://www.gnu.org/software/bash/manual/bash.html#Bourne-Shell-Builtins — `command`, `exec` (Bash Reference Manual §4.1)
+ * @see https://pubs.opengroup.org/onlinepubs/9699919799/utilities/command.html — POSIX `command`
+ * @see https://www.gnu.org/software/coreutils/manual/html_node/env-invocation.html — GNU coreutils `env`
+ * @see https://pubs.opengroup.org/onlinepubs/9699919799/utilities/env.html — POSIX `env`
+ * @see https://pubs.opengroup.org/onlinepubs/9699919799/utilities/nohup.html — POSIX `nohup`
+ * @see https://www.gnu.org/software/coreutils/manual/html_node/nice-invocation.html — GNU coreutils `nice`
+ * @see https://pubs.opengroup.org/onlinepubs/9699919799/utilities/nice.html — POSIX `nice`
+ * @see https://pubs.opengroup.org/onlinepubs/9699919799/utilities/time.html — POSIX `time` utility (distinct from the bash `time` *reserved word*, which mvdan/sh models as a transparent `TimeClause` — see {@link WrapperSpec}'s `time` entry below)
+ * @see https://www.gnu.org/software/coreutils/manual/html_node/timeout-invocation.html — GNU coreutils `timeout`
+ * @see https://www.sudo.ws/docs/man/sudo.man/ — `sudo(8)`
+ * @see https://www.gnu.org/software/findutils/manual/html_node/find_html/xargs-options.html — GNU `xargs` (why it's excluded, above)
+ * @public
+ */
+export declare const DEFAULT_TRANSPARENT_WRAPPERS: readonly WrapperSpec[];
+
 /**
  * Enumerates every command invocation (`CallExpr`) reachable from `root`,
  * with its resolved words ({@link resolveWord}) and the path used to reach
@@ -145,7 +288,13 @@ export declare interface CommandSite {
  * nesting-depth guard below, regardless of how many stages/links it has.
  *
  * @param root - Any `ShNode` — typically a `File` from `parseSync`, but any
- * subtree (a `Stmt`, a `Command`, or even a bare `Word`) is handled.
+ * subtree (a `Stmt`, a `Command`, or even a bare `Word`) is handled. Note
+ * `parseSync` itself already refuses (via its own `ShParseMaxDepthError`) any
+ * input whose estimated nesting exceeds *its* limit before ever producing a
+ * tree — see `parse-depth-guard.ts` — so a `root` sourced from `parseSync`
+ * has already passed that earlier, lower-level line of defense; this
+ * module's own guard below remains a second, independent backstop for
+ * trees built or mutated some other way.
  * @throws {@link ShAnalyzeMaxDepthError} if `root`'s genuinely nested
      * structure (subshells within subshells, chained command/process
      * substitutions, deeply nested `if`/`case`/loop/function/`time`/`{ }`
@@ -163,228 +312,460 @@ export declare interface CommandSite {
   *
   * @public
   */
- declare interface Position {
+ export declare interface Position {
      readonly line: number;
      readonly column: number;
  }
 
  /**
-  * Determines whether a `Word` node is statically a known string, and if
-  * so, what that string is — the atom of shell-AST static analysis (e.g.
-  * "is this word literally `rm`"). A word is static iff every part is a
-  * literal after shell unquoting: a bare `Lit` (backslash escapes
-  * processed), a `SglQuoted` (including `$'...'` ANSI-C escapes decoded),
-  * or a `DblQuoted` containing only literal parts (and not itself a
-  * `$"..."` locale translation) — including concatenations of these (`'r'm`
-  * resolves to `"rm"`). A word containing any expansion (`ParamExp`,
-  * `CmdSubst`, `ArithmExp`, `ProcSubst`), a triggering unquoted `~` (see
-  * `options.context`), an unquoted glob metacharacter/bracket
-  * expression/`ExtGlob`, a `$"..."` locale translation, or an unrepresentable
-  * `$'\U...'` escape is `static: false` with a reason — never an error, and
-  * never a safety judgment (see {@link WordResolution}).
+  * Follows `site`'s argv0 through zero or more *transparent wrappers* —
+  * commands whose own argv0 isn't the command actually run, because they
+  * just locate and re-exec another command (`env FOO=1 rm -rf /`,
+  * `command rm`, `nohup rm`, `sudo -u x "$prog"`) — to the **effective**
+  * command: the one a permission/policy check must actually judge, since
+  * argv0 alone is trivially spoofable through any of these.
   *
-  * @param word - A `Word` node, e.g. `parseSync(...).stmts[0].cmd.args[0]`.
-  * @param options - See {@link ResolveWordOptions}.
-  * @throws TypeError if `word.type` is not `"Word"` — a programmer-error
-  * misuse of the API, not a "malformed shell source" case (well-formed
-  * shell source, however dynamic, never throws; see {@link WordResolution}).
+  * The wrapper table ({@link ResolveArgv0Options.transparentWrappers},
+  * defaulting to {@link DEFAULT_TRANSPARENT_WRAPPERS}) is plain data: each
+  * {@link WrapperSpec} declares how to locate the word it wraps, and
+  * neither this function nor the table encodes any safety judgment about
+  * *which* commands are dangerous — matching {@link CommandSite}'s and
+  * {@link resolveWord}'s "facts only" posture. A caller can drop a default
+  * entry (that name then resolves as an ordinary, non-transparent
+  * command) or add their own (e.g. a project's `with-retry` helper) and
+  * both directions are followed identically to any built-in entry.
   *
-  * @public
-  */
- export declare function resolveWord(word: ShNode, options?: ResolveWordOptions): WordResolution;
-
- /**
-  * Options controlling {@link resolveWord}'s tilde-expansion detection.
-  *
-  * @public
-  */
- export declare interface ResolveWordOptions {
-     /**
-      * Which Bash grammar position `word` occupies — the two positions Bash
-      * §3.5.2 ("Tilde Expansion") documents distinct tilde-expansion triggers
-      * for:
-      *
-      * - `'command-argument'` — an ordinary simple-command argument word (e.g.
-      *   `echo <word>`). Only a *word-initial* unquoted `~` triggers tilde
-      *   expansion; an unquoted `~` elsewhere in the word (including right
-      *   after a `:`) is an ordinary character (`echo a:~b` prints `a:~b`
-      *   literally in real bash).
-      * - `'assignment-value'` — the value side of a shell assignment (e.g.
-      *   `PATH=<word>`, an `Assign` node's `value`). Bash additionally
-      *   tilde-expands an unquoted `~` immediately following an unquoted `:`
-      *   anywhere in the value (`PATH=/foo:~/bar` expands the `~/bar`
-      *   segment) — this is documented for `PATH`-like colon-separated
-      *   assignment values specifically.
-      *
-      * **Default: `'assignment-value'` semantics apply whenever this option is
-      * omitted.** `resolveWord` takes a bare `Word` node with no grammar
-      * context attached, so it cannot see whether its caller extracted that
-      * word from a command argument or an assignment value — omitting this
-      * option is deliberately treated as the *more conservative* of the two
-      * (the one that reports `'tilde'` in more cases), so a caller that
-      * doesn't know or care about the distinction never under-reports a real
-      * tilde-expansion site. Pass `'command-argument'` explicitly to opt into
-      * the narrower, word-initial-only check that matches real bash's
-      * behavior for ordinary arguments.
-      *
-      * @see https://www.gnu.org/software/bash/manual/bash.html#Tilde-Expansion
-      */
-     readonly context?: 'command-argument' | 'assignment-value';
- }
-
- /**
-  * 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.
+  * **A statically-unknowable word is never guessed through** — three
+  * distinct cases all stop the chain immediately at that word rather than
+  * falling back to any other guess:
   *
-  * `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".
+  * 1. `argv0` or any wrapper's located word itself resolves `static: false`
+  *    (an expansion, tilde, glob, …) — `sudo -u x "$prog"` reports
+  *    `effective: { static: false, reason: 'expansion' }` with
+  *    `chain: [<sudo>, <"$prog">]`, not `rm`/`sudo`/anything static.
+  * 2. A *statically known* word shaped like a flag (`-`-prefixed, not
+  *    `--`) doesn't match any flag/operand shape the current
+  *    {@link WrapperSpec} recognizes — `sudo -D /tmp rm x` (`-D` isn't
+  *    modeled for `sudo`) reports an `effective` of `static: false` with
+  *    `reason: 'unknown-flag'`, **not** `rm` (the pre-fix behavior: any
+  *    unrecognized word, flag-shaped or not, was silently treated as the
+  *    wrapped command — a false report that hid the real effective
+  *    command behind a flag this table simply hadn't modeled yet).
+  * 3. A recognized flag's value structurally embeds the real command
+  *    rather than naming it as a separate word — `env -S 'rm -rf /'`
+  *    reports `effective: { static: false, reason: 'embedded-command' }`
+  *    (see {@link WrapperSpec.unresolvableFlags}'s doc comment).
   *
-  * @public
-  */
- export declare class ShAnalyzeMaxDepthError extends ShBridgeError {
-     readonly code = "ESLINT_SH_ANALYZE_MAX_DEPTH";
-     /** The maximum nesting depth `enumerateCommands` supports; the same value every time (not caller-configurable). */
-     readonly maxDepth: number;
-     constructor(maxDepth: number);
- }
-
- /**
-  * Common base class for every error this package throws — originally just
-  * {@link parseSync}'s errors, now also the `sh-ast/analyze` layer's (see
-  * {@link ShAnalyzeMaxDepthError}). Provides a stable, documented `code`
-  * discriminator (e.g. `"ESLINT_SH_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 ShParseError},
-  * {@link ShInvalidDialectError}, {@link ShBridgeInternalError},
-  * {@link ShAnalyzeMaxDepthError}).
+  * `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
+  * distinct from a wrapper's own `VAR=val` *operands* (`env A=1 rm x`,
+  * `sudo A=1 rm x`), which {@link WrapperSpec.skipAssignmentOperands}
+  * handles per-wrapper.
   *
-  * @public
-  */
- declare abstract class ShBridgeError extends Error {
-     /**
-      * Stable, machine-readable discriminator for this error kind. Distinct
-      * per subclass and will not change once published.
+  * @param site - A {@link CommandSite}, typically from {@link enumerateCommands}.
+  * @param options - See {@link ResolveArgv0Options}.
+  * @throws TypeError if `site.argv` is empty — a programmer-error misuse of
+  * the API (every `CommandSite` `enumerateCommands` ever produces has at
+  * 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
+      * {@link ResolveArgv0Options.transparentWrappers}'s doc comment).
+      * @public
       */
-     abstract readonly code: string;
- }
+  export declare function resolveArgv0(site: CommandSite, options?: ResolveArgv0Options): Argv0Resolution;
 
- /**
-  * A normalized AST node produced by {@link parseSync}.
-  *
-  * `range` and `loc` are expressed in UTF-16 code units, so
-  * `code.slice(node.range[0], node.range[1])` reproduces the node's exact
-  * source text — even though mvdan/sh itself reports byte offsets and
-  * byte-counting columns internally (see design/ARCHITECTURE.md's
-  * "Serialization contract"). Every other field copied over from mvdan/sh's
-  * typedjson tree keeps its original value but with the field name
-  * lowercased (`Stmts` becomes `stmts`, `CondLast` becomes `condlast`, etc.).
-  *
-  * @public
-  */
- declare interface ShNode {
-     readonly type: string;
-     readonly range: readonly [number, number];
-     readonly loc: {
-         readonly start: Position;
-         readonly end: Position;
-     };
-     [field: string]: unknown;
- }
+  /**
+   * Options accepted by {@link resolveArgv0}.
+   *
+   * @public
+   */
+  export declare interface ResolveArgv0Options {
+      /**
+       * The transparent-wrapper table to follow. Defaults to
+       * {@link DEFAULT_TRANSPARENT_WRAPPERS}. Pass a replacement array to drop
+       * a default entry entirely (that wrapper is then treated as an ordinary,
+       * non-transparent effective command), or add project-specific entries
+       * (e.g. a `with-retry` wrapper) — the table is plain data, not baked-in
+       * policy.
+       *
+       * Validated at the {@link resolveArgv0} boundary: a malformed entry (a
+       * non-array `names`, an empty `names`, or a wrong-typed flag field)
+       * throws {@link ShAnalyzeInvalidWrapperSpecError} immediately, rather
+       * than failing later with a confusing native `TypeError` deep inside
+       * flag matching.
+       */
+      readonly transparentWrappers?: readonly WrapperSpec[];
+  }
 
- /**
-  * The result of statically resolving a `Word` node's text. Reports facts
-  * only — never a safety verdict, never a hardcoded command/wrapper list.
-  * `static: false` ("unknowable") is a first-class, valid result, not an
-  * error condition.
-  *
-  * @public
-  */
- export declare type WordResolution = {
-     /** The word is a compile-time-known string. */
-     readonly static: true;
-     /** The word's exact resolved text (quotes and escapes removed). */
-     readonly text: string;
- } | {
-     /** The word's value depends on program state, the environment, or the filesystem. */
-     readonly static: false;
-     /** Why this word cannot be statically resolved. */
-     readonly reason: WordResolutionReason;
- };
+  /**
+   * Determines whether a `Word` node is statically a known string, and if
+   * so, what that string is — the atom of shell-AST static analysis (e.g.
+   * "is this word literally `rm`"). A word is static iff every part is a
+   * literal after shell unquoting: a bare `Lit` (backslash escapes
+   * processed), a `SglQuoted` (including `$'...'` ANSI-C escapes decoded),
+   * or a `DblQuoted` containing only literal parts (and not itself a
+   * `$"..."` locale translation) — including concatenations of these (`'r'm`
+   * resolves to `"rm"`). A word containing any expansion (`ParamExp`,
+   * `CmdSubst`, `ArithmExp`, `ProcSubst`), a triggering unquoted `~` (see
+   * `options.context`), an unquoted glob metacharacter/bracket
+   * expression/`ExtGlob`, a `$"..."` locale translation, or an unrepresentable
+   * `$'\U...'` escape is `static: false` with a reason — never an error, and
+   * never a safety judgment (see {@link WordResolution}).
+   *
+   * @param word - A `Word` node, e.g. `parseSync(...).stmts[0].cmd.args[0]`.
+   * A `word` sourced from `parseSync` has already passed that function's own
+   * pathological-nesting guard (`ShParseMaxDepthError` — see
+   * `parse-depth-guard.ts`), which rejects deeply-nested input before it is
+   * ever turned into a tree at all, so `resolveWord` itself never needs (and
+   * does not implement) a depth guard of its own.
+   * @param options - See {@link ResolveWordOptions}.
+   * @throws TypeError if `word.type` is not `"Word"` — a programmer-error
+   * misuse of the API, not a "malformed shell source" case (well-formed
+   * shell source, however dynamic, never throws; see {@link WordResolution}).
+   *
+   * @public
+   */
+  export declare function resolveWord(word: ShNode, options?: ResolveWordOptions): WordResolution;
 
- /**
-  * Why a {@link resolveWord} result is `static: false`: the word's exact
-  * text cannot be determined from source alone.
-  *
-  * - `'expansion'` — the word contains a `ParamExp` (`$x`, `${x}`), a
-  *   `CmdSubst` (command substitution, either `$(...)` or backtick form), an
-  *   `ArithmExp` (`$((expr))`), or a `ProcSubst` (`<(cmd)`/`>(cmd)`) part:
-  *   its value depends on program state (variables, command output, process
-  *   substitution) that only exists at run time.
-  * - `'tilde'` — an unquoted, unescaped `~` triggers Bash tilde expansion
-  *   (Bash Reference Manual §3.5.2, "Tilde Expansion") at the start of the
-  *   word, or — when `resolveWord`'s `context` option is `'assignment-value'`
-  *   or omitted — immediately after an unquoted `:` anywhere in the word too
-  *   (§3.5.2 also documents this for assignment-statement values, e.g.
-  *   `PATH=/foo:~/bar`). Either way: statically shaped, but its value
-  *   depends on the filesystem/environment (`$HOME`, NSS user database
-  *   lookups) at run time. See `resolveWord`'s `context` parameter doc for
-  *   the full command-argument-vs-assignment-value distinction.
-  * - `'glob'` — the word contains an unquoted, unescaped glob metacharacter
-  *   (`*`/`?`), an unquoted bracket expression (`[...]` — an unquoted `[`
-  *   with a later unquoted `]` in the same word, POSIX 2.13.1 / Bash
-  *   Reference Manual §3.5.8.1, "Pattern Matching"), or an `ExtGlob` part
-  *   (Bash Reference Manual §3.5.8, "Filename Expansion"): its value depends
-  *   on which filesystem entries exist at run time.
-  * - `'brace'` — the word contains a `BraceExp` part (`{a,b}`/`{1..10}`,
-  *   Bash Reference Manual §3.5.1, "Brace Expansion"). mvdan/sh v3.13.1 only
-  *   ever produces this node type when its caller applies `syntax.SplitBraces`
-  *   to the parsed tree; this bridge's shim does not call it, so today a
-  *   brace expression like `{a,b}` reaches {@link resolveWord} as an
-  *   ordinary `Lit` (indistinguishable, in the AST this bridge produces,
-  *   from literal `{`/`,`/`}` characters) rather than as a `BraceExp` part.
-  *   This reason is handled here for forward-compatibility with that node
-  *   type and is not reachable through {@link resolveWord} today.
-  * - `'locale'` — the word contains a `$"..."` locale-translated string
-  *   (Bash Reference Manual §3.1.2.5, "Locale-Specific Translation"): its
-  *   value is looked up in the current locale's translation catalog at run
-  *   time via `gettext`, regardless of whether its contents also contain an
-  *   expansion. `'locale'` takes precedence over any `'expansion'` a
-  *   `$"..."` word's *contents* would otherwise report — the `DblQuoted`
-  *   node's own `dollar` flag is checked before its children are visited at
-  *   all, so e.g. `$"hi $x"` reports `'locale'`, never `'expansion'`.
-  * - `'unsupported'` — the word contains a `$'...'` (ANSI-C quoted) `\u`/`\U`
-  *   escape whose value has no corresponding Unicode character (greater than
-  *   `U+10FFFF`, e.g. `$'\UFFFFFFFF'`): real bash's output for this case is
-  *   an undocumented, non-UTF-8 byte sequence with no exact representation
-  *   as a JavaScript string (see `ansi-c-escapes.ts`'s
-  *   `MAX_UNICODE_CODE_POINT` doc comment for the empirical detail) — this
-  *   package declines to claim a `static: true` text bash never actually
-  *   produces.
-  *
-  * This union may grow in a **minor** release — new mvdan/sh word-part node
-  * types, or new statically-shaped-but-dynamic categories, can add new reason
-  * strings without that being a breaking change. It is deliberately not
-  * sealed against extension elsewhere in the codebase. A reason string this
-  * version of the package doesn't yet know about only ever accompanies
-  * `static: false`, never changes the meaning of `static: true`, so runtime
-  * consumers that only branch on `.static` are safe by construction across
-  * such additions; an exhaustive compile-time `switch` over `.reason` should
-  * still include a `default` case to stay forward-compatible.
-  *
-  * @public
-  */
- export declare type WordResolutionReason = 'expansion' | 'tilde' | 'glob' | 'brace' | 'locale' | 'unsupported';
+  /**
+   * Options controlling {@link resolveWord}'s tilde-expansion detection.
+   *
+   * @public
+   */
+  export declare interface ResolveWordOptions {
+      /**
+       * Which Bash grammar position `word` occupies — the two positions Bash
+       * §3.5.2 ("Tilde Expansion") documents distinct tilde-expansion triggers
+       * for:
+       *
+       * - `'command-argument'` — an ordinary simple-command argument word (e.g.
+       *   `echo <word>`). Only a *word-initial* unquoted `~` triggers tilde
+       *   expansion; an unquoted `~` elsewhere in the word (including right
+       *   after a `:`) is an ordinary character (`echo a:~b` prints `a:~b`
+       *   literally in real bash).
+       * - `'assignment-value'` — the value side of a shell assignment (e.g.
+       *   `PATH=<word>`, an `Assign` node's `value`). Bash additionally
+       *   tilde-expands an unquoted `~` immediately following an unquoted `:`
+       *   anywhere in the value (`PATH=/foo:~/bar` expands the `~/bar`
+       *   segment) — this is documented for `PATH`-like colon-separated
+       *   assignment values specifically.
+       *
+       * **Default: `'assignment-value'` semantics apply whenever this option is
+       * omitted.** `resolveWord` takes a bare `Word` node with no grammar
+       * context attached, so it cannot see whether its caller extracted that
+       * word from a command argument or an assignment value — omitting this
+       * option is deliberately treated as the *more conservative* of the two
+       * (the one that reports `'tilde'` in more cases), so a caller that
+       * doesn't know or care about the distinction never under-reports a real
+       * tilde-expansion site. Pass `'command-argument'` explicitly to opt into
+       * the narrower, word-initial-only check that matches real bash's
+       * behavior for ordinary arguments.
+       *
+       * @see https://www.gnu.org/software/bash/manual/bash.html#Tilde-Expansion
+       */
+      readonly context?: 'command-argument' | 'assignment-value';
+  }
+
+  /**
+   * 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);
+  }
+
+  /**
+   * 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);
+  }
+
+  /**
+   * 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;
+  }
+
+  /**
+   * A normalized AST node produced by {@link sh-ast#parseSync | parseSync}.
+   *
+   * `range` and `loc` are expressed in UTF-16 code units, so
+   * `code.slice(node.range[0], node.range[1])` reproduces the node's exact
+   * source text — even though mvdan/sh itself reports byte offsets and
+   * byte-counting columns internally (see design/ARCHITECTURE.md's
+   * "Serialization contract"). Every other field copied over from mvdan/sh's
+   * typedjson tree keeps its original value but with the field name
+   * lowercased (`Stmts` becomes `stmts`, `CondLast` becomes `condlast`, etc.).
+   *
+   * Also re-exported from `sh-ast/analyze` (see #23) — the subpath's public
+   * surface consumes and exposes `ShNode`, so a consumer can reference the type
+   * without also importing from the root `sh-ast` entry point.
+   *
+   * @public
+   */
+  export declare interface ShNode {
+      readonly type: string;
+      readonly range: readonly [number, number];
+      readonly loc: {
+          readonly start: Position;
+          readonly end: Position;
+      };
+      [field: string]: unknown;
+  }
+
+  /**
+   * The result of statically resolving a `Word` node's text. Reports facts
+   * only — never a safety verdict, never a hardcoded command/wrapper list.
+   * `static: false` ("unknowable") is a first-class, valid result, not an
+   * error condition.
+   *
+   * @public
+   */
+  export declare type WordResolution = {
+      /** The word is a compile-time-known string. */
+      readonly static: true;
+      /** The word's exact resolved text (quotes and escapes removed). */
+      readonly text: string;
+  } | {
+      /** The word's value depends on program state, the environment, or the filesystem. */
+      readonly static: false;
+      /** Why this word cannot be statically resolved. */
+      readonly reason: WordResolutionReason;
+  };
+
+  /**
+   * Why a {@link resolveWord} result is `static: false`: the word's exact
+   * text cannot be determined from source alone.
+   *
+   * - `'expansion'` — the word contains a `ParamExp` (`$x`, `${x}`), a
+   *   `CmdSubst` (command substitution, either `$(...)` or backtick form), an
+   *   `ArithmExp` (`$((expr))`), or a `ProcSubst` (`<(cmd)`/`>(cmd)`) part:
+   *   its value depends on program state (variables, command output, process
+   *   substitution) that only exists at run time.
+   * - `'tilde'` — an unquoted, unescaped `~` triggers Bash tilde expansion
+   *   (Bash Reference Manual §3.5.2, "Tilde Expansion") at the start of the
+   *   word, or — when `resolveWord`'s `context` option is `'assignment-value'`
+   *   or omitted — immediately after an unquoted `:` anywhere in the word too
+   *   (§3.5.2 also documents this for assignment-statement values, e.g.
+   *   `PATH=/foo:~/bar`). Either way: statically shaped, but its value
+   *   depends on the filesystem/environment (`$HOME`, NSS user database
+   *   lookups) at run time. See `resolveWord`'s `context` parameter doc for
+   *   the full command-argument-vs-assignment-value distinction.
+   * - `'glob'` — the word contains an unquoted, unescaped glob metacharacter
+   *   (`*`/`?`), an unquoted bracket expression (`[...]` — an unquoted `[`
+   *   with a later unquoted `]` in the same word, POSIX 2.13.1 / Bash
+   *   Reference Manual §3.5.8.1, "Pattern Matching"), or an `ExtGlob` part
+   *   (Bash Reference Manual §3.5.8, "Filename Expansion"): its value depends
+   *   on which filesystem entries exist at run time.
+   * - `'brace'` — the word contains a `BraceExp` part (`{a,b}`/`{1..10}`,
+   *   Bash Reference Manual §3.5.1, "Brace Expansion"). mvdan/sh v3.13.1 only
+   *   ever produces this node type when its caller applies `syntax.SplitBraces`
+   *   to the parsed tree; this bridge's shim does not call it, so today a
+   *   brace expression like `{a,b}` reaches {@link resolveWord} as an
+   *   ordinary `Lit` (indistinguishable, in the AST this bridge produces,
+   *   from literal `{`/`,`/`}` characters) rather than as a `BraceExp` part.
+   *   This reason is handled here for forward-compatibility with that node
+   *   type and is not reachable through {@link resolveWord} today.
+   * - `'locale'` — the word contains a `$"..."` locale-translated string
+   *   (Bash Reference Manual §3.1.2.5, "Locale-Specific Translation"): its
+   *   value is looked up in the current locale's translation catalog at run
+   *   time via `gettext`, regardless of whether its contents also contain an
+   *   expansion. `'locale'` takes precedence over any `'expansion'` a
+   *   `$"..."` word's *contents* would otherwise report — the `DblQuoted`
+   *   node's own `dollar` flag is checked before its children are visited at
+   *   all, so e.g. `$"hi $x"` reports `'locale'`, never `'expansion'`.
+   * - `'unsupported'` — the word contains a `$'...'` (ANSI-C quoted) `\u`/`\U`
+   *   escape whose value has no corresponding Unicode character (greater than
+   *   `U+10FFFF`, e.g. `$'\UFFFFFFFF'`): real bash's output for this case is
+   *   an undocumented, non-UTF-8 byte sequence with no exact representation
+   *   as a JavaScript string (see `ansi-c-escapes.ts`'s
+   *   `MAX_UNICODE_CODE_POINT` doc comment for the empirical detail) — this
+   *   package declines to claim a `static: true` text bash never actually
+   *   produces.
+   *
+   * This union may grow in a **minor** release — new mvdan/sh word-part node
+   * types, or new statically-shaped-but-dynamic categories, can add new reason
+   * strings without that being a breaking change. It is deliberately not
+   * sealed against extension elsewhere in the codebase. A reason string this
+   * version of the package doesn't yet know about only ever accompanies
+   * `static: false`, never changes the meaning of `static: true`, so runtime
+   * consumers that only branch on `.static` are safe by construction across
+   * such additions; an exhaustive compile-time `switch` over `.reason` should
+   * still include a `default` case to stay forward-compatible.
+   *
+   * @public
+   */
+  export declare type WordResolutionReason = 'expansion' | 'tilde' | 'glob' | 'brace' | 'locale' | 'unsupported';
+
+  /**
+   * A data-only description of one "transparent wrapper" — a command whose
+   * own argv0 is not the *effective* command actually run, because it just
+   * locates and re-execs another command (`env`, `sudo`, `nohup`, …).
+   * {@link resolveArgv0} interprets every field here structurally (skip N
+   * words, recognize this literal flag, …); adding a new `WrapperSpec` never
+   * requires a code change to {@link resolveArgv0} itself — that's what makes
+   * {@link DEFAULT_TRANSPARENT_WRAPPERS} data rather than a set of hardcoded
+   * `if (name === 'env')` branches, and what lets a caller extend or replace
+   * the table with their own project-specific wrappers (e.g. a `with-retry`
+   * helper).
+   *
+   * Every flag/operand-recognizing field is checked against a word's
+   * *statically resolved* text only (its `.text` on a {@link WordResolution}
+   * `static: true` result) — a dynamic word can never be identified as one of
+   * a wrapper's own flags or operands (see {@link resolveArgv0}'s doc comment
+   * for why an unrecognizable word always ends the chain rather than being
+   * guessed through).
+   *
+   * This shape may grow new optional fields in a **minor** release as this
+   * bridge models more wrapper flag conventions; existing fields' meaning
+   * never changes.
+   *
+   * @public
+   */
+  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.
+       *
+       * 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']`).
+       */
+      readonly names: readonly string[];
+      /**
+       * When `true`, a `NAME=value`-shaped operand (an unquoted identifier
+       * followed by `=`, e.g. `A=1`) appearing after the wrapper name is
+       * skipped — this is `env`'s and `sudo`'s own `VAR=val` *operand*
+       * mechanism (setting variables in the wrapped command's environment),
+       * which is a distinct, per-wrapper concept from the shell-level
+       * `CallExpr.assigns` prefixes {@link Argv0Resolution.assignmentsSkipped}
+       * counts.
+       */
+      readonly skipAssignmentOperands?: boolean;
+      /** Exact flag tokens that take no operand of their own (e.g. `-i`, `-c`). */
+      readonly noArgFlags?: readonly string[];
+      /**
+       * A regular expression matched against a whole flag-position word for
+       * flag *shapes* that aren't fixed strings — e.g. `nice`'s legacy attached
+       * adjustment form (`nice -10 cmd`). Consumes no separate operand word,
+       * like {@link WrapperSpec.noArgFlags}.
+       */
+      readonly noArgFlagPattern?: RegExp;
+      /**
+       * Exact flag tokens that take an operand (e.g. `-u user`, `-n 10`).
+       * Recognized in every standard getopt-style form:
+       *
+       * - Separate word: `-u user` (both words skipped).
+       * - Attached short form: `-uuser` (one word — everything after the flag
+       *   character is the operand text, exactly like real getopt).
+       * - Clustered with preceding no-operand short flags:
+       *   `-Eu user`/`-Euuser` (`-E` from {@link WrapperSpec.noArgFlags},
+       *   `-u` from here) — see {@link resolveArgv0}'s doc comment for the
+       *   clustering algorithm.
+       * - Attached long form (only for an entry starting with `--`):
+       *   `--long-flag=value` (one word).
+       *
+       * Any of these forms is recognized without a separate `WrapperSpec`
+       * field — the shapes are derived structurally from `argFlags` and
+       * `noArgFlags` together, matching how real short-option parsing works,
+       * rather than needing to be spelled out per wrapper.
+       */
+      readonly argFlags?: readonly string[];
+      /**
+       * Exact flag tokens (and, for a `--`-prefixed entry, its attached
+       * `--flag=value` form; for a short `-X` entry, its attached `-Xvalue`
+       * form) that make the **whole** {@link resolveArgv0} resolution
+       * unresolvable the moment they're seen, rather than being skipped like
+       * {@link WrapperSpec.argFlags} or ending the chain normally like an
+       * unrecognized word. For a flag whose *value itself* structurally embeds
+       * the real command in a way no `WrapperSpec` field can name a fixed
+       * "the wrapped command is word N" position for — e.g. `env -S string`
+       * splices `string`'s own words into argv, so the real command is
+       * *inside* that operand, not identifiable as a separate word at all (see
+       * `env`'s table entry). Reported via
+       * {@link Argv0Resolution.effective}'s `'embedded-command'` reason.
+       */
+      readonly unresolvableFlags?: readonly string[];
+      /**
+       * Exact flag tokens whose mere presence means this wrapper's own
+       * invocation *is* the effective command — nothing after it is ever the
+       * wrapped command, regardless of what other words follow. E.g.
+       * `command -v rm` doesn't execute `rm` at all; it prints whether `rm`
+       * is a recognized command name (Bash Reference Manual §4.1). Checked
+       * independently of word position (not "the Nth flag"), and takes
+       * precedence the moment it's seen — see `command`'s table entry.
+       */
+      readonly stopsChainFlags?: readonly string[];
+      /**
+       * The number of plain (non-flag, non-assignment-operand) words this
+       * wrapper requires *before* the wrapped command word — e.g. `timeout`'s
+       * mandatory `DURATION` operand (`timeout 10 rm -rf x`).
+       */
+      readonly positionalOperandsBeforeCommand?: number;
+  }
 
- export { }
+  export { }