sh-ast 0.3.1 → 0.4.0

package/dist/analyze.d.ts

@@ -1,3 +1,129 @@
+/**
+ * Upstream BinAritOperator constant Add. Its numeric value is preserved exactly.
+ *
+ * +
+ *
+ * @public
+ */
+declare const Add: 81;
+
+/**
+ * Upstream BinAritOperator constant AddAssgn. Its numeric value is preserved exactly.
+ *
+ * +=
+ *
+ * @public
+ */
+declare const AddAssgn: 49;
+
+/**
+ * Upstream ParExpOperator constant AlternateUnset. Its numeric value is preserved exactly.
+ *
+ * +
+ *
+ * @public
+ */
+declare const AlternateUnset: 81;
+
+/**
+ * Upstream ParExpOperator constant AlternateUnsetOrNull. Its numeric value is preserved exactly.
+ *
+ * :+
+ *
+ * @public
+ */
+declare const AlternateUnsetOrNull: 82;
+
+/**
+ * Upstream BinAritOperator constant And. Its numeric value is preserved exactly.
+ *
+ * &
+ *
+ * @public
+ */
+declare const And: 10;
+
+/**
+ * Upstream BinAritOperator constant AndArit. Its numeric value is preserved exactly.
+ *
+ * &&
+ *
+ * @public
+ */
+declare const AndArit: 11;
+
+/**
+ * Upstream BinAritOperator constant AndAssgn. Its numeric value is preserved exactly.
+ *
+ * &=
+ *
+ * @public
+ */
+declare const AndAssgn: 54;
+
+/**
+ * Upstream BinAritOperator constant AndBoolAssgn. Its numeric value is preserved exactly.
+ *
+ * &&=
+ *
+ * @public
+ */
+declare const AndBoolAssgn: 59;
+
+/**
+ * Upstream BinCmdOperator constant AndStmt. Its numeric value is preserved exactly.
+ *
+ * &&
+ *
+ * @public
+ */
+declare const AndStmt: 11;
+
+/**
+ * Upstream BinTestOperator constant AndTest. Its numeric value is preserved exactly.
+ *
+ * &&
+ *
+ * @public
+ */
+declare const AndTest: 11;
+
+/**
+ * Upstream RedirOperator constant AppAll. Its numeric value is preserved exactly.
+ *
+ * &\>\>
+ *
+ * @public
+ */
+declare const AppAll: 76;
+
+/**
+ * Upstream RedirOperator constant AppAllClob. Its numeric value is preserved exactly.
+ *
+ * &\>\>| with `LangZsh`
+ *
+ * @public
+ */
+declare const AppAllClob: 77;
+
+/**
+ * Upstream RedirOperator constant AppClob. Its numeric value is preserved exactly.
+ *
+ * \>\>| with `LangZsh`
+ *
+ * @public
+ */
+declare const AppClob: 70;
+
+/**
+ * Upstream RedirOperator constant AppOut. Its numeric value is preserved exactly.
+ *
+ * \>\>
+ *
+ * @public
+ */
+declare const AppOut: 64;
+
 /**
  * The result of statically resolving one position in an
  * {@link Argv0Resolution.chain}: either an ordinary {@link WordResolution}
@@ -43,11 +169,11 @@ export declare interface Argv0Resolution {
     readonly effective: Argv0ChainWord;
     /**
      * The number of `VAR=val` shell-assignment prefixes on the `CallExpr`
-     * itself (`CommandSite.node.assigns`, e.g. the `FOO=bar` in
+     * 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
+     * exactly `CommandSite.node.Assigns`'s length, independent of the
      * wrapper chain found afterward.
      */
     readonly assignmentsSkipped: number;
@@ -96,479 +222,3699 @@ export declare interface Argv0UnresolvedWord {
 }
 
 /**
- * A single frame of the path from the root of the tree down to a
- * {@link CommandSite}, describing *how* the command is reached — never
- * whether it is safe to run. `CommandSite.context` is an ordered stack of
- * these, outermost frame first:
- *
- * - `'and'`/`'or'` (`side: 'right'`) — the right-hand operand of a
- *   `BinaryCmd` (mvdan/sh's node for both `&&` and `||`); only the right
- *   side is tagged; the left side inherits the surrounding context
- *   unchanged, since it runs unconditionally relative to this operator.
- * - `'pipeline'` (`stage: n`) — one stage of a `|`/`|&` chain (also a
- *   `BinaryCmd`, left-associatively nested by mvdan/sh); every stage is
- *   tagged, 0-indexed left to right, regardless of whether the chain mixes
- *   `|` and `|&`.
- * - `'subshell'` — inside a `Subshell` (`( ... )`).
- * - `'cmdSubst'`/`'procSubst'` — inside a `CmdSubst` (`$(...)`/backticks) or
- *   `ProcSubst` (`<(...)`/`>(...)`) reached from *any* word-bearing
- *   position (an argument, a redirection target, a case subject, a loop's
- *   word list, an assignment value, a test/arithmetic operand, …) — not
- *   only from `CallExpr.args`.
- * - `'if'` (`branch: 'cond' | 'then' | 'else'`) — inside an `IfClause`'s
- *   condition, then-branch, or else-branch (mvdan/sh nests `elif` chains as
- *   `IfClause.else` pointing to another `IfClause`, so an `elif`'s own
- *   condition/then are reached through an `{kind:'if',branch:'else'}` frame
- *   first, then their own `'cond'`/`'then'` frame — reflecting the real
- *   nesting rather than collapsing it).
- * - `'case'` — inside one `CaseClause` branch's statement list (not the
- *   case subject word or the patterns).
- * - `'loop'` (`role` is `'body'` or `'cond'`) — inside a `ForClause`'s
- *   statement list (`role: 'body'` only — a `for` loop has no
- *   statement-list condition) or a `WhileClause`'s (`role: 'cond'` for the
- *   condition, `role: 'body'` for the loop body).
- * - `'function'` (`name`) — inside a `FuncDecl`'s body; `name` is the
- *   function's literal name text.
- * - `'background'`/`'negated'` — the enclosing `Stmt` has mvdan/sh's
- *   Background/Negated flag set (`cmd &`, `! cmd`).
- * - `'coproc'` — inside a `CoprocClause`'s statement (a `coproc` block,
- *   optionally named).
+ * ArithmCmd represents an arithmetic command.
  *
- * A `Block` grouping (`{ ...; }`) and a `TimeClause` (`time cmd`) are
- * deliberately transparent — grouping and timing a command doesn't change
- * how it's reached, so no frame is added for either.
+ * This node will only appear with `LangBash` and `LangMirBSDKorn`.
  *
- * This union may grow in a **minor** release — a future mvdan/sh grammar
- * construct this module starts modeling can add a new `kind` variant
- * without that being a breaking change (mirroring
- * {@link WordResolutionReason}'s semver policy in `resolve-word.ts`). It is
- * deliberately not sealed against extension elsewhere in the codebase.
- * Every existing variant's shape (its extra fields, if any) is stable —
- * only new variants are ever added — so an exhaustive compile-time
- * `switch` over `.kind` should still include a `default` case to stay
- * forward-compatible.
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
  *
  * @public
  */
-export declare type CommandContext = {
-    readonly kind: 'and';
-    readonly side: 'right';
-} | {
-    readonly kind: 'or';
-    readonly side: 'right';
-} | {
-    readonly kind: 'pipeline';
-    readonly stage: number;
-} | {
-    readonly kind: 'subshell';
-} | {
-    readonly kind: 'cmdSubst';
-} | {
-    readonly kind: 'procSubst';
-} | {
-    readonly kind: 'if';
-    readonly branch: 'then' | 'else' | 'cond';
-} | {
-    readonly kind: 'case';
-} | {
-    readonly kind: 'loop';
-    readonly role: 'body' | 'cond';
-} | {
-    readonly kind: 'function';
-    readonly name: string;
-} | {
-    readonly kind: 'background';
-} | {
-    readonly kind: 'negated';
-} | {
-    readonly kind: 'coproc';
-};
+export declare interface ArithmCmd {
+    /**
+     * Identifies the upstream concrete record when carried through an interface union.
+     */
+    Type: 'ArithmCmd';
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    Left: SyntaxPos;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    Right: SyntaxPos;
+    /**
+     * mksh's ((# expr))
+     *
+     * False is an explicit upstream value and is never omitted.
+     */
+    Unsigned: boolean;
+    /**
+     * Null preserves the upstream absence of this component.
+     */
+    X: ArithmExpr | null;
+}
 
 /**
- * One place in the tree where a command is actually invoked — a `CallExpr`
- * node, together with its resolved words and the path used to reach it.
- * Facts only, matching {@link resolveWord}'s posture: no safety verdict, no
- * hardcoded command/wrapper list. A dynamic (`static: false`) `argv0` is a
- * normal, expected result — not an error and not itself reported as
- * "unknown"/"unsafe".
+ * ArithmExp represents an arithmetic expansion.
+ *
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
  *
  * @public
  */
-export declare interface CommandSite {
-    /** The `CallExpr` node this site was found at. */
-    readonly node: ShNode;
+export declare interface ArithmExp {
     /**
-     * `resolveWord` applied to the first word (`argv[0]`), with
-     * `{ context: 'command-argument' }` — every `CallExpr` word is an
-     * ordinary command-argument position, never an assignment value, so
-     * only a word-initial unquoted `~` triggers tilde expansion (an
-     * unquoted `~` after a `:`, e.g. `a:~/b`, is literal text here — see
-     * `ResolveWordOptions.context`'s doc comment).
+     * Identifies the upstream concrete record when carried through an interface union.
      */
-    readonly argv0: WordResolution;
-    /** `resolveWord` applied to every word, in argument order (same `{ context: 'command-argument' }` as {@link CommandSite.argv0}). */
-    readonly argv: readonly WordResolution[];
-    /** The path from the tree root to this site, outermost frame first. */
-    readonly context: readonly CommandContext[];
+    Type: 'ArithmExp';
+    /**
+     * deprecated $`expr` form
+     *
+     * False is an explicit upstream value and is never omitted.
+     */
+    Bracket: boolean;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    Left: SyntaxPos;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    Right: SyntaxPos;
+    /**
+     * mksh's $((# expr))
+     *
+     * False is an explicit upstream value and is never omitted.
+     */
+    Unsigned: boolean;
+    /**
+     * Null preserves the upstream absence of this component.
+     */
+    X: ArithmExpr | null;
 }
 
 /**
- * `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.
+ * The concrete records and typed nil pointers accepted by upstream syntax.ArithmExpr. Typed nil kinds are limited to this interface's actual implementers; auxiliary records are excluded.
  *
- * @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[];
+export declare type ArithmExpr =
+| BinaryArithm
+| FlagsArithm
+| ParenArithm
+| UnaryArithm
+| Word
+| TypedNil<'BinaryArithm' | 'FlagsArithm' | 'ParenArithm' | 'UnaryArithm' | 'Word'>;
 
 /**
- * Enumerates every command invocation (`CallExpr`) reachable from `root`,
- * with its resolved words ({@link resolveWord}) and the path used to reach
- * it ({@link CommandContext}). Descends everywhere a command can occur:
- * statement lists, both sides of `&&`/`||`/pipelines, subshells/blocks,
- * if/case branches *and* conditions, loop bodies *and* conditions, function
- * bodies, background/negated/coproc statements, and — critically —
- * `CmdSubst`/`ProcSubst` nested inside words, wherever those words occur
- * (arguments, redirection targets, case subjects/patterns, loop word
- * lists, assignment values, test/arithmetic operands, …), not only inside
- * `CallExpr.args`.
+ * ArrayElem represents a Bash array element.
  *
- * An assignment-only `CallExpr` (`FOO=bar`, `args` empty) has no first word
- * to resolve and is not itself a command invocation — no program runs — so
- * it produces no {@link CommandSite}; any command substitution nested in
- * its assigned value (`FOO=$(sub)`) is still found and reported.
+ * Index can be nil; for example, declare -a x=(value).
+ * Value can be nil; for example, declare -A x=(`index`=).
+ * Finally, neither can be nil; for example, declare -A x=(`index`=value)
  *
- * Results are sorted by source position (`node.range[0]`), so nested
- * command substitutions and out-of-structural-order redirection targets
- * still come back in source order regardless of traversal order.
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
  *
- * Facts only, matching {@link resolveWord}'s posture: no safety verdict, no
- * command/wrapper allowlist or denylist, no dataflow. A statically unknown
- * `argv0` (`static: false`) is a normal, expected result.
+ * @public
+ */
+export declare interface ArrayElem {
+    /**
+     * Identifies the upstream concrete record when carried through an interface union.
+     */
+    Type: 'ArrayElem';
+    /**
+     * Ordered upstream entries. Null preserves a nil slice and differs from an empty array.
+     */
+    Comments: Comment_2[] | null;
+    /**
+     * Null preserves the upstream absence of this component.
+     */
+    Index: ArithmExpr | null;
+    /**
+     * Null preserves the upstream absence of this component.
+     */
+    Value: Word | null;
+}
+
+/**
+ * Upstream ParExpOperator constant ArrayExclude. Its numeric value is preserved exactly.
  *
- * A long *linear* chain — `|`/`|&`/`&&`/`||` of any realistic length — is
- * traversed iteratively and never risks a stack overflow or trips the
- * nesting-depth guard below, regardless of how many stages/links it has.
+ * :| with `LangZsh`
  *
- * @param root - Any `ShNode` — typically a `File` from `parseSync`, but any
- * 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`/`{ }`
-     * bodies, chained `elif`) exceeds this module's defensive recursion-depth
-     * guard — see that error's doc comment for why this fails closed instead
-     * of returning a partial result, and why a gate-style consumer should treat
-     * it as `deny`.
-     * @public
+ * @public
+ */
+declare const ArrayExclude: 94;
+
+/**
+ * ArrayExpr represents a Bash array expression.
+ *
+ * This node will only appear with `LangBash`.
+ *
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+ *
+ * @public
+ */
+export declare interface ArrayExpr {
+    /**
+     * Identifies the upstream concrete record when carried through an interface union.
+     */
+    Type: 'ArrayExpr';
+    /**
+     * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+     */
+    Elems: (ArrayElem | null)[] | null;
+    /**
+     * Ordered upstream entries. Null preserves a nil slice and differs from an empty array.
+     */
+    Last: Comment_2[] | null;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    Lparen: SyntaxPos;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
      */
- export declare function enumerateCommands(root: ShNode): CommandSite[];
+    Rparen: SyntaxPos;
+}
 
- /**
-  * A 1-based line/column position. Columns are UTF-16 code units, matching
-  * JavaScript string indexing (see {@link ShNode.range}).
-  *
-  * @public
-  */
- export declare interface Position {
-     readonly line: number;
-     readonly column: number;
- }
+/**
+ * Upstream ParExpOperator constant ArrayIntersect. Its numeric value is preserved exactly.
+ *
+ * :* with `LangZsh`
+ *
+ * @public
+ */
+declare const ArrayIntersect: 95;
 
- /**
-  * 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.
-  *
-  * 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.
-  *
-  * **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:
-  *
-  * 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).
-  *
-  * `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.
-  *
-  * @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
-      */
-  export declare function resolveArgv0(site: CommandSite, options?: ResolveArgv0Options): Argv0Resolution;
+/**
+ * Upstream BinAritOperator constant Assgn. Its numeric value is preserved exactly.
+ *
+ * =
+ *
+ * @public
+ */
+declare const Assgn: 87;
+
+/**
+ * Assign represents an assignment to a variable.
+ *
+ * Here and elsewhere, Index can mean either an index expression into an indexed
+ * array, or a string key into an associative array.
+ *
+ * If Index is non-nil, the value will be a word and not an array as nested
+ * arrays are not allowed.
+ *
+ * If Naked is true and Name is nil, the assignment is part of a `DeclClause` and
+ * the argument (in the Value field) will be evaluated at run-time. This
+ * includes parameter expansions, which may expand to assignments or options.
+ *
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+ *
+ * @public
+ */
+export declare interface Assign {
+    /**
+     * Identifies the upstream concrete record when carried through an interface union.
+     */
+    Type: 'Assign';
+    /**
+     * +=
+     *
+     * False is an explicit upstream value and is never omitted.
+     */
+    Append: boolean;
+    /**
+     * =(arr)
+     *
+     * Null preserves the upstream absence of this component.
+     */
+    Array: ArrayExpr | null;
+    /**
+     * `i`, ["k"]
+     *
+     * Null preserves the upstream absence of this component.
+     */
+    Index: ArithmExpr | null;
+    /**
+     * without '='
+     *
+     * False is an explicit upstream value and is never omitted.
+     */
+    Naked: boolean;
+    /**
+     * must be a valid name
+     *
+     * Null preserves the upstream absence of this component.
+     */
+    Name: Lit | null;
+    /**
+     * =val
+     *
+     * Null preserves the upstream absence of this component.
+     */
+    Value: Word | null;
+}
+
+/**
+ * Upstream ParExpOperator constant AssignUnset. Its numeric value is preserved exactly.
+ *
+ * =
+ *
+ * @public
+ */
+declare const AssignUnset: 87;
+
+/**
+ * Upstream ParExpOperator constant AssignUnsetOrNull. Its numeric value is preserved exactly.
+ *
+ * :=
+ *
+ * @public
+ */
+declare const AssignUnsetOrNull: 88;
+
+/**
+ * The upstream BinAritOperator domain: exact named tokens, the Go zero value, and explicitly validated unnamed uint32 values. Constants shared by upstream families retain their shared numeric identity.
+ *
+ * @public
+ */
+export declare type BinAritOperator =
+| 0
+| typeof Add
+| typeof AddAssgn
+| typeof And
+| typeof AndArit
+| typeof AndAssgn
+| typeof AndBoolAssgn
+| typeof Assgn
+| typeof Comma
+| typeof Eql
+| typeof Geq
+| typeof Gtr
+| typeof Leq
+| typeof Lss
+| typeof Mul
+| typeof MulAssgn
+| typeof Neq
+| typeof Or
+| typeof OrArit
+| typeof OrAssgn
+| typeof OrBoolAssgn
+| typeof Pow
+| typeof PowAssgn
+| typeof Quo
+| typeof QuoAssgn
+| typeof Rem
+| typeof RemAssgn
+| typeof Shl
+| typeof ShlAssgn
+| typeof Shr
+| typeof ShrAssgn
+| typeof Sub
+| typeof SubAssgn
+| typeof TernColon
+| typeof TernQuest
+| typeof Xor
+| typeof XorAssgn
+| typeof XorBool
+| typeof XorBoolAssgn
+| RawOperator<'BinAritOperator'>;
+
+/**
+ * BinaryArithm represents a binary arithmetic expression.
+ *
+ * If Op is any assign operator, X will be a word with a single `Lit` whose value
+ * is a valid name.
+ *
+ * Ternary operators like "a ? b : c" are fit into this structure. Thus, if
+ * Op==`TernQuest`, Y will be a `BinaryArithm` with Op==`TernColon`.
+ * `TernColon` does not appear in any other scenario.
+ *
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+ *
+ * @public
+ */
+export declare interface BinaryArithm {
+    /**
+     * Identifies the upstream concrete record when carried through an interface union.
+     */
+    Type: 'BinaryArithm';
+    /**
+     * Upstream operator value, preserving named tokens, zero, and explicitly represented raw uint32 values.
+     */
+    Op: BinAritOperator;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    OpPos: SyntaxPos;
+    /**
+     * Null preserves the upstream absence of this component.
+     */
+    X: ArithmExpr | null;
+    /**
+     * Null preserves the upstream absence of this component.
+     */
+    Y: ArithmExpr | null;
+}
+
+/**
+ * BinaryCmd represents a binary expression between two statements.
+ *
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+ *
+ * @public
+ */
+export declare interface BinaryCmd {
+    /**
+     * Identifies the upstream concrete record when carried through an interface union.
+     */
+    Type: 'BinaryCmd';
+    /**
+     * Upstream operator value, preserving named tokens, zero, and explicitly represented raw uint32 values.
+     */
+    Op: BinCmdOperator;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    OpPos: SyntaxPos;
+    /**
+     * Null preserves the upstream absence of this component.
+     */
+    X: Stmt | null;
+    /**
+     * Null preserves the upstream absence of this component.
+     */
+    Y: Stmt | null;
+}
+
+/**
+ * BinaryTest represents a binary test expression.
+ *
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+ *
+ * @public
+ */
+export declare interface BinaryTest {
+    /**
+     * Identifies the upstream concrete record when carried through an interface union.
+     */
+    Type: 'BinaryTest';
+    /**
+     * Upstream operator value, preserving named tokens, zero, and explicitly represented raw uint32 values.
+     */
+    Op: BinTestOperator;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    OpPos: SyntaxPos;
+    /**
+     * Null preserves the upstream absence of this component.
+     */
+    X: TestExpr | null;
+    /**
+     * Null preserves the upstream absence of this component.
+     */
+    Y: TestExpr | null;
+}
+
+/**
+ * The upstream BinCmdOperator domain: exact named tokens, the Go zero value, and explicitly validated unnamed uint32 values. Constants shared by upstream families retain their shared numeric identity.
+ *
+ * @public
+ */
+export declare type BinCmdOperator =
+0 | typeof AndStmt | typeof OrStmt | typeof Pipe | typeof PipeAll | RawOperator<'BinCmdOperator'>;
+
+/**
+ * The upstream BinTestOperator domain: exact named tokens, the Go zero value, and explicitly validated unnamed uint32 values. Constants shared by upstream families retain their shared numeric identity.
+ *
+ * @public
+ */
+export declare type BinTestOperator =
+| 0
+| typeof AndTest
+| typeof OrTest
+| typeof TsAfter
+| typeof TsBefore
+| typeof TsDevIno
+| typeof TsEql
+| typeof TsGeq
+| typeof TsGtr
+| typeof TsLeq
+| typeof TsLss
+| typeof TsMatch
+| typeof TsMatchShort
+| typeof TsNeq
+| typeof TsNewer
+| typeof TsNoMatch
+| typeof TsOlder
+| typeof TsReMatch
+| RawOperator<'BinTestOperator'>;
+
+/**
+ * Upstream UnAritOperator constant BitNegation. Its numeric value is preserved exactly.
+ *
+ * ~
+ *
+ * @public
+ */
+declare const BitNegation: 40;
+
+/**
+ * Block represents a series of commands that should be executed in a nested
+ * scope. It is essentially a list of statements within curly braces.
+ *
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+ *
+ * @public
+ */
+export declare interface Block {
+    /**
+     * Identifies the upstream concrete record when carried through an interface union.
+     */
+    Type: 'Block';
+    /**
+     * Ordered upstream entries. Null preserves a nil slice and differs from an empty array.
+     */
+    Last: Comment_2[] | null;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    Lbrace: SyntaxPos;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    Rbrace: SyntaxPos;
+    /**
+     * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+     */
+    Stmts: (Stmt | null)[] | null;
+}
+
+/**
+ * BraceExp represents a Bash brace expression, such as "\{a,f\}" or "\{1..10\}".
+ *
+ * This node will only appear as a result of `SplitBraces`.
+ *
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+ *
+ * @public
+ */
+export declare interface BraceExp {
+    /**
+     * Identifies the upstream concrete record when carried through an interface union.
+     */
+    Type: 'BraceExp';
+    /**
+     * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+     */
+    Elems: (Word | null)[] | null;
+    /**
+     * \{x..y[..incr]\} instead of \{x,y[,...]\}
+     *
+     * False is an explicit upstream value and is never omitted.
+     */
+    Sequence: boolean;
+}
+
+/**
+ * Upstream CaseOperator constant Break. Its numeric value is preserved exactly.
+ *
+ * ;;
+ *
+ * @public
+ */
+declare const Break: 35;
+
+/**
+ * CallExpr represents a command execution or function call, otherwise known as
+ * a "simple command".
+ *
+ * If Args is empty, Assigns apply to the shell environment. Otherwise, they are
+ * variables that cannot be arrays and which only apply to the call.
+ *
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+ *
+ * @public
+ */
+export declare interface CallExpr {
+    /**
+     * Identifies the upstream concrete record when carried through an interface union.
+     */
+    Type: 'CallExpr';
+    /**
+     * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+     */
+    Args: (Word | null)[] | null;
+    /**
+     * a=x b=y args
+     *
+     * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+     */
+    Assigns: (Assign | null)[] | null;
+}
+
+/**
+ * CaseClause represents a case (switch) clause.
+ *
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+ *
+ * @public
+ */
+export declare interface CaseClause {
+    /**
+     * Identifies the upstream concrete record when carried through an interface union.
+     */
+    Type: 'CaseClause';
+    /**
+     * deprecated mksh form with braces instead of in/esac
+     *
+     * False is an explicit upstream value and is never omitted.
+     */
+    Braces: boolean;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    Case: SyntaxPos;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    Esac: SyntaxPos;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    In: SyntaxPos;
+    /**
+     * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+     */
+    Items: (CaseItem | null)[] | null;
+    /**
+     * Ordered upstream entries. Null preserves a nil slice and differs from an empty array.
+     */
+    Last: Comment_2[] | null;
+    /**
+     * Null preserves the upstream absence of this component.
+     */
+    Word: Word | null;
+}
+
+/**
+ * CaseItem represents a pattern list (case) within a `CaseClause`.
+ *
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+ *
+ * @public
+ */
+export declare interface CaseItem {
+    /**
+     * Identifies the upstream concrete record when carried through an interface union.
+     */
+    Type: 'CaseItem';
+    /**
+     * Ordered upstream entries. Null preserves a nil slice and differs from an empty array.
+     */
+    Comments: Comment_2[] | null;
+    /**
+     * Ordered upstream entries. Null preserves a nil slice and differs from an empty array.
+     */
+    Last: Comment_2[] | null;
+    /**
+     * Upstream operator value, preserving named tokens, zero, and explicitly represented raw uint32 values.
+     */
+    Op: CaseOperator;
+    /**
+     * unset if it was finished by "esac"
+     *
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    OpPos: SyntaxPos;
+    /**
+     * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+     */
+    Patterns: (Word | null)[] | null;
+    /**
+     * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+     */
+    Stmts: (Stmt | null)[] | null;
+}
+
+/**
+ * The upstream CaseOperator domain: exact named tokens, the Go zero value, and explicitly validated unnamed uint32 values. Constants shared by upstream families retain their shared numeric identity.
+ *
+ * @public
+ */
+export declare type CaseOperator =
+| 0
+| typeof Break
+| typeof Fallthrough
+| typeof Resume
+| typeof ResumeKorn
+| RawOperator<'CaseOperator'>;
+
+/**
+ * Upstream ProcOperator constant CmdIn. Its numeric value is preserved exactly.
+ *
+ * \<(
+ *
+ * @public
+ */
+declare const CmdIn: 78;
+
+/**
+ * Upstream ProcOperator constant CmdInTemp. Its numeric value is preserved exactly.
+ *
+ * =(
+ *
+ * @public
+ */
+declare const CmdInTemp: 79;
+
+/**
+ * Upstream ProcOperator constant CmdOut. Its numeric value is preserved exactly.
+ *
+ * \>(
+ *
+ * @public
+ */
+declare const CmdOut: 80;
+
+/**
+ * CmdSubst represents a command substitution.
+ *
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+ *
+ * @public
+ */
+export declare interface CmdSubst {
+    /**
+     * Identifies the upstream concrete record when carried through an interface union.
+     */
+    Type: 'CmdSubst';
+    /**
+     * deprecated `foo`
+     *
+     * False is an explicit upstream value and is never omitted.
+     */
+    Backquotes: boolean;
+    /**
+     * Ordered upstream entries. Null preserves a nil slice and differs from an empty array.
+     */
+    Last: Comment_2[] | null;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    Left: SyntaxPos;
+    /**
+     * mksh's $\{|foo;\}
+     *
+     * False is an explicit upstream value and is never omitted.
+     */
+    ReplyVar: boolean;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    Right: SyntaxPos;
+    /**
+     * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+     */
+    Stmts: (Stmt | null)[] | null;
+    /**
+     * mksh's $\{ foo;\}
+     *
+     * False is an explicit upstream value and is never omitted.
+     */
+    TempFile: boolean;
+}
+
+/**
+ * Upstream BinAritOperator constant Comma. Its numeric value is preserved exactly.
+ *
+ * ,
+ *
+ * @public
+ */
+declare const Comma: 98;
+
+/**
+ * The concrete records and typed nil pointers accepted by upstream syntax.Command. Typed nil kinds are limited to this interface's actual implementers; auxiliary records are excluded.
+ *
+ * @public
+ */
+export declare type Command =
+| ArithmCmd
+| BinaryCmd
+| Block
+| CallExpr
+| CaseClause
+| CoprocClause
+| DeclClause
+| ForClause
+| FuncDecl
+| IfClause
+| LetClause
+| Subshell
+| TestClause
+| TestDecl
+| TimeClause
+| WhileClause
+| TypedNil<
+| 'ArithmCmd'
+| 'BinaryCmd'
+| 'Block'
+| 'CallExpr'
+| 'CaseClause'
+| 'CoprocClause'
+| 'DeclClause'
+| 'ForClause'
+| 'FuncDecl'
+| 'IfClause'
+| 'LetClause'
+| 'Subshell'
+| 'TestClause'
+| 'TestDecl'
+| 'TimeClause'
+| 'WhileClause'
+>;
+
+/**
+ * A single frame of the path from the root of the tree down to a
+ * {@link CommandSite}, describing *how* the command is reached — never
+ * whether it is safe to run. `CommandSite.context` is an ordered stack of
+ * these, outermost frame first:
+ *
+ * - `'and'`/`'or'` (`side: 'right'`) — the right-hand operand of a
+ *   `BinaryCmd` (mvdan/sh's node for both `&&` and `||`); only the right
+ *   side is tagged; the left side inherits the surrounding context
+ *   unchanged, since it runs unconditionally relative to this operator.
+ * - `'pipeline'` (`stage: n`) — one stage of a `|`/`|&` chain (also a
+ *   `BinaryCmd`, left-associatively nested by mvdan/sh); every stage is
+ *   tagged, 0-indexed left to right, regardless of whether the chain mixes
+ *   `|` and `|&`.
+ * - `'subshell'` — inside a `Subshell` (`( ... )`).
+ * - `'cmdSubst'`/`'procSubst'` — inside a `CmdSubst` (`$(...)`/backticks) or
+ *   `ProcSubst` (`<(...)`/`>(...)`) reached from *any* word-bearing
+ *   position (an argument, a redirection target, a case subject, a loop's
+ *   word list, an assignment value, a test/arithmetic operand, …) — not
+ *   only from `CallExpr.Args`.
+ * - `'if'` (`branch: 'cond' | 'then' | 'else'`) — inside an `IfClause`'s
+ *   condition, then-branch, or else-branch (mvdan/sh nests `elif` chains as
+ *   `IfClause.Else` pointing to another `IfClause`, so an `elif`'s own
+ *   condition/then are reached through an `{kind:'if',branch:'else'}` frame
+ *   first, then their own `'cond'`/`'then'` frame — reflecting the real
+ *   nesting rather than collapsing it).
+ * - `'case'` — inside one `CaseClause` branch's statement list (not the
+ *   case subject word or the patterns).
+ * - `'loop'` (`role` is `'body'` or `'cond'`) — inside a `ForClause`'s
+ *   statement list (`role: 'body'` only — a `for` loop has no
+ *   statement-list condition) or a `WhileClause`'s (`role: 'cond'` for the
+ *   condition, `role: 'body'` for the loop body).
+ * - `'function'` (`name`) — inside a `FuncDecl`'s body; `name` is the
+ *   function's literal name text.
+ * - `'background'`/`'negated'` — the enclosing `Stmt` has mvdan/sh's
+ *   Background/Negated flag set (`cmd &`, `! cmd`).
+ * - `'coproc'` — inside a `CoprocClause`'s statement (a `coproc` block,
+ *   optionally named).
+ *
+ * A `Block` grouping (`{ ...; }`) and a `TimeClause` (`time cmd`) are
+ * deliberately transparent — grouping and timing a command doesn't change
+ * how it's reached, so no frame is added for either.
+ *
+ * This union may grow in a **minor** release — a future mvdan/sh grammar
+ * construct this module starts modeling can add a new `kind` variant
+ * without that being a breaking change (mirroring
+ * {@link WordResolutionReason}'s semver policy in `resolve-word.ts`). It is
+ * deliberately not sealed against extension elsewhere in the codebase.
+ * Every existing variant's shape (its extra fields, if any) is stable —
+ * only new variants are ever added — so an exhaustive compile-time
+ * `switch` over `.kind` should still include a `default` case to stay
+ * forward-compatible.
+ *
+ * @public
+ */
+export declare type CommandContext = {
+    readonly kind: 'and';
+    readonly side: 'right';
+} | {
+    readonly kind: 'or';
+    readonly side: 'right';
+} | {
+    readonly kind: 'pipeline';
+    readonly stage: number;
+} | {
+    readonly kind: 'subshell';
+} | {
+    readonly kind: 'cmdSubst';
+} | {
+    readonly kind: 'procSubst';
+} | {
+    readonly kind: 'if';
+    readonly branch: 'then' | 'else' | 'cond';
+} | {
+    readonly kind: 'case';
+} | {
+    readonly kind: 'loop';
+    readonly role: 'body' | 'cond';
+} | {
+    readonly kind: 'function';
+    readonly name: GoString;
+} | {
+    readonly kind: 'background';
+} | {
+    readonly kind: 'negated';
+} | {
+    readonly kind: 'coproc';
+};
+
+/**
+ * One place in the tree where a command is actually invoked — a `CallExpr`
+ * node, together with its resolved words and the path used to reach it.
+ * Facts only, matching {@link resolveWord}'s posture: no safety verdict, no
+ * hardcoded command/wrapper list. A dynamic (`static: false`) `argv0` is a
+ * normal, expected result — not an error and not itself reported as
+ * "unknown"/"unsafe".
+ *
+ * @public
+ */
+export declare interface CommandSite {
+    /** The `CallExpr` node this site was found at. */
+    readonly node: CallExpr;
+    /**
+     * `resolveWord` applied to the first word (`argv[0]`), with
+     * `{ context: 'command-argument' }` — every `CallExpr` word is an
+     * ordinary command-argument position, never an assignment value, so
+     * only a word-initial unquoted `~` triggers tilde expansion (an
+     * unquoted `~` after a `:`, e.g. `a:~/b`, is literal text here — see
+     * `ResolveWordOptions.context`'s doc comment).
+     */
+    readonly argv0: WordResolution;
+    /** `resolveWord` applied to every word, in argument order (same `{ context: 'command-argument' }` as {@link CommandSite.argv0}). */
+    readonly argv: readonly WordResolution[];
+    /** The path from the tree root to this site, outermost frame first. */
+    readonly context: readonly CommandContext[];
+}
+
+/**
+ * Comment represents a single comment on a single line.
+ *
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+ *
+ * @public
+ */
+declare interface Comment_2 {
+    /**
+     * Identifies the upstream concrete record when carried through an interface union.
+     */
+    Type: 'Comment';
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    Hash: SyntaxPos;
+    /**
+     * Upstream string bytes; non-UTF-8 values remain bytes rather than replacement text.
+     */
+    Text: GoString;
+}
+export { Comment_2 as Comment }
+
+/**
+ * CoprocClause represents a Bash coproc clause.
+ *
+ * This node will only appear with `LangBash`.
+ *
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+ *
+ * @public
+ */
+export declare interface CoprocClause {
+    /**
+     * Identifies the upstream concrete record when carried through an interface union.
+     */
+    Type: 'CoprocClause';
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    Coproc: SyntaxPos;
+    /**
+     * Null preserves the upstream absence of this component.
+     */
+    Name: Word | null;
+    /**
+     * Null preserves the upstream absence of this component.
+     */
+    Stmt: Stmt | null;
+}
+
+/**
+ * CStyleLoop represents the behavior of a for clause similar to the C
+ * language.
+ *
+ * This node will only appear with `LangBash`.
+ *
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+ *
+ * @public
+ */
+export declare interface CStyleLoop {
+    /**
+     * Identifies the upstream concrete record when carried through an interface union.
+     */
+    Type: 'CStyleLoop';
+    /**
+     * Init, Cond, Post can each be nil, if the for loop construct omits it.
+     *
+     * Null preserves the upstream absence of this component.
+     */
+    Cond: ArithmExpr | null;
+    /**
+     * Init, Cond, Post can each be nil, if the for loop construct omits it.
+     *
+     * Null preserves the upstream absence of this component.
+     */
+    Init: ArithmExpr | null;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    Lparen: SyntaxPos;
+    /**
+     * Init, Cond, Post can each be nil, if the for loop construct omits it.
+     *
+     * Null preserves the upstream absence of this component.
+     */
+    Post: ArithmExpr | null;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    Rparen: SyntaxPos;
+}
+
+/**
+ * Upstream RedirOperator constant DashHdoc. Its numeric value is preserved exactly.
+ *
+ * \<\<-
+ *
+ * @public
+ */
+declare const DashHdoc: 72;
+
+/**
+ * DblQuoted represents a list of nodes within double quotes.
+ *
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+ *
+ * @public
+ */
+export declare interface DblQuoted {
+    /**
+     * Identifies the upstream concrete record when carried through an interface union.
+     */
+    Type: 'DblQuoted';
+    /**
+     * $""
+     *
+     * False is an explicit upstream value and is never omitted.
+     */
+    Dollar: boolean;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    Left: SyntaxPos;
+    /**
+     * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+     */
+    Parts: (WordPart | null)[] | null;
+    /**
+     * Recorded source position; invalid and recovered states remain distinct.
+     */
+    Right: SyntaxPos;
+}
+
+/**
+ * Upstream UnAritOperator constant Dec. Its numeric value is preserved exactly.
+ *
+ * --
+ *
+ * @public
+ */
+declare const Dec: 42;
+
+/**
+ * DeclClause represents a Bash declare clause.
+ *
+ * Args can contain a mix of regular and naked assignments. The naked
+ * assignments can represent either options or variable names.
+ *
+ * This node will only appear with `LangBash`.
+ *
+ * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+ *
+ * @public
+ */
+export declare interface DeclClause {
+    /**
+     * Identifies the upstream concrete record when carried through an interface union.
+     */
+    Type: 'DeclClause';
+    /**
+     * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+     */
+    Args: (Assign | null)[] | null;
+    /**
+     * Variant is one of "declare", "local", "export", "readonly",
+     * "typeset", or "nameref".
+     *
+     * Null preserves the upstream absence of this component.
+     */
+    Variant: Lit | null;
+}
+
+/**
+ * `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. Per-call wrapper options are
+ * separate values and cannot mutate these shared defaults.
+ *
+ * `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[];
+
+/**
+ * Upstream ParExpOperator constant DefaultUnset. Its numeric value is preserved exactly.
+ *
+ * -
+ *
+ * @public
+ */
+declare const DefaultUnset: 83;
+
+/**
+ * Upstream ParExpOperator constant DefaultUnsetOrNull. Its numeric value is preserved exactly.
+ *
+ * :-
+ *
+ * @public
+ */
+declare const DefaultUnsetOrNull: 84;
+
+/**
+ * Upstream RedirOperator constant DplIn. Its numeric value is preserved exactly.
+ *
+ * \<&
+ *
+ * @public
+ */
+declare const DplIn: 67;
+
+/**
+ * Upstream RedirOperator constant DplOut. Its numeric value is preserved exactly.
+ *
+ * \>&
+ *
+ * @public
+ */
+declare const DplOut: 68;
+
+/**
+ * Enumerates every command invocation (`CallExpr`) reachable from `root`,
+ * with its resolved words ({@link resolveWord}) and the path used to reach
+ * it ({@link CommandContext}). Descends everywhere a command can occur:
+ * statement lists, both sides of `&&`/`||`/pipelines, subshells/blocks,
+ * if/case branches *and* conditions, loop bodies *and* conditions, function
+ * bodies, background/negated/coproc statements, and — critically —
+ * `CmdSubst`/`ProcSubst` nested inside words, wherever those words occur
+ * (arguments, redirection targets, case subjects/patterns, loop word
+ * lists, assignment values, test/arithmetic operands, …), not only inside
+ * `CallExpr.Args`.
+ *
+ * An assignment-only `CallExpr` (`FOO=bar`, `args` empty) has no first word
+ * to resolve and is not itself a command invocation — no program runs — so
+ * it produces no {@link CommandSite}; any command substitution nested in
+ * its assigned value (`FOO=$(sub)`) is still found and reported.
+ *
+ * Results are sorted by source position (`nodePos(node).Offset`), so nested
+ * command substitutions and out-of-structural-order redirection targets
+ * still come back in source order regardless of traversal order.
+ *
+ * Facts only, matching {@link resolveWord}'s posture: no safety verdict, no
+ * command/wrapper allowlist or denylist, no dataflow. A statically unknown
+ * `argv0` (`static: false`) is a normal, expected result.
+ *
+ * A long *linear* chain — `|`/`|&`/`&&`/`||` of any realistic length — is
+ * traversed iteratively and never risks a stack overflow or trips the
+ * nesting-depth guard below, regardless of how many stages/links it has.
+ *
+ * @param root - Any `Node` — typically a `File` from `parseSync`, but any
+ * subtree (a `Stmt`, a `Command`, or even a bare `Word`) is handled.
+ * The depth guard also applies to caller-built or mutated trees.
+ * @throws {@link ShAnalyzeMaxDepthError} if `root`'s genuinely nested
+     * structure (subshells within subshells, chained command/process
+     * substitutions, deeply nested `if`/`case`/loop/function/`time`/`{ }`
+     * bodies, chained `elif`) exceeds this module's defensive recursion-depth
+     * guard — see that error's doc comment for why this fails closed instead
+     * of returning a partial result, and why a gate-style consumer should treat
+     * it as `deny`.
+     * @public
+     */
+ export declare function enumerateCommands(root: Node_2): CommandSite[];
+
+ /**
+  * Upstream BinAritOperator constant Eql. Its numeric value is preserved exactly.
+  *
+  * ==
+  *
+  * @public
+  */
+ declare const Eql: 45;
+
+ /**
+  * Upstream ParExpOperator constant ErrorUnset. Its numeric value is preserved exactly.
+  *
+  * ?
+  *
+  * @public
+  */
+ declare const ErrorUnset: 85;
+
+ /**
+  * Upstream ParExpOperator constant ErrorUnsetOrNull. Its numeric value is preserved exactly.
+  *
+  * :?
+  *
+  * @public
+  */
+ declare const ErrorUnsetOrNull: 86;
+
+ /**
+  * Expansion represents string manipulation in a `ParamExp` other than those
+  * covered by `Replace`.
+  *
+  * Auxiliary syntax data, not a syntax.Node; it has no independent source bounds.
+  *
+  * @public
+  */
+ export declare interface Expansion {
+     /**
+      * Identifies the upstream concrete record when carried through an interface union.
+      */
+     Type: 'Expansion';
+     /**
+      * Upstream operator value, preserving named tokens, zero, and explicitly represented raw uint32 values.
+      */
+     Op: ParExpOperator;
+     /**
+      * Null preserves the upstream absence of this component.
+      */
+     Word: Word | null;
+ }
+
+ /**
+  * ExtGlob represents a Bash extended globbing expression. Note that these are
+  * parsed independently of whether or not `shopt -s extglob` has been used,
+  * as the parser runs statically and independently of any interpreter.
+  *
+  * This node will only appear with `LangBash` and `LangMirBSDKorn`.
+  *
+  * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+  *
+  * @public
+  */
+ export declare interface ExtGlob {
+     /**
+      * Identifies the upstream concrete record when carried through an interface union.
+      */
+     Type: 'ExtGlob';
+     /**
+      * Upstream operator value, preserving named tokens, zero, and explicitly represented raw uint32 values.
+      */
+     Op: GlobOperator;
+     /**
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     OpPos: SyntaxPos;
+     /**
+      * Null preserves the upstream absence of this component.
+      */
+     Pattern: Lit | null;
+ }
+
+ /**
+  * Upstream CaseOperator constant Fallthrough. Its numeric value is preserved exactly.
+  *
+  * ;&
+  *
+  * @public
+  */
+ declare const Fallthrough: 36;
+
+ /**
+  * File represents a shell source file.
+  *
+  * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+  *
+  * @public
+  */
+ declare interface File_2 {
+     /**
+      * Identifies the upstream concrete record when carried through an interface union.
+      */
+     Type: 'File';
+     /**
+      * Ordered upstream entries. Null preserves a nil slice and differs from an empty array.
+      */
+     Last: Comment_2[] | null;
+     /**
+      * Upstream string bytes; non-UTF-8 values remain bytes rather than replacement text.
+      */
+     Name: GoString;
+     /**
+      * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+      */
+     Stmts: (Stmt | null)[] | null;
+ }
+ export { File_2 as File }
+
+ /**
+  * FlagsArithm represents zsh subscript flags attached to an arithmetic expression,
+  * such as $\{array[(flags)expr]\}.
+  *
+  * This node will only appear with `LangZsh`.
+  *
+  * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+  *
+  * @public
+  */
+ export declare interface FlagsArithm {
+     /**
+      * Identifies the upstream concrete record when carried through an interface union.
+      */
+     Type: 'FlagsArithm';
+     /**
+      * Null preserves the upstream absence of this component.
+      */
+     Flags: Lit | null;
+     /**
+      * Null preserves the upstream absence of this component.
+      */
+     X: ArithmExpr | null;
+ }
+
+ /**
+  * ForClause represents a for or a select clause. The latter is only present in
+  * Bash.
+  *
+  * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+  *
+  * @public
+  */
+ export declare interface ForClause {
+     /**
+      * Identifies the upstream concrete record when carried through an interface union.
+      */
+     Type: 'ForClause';
+     /**
+      * deprecated form with \{ \} instead of do/done
+      *
+      * False is an explicit upstream value and is never omitted.
+      */
+     Braces: boolean;
+     /**
+      * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+      */
+     Do: (Stmt | null)[] | null;
+     /**
+      * Ordered upstream entries. Null preserves a nil slice and differs from an empty array.
+      */
+     DoLast: Comment_2[] | null;
+     /**
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     DoPos: SyntaxPos;
+     /**
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     DonePos: SyntaxPos;
+     /**
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     ForPos: SyntaxPos;
+     /**
+      * Null preserves the upstream absence of this component.
+      */
+     Loop: Loop | null;
+     /**
+      * False is an explicit upstream value and is never omitted.
+      */
+     Select: boolean;
+ }
+
+ /**
+  * FuncDecl represents the declaration of a function.
+  *
+  * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+  *
+  * @public
+  */
+ export declare interface FuncDecl {
+     /**
+      * Identifies the upstream concrete record when carried through an interface union.
+      */
+     Type: 'FuncDecl';
+     /**
+      * Null preserves the upstream absence of this component.
+      */
+     Body: Stmt | null;
+     /**
+      * Only one of these is set at a time.
+      * Neither is set when declaring an anonymous func with `LangZsh`.
+      *
+      * Null preserves the upstream absence of this component.
+      */
+     Name: Lit | null;
+     /**
+      * When declaring many func names with `LangZsh`.
+      *
+      * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+      */
+     Names: (Lit | null)[] | null;
+     /**
+      * with () parentheses, can only be false when RsrvWord==true
+      *
+      * False is an explicit upstream value and is never omitted.
+      */
+     Parens: boolean;
+     /**
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     Position: SyntaxPos;
+     /**
+      * non-posix "function f" style
+      *
+      * False is an explicit upstream value and is never omitted.
+      */
+     RsrvWord: boolean;
+ }
+
+ /**
+  * Upstream BinAritOperator constant Geq. Its numeric value is preserved exactly.
+  *
+  * \>=
+  *
+  * @public
+  */
+ declare const Geq: 48;
+
+ /**
+  * Upstream GlobOperator constant GlobExcept. Its numeric value is preserved exactly.
+  *
+  * !(
+  *
+  * @public
+  */
+ declare const GlobExcept: 143;
+
+ /**
+  * Upstream GlobOperator constant GlobOne. Its numeric value is preserved exactly.
+  *
+  * \@(
+  *
+  * @public
+  */
+ declare const GlobOne: 142;
+
+ /**
+  * Upstream GlobOperator constant GlobOneOrMore. Its numeric value is preserved exactly.
+  *
+  * +(
+  *
+  * @public
+  */
+ declare const GlobOneOrMore: 141;
+
+ /**
+  * The upstream GlobOperator domain: exact named tokens, the Go zero value, and explicitly validated unnamed uint32 values. Constants shared by upstream families retain their shared numeric identity.
+  *
+  * @public
+  */
+ export declare type GlobOperator =
+ | 0
+ | typeof GlobExcept
+ | typeof GlobOne
+ | typeof GlobOneOrMore
+ | typeof GlobZeroOrMore
+ | typeof GlobZeroOrOne
+ | RawOperator<'GlobOperator'>;
+
+ /**
+  * Upstream GlobOperator constant GlobZeroOrMore. Its numeric value is preserved exactly.
+  *
+  * *(
+  *
+  * @public
+  */
+ declare const GlobZeroOrMore: 140;
+
+ /**
+  * Upstream GlobOperator constant GlobZeroOrOne. Its numeric value is preserved exactly.
+  *
+  * ?(
+  *
+  * @public
+  */
+ declare const GlobZeroOrOne: 139;
+
+ /**
+  * A Go string's exact bytes. Valid UTF-8 is represented as a JavaScript string; other bytes use Uint8Array. String inputs must not contain unpaired surrogates, which have no faithful UTF-8 representation.
+  *
+  * @public
+  */
+ export declare type GoString = string | Uint8Array;
+
+ /**
+  * Upstream BinAritOperator constant Gtr. Its numeric value is preserved exactly.
+  *
+  * \>
+  *
+  * @public
+  */
+ declare const Gtr: 63;
+
+ /**
+  * Upstream RedirOperator constant Hdoc. Its numeric value is preserved exactly.
+  *
+  * \<\<
+  *
+  * @public
+  */
+ declare const Hdoc: 71;
+
+ /**
+  * IfClause represents an if statement.
+  *
+  * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+  *
+  * @public
+  */
+ export declare interface IfClause {
+     /**
+      * Identifies the upstream concrete record when carried through an interface union.
+      */
+     Type: 'IfClause';
+     /**
+      * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+      */
+     Cond: (Stmt | null)[] | null;
+     /**
+      * Ordered upstream entries. Null preserves a nil slice and differs from an empty array.
+      */
+     CondLast: Comment_2[] | null;
+     /**
+      * if non-nil, an "elif" or an "else"
+      *
+      * Null preserves the upstream absence of this component.
+      */
+     Else: IfClause | null;
+     /**
+      * position of "fi", shared with .Else if non-nil
+      *
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     FiPos: SyntaxPos;
+     /**
+      * comments on the first "elif", "else", or "fi"
+      *
+      * Ordered upstream entries. Null preserves a nil slice and differs from an empty array.
+      */
+     Last: Comment_2[] | null;
+     /**
+      * position of the starting "if", "elif", or "else" token
+      *
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     Position: SyntaxPos;
+     /**
+      * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+      */
+     Then: (Stmt | null)[] | null;
+     /**
+      * Ordered upstream entries. Null preserves a nil slice and differs from an empty array.
+      */
+     ThenLast: Comment_2[] | null;
+     /**
+      * position of "then", empty if this is an "else"
+      *
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     ThenPos: SyntaxPos;
+ }
+
+ /**
+  * Upstream UnAritOperator constant Inc. Its numeric value is preserved exactly.
+  *
+  * ++
+  *
+  * @public
+  */
+ declare const Inc: 41;
+
+ /**
+  * Upstream BinAritOperator constant Leq. Its numeric value is preserved exactly.
+  *
+  * \<=
+  *
+  * @public
+  */
+ declare const Leq: 47;
+
+ /**
+  * LetClause represents a Bash let clause.
+  *
+  * This node will only appear with `LangBash` and `LangMirBSDKorn`.
+  *
+  * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+  *
+  * @public
+  */
+ export declare interface LetClause {
+     /**
+      * Identifies the upstream concrete record when carried through an interface union.
+      */
+     Type: 'LetClause';
+     /**
+      * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+      */
+     Exprs: (ArithmExpr | null)[] | null;
+     /**
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     Let: SyntaxPos;
+ }
+
+ /**
+  * Lit represents a string literal.
+  *
+  * Note that a parsed string literal may not appear as-is in the original source
+  * code, as it is possible to split literals by escaping newlines. The splitting
+  * is lost, but the end position is not.
+  *
+  * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+  *
+  * @public
+  */
+ export declare interface Lit {
+     /**
+      * Identifies the upstream concrete record when carried through an interface union.
+      */
+     Type: 'Lit';
+     /**
+      * Upstream string bytes; non-UTF-8 values remain bytes rather than replacement text.
+      */
+     Value: GoString;
+     /**
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     ValueEnd: SyntaxPos;
+     /**
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     ValuePos: SyntaxPos;
+ }
+
+ /**
+  * The concrete records and typed nil pointers accepted by upstream syntax.Loop. Typed nil kinds are limited to this interface's actual implementers; auxiliary records are excluded.
+  *
+  * @public
+  */
+ export declare type Loop = CStyleLoop | WordIter | TypedNil<'CStyleLoop' | 'WordIter'>;
+
+ /**
+  * Upstream ParExpOperator constant LowerAll. Its numeric value is preserved exactly.
+  *
+  * ,,
+  *
+  * @public
+  */
+ declare const LowerAll: 99;
+
+ /**
+  * Upstream ParExpOperator constant LowerFirst. Its numeric value is preserved exactly.
+  *
+  * ,
+  *
+  * @public
+  */
+ declare const LowerFirst: 98;
+
+ /**
+  * Upstream BinAritOperator constant Lss. Its numeric value is preserved exactly.
+  *
+  * \<
+  *
+  * @public
+  */
+ declare const Lss: 65;
+
+ /**
+  * Upstream ParExpOperator constant MatchEmpty. Its numeric value is preserved exactly.
+  *
+  * :# with `LangZsh`
+  *
+  * @public
+  */
+ declare const MatchEmpty: 93;
+
+ /**
+  * Upstream UnAritOperator constant Minus. Its numeric value is preserved exactly.
+  *
+  * -
+  *
+  * @public
+  */
+ declare const Minus: 83;
+
+ /**
+  * Upstream BinAritOperator constant Mul. Its numeric value is preserved exactly.
+  *
+  * *
+  *
+  * @public
+  */
+ declare const Mul: 43;
+
+ /**
+  * Upstream BinAritOperator constant MulAssgn. Its numeric value is preserved exactly.
+  *
+  * *=
+  *
+  * @public
+  */
+ declare const MulAssgn: 51;
+
+ /**
+  * Upstream ParNamesOperator constant NamesPrefix. Its numeric value is preserved exactly.
+  *
+  * *
+  *
+  * @public
+  */
+ declare const NamesPrefix: 43;
+
+ /**
+  * Upstream ParNamesOperator constant NamesPrefixWords. Its numeric value is preserved exactly.
+  *
+  * \@
+  *
+  * @public
+  */
+ declare const NamesPrefixWords: 100;
+
+ /**
+  * Upstream BinAritOperator constant Neq. Its numeric value is preserved exactly.
+  *
+  * !=
+  *
+  * @public
+  */
+ declare const Neq: 46;
+
+ /**
+  * The concrete records and typed nil pointers accepted by upstream syntax.Node. Typed nil kinds are limited to this interface's actual implementers; auxiliary records are excluded.
+  *
+  * @public
+  */
+ declare type Node_2 =
+ | ArithmCmd
+ | ArithmExp
+ | ArrayElem
+ | ArrayExpr
+ | Assign
+ | BinaryArithm
+ | BinaryCmd
+ | BinaryTest
+ | Block
+ | BraceExp
+ | CStyleLoop
+ | CallExpr
+ | CaseClause
+ | CaseItem
+ | CmdSubst
+ | Comment_2
+ | CoprocClause
+ | DblQuoted
+ | DeclClause
+ | ExtGlob
+ | File_2
+ | FlagsArithm
+ | ForClause
+ | FuncDecl
+ | IfClause
+ | LetClause
+ | Lit
+ | ParamExp
+ | ParenArithm
+ | ParenTest
+ | ProcSubst
+ | Redirect
+ | SglQuoted
+ | Stmt
+ | Subshell
+ | TestClause
+ | TestDecl
+ | TimeClause
+ | UnaryArithm
+ | UnaryTest
+ | WhileClause
+ | Word
+ | WordIter
+ | TypedNil<
+ | 'ArithmCmd'
+ | 'ArithmExp'
+ | 'ArrayElem'
+ | 'ArrayExpr'
+ | 'Assign'
+ | 'BinaryArithm'
+ | 'BinaryCmd'
+ | 'BinaryTest'
+ | 'Block'
+ | 'BraceExp'
+ | 'CStyleLoop'
+ | 'CallExpr'
+ | 'CaseClause'
+ | 'CaseItem'
+ | 'CmdSubst'
+ | 'Comment'
+ | 'CoprocClause'
+ | 'DblQuoted'
+ | 'DeclClause'
+ | 'ExtGlob'
+ | 'File'
+ | 'FlagsArithm'
+ | 'ForClause'
+ | 'FuncDecl'
+ | 'IfClause'
+ | 'LetClause'
+ | 'Lit'
+ | 'ParamExp'
+ | 'ParenArithm'
+ | 'ParenTest'
+ | 'ProcSubst'
+ | 'Redirect'
+ | 'SglQuoted'
+ | 'Stmt'
+ | 'Subshell'
+ | 'TestClause'
+ | 'TestDecl'
+ | 'TimeClause'
+ | 'UnaryArithm'
+ | 'UnaryTest'
+ | 'WhileClause'
+ | 'Word'
+ | 'WordIter'
+ >;
+ export { Node_2 as Node }
+
+ /**
+  * Upstream UnAritOperator constant Not. Its numeric value is preserved exactly.
+  *
+  * !
+  *
+  * @public
+  */
+ declare const Not: 39;
+
+ /**
+  * The upstream uint32 operator families. A family name identifies the Go named type, not the spelling of one token.
+  *
+  * @public
+  */
+ export declare type OperatorFamily =
+ | 'BinAritOperator'
+ | 'BinCmdOperator'
+ | 'BinTestOperator'
+ | 'CaseOperator'
+ | 'GlobOperator'
+ | 'ParExpOperator'
+ | 'ParNamesOperator'
+ | 'ProcOperator'
+ | 'RedirOperator'
+ | 'UnAritOperator'
+ | 'UnTestOperator';
+
+ /**
+  * Upstream BinAritOperator constant Or. Its numeric value is preserved exactly.
+  *
+  * |
+  *
+  * @public
+  */
+ declare const Or: 13;
+
+ /**
+  * Upstream BinAritOperator constant OrArit. Its numeric value is preserved exactly.
+  *
+  * ||
+  *
+  * @public
+  */
+ declare const OrArit: 12;
+
+ /**
+  * Upstream BinAritOperator constant OrAssgn. Its numeric value is preserved exactly.
+  *
+  * |=
+  *
+  * @public
+  */
+ declare const OrAssgn: 55;
+
+ /**
+  * Upstream BinAritOperator constant OrBoolAssgn. Its numeric value is preserved exactly.
+  *
+  * ||=
+  *
+  * @public
+  */
+ declare const OrBoolAssgn: 60;
+
+ /**
+  * Upstream BinCmdOperator constant OrStmt. Its numeric value is preserved exactly.
+  *
+  * ||
+  *
+  * @public
+  */
+ declare const OrStmt: 12;
+
+ /**
+  * Upstream BinTestOperator constant OrTest. Its numeric value is preserved exactly.
+  *
+  * ||
+  *
+  * @public
+  */
+ declare const OrTest: 12;
+
+ /**
+  * Upstream ParExpOperator constant OtherParamOps. Its numeric value is preserved exactly.
+  *
+  * \@
+  *
+  * @public
+  */
+ declare const OtherParamOps: 100;
+
+ /**
+  * ParamExp represents a parameter expansion.
+  *
+  * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+  *
+  * @public
+  */
+ export declare interface ParamExp {
+     /**
+      * Identifies the upstream concrete record when carried through an interface union.
+      */
+     Type: 'ParamExp';
+     /**
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     Dollar: SyntaxPos;
+     /**
+      * Only one of these is set at a time.
+      * given how we've grown the number of booleans
+      * $\{!a\}
+      *
+      * False is an explicit upstream value and is never omitted.
+      */
+     Excl: boolean;
+     /**
+      * $\{a:-b\}, $\{a#b\}, etc
+      *
+      * Null preserves the upstream absence of this component.
+      */
+     Exp: Expansion | null;
+     /**
+      * $\{(flags)a\} with `LangZsh`
+      *
+      * Null preserves the upstream absence of this component.
+      */
+     Flags: Lit | null;
+     /**
+      * $\{a`i`\}, $\{a["k"]\}, or a $\{a[i,j]\} slice with `LangZsh`
+      *
+      * Null preserves the upstream absence of this component.
+      */
+     Index: ArithmExpr | null;
+     /**
+      * $\{+a\} with `LangZsh`
+      *
+      * False is an explicit upstream value and is never omitted.
+      */
+     IsSet: boolean;
+     /**
+      * $\{#a\}
+      *
+      * False is an explicit upstream value and is never omitted.
+      */
+     Length: boolean;
+     /**
+      * Only one of these is set at a time.
+      * because it should be impossible for multiple to be set at once,
+      * and a flat structure like this takes up more space.
+      * $\{a:h2\} with `LangZsh`
+      *
+      * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+      */
+     Modifiers: (Lit | null)[] | null;
+     /**
+      * $\{!prefix*\} or $\{!prefix\@\}
+      *
+      * Upstream operator value, preserving named tokens, zero, and explicitly represented raw uint32 values.
+      */
+     Names: ParNamesOperator;
+     /**
+      * A nested parameter expression in the form of `ParamExp` or `CmdSubst`,
+      * or either of those in a `DblQuoted`. Only possible with `LangZsh`.
+      *
+      * Null preserves the upstream absence of this component.
+      */
+     NestedParam: WordPart | null;
+     /**
+      * Only one of these is set at a time,
+      * or neither with `LangZsh` when the name is omitted.
+      * even if that would be mildly annoying to non-Zsh users.
+      *
+      * Null preserves the upstream absence of this component.
+      */
+     Param: Lit | null;
+     /**
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     Rbrace: SyntaxPos;
+     /**
+      * $\{a/x/y\}
+      *
+      * Null preserves the upstream absence of this component.
+      */
+     Repl: Replace | null;
+     /**
+      * $a instead of $\{a\}
+      *
+      * False is an explicit upstream value and is never omitted.
+      */
+     Short: boolean;
+     /**
+      * $\{a:x:y\}
+      *
+      * Null preserves the upstream absence of this component.
+      */
+     Slice: Slice | null;
+     /**
+      * mksh's $\{%a\}
+      *
+      * False is an explicit upstream value and is never omitted.
+      */
+     Width: boolean;
+ }
+
+ /**
+  * ParenArithm represents an arithmetic expression within parentheses.
+  *
+  * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+  *
+  * @public
+  */
+ export declare interface ParenArithm {
+     /**
+      * Identifies the upstream concrete record when carried through an interface union.
+      */
+     Type: 'ParenArithm';
+     /**
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     Lparen: SyntaxPos;
+     /**
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     Rparen: SyntaxPos;
+     /**
+      * Null preserves the upstream absence of this component.
+      */
+     X: ArithmExpr | null;
+ }
+
+ /**
+  * ParenTest represents a test expression within parentheses.
+  *
+  * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+  *
+  * @public
+  */
+ export declare interface ParenTest {
+     /**
+      * Identifies the upstream concrete record when carried through an interface union.
+      */
+     Type: 'ParenTest';
+     /**
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     Lparen: SyntaxPos;
+     /**
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     Rparen: SyntaxPos;
+     /**
+      * Null preserves the upstream absence of this component.
+      */
+     X: TestExpr | null;
+ }
+
+ /**
+  * The upstream ParExpOperator domain: exact named tokens, the Go zero value, and explicitly validated unnamed uint32 values. Constants shared by upstream families retain their shared numeric identity.
+  *
+  * @public
+  */
+ export declare type ParExpOperator =
+ | 0
+ | typeof AlternateUnset
+ | typeof AlternateUnsetOrNull
+ | typeof ArrayExclude
+ | typeof ArrayIntersect
+ | typeof AssignUnset
+ | typeof AssignUnsetOrNull
+ | typeof DefaultUnset
+ | typeof DefaultUnsetOrNull
+ | typeof ErrorUnset
+ | typeof ErrorUnsetOrNull
+ | typeof LowerAll
+ | typeof LowerFirst
+ | typeof MatchEmpty
+ | typeof OtherParamOps
+ | typeof RemLargePrefix
+ | typeof RemLargeSuffix
+ | typeof RemSmallPrefix
+ | typeof RemSmallSuffix
+ | typeof UpperAll
+ | typeof UpperFirst
+ | RawOperator<'ParExpOperator'>;
+
+ /**
+  * The upstream ParNamesOperator domain: exact named tokens, the Go zero value, and explicitly validated unnamed uint32 values. Constants shared by upstream families retain their shared numeric identity.
+  *
+  * @public
+  */
+ export declare type ParNamesOperator =
+ 0 | typeof NamesPrefix | typeof NamesPrefixWords | RawOperator<'ParNamesOperator'>;
+
+ /**
+  * Upstream BinCmdOperator constant Pipe. Its numeric value is preserved exactly.
+  *
+  * |
+  *
+  * @public
+  */
+ declare const Pipe: 13;
+
+ /**
+  * Upstream BinCmdOperator constant PipeAll. Its numeric value is preserved exactly.
+  *
+  * |&
+  *
+  * @public
+  */
+ declare const PipeAll: 14;
+
+ /**
+  * Upstream UnAritOperator constant Plus. Its numeric value is preserved exactly.
+  *
+  * +
+  *
+  * @public
+  */
+ declare const Plus: 81;
+
+ /**
+  * Upstream BinAritOperator constant Pow. Its numeric value is preserved exactly.
+  *
+  * **
+  *
+  * @public
+  */
+ declare const Pow: 44;
+
+ /**
+  * Upstream BinAritOperator constant PowAssgn. Its numeric value is preserved exactly.
+  *
+  * **=
+  *
+  * @public
+  */
+ declare const PowAssgn: 62;
+
+ /**
+  * The upstream ProcOperator domain: exact named tokens, the Go zero value, and explicitly validated unnamed uint32 values. Constants shared by upstream families retain their shared numeric identity.
+  *
+  * @public
+  */
+ export declare type ProcOperator =
+ 0 | typeof CmdIn | typeof CmdInTemp | typeof CmdOut | RawOperator<'ProcOperator'>;
+
+ /**
+  * ProcSubst represents a Bash process substitution.
+  *
+  * This node will only appear with `LangBash`.
+  *
+  * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+  *
+  * @public
+  */
+ export declare interface ProcSubst {
+     /**
+      * Identifies the upstream concrete record when carried through an interface union.
+      */
+     Type: 'ProcSubst';
+     /**
+      * Ordered upstream entries. Null preserves a nil slice and differs from an empty array.
+      */
+     Last: Comment_2[] | null;
+     /**
+      * Upstream operator value, preserving named tokens, zero, and explicitly represented raw uint32 values.
+      */
+     Op: ProcOperator;
+     /**
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     OpPos: SyntaxPos;
+     /**
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     Rparen: SyntaxPos;
+     /**
+      * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+      */
+     Stmts: (Stmt | null)[] | null;
+ }
+
+ /**
+  * Upstream BinAritOperator constant Quo. Its numeric value is preserved exactly.
+  *
+  * /
+  *
+  * @public
+  */
+ declare const Quo: 101;
+
+ /**
+  * Upstream BinAritOperator constant QuoAssgn. Its numeric value is preserved exactly.
+  *
+  * /=
+  *
+  * @public
+  */
+ declare const QuoAssgn: 52;
+
+ /**
+  * An explicitly represented unnamed uint32 value in one upstream operator family. The runtime constructor checks integer range; this type does not claim that every value is meaningful to every parser or printer operation. The structural family marker remains interoperable across package entry points while preventing accidental cross-family assignment.
+  *
+  * @public
+  */
+ export declare type RawOperator<Family extends OperatorFamily> = number & {
+     readonly __shAstOperatorFamily: Family;
+ };
+
+ /**
+  * Upstream RedirOperator constant RdrAll. Its numeric value is preserved exactly.
+  *
+  * &\>
+  *
+  * @public
+  */
+ declare const RdrAll: 74;
+
+ /**
+  * Upstream RedirOperator constant RdrAllClob. Its numeric value is preserved exactly.
+  *
+  * &\>| with `LangZsh`
+  *
+  * @public
+  */
+ declare const RdrAllClob: 75;
+
+ /**
+  * Upstream RedirOperator constant RdrClob. Its numeric value is preserved exactly.
+  *
+  * \>|
+  *
+  * @public
+  */
+ declare const RdrClob: 69;
+
+ /**
+  * Upstream RedirOperator constant RdrIn. Its numeric value is preserved exactly.
+  *
+  * \<
+  *
+  * @public
+  */
+ declare const RdrIn: 65;
+
+ /**
+  * Upstream RedirOperator constant RdrInOut. Its numeric value is preserved exactly.
+  *
+  * \<\>
+  *
+  * @public
+  */
+ declare const RdrInOut: 66;
+
+ /**
+  * Upstream RedirOperator constant RdrOut. Its numeric value is preserved exactly.
+  *
+  * \>
+  *
+  * @public
+  */
+ declare const RdrOut: 63;
+
+ /**
+  * Redirect represents an input/output redirection.
+  *
+  * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+  *
+  * @public
+  */
+ export declare interface Redirect {
+     /**
+      * Identifies the upstream concrete record when carried through an interface union.
+      */
+     Type: 'Redirect';
+     /**
+      * here-document body
+      *
+      * Null preserves the upstream absence of this component.
+      */
+     Hdoc: Word | null;
+     /**
+      * fd\>, or \{varname\}\> in Bash
+      *
+      * Null preserves the upstream absence of this component.
+      */
+     N: Lit | null;
+     /**
+      * Upstream operator value, preserving named tokens, zero, and explicitly represented raw uint32 values.
+      */
+     Op: RedirOperator;
+     /**
+      * Recorded source position; invalid and recovered states remain distinct.
+      */
+     OpPos: SyntaxPos;
+     /**
+      * \>word
+      *
+      * Null preserves the upstream absence of this component.
+      */
+     Word: Word | null;
+ }
+
+ /**
+  * The upstream RedirOperator domain: exact named tokens, the Go zero value, and explicitly validated unnamed uint32 values. Constants shared by upstream families retain their shared numeric identity.
+  *
+  * @public
+  */
+ export declare type RedirOperator =
+ | 0
+ | typeof AppAll
+ | typeof AppAllClob
+ | typeof AppClob
+ | typeof AppOut
+ | typeof DashHdoc
+ | typeof DplIn
+ | typeof DplOut
+ | typeof Hdoc
+ | typeof RdrAll
+ | typeof RdrAllClob
+ | typeof RdrClob
+ | typeof RdrIn
+ | typeof RdrInOut
+ | typeof RdrOut
+ | typeof WordHdoc
+ | RawOperator<'RedirOperator'>;
+
+ /**
+  * Upstream BinAritOperator constant Rem. Its numeric value is preserved exactly.
+  *
+  * %
+  *
+  * @public
+  */
+ declare const Rem: 89;
+
+ /**
+  * Upstream BinAritOperator constant RemAssgn. Its numeric value is preserved exactly.
+  *
+  * %=
+  *
+  * @public
+  */
+ declare const RemAssgn: 53;
+
+ /**
+  * Upstream ParExpOperator constant RemLargePrefix. Its numeric value is preserved exactly.
+  *
+  * ##
+  *
+  * @public
+  */
+ declare const RemLargePrefix: 92;
+
+ /**
+  * Upstream ParExpOperator constant RemLargeSuffix. Its numeric value is preserved exactly.
+  *
+  * %%
+  *
+  * @public
+  */
+ declare const RemLargeSuffix: 90;
+
+ /**
+  * Upstream ParExpOperator constant RemSmallPrefix. Its numeric value is preserved exactly.
+  *
+  * #
+  *
+  * @public
+  */
+ declare const RemSmallPrefix: 91;
+
+ /**
+  * Upstream ParExpOperator constant RemSmallSuffix. Its numeric value is preserved exactly.
+  *
+  * %
+  *
+  * @public
+  */
+ declare const RemSmallSuffix: 89;
+
+ /**
+  * Replace represents a search and replace expression inside a `ParamExp`.
+  *
+  * Auxiliary syntax data, not a syntax.Node; it has no independent source bounds.
+  *
+  * @public
+  */
+ export declare interface Replace {
+     /**
+      * Identifies the upstream concrete record when carried through an interface union.
+      */
+     Type: 'Replace';
+     /**
+      * False is an explicit upstream value and is never omitted.
+      */
+     All: boolean;
+     /**
+      * Null preserves the upstream absence of this component.
+      */
+     Orig: Word | null;
+     /**
+      * Null preserves the upstream absence of this component.
+      */
+     With: Word | null;
+ }
+
+ /**
+  * 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.
+  *
+  * 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.
+  *
+  * **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:
+  *
+  * 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).
+  *
+  * `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.
+  *
+  * @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
+      */
+  export declare function resolveArgv0(site: CommandSite, options?: ResolveArgv0Options): Argv0Resolution;
+
+  /**
+   * 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[];
+  }
+
+  /**
+   * 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]`.
+   * @param options - See {@link ResolveWordOptions}.
+   * @throws TypeError if `word.Type` is neither `"Word"` nor `"TypedNil"` — 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: Node_2, 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';
+  }
+
+  /**
+   * Upstream CaseOperator constant Resume. Its numeric value is preserved exactly.
+   *
+   * ;;&
+   *
+   * @public
+   */
+  declare const Resume: 37;
+
+  /**
+   * Upstream CaseOperator constant ResumeKorn. Its numeric value is preserved exactly.
+   *
+   * ;|
+   *
+   * @public
+   */
+  declare const ResumeKorn: 38;
+
+  /**
+   * SglQuoted represents a string within single quotes.
+   *
+   * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+   *
+   * @public
+   */
+  export declare interface SglQuoted {
+      /**
+       * Identifies the upstream concrete record when carried through an interface union.
+       */
+      Type: 'SglQuoted';
+      /**
+       * $''
+       *
+       * False is an explicit upstream value and is never omitted.
+       */
+      Dollar: boolean;
+      /**
+       * Recorded source position; invalid and recovered states remain distinct.
+       */
+      Left: SyntaxPos;
+      /**
+       * Recorded source position; invalid and recovered states remain distinct.
+       */
+      Right: SyntaxPos;
+      /**
+       * Upstream string bytes; non-UTF-8 values remain bytes rather than replacement text.
+       */
+      Value: GoString;
+  }
+
+  /**
+   * 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);
+  }
+
+  /** Shared failure classes for binding invariants, resource limits, and analysis contracts. */
+  /**
+   * Common base for every package failure, including upstream syntax errors and
+   * analysis errors. The stable code discriminator supports programmatic handling
+   * without interpreting display messages. Only concrete subclasses are thrown.
+   * @public
+   */
+  export declare abstract class ShAstError extends Error {
+      /** Stable machine-readable identity of the concrete failure kind. */
+      abstract readonly code: string;
+  }
+
+  /**
+   * Upstream BinAritOperator constant Shl. Its numeric value is preserved exactly.
+   *
+   * \<\<
+   *
+   * @public
+   */
+  declare const Shl: 71;
+
+  /**
+   * Upstream BinAritOperator constant ShlAssgn. Its numeric value is preserved exactly.
+   *
+   * \<\<=
+   *
+   * @public
+   */
+  declare const ShlAssgn: 57;
+
+  /**
+   * Upstream BinAritOperator constant Shr. Its numeric value is preserved exactly.
+   *
+   * \>\>
+   *
+   * @public
+   */
+  declare const Shr: 64;
+
+  /**
+   * Upstream BinAritOperator constant ShrAssgn. Its numeric value is preserved exactly.
+   *
+   * \>\>=
+   *
+   * @public
+   */
+  declare const ShrAssgn: 58;
+
+  /**
+   * Slice represents a character slicing expression inside a `ParamExp`.
+   *
+   * This node will only appear with `LangBash` and `LangMirBSDKorn`.
+   * `LangZsh` uses a `BinaryArithm` with `Comma` in `ParamExp.Index` instead.
+   *
+   * Auxiliary syntax data, not a syntax.Node; it has no independent source bounds.
+   *
+   * @public
+   */
+  export declare interface Slice {
+      /**
+       * Identifies the upstream concrete record when carried through an interface union.
+       */
+      Type: 'Slice';
+      /**
+       * Null preserves the upstream absence of this component.
+       */
+      Length: ArithmExpr | null;
+      /**
+       * Null preserves the upstream absence of this component.
+       */
+      Offset: ArithmExpr | null;
+  }
+
+  /**
+   * Stmt represents a statement, also known as a "complete command". It is
+   * compromised of a command and other components that may come before or after
+   * it.
+   *
+   * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+   *
+   * @public
+   */
+  export declare interface Stmt {
+      /**
+       * Identifies the upstream concrete record when carried through an interface union.
+       */
+      Type: 'Stmt';
+      /**
+       * stmt &
+       *
+       * False is an explicit upstream value and is never omitted.
+       */
+      Background: boolean;
+      /**
+       * Null preserves the upstream absence of this component.
+       */
+      Cmd: Command | null;
+      /**
+       * Ordered upstream entries. Null preserves a nil slice and differs from an empty array.
+       */
+      Comments: Comment_2[] | null;
+      /**
+       * mksh's |&
+       *
+       * False is an explicit upstream value and is never omitted.
+       */
+      Coprocess: boolean;
+      /**
+       * zsh's &| or &!
+       *
+       * False is an explicit upstream value and is never omitted.
+       */
+      Disown: boolean;
+      /**
+       * ! stmt
+       *
+       * False is an explicit upstream value and is never omitted.
+       */
+      Negated: boolean;
+      /**
+       * Recorded source position; invalid and recovered states remain distinct.
+       */
+      Position: SyntaxPos;
+      /**
+       * stmt \>a \<b
+       *
+       * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+       */
+      Redirs: (Redirect | null)[] | null;
+      /**
+       * position of ';', '&', or '|&', if any
+       *
+       * Recorded source position; invalid and recovered states remain distinct.
+       */
+      Semicolon: SyntaxPos;
+  }
+
+  /**
+   * Upstream BinAritOperator constant Sub. Its numeric value is preserved exactly.
+   *
+   * -
+   *
+   * @public
+   */
+  declare const Sub: 83;
+
+  /**
+   * Upstream BinAritOperator constant SubAssgn. Its numeric value is preserved exactly.
+   *
+   * -=
+   *
+   * @public
+   */
+  declare const SubAssgn: 50;
+
+  /**
+   * Subshell represents a series of commands that should be executed in a nested
+   * shell environment.
+   *
+   * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+   *
+   * @public
+   */
+  export declare interface Subshell {
+      /**
+       * Identifies the upstream concrete record when carried through an interface union.
+       */
+      Type: 'Subshell';
+      /**
+       * Ordered upstream entries. Null preserves a nil slice and differs from an empty array.
+       */
+      Last: Comment_2[] | null;
+      /**
+       * Recorded source position; invalid and recovered states remain distinct.
+       */
+      Lparen: SyntaxPos;
+      /**
+       * Recorded source position; invalid and recovered states remain distinct.
+       */
+      Rparen: SyntaxPos;
+      /**
+       * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+       */
+      Stmts: (Stmt | null)[] | null;
+  }
+
+  /**
+   * The observable value of an upstream syntax.Pos. Offset and Col count bytes; Line and Col use upstream numbering and overflow behavior. IsValid, IsRecovered, and OffsetOverflow retain distinctions that coordinates alone cannot express. Token positions are data; node bounds are derived operations.
+   *
+   * @public
+   */
+  export declare interface SyntaxPos {
+      /**
+       * Zero-based source byte offset, including upstream saturation behavior.
+       */
+      Offset: number;
+      /**
+       * One-based source line; zero retains upstream invalid or overflow information.
+       */
+      Line: number;
+      /**
+       * One-based byte column; zero retains upstream invalid or overflow information.
+       */
+      Col: number;
+      /**
+       * Whether upstream considers this position useful; recovered positions are not valid.
+       */
+      IsValid: boolean;
+      /**
+       * Whether upstream synthesized this missing syntax position during error recovery.
+       */
+      IsRecovered: boolean;
+      /**
+       * Whether the stored upstream offset exceeds its representable source-offset maximum, including the recovered sentinel. This preserves ordering distinctions even when Offset() reports zero; ordinary zero-invalid positions have false here.
+       */
+      OffsetOverflow: boolean;
+  }
+
+  /**
+   * Upstream BinAritOperator constant TernColon. Its numeric value is preserved exactly.
+   *
+   * :
+   *
+   * @public
+   */
+  declare const TernColon: 104;
+
+  /**
+   * Upstream BinAritOperator constant TernQuest. Its numeric value is preserved exactly.
+   *
+   * ?
+   *
+   * @public
+   */
+  declare const TernQuest: 85;
+
+  /**
+   * TestClause represents a Bash extended test clause.
+   *
+   * This node will only appear with `LangBash` and `LangMirBSDKorn`.
+   *
+   * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+   *
+   * @public
+   */
+  export declare interface TestClause {
+      /**
+       * Identifies the upstream concrete record when carried through an interface union.
+       */
+      Type: 'TestClause';
+      /**
+       * Recorded source position; invalid and recovered states remain distinct.
+       */
+      Left: SyntaxPos;
+      /**
+       * Recorded source position; invalid and recovered states remain distinct.
+       */
+      Right: SyntaxPos;
+      /**
+       * Null preserves the upstream absence of this component.
+       */
+      X: TestExpr | null;
+  }
+
+  /**
+   * TestDecl represents the declaration of a Bats test function.
+   *
+   * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+   *
+   * @public
+   */
+  export declare interface TestDecl {
+      /**
+       * Identifies the upstream concrete record when carried through an interface union.
+       */
+      Type: 'TestDecl';
+      /**
+       * Null preserves the upstream absence of this component.
+       */
+      Body: Stmt | null;
+      /**
+       * Null preserves the upstream absence of this component.
+       */
+      Description: Word | null;
+      /**
+       * Recorded source position; invalid and recovered states remain distinct.
+       */
+      Position: SyntaxPos;
+  }
+
+  /**
+   * The concrete records and typed nil pointers accepted by upstream syntax.TestExpr. Typed nil kinds are limited to this interface's actual implementers; auxiliary records are excluded.
+   *
+   * @public
+   */
+  export declare type TestExpr =
+  | BinaryTest
+  | ParenTest
+  | UnaryTest
+  | Word
+  | TypedNil<'BinaryTest' | 'ParenTest' | 'UnaryTest' | 'Word'>;
+
+  /**
+   * TimeClause represents a Bash time clause. PosixFormat corresponds to the -p
+   * flag.
+   *
+   * This node will only appear with `LangBash` and `LangMirBSDKorn`.
+   *
+   * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+   *
+   * @public
+   */
+  export declare interface TimeClause {
+      /**
+       * Identifies the upstream concrete record when carried through an interface union.
+       */
+      Type: 'TimeClause';
+      /**
+       * False is an explicit upstream value and is never omitted.
+       */
+      PosixFormat: boolean;
+      /**
+       * Null preserves the upstream absence of this component.
+       */
+      Stmt: Stmt | null;
+      /**
+       * Recorded source position; invalid and recovered states remain distinct.
+       */
+      Time: SyntaxPos;
+  }
+
+  /**
+   * Upstream BinTestOperator constant TsAfter. Its numeric value is preserved exactly.
+   *
+   * \>
+   *
+   * @public
+   */
+  declare const TsAfter: 63;
+
+  /**
+   * Upstream BinTestOperator constant TsBefore. Its numeric value is preserved exactly.
+   *
+   * \<
+   *
+   * @public
+   */
+  declare const TsBefore: 65;
+
+  /**
+   * Upstream UnTestOperator constant TsBlckSp. Its numeric value is preserved exactly.
+   *
+   * -b
+   *
+   * @public
+   */
+  declare const TsBlckSp: 109;
+
+  /**
+   * Upstream UnTestOperator constant TsCharSp. Its numeric value is preserved exactly.
+   *
+   * -c
+   *
+   * @public
+   */
+  declare const TsCharSp: 108;
+
+  /**
+   * Upstream BinTestOperator constant TsDevIno. Its numeric value is preserved exactly.
+   *
+   * -ef
+   *
+   * @public
+   */
+  declare const TsDevIno: 132;
+
+  /**
+   * Upstream UnTestOperator constant TsDirect. Its numeric value is preserved exactly.
+   *
+   * -d
+   *
+   * @public
+   */
+  declare const TsDirect: 107;
+
+  /**
+   * Upstream UnTestOperator constant TsEmpStr. Its numeric value is preserved exactly.
+   *
+   * -z
+   *
+   * @public
+   */
+  declare const TsEmpStr: 124;
+
+  /**
+   * Upstream BinTestOperator constant TsEql. Its numeric value is preserved exactly.
+   *
+   * -eq
+   *
+   * @public
+   */
+  declare const TsEql: 133;
+
+  /**
+   * Upstream UnTestOperator constant TsExec. Its numeric value is preserved exactly.
+   *
+   * -x
+   *
+   * @public
+   */
+  declare const TsExec: 121;
+
+  /**
+   * Upstream UnTestOperator constant TsExists. Its numeric value is preserved exactly.
+   *
+   * -e
+   *
+   * @public
+   */
+  declare const TsExists: 105;
+
+  /**
+   * Upstream UnTestOperator constant TsFdTerm. Its numeric value is preserved exactly.
+   *
+   * -t
+   *
+   * @public
+   */
+  declare const TsFdTerm: 123;
+
+  /**
+   * Upstream BinTestOperator constant TsGeq. Its numeric value is preserved exactly.
+   *
+   * -ge
+   *
+   * @public
+   */
+  declare const TsGeq: 136;
+
+  /**
+   * Upstream UnTestOperator constant TsGIDSet. Its numeric value is preserved exactly.
+   *
+   * -g
+   *
+   * @public
+   */
+  declare const TsGIDSet: 114;
+
+  /**
+   * Upstream UnTestOperator constant TsGrpOwn. Its numeric value is preserved exactly.
+   *
+   * -G
+   *
+   * @public
+   */
+  declare const TsGrpOwn: 116;
+
+  /**
+   * Upstream BinTestOperator constant TsGtr. Its numeric value is preserved exactly.
+   *
+   * -gt
+   *
+   * @public
+   */
+  declare const TsGtr: 138;
+
+  /**
+   * Upstream BinTestOperator constant TsLeq. Its numeric value is preserved exactly.
+   *
+   * -le
+   *
+   * @public
+   */
+  declare const TsLeq: 135;
+
+  /**
+   * Upstream BinTestOperator constant TsLss. Its numeric value is preserved exactly.
+   *
+   * -lt
+   *
+   * @public
+   */
+  declare const TsLss: 137;
+
+  /**
+   * Upstream BinTestOperator constant TsMatch. Its numeric value is preserved exactly.
+   *
+   * ==
+   *
+   * @public
+   */
+  declare const TsMatch: 45;
+
+  /**
+   * Upstream BinTestOperator constant TsMatchShort. Its numeric value is preserved exactly.
+   *
+   * =
+   *
+   * @public
+   */
+  declare const TsMatchShort: 87;
+
+  /**
+   * Upstream UnTestOperator constant TsModif. Its numeric value is preserved exactly.
+   *
+   * -N
+   *
+   * @public
+   */
+  declare const TsModif: 118;
+
+  /**
+   * Upstream UnTestOperator constant TsNempStr. Its numeric value is preserved exactly.
+   *
+   * -n
+   *
+   * @public
+   */
+  declare const TsNempStr: 125;
+
+  /**
+   * Upstream BinTestOperator constant TsNeq. Its numeric value is preserved exactly.
+   *
+   * -ne
+   *
+   * @public
+   */
+  declare const TsNeq: 134;
+
+  /**
+   * Upstream BinTestOperator constant TsNewer. Its numeric value is preserved exactly.
+   *
+   * -nt
+   *
+   * @public
+   */
+  declare const TsNewer: 130;
+
+  /**
+   * Upstream UnTestOperator constant TsNmPipe. Its numeric value is preserved exactly.
+   *
+   * -p
+   *
+   * @public
+   */
+  declare const TsNmPipe: 110;
+
+  /**
+   * Upstream UnTestOperator constant TsNoEmpty. Its numeric value is preserved exactly.
+   *
+   * -s
+   *
+   * @public
+   */
+  declare const TsNoEmpty: 122;
+
+  /**
+   * Upstream BinTestOperator constant TsNoMatch. Its numeric value is preserved exactly.
+   *
+   * !=
+   *
+   * @public
+   */
+  declare const TsNoMatch: 46;
+
+  /**
+   * Upstream UnTestOperator constant TsNot. Its numeric value is preserved exactly.
+   *
+   * !
+   *
+   * @public
+   */
+  declare const TsNot: 39;
+
+  /**
+   * Upstream BinTestOperator constant TsOlder. Its numeric value is preserved exactly.
+   *
+   * -ot
+   *
+   * @public
+   */
+  declare const TsOlder: 131;
+
+  /**
+   * Upstream UnTestOperator constant TsOptSet. Its numeric value is preserved exactly.
+   *
+   * -o
+   *
+   * @public
+   */
+  declare const TsOptSet: 126;
+
+  /**
+   * Upstream UnTestOperator constant TsParen. Its numeric value is preserved exactly.
+   *
+   * (
+   *
+   * @public
+   */
+  declare const TsParen: 27;
+
+  /**
+   * Upstream UnTestOperator constant TsRead. Its numeric value is preserved exactly.
+   *
+   * -r
+   *
+   * @public
+   */
+  declare const TsRead: 119;
 
   /**
-   * Options accepted by {@link resolveArgv0}.
+   * Upstream UnTestOperator constant TsRefVar. Its numeric value is preserved exactly.
+   *
+   * -R
    *
    * @public
    */
-  export declare interface ResolveArgv0Options {
+  declare const TsRefVar: 128;
+
+  /**
+   * Upstream UnTestOperator constant TsRegFile. Its numeric value is preserved exactly.
+   *
+   * -f
+   *
+   * @public
+   */
+  declare const TsRegFile: 106;
+
+  /**
+   * Upstream BinTestOperator constant TsReMatch. Its numeric value is preserved exactly.
+   *
+   * =~
+   *
+   * @public
+   */
+  declare const TsReMatch: 129;
+
+  /**
+   * Upstream UnTestOperator constant TsSmbLink. Its numeric value is preserved exactly.
+   *
+   * -L
+   *
+   * @public
+   */
+  declare const TsSmbLink: 112;
+
+  /**
+   * Upstream UnTestOperator constant TsSocket. Its numeric value is preserved exactly.
+   *
+   * -S
+   *
+   * @public
+   */
+  declare const TsSocket: 111;
+
+  /**
+   * Upstream UnTestOperator constant TsSticky. Its numeric value is preserved exactly.
+   *
+   * -k
+   *
+   * @public
+   */
+  declare const TsSticky: 113;
+
+  /**
+   * Upstream UnTestOperator constant TsUIDSet. Its numeric value is preserved exactly.
+   *
+   * -u
+   *
+   * @public
+   */
+  declare const TsUIDSet: 115;
+
+  /**
+   * Upstream UnTestOperator constant TsUsrOwn. Its numeric value is preserved exactly.
+   *
+   * -O
+   *
+   * @public
+   */
+  declare const TsUsrOwn: 117;
+
+  /**
+   * Upstream UnTestOperator constant TsVarSet. Its numeric value is preserved exactly.
+   *
+   * -v
+   *
+   * @public
+   */
+  declare const TsVarSet: 127;
+
+  /**
+   * Upstream UnTestOperator constant TsWrite. Its numeric value is preserved exactly.
+   *
+   * -w
+   *
+   * @public
+   */
+  declare const TsWrite: 120;
+
+  /**
+   * An upstream interface containing a nil pointer of a concrete syntax.Node kind. This differs from a nil interface (null): the concrete Go type remains observable and can affect operations. Only interface-valued positions admit this tag; concrete pointer fields use null. No record fields or node bounds are stored on the tag.
+   *
+   * @public
+   */
+  export declare interface TypedNil<
+  ConcreteKind extends
+  | 'ArithmCmd'
+  | 'ArithmExp'
+  | 'ArrayElem'
+  | 'ArrayExpr'
+  | 'Assign'
+  | 'BinaryArithm'
+  | 'BinaryCmd'
+  | 'BinaryTest'
+  | 'Block'
+  | 'BraceExp'
+  | 'CStyleLoop'
+  | 'CallExpr'
+  | 'CaseClause'
+  | 'CaseItem'
+  | 'CmdSubst'
+  | 'Comment'
+  | 'CoprocClause'
+  | 'DblQuoted'
+  | 'DeclClause'
+  | 'ExtGlob'
+  | 'File'
+  | 'FlagsArithm'
+  | 'ForClause'
+  | 'FuncDecl'
+  | 'IfClause'
+  | 'LetClause'
+  | 'Lit'
+  | 'ParamExp'
+  | 'ParenArithm'
+  | 'ParenTest'
+  | 'ProcSubst'
+  | 'Redirect'
+  | 'SglQuoted'
+  | 'Stmt'
+  | 'Subshell'
+  | 'TestClause'
+  | 'TestDecl'
+  | 'TimeClause'
+  | 'UnaryArithm'
+  | 'UnaryTest'
+  | 'WhileClause'
+  | 'Word'
+  | 'WordIter',
+  > {
       /**
-       * 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.
+       * Distinguishes a typed nil interface value from a concrete syntax record.
        */
-      readonly transparentWrappers?: readonly WrapperSpec[];
+      Type: 'TypedNil';
+      /**
+       * The concrete Go pointer type retained by the non-nil interface.
+       */
+      Kind: ConcreteKind;
   }
 
   /**
-   * 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}).
+   * The upstream UnAritOperator domain: exact named tokens, the Go zero value, and explicitly validated unnamed uint32 values. Constants shared by upstream families retain their shared numeric identity.
    *
    * @public
    */
-  export declare function resolveWord(word: ShNode, options?: ResolveWordOptions): WordResolution;
+  export declare type UnAritOperator =
+  | 0
+  | typeof BitNegation
+  | typeof Dec
+  | typeof Inc
+  | typeof Minus
+  | typeof Not
+  | typeof Plus
+  | RawOperator<'UnAritOperator'>;
 
   /**
-   * Options controlling {@link resolveWord}'s tilde-expansion detection.
+   * UnaryArithm represents an unary arithmetic expression. The unary operator
+   * may come before or after the sub-expression.
+   *
+   * If Op is `Inc` or `Dec`, X will be a word with a single `Lit` whose value is a
+   * valid name.
+   *
+   * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
    *
    * @public
    */
-  export declare interface ResolveWordOptions {
+  export declare interface UnaryArithm {
       /**
-       * 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
+       * Identifies the upstream concrete record when carried through an interface union.
        */
-      readonly context?: 'command-argument' | 'assignment-value';
+      Type: 'UnaryArithm';
+      /**
+       * Upstream operator value, preserving named tokens, zero, and explicitly represented raw uint32 values.
+       */
+      Op: UnAritOperator;
+      /**
+       * Recorded source position; invalid and recovered states remain distinct.
+       */
+      OpPos: SyntaxPos;
+      /**
+       * False is an explicit upstream value and is never omitted.
+       */
+      Post: boolean;
+      /**
+       * Null preserves the upstream absence of this component.
+       */
+      X: ArithmExpr | null;
   }
 
   /**
-   * 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.
+   * UnaryTest represents a unary test expression. The unary operator may come
+   * before or after the sub-expression.
+   *
+   * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
    *
    * @public
    */
-  export declare class ShAnalyzeInvalidWrapperSpecError extends ShAstError {
-      readonly code = "SH_AST_ANALYZE_INVALID_WRAPPER_SPEC";
-      constructor(message: string);
+  export declare interface UnaryTest {
+      /**
+       * Identifies the upstream concrete record when carried through an interface union.
+       */
+      Type: 'UnaryTest';
+      /**
+       * Upstream operator value, preserving named tokens, zero, and explicitly represented raw uint32 values.
+       */
+      Op: UnTestOperator;
+      /**
+       * Recorded source position; invalid and recovered states remain distinct.
+       */
+      OpPos: SyntaxPos;
+      /**
+       * Null preserves the upstream absence of this component.
+       */
+      X: TestExpr | null;
   }
 
   /**
-   * 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.
+   * The upstream UnTestOperator domain: exact named tokens, the Go zero value, and explicitly validated unnamed uint32 values. Constants shared by upstream families retain their shared numeric identity.
    *
-   * `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 type UnTestOperator =
+  | 0
+  | typeof TsBlckSp
+  | typeof TsCharSp
+  | typeof TsDirect
+  | typeof TsEmpStr
+  | typeof TsExec
+  | typeof TsExists
+  | typeof TsFdTerm
+  | typeof TsGIDSet
+  | typeof TsGrpOwn
+  | typeof TsModif
+  | typeof TsNempStr
+  | typeof TsNmPipe
+  | typeof TsNoEmpty
+  | typeof TsNot
+  | typeof TsOptSet
+  | typeof TsParen
+  | typeof TsRead
+  | typeof TsRefVar
+  | typeof TsRegFile
+  | typeof TsSmbLink
+  | typeof TsSocket
+  | typeof TsSticky
+  | typeof TsUIDSet
+  | typeof TsUsrOwn
+  | typeof TsVarSet
+  | typeof TsWrite
+  | RawOperator<'UnTestOperator'>;
+
+  /**
+   * Upstream ParExpOperator constant UpperAll. Its numeric value is preserved exactly.
+   *
+   * ^^
    *
    * @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);
+  declare const UpperAll: 97;
+
+  /**
+   * Upstream ParExpOperator constant UpperFirst. Its numeric value is preserved exactly.
+   *
+   * ^
+   *
+   * @public
+   */
+  declare const UpperFirst: 96;
+
+  /**
+   * WhileClause represents a while or an until clause.
+   *
+   * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
+   *
+   * @public
+   */
+  export declare interface WhileClause {
+      /**
+       * Identifies the upstream concrete record when carried through an interface union.
+       */
+      Type: 'WhileClause';
+      /**
+       * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+       */
+      Cond: (Stmt | null)[] | null;
+      /**
+       * Ordered upstream entries. Null preserves a nil slice and differs from an empty array.
+       */
+      CondLast: Comment_2[] | null;
+      /**
+       * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+       */
+      Do: (Stmt | null)[] | null;
+      /**
+       * Ordered upstream entries. Null preserves a nil slice and differs from an empty array.
+       */
+      DoLast: Comment_2[] | null;
+      /**
+       * Recorded source position; invalid and recovered states remain distinct.
+       */
+      DoPos: SyntaxPos;
+      /**
+       * Recorded source position; invalid and recovered states remain distinct.
+       */
+      DonePos: SyntaxPos;
+      /**
+       * False is an explicit upstream value and is never omitted.
+       */
+      Until: boolean;
+      /**
+       * Recorded source position; invalid and recovered states remain distinct.
+       */
+      WhilePos: SyntaxPos;
   }
 
   /**
-   * 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}).
+   * Word represents a shell word, containing one or more word parts contiguous to
+   * each other. The word is delimited by word boundaries, such as spaces,
+   * newlines, semicolons, or parentheses.
    *
-   * 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.
+   * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
    *
    * @public
    */
-  export declare abstract class ShAstError extends Error {
+  export declare interface Word {
       /**
-       * Stable, machine-readable discriminator for this error kind. Distinct
-       * per subclass and will not change once published.
+       * Identifies the upstream concrete record when carried through an interface union.
        */
-      abstract readonly code: string;
+      Type: 'Word';
+      /**
+       * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+       */
+      Parts: (WordPart | null)[] | null;
   }
 
   /**
-   * A normalized AST node produced by {@link sh-ast#parseSync | parseSync}.
+   * Upstream RedirOperator constant WordHdoc. Its numeric value is preserved exactly.
+   *
+   * \<\<\<
    *
-   * `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 const WordHdoc: 73;
+
+  /**
+   * WordIter represents the iteration of a variable over a series of words in a
+   * for clause. If InPos is an invalid position, the "in" token was missing, so
+   * the iteration is over the shell's positional parameters.
    *
-   * 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.
+   * A syntax node with mutable upstream fields. Its source bounds are derived from the current fields and children.
    *
    * @public
    */
-  export declare interface ShNode {
-      readonly type: string;
-      readonly range: readonly [number, number];
-      readonly loc: {
-          readonly start: Position;
-          readonly end: Position;
-      };
-      [field: string]: unknown;
+  export declare interface WordIter {
+      /**
+       * Identifies the upstream concrete record when carried through an interface union.
+       */
+      Type: 'WordIter';
+      /**
+       * position of "in"
+       *
+       * Recorded source position; invalid and recovered states remain distinct.
+       */
+      InPos: SyntaxPos;
+      /**
+       * Ordered upstream entries. Null preserves a nil slice and differs from an empty array. Null entries preserve nil elements.
+       */
+      Items: (Word | null)[] | null;
+      /**
+       * Null preserves the upstream absence of this component.
+       */
+      Name: Lit | null;
   }
 
+  /**
+   * The concrete records and typed nil pointers accepted by upstream syntax.WordPart. Typed nil kinds are limited to this interface's actual implementers; auxiliary records are excluded.
+   *
+   * @public
+   */
+  export declare type WordPart =
+  | ArithmExp
+  | BraceExp
+  | CmdSubst
+  | DblQuoted
+  | ExtGlob
+  | Lit
+  | ParamExp
+  | ProcSubst
+  | SglQuoted
+  | TypedNil<
+  | 'ArithmExp'
+  | 'BraceExp'
+  | 'CmdSubst'
+  | 'DblQuoted'
+  | 'ExtGlob'
+  | 'Lit'
+  | 'ParamExp'
+  | 'ProcSubst'
+  | 'SglQuoted'
+  >;
+
   /**
    * The result of statically resolving a `Word` node's text. Reports facts
    * only — never a safety verdict, never a hardcoded command/wrapper list.
@@ -630,7 +3976,8 @@ export declare const DEFAULT_TRANSPARENT_WRAPPERS: readonly WrapperSpec[];
    *   `$"..."` 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`
+   * - `'unsupported'` — a word contains a nil or typed nil part, a literal carries a byte-preserving `Uint8Array`
+   *   rather than Unicode text, or 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
@@ -702,7 +4049,7 @@ export declare const DEFAULT_TRANSPARENT_WRAPPERS: readonly WrapperSpec[];
        * 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}
+       * `CallExpr.Assigns` prefixes {@link Argv0Resolution.assignmentsSkipped}
        * counts.
        */
       readonly skipAssignmentOperands?: boolean;
@@ -768,4 +4115,40 @@ export declare const DEFAULT_TRANSPARENT_WRAPPERS: readonly WrapperSpec[];
       readonly positionalOperandsBeforeCommand?: number;
   }
 
+  /**
+   * Upstream BinAritOperator constant Xor. Its numeric value is preserved exactly.
+   *
+   * ^
+   *
+   * @public
+   */
+  declare const Xor: 96;
+
+  /**
+   * Upstream BinAritOperator constant XorAssgn. Its numeric value is preserved exactly.
+   *
+   * ^=
+   *
+   * @public
+   */
+  declare const XorAssgn: 56;
+
+  /**
+   * Upstream BinAritOperator constant XorBool. Its numeric value is preserved exactly.
+   *
+   * ^^
+   *
+   * @public
+   */
+  declare const XorBool: 97;
+
+  /**
+   * Upstream BinAritOperator constant XorBoolAssgn. Its numeric value is preserved exactly.
+   *
+   * ^^=
+   *
+   * @public
+   */
+  declare const XorBoolAssgn: 61;
+
   export { }