sh-ast 0.3.1 → 0.5.0

package/README.md

@@ -1,53 +1,181 @@
 # sh-ast
 
-A synchronous, fully-typed shell AST for JavaScript and TypeScript. `sh-ast` parses shell scripts
-(bash, POSIX sh, mksh, zsh, and bats) using [mvdan/sh](https://github.com/mvdan/sh) — the Go
-shell parser used by `shfmt` and `shellcheck`-adjacent tooling — via a small Go/WASM shim, and
-normalizes the result into a plain-object AST with UTF-16-safe positions that's natural to
-consume from JS/TS (linters, formatters, codemods, static analysis, or anything else that needs
-to understand shell source structurally).
+A synchronous TypeScript interface to the `syntax` package of
+[mvdan/sh](https://github.com/mvdan/sh), pinned to **v3.13.1**. Parsing returns
+mutable records preserving upstream fields, defaults, nulls, numeric operators,
+byte strings, and token positions. First use initializes WebAssembly synchronously
+in Node.js; no initialization promise is required.
+
+Traversal uses ordinary TypeScript arrays with explicit mutation limits. The
+[accepted representation decision](../../design/WALK-MUTATION-DECISION.md) records
+which live edits are supported and why this interface does not model Go storage
+capacity, reslicing, or value-slot addresses.
 
 ```ts
-import { parseSync } from 'sh-ast';
+import { LangBash, nodeEnd, parseSync } from 'sh-ast';
+
+const file = parseSync('echo hi', { Variant: LangBash, KeepComments: true });
+const command = file.Stmts?.[0]?.Cmd;
+if (command?.Type === 'CallExpr') {
+  console.log(command.Args?.[0]?.Parts); // upstream WordPart alternatives
+  console.log(nodeEnd(command).Offset); // exclusive byte offset
+}
+```
+
+## Public contract
+
+- `parseSync(source, options?)` accepts a well-formed Unicode string or exact
+  `Uint8Array` bytes. Invalid UTF-8 reaches upstream and produces its parse error;
+  lone JavaScript surrogates are rejected before encoding.
+- `ParseOptions` contains `Filename`, `KeepComments`, `Variant`, `StopAt`, and
+  `RecoverErrors`. Defaults match upstream, including `KeepComments: false`.
+  `Variant` uses exported constants such as `LangBash` and `LangPOSIX`.
+- `File`, `Node`, and concrete records retain upstream spelling and a `Type`
+  discriminator. Every field is present; nil slices/pointers use `null`, while an
+  allocated empty slice is `[]`. `Slice`, `Replace`, and `Expansion` are auxiliary
+  records, not Nodes. Interface unions also admit `TypedNil<Kind>` with
+  `{ Type: 'TypedNil', Kind: 'Word' }` spelling: this preserves a Go interface
+  holding a nil pointer of a concrete type, distinct from an ordinary `null`
+  interface. A tag is allowed only where that concrete type implements the
+  declared interface; concrete pointer fields continue to use `null`.
+- `GoString` is `string | Uint8Array`: valid UTF-8 is text; other Go string bytes
+  remain bytes. Consumers must explicitly handle both representations.
+- `SyntaxPos` preserves `Offset`, `Line`, `Col`, `IsValid`, `IsRecovered`, and
+  `OffsetOverflow`. Offsets and columns count bytes; lines/columns are one-based.
+  Invalid, recovered, and overflow states remain distinct. No UTF-16 projection is
+  performed by this package.
+- `nodePos(node)` and `nodeEnd(node)` independently compute upstream bounds from
+  the current fields, including after edits. They do not return cached parse-time
+  bounds. Incomplete constructed nodes can support one bound but fail the other.
+- `parseWithPositionsSync(source, options?)` parses once and returns `{ File,
+Positions }`. `Positions.get(node)` reads immutable original bounds by node
+  identity without additional WASM calls. Editing `File` leaves these observations
+  unchanged; copied or foreign nodes have no entry. Use this separate snapshot for
+  source-location adapters, and live `nodePos`/`nodeEnd` for edited syntax. A
+  captured upstream bounds failure is thrown when its pair is requested; it does
+  not discard a successful parse. Parser failures retain the same structured
+  error and partial File as `parseSync`.
+- `newPos(offset, line, column)` preserves upstream clamping/overflow semantics.
+  Its uint64 inputs and the parser's Go int options accept safe integers or exact
+  `bigint`; stored position components and operator values are numbers.
+- Operator families have named numeric constants and a distinct raw uint32 path,
+  `rawOperator('RedirOperator', value)`, for unnamed upstream values. Representing
+  a value does not promise every upstream operation accepts it.
+- `SYNTAX_SCHEMA` and `SYNTAX_INTERFACES` are deeply frozen field/interface
+  metadata. Their order is not upstream Walk order.
+- `walk(node, callback)` calls the callback synchronously on entry and with `null`
+  on exit. Return `false` on entry to prune that occurrence, including its exit;
+  exit boolean values do not control traversal. Every callback result must be a
+  boolean; Promises and other values throw `InputError`. Child reads happen live, and
+  nested calls keep independent state. Specialized statement/item comment loops
+  visit value copies; ordinary comment lists visit their stored objects. The
+  array reference and initial length are captured when each list starts. Future
+  existing slots are read live; indices added beyond the captured extent are
+  ignored by that active traversal. Replacing the owner's array field does not retarget an active list.
+  See the mutation limits below.
+- `printSync(node, options?)` reconstructs the current edited tree and collects a
+  fresh upstream printer's output as `GoString`. Supported roots are File, Stmt,
+  Word, Assign, Command and WordPart alternatives. Only File gets a guaranteed
+  final newline. Printing applies upstream formatting; it does not replay the
+  original source or promise source-byte identity.
+- `PrintOptions` exposes `Indent`, `BinaryNextLine`, `SwitchCaseIndent`,
+  `SpaceRedirects`, `KeepPadding`, `Minify`, `SingleLine`, and `FunctionNextLine`.
+  Indent accepts an exact uint64 as a safe number or bigint, with zero selecting
+  tabs. Boolean defaults are false. KeepPadding is upstream's best-effort,
+  deprecated option; Minify and SingleLine together return an upstream error.
+
+`ParseError` and `LangError` preserve upstream fields, exact `Message` bytes, and
+any partial `File`. Their ordinary `Error.message` is a display string.
+`InputError` reports invalid binding inputs, upstream option constraints, or
+unsupported constructed nodes whose requested bound panics upstream.
+`ShInternalError` reports transport failures or unexpected upstream panics.
+`PrintError` retains ordinary upstream printer failures, and `PrintPanicError`
+retains panics from printing representable inputs. `WalkPanicError` represents
+upstream-equivalent traversal panics; callback exceptions retain their identity.
+All extend `ShAstError`. The conservative structural-depth guard throws
+`ShParseMaxDepthError` before potentially exhausting the WASM stack. It is a
+binding resource constraint and can reject deeply nested quoted or commented text.
+Printing collects complete output; large trees or indentation widths can consume
+substantial memory and time. The parse guard does not bound arbitrary constructed
+printing inputs. No arbitrary writer, partial-output, or reusable-printer protocol
+is exposed.
+
+## Traversal mutation limits
+
+Supported edits preserve a node's kind and shape: change syntax fields, replace
+pointer children before their read, replace future existing list slots, append
+beyond an active list's captured extent, or assign a new array to the owner field.
+Changes before a list starts are included in its captured reference and length.
+Pruning and synchronous nested walks retain their control behavior; nested walks
+see the tree at their own entry, while edits to shared objects remain live.
+
+Keep every index in an active list's captured extent present. Removing one,
+leaving a hole there, or shrinking below that extent is outside the supported
+contract, including through aliases. Truncation, `delete`, `pop`, `shift`, or a
+length-reducing `splice` can do this; removing appended indices beyond the captured
+extent does not affect the active list. No mutation detector or specific
+error/result is promised for those edits. Assign a new owner array
+instead; the active list keeps its original array and later walks see the new one.
+Length-preserving replacement or reordering, including `sort` and `reverse`,
+follows live slot reads and may revisit an object moved into a later slot. Walk
+does not promise to visit each object only once. An appended object moved into an
+original future slot is visited through that slot.
+
+Stored Comment callbacks receive JavaScript objects. Replacing a Comment slot
+leaves a retained callback object unchanged; it does not behave as a pointer to a
+Go value slot. Specialized Stmt/CaseItem/ArrayElem comment callbacks receive
+copies, so editing those callback values does not edit the original comments.
+Ordinary JavaScript aliases remain live; this interface does not clone shared
+arrays or objects. It does not model Go slice capacity, distinct slice headers
+sharing backing stores, or reslicing. These limits preclude unrestricted Go
+storage mutation parity while preserving live field edits and upstream traversal control.
+
+## Editing and printing
 
-const file = parseSync('echo hi');
-file.stmts[0].cmd.type; // "CallExpr"
+```ts
+import { parseSync, printSync, walk } from 'sh-ast';
+
+const file = parseSync("printf '%s\\n' 'old 🎉'\n", { KeepComments: true });
+walk(file, (node) => {
+  if (node?.Type === 'SglQuoted' && node.Value === 'old 🎉') {
+    node.Value = 'new 🎉';
+  }
+  return true;
+});
+const output = printSync(file);
 ```
 
-## Provenance
-
-`sh-ast` was extracted from [`eslint-sh`](https://github.com/mike-north/eslint-sh) (as
-`@eslint-sh/bridge`) at commit
-[`bdd55b3`](https://github.com/mike-north/eslint-sh/commit/bdd55b3), where it was built as the
-parser core underneath an ESLint plugin for shell scripts. The full commit history predating the
-extraction lives in that repository. This package carries no ESLint dependency and exposes the
-same public API `@eslint-sh/bridge` did.
-
-## Status
-
-The visitor-keys and child-type-schema tables, plus the `ShNodes.*` TypeScript typings, are
-generated from mvdan/sh's `syntax` package struct definitions by `tools/gen-visitor-keys` — see
-that tool's README for "The schema table is generated, not hand-written".
-
-## Public API
-
-- `parseSync(text, options?)` — synchronous parse; throws `ShParseError` (with `.line`,
-  `.column`, `.filename`) on a shell syntax error.
-- `ParseOptions` — `{ dialect?, filename? }`; `dialect` is one of `bash | posix | mksh | bats |
-zsh`, mapped to mvdan/sh's `LangVariant` by string name.
-- `ShNode` / `ShFile` — normalized node shape (`type`, `range`, `loc`, plus lowercased fields
-  from mvdan/sh's tree).
-- `ShNodes` — generated, strongly-typed `ShNode` subtypes for every mvdan/sh node type (e.g.
-  `ShNodes.ShCallExprNode`, `ShNodes.ShDeclClauseNode`), plus union aliases (`ShAnyNode`,
-  `ShCommandNode`, `ShWordPartNode`, …). Additive and optional — `ShNode`'s index signature
-  remains the base contract.
-- `visitorKeys` — generated node-type → child-field-name table.
-- `walk(node, visit)` — visits every node in a normalized tree; discovers children structurally
-  rather than depending on `visitorKeys`.
+This edits a field without replacing array storage. Node positions still describe
+their upstream token values; live `nodePos` and `nodeEnd` compute from current
+fields, while a separately captured parse snapshot remains tied to original
+source. Consumers such as ESLint can edit a separate tree and use printed output
+as a fix without mutating their original lint view or traversal cache.
+
+`sh-ast/analyze` remains a separate syntactic interpretation layer. Its word,
+command, and wrapper analysis consumes the faithful records; it does not define
+parser behavior or the core tree representation.
+
+## Migration from 0.3
+
+Fields now use upstream spelling (`Type`, `Stmts`, `Cmd`, `Value`) and explicit
+null/default values. Replace dialect strings with numeric `Variant` constants,
+request comments explicitly, and handle structured errors and byte positions.
+The root no longer exports normalized `ShNode`/`ShNodes`, `range`/`loc`, or
+`visitorKeys`. The new walker uses entry/null-exit callbacks rather than the former
+structural helper's protocol. Consumers such as ESLint own their source-coordinate
+and traversal views. Whole-file parsing, collected printing and the live walker
+with the mutation limits above form this candidate's scope. Stateful/incremental parser protocols
+and full syntax-package parity are deferred.
+
+The [design collection](../../design/ARCHITECTURE.md) and
+[implementation evidence](../../design/IMPLEMENTATION.md) describe the release
+boundaries, concrete choices, and validation status. This package has no ESLint
+runtime dependency. It originated in
+[`eslint-sh`](https://github.com/mike-north/eslint-sh) at commit `bdd55b3`.
 
 ## Dialect enforcement
 
-`dialect` maps directly onto mvdan/sh's `LangVariant` (`LangBash`, `LangPOSIX`, `LangMirBSDKorn`,
+`Variant` accepts mvdan/sh's `LangVariant` (`LangBash`, `LangPOSIX`, `LangMirBSDKorn`,
 `LangBats`, `LangZsh`). mvdan/sh gates most dialect-specific syntax with a hard parse error
 (`checkLang` in its `syntax/parser.go`) when the requested dialect isn't in that construct's
 allowed set — but two dialect-specific keywords (`[[` test clauses and `let`) have **no such gate**:
@@ -79,12 +207,12 @@ post-processing pass, which `shim/main.go` does not invoke. `{a,b}` always parse
 
 \*\*\* zsh's lexer never tokenizes `@(` as an extended-glob opener at all — deliberately, to avoid
 ambiguity with zsh's own glob qualifiers like `*(N)`. So `ls @(a|b)` parses without error under
-`dialect: 'zsh'`, but produces plain `Lit` word parts rather than an `ExtGlob` node; the
+`Variant: LangZsh`, but produces plain `Lit` word parts rather than an `ExtGlob` node; the
 `checkLang` gate that rejects extended globs under posix is never reached for zsh.
 
 ### `[[ ... ]]` and `let` under posix: accepted by design
 
-`dialect: 'posix'` accepting `[[ a == b ]]` and `let x=1` is **intentional upstream behavior, not
+`Variant: LangPOSIX` accepting `[[ a == b ]]` and `let x=1` is **intentional upstream behavior, not
 a bridge bug**. POSIX sh has no `[[` test clause or `let` builtin as syntax — so mvdan/sh's parser
 doesn't special-case those keywords at all outside bash-like/mksh/zsh; it falls through to
 ordinary word/command parsing, exactly as a real POSIX-mode shell would tokenize `[[` as a command
@@ -94,114 +222,42 @@ either by an explicit `checkLang` gate or, for process substitution, after lexer
 operator inside `[[ a =~ b ]]` remains ordinary command text because POSIX mode never enters the
 test-clause parser.
 
-Concretely, under `dialect: 'posix'`:
+Concretely, under `Variant: LangPOSIX`:
 
 ```ts
-const file = parseSync('[[ a == b ]]', { dialect: 'posix' });
-file.stmts[0].cmd.type; // "CallExpr" — a command literally named "[[", not "TestClause"
+import { LangPOSIX, parseSync } from 'sh-ast';
+
+const file = parseSync('[[ a == b ]]', { Variant: LangPOSIX });
+file.Stmts?.[0]?.Cmd?.Type; // "CallExpr" — a command literally named "[[", not "TestClause"
 ```
 
 Evidence: mvdan/sh's own test suite (`syntax/filetests_test.go`) asserts this exact shape for
-`LangPOSIX`, and `shim/main.go` passes the requested dialect through to mvdan/sh's
-`LangVariant.Set` unmodified — the bridge does not special-case or mis-map `[[`.
+`LangPOSIX`, and the syntax bridge passes the requested numeric variant to mvdan/sh's
+`Variant` control — the bridge does not special-case or mis-map `[[`.
 
-## Regenerating the schema tables
+## Generated model
 
-After bumping the pinned mvdan/sh version (`shim/go.mod` _and_ `../../tools/gen-visitor-keys/go.mod`
-must move together):
-
-```sh
-pnpm run generate:sh-ast-schema
-```
-
-This regenerates `generated/visitor-keys.js(.d.ts)`, `generated/child-type-schema.js(.d.ts)`, and
-`generated/node-types.d.ts`, then formats them with Prettier. CI
-(`.github/workflows/gen-visitor-keys.yml`) reruns the same script and fails the build if the
-committed artifacts don't come back byte-identical — the drift gate for future mvdan/sh bumps.
-Re-run the kitchen-sink golden test (`test/kitchen-sink.test.ts`) afterward; it fails if the new
-mvdan/sh version adds a node type the fixtures don't yet exercise.
+The generator reads the pinned upstream struct definitions. Run
+`pnpm run generate:sh-ast-schema` after changing the matching pins in
+`shim/go.mod` and `../../tools/gen-visitor-keys/go.mod`. Faithful declarations,
+constants, and complete field metadata live in `generated/syntax-*`.
+Independent Go reflection tests, manually derived type assertions, and runtime
+fixtures check fidelity; regeneration alone checks only drift.
 
 ## The WASM shim
 
-`shim/main.go` parses with `mvdan.cc/sh/v3/syntax` and encodes the result with
-`shim/internal/nodeencode` — a performance fork of `mvdan.cc/sh/v3/syntax/typedjson`'s encode
-path (see that package's doc comment for why: typedjson's reflection-based encoder rebuilds an
-identical synthetic struct type per node _instance_ rather than once per node _type_, which
-dominated warm-parse latency — see "Performance" below) — so interface-typed nodes (`CallExpr`,
-`BinaryCmd`, …) carry a `Type` discriminator, exactly as upstream typedjson does (verified
-byte-identical in `shim/internal/nodeencode/encode_test.go`). The whole result envelope —
-including any error message — is marshaled with Go's `encoding/json`, so JSON-significant bytes
-in an error message (e.g. an unclosed-quote message containing `"`) survive the Go→JS boundary
-intact.
-
-The shim exposes a linear-memory ABI — `alloc`/`process`/`free` WASM exports plus the `mem`
-memory export — instead of a `syscall/js` global function. `wasm-instance.ts` writes UTF-8 bytes
-directly into WASM memory and reads the JSON result back with `TextDecoder`, avoiding
-`syscall/js`'s much more expensive per-call JS↔Go value marshaling (see "Performance" below).
-
-### Performance
-
-Local measurement (700-line/~9k-node fixture, warm instance, Apple M-series):
-
-| Stage                                 | Before (syscall/js + typedjson) | After (linear memory + nodeencode) |
-| ------------------------------------- | ------------------------------: | ---------------------------------: |
-| End-to-end warm `parseSync` (p50)     |                          ~97 ms |                             ~29 ms |
-| wasm call (parse + encode + transfer) |                          ~91 ms |                           ~23.5 ms |
-| `JSON.parse`                          |                           ~3 ms |                              ~3 ms |
-| `normalize`                           |                         ~2.5 ms |                            ~2.7 ms |
-| `sh-ast.wasm` size                    |                        ~4.10 MB |                           ~3.82 MB |
-
-The dominant fix was **not** the transport switch alone — profiling found `typedjson.Encode`'s
-`reflect.StructOf` call (rebuilding an identical synthetic struct type once per node _instance_)
-responsible for ~80ms of the ~90ms wasm call; `nodeencode`'s per-_type_ cache cut that to ~14ms.
-The linear-memory ABI switch and a hand-rolled envelope wrap (skipping a redundant
-`encoding/json.Marshal` re-compaction of the already-encoded AST bytes) account for the rest.
-
-**TinyGo**, evaluated for its ~4x smaller runtime, cannot run this shim: it compiles
-`reflect.StructOf` calls without error but panics at runtime with `unimplemented:
-reflect.StructOf()` the moment `nodeencode`/`typedjson`'s encoder runs (confirmed against
-TinyGo 0.41.1). Standard Go + `wasm-opt -Oz` (binaryen, pinned in CI) is the fallback:
-`sh-ast.wasm` is optimized after every build, for a ~7% size reduction (~4.09 MB → ~3.82 MB) with
-no behavior change. Neither path reaches a 1.5 MB stretch target.
-
-After editing `shim/main.go` or `shim/internal/nodeencode`, rebuild the committed
-`shim/sh-ast.wasm`:
-
-```sh
-cd shim
-GOOS=js GOARCH=wasm go build -buildvcs=false -trimpath -ldflags="-s -w -buildid=" -o sh-ast.wasm .
-wasm-opt -Oz --enable-bulk-memory-opt --enable-nontrapping-float-to-int sh-ast.wasm -o sh-ast.wasm
-```
-
-`wasm-opt` ships with [binaryen](https://github.com/WebAssembly/binaryen/releases) — CI installs
-a pinned release (see `.github/workflows/wasm-reproducibility.yml`'s `BINARYEN_VERSION`); install
-the same version locally (`brew install binaryen`, or download the pinned release directly) so
-your rebuild matches CI byte-for-byte. `--enable-bulk-memory-opt` and
-`--enable-nontrapping-float-to-int` tell `wasm-opt` to accept the two WASM proposal features
-Go's `js/wasm` target already emits (both broadly supported in Node and browsers since ~2020) —
-without them, `wasm-opt` rejects the input as invalid.
-
-The `-buildid=` flag blanks out Go's build-ID metadata (used only by the Go toolchain's own
-build cache, never read at runtime); without it, `-trimpath` alone is not enough for a
-byte-identical rebuild — the embedded build ID otherwise varies between build-cache states even
-with identical source and dependencies.
-
-`-buildvcs=false` is equally required: Go 1.18+ stamps binaries with `vcs.revision`/`vcs.time`/
-`vcs.modified` by default (`-buildvcs=auto`), reading whatever commit and dirty-state the
-checkout happens to be in at build time. That stamp isn't touched by `-s -w` (it lives outside
-the symbol table/DWARF that those flags strip), so two builds of _identical source_ differ
-whenever the checkout's commit or dirty-state differs — which is exactly what happens for a
-`pull_request`-triggered CI run (GitHub synthesizes a fresh merge commit, with its own SHA and
-timestamp, on every run) versus a `push`-triggered run (checks out the named branch commit
-as-is), and equally for a local checkout with any uncommitted changes elsewhere in the working
-tree. `-buildvcs=false` removes this source of non-determinism entirely; verified byte-for-byte
-identical across a native macOS/arm64 build, a `linux/amd64` build under Docker/QEMU emulation,
-and real `ubuntu-latest` CI runs triggered via `push`, `pull_request`, and `workflow_dispatch`.
-
-`wasm-opt -Oz` is a deterministic, version-pinned transform: rebuilding twice (Go build +
-wasm-opt) produces byte-identical output, verified locally and by CI's `rebuild-match` job.
-
-CI rebuilds the shim with a pinned Go toolchain (`shim/go.mod`) and a pinned `wasm-opt`
-(`.github/workflows/wasm-reproducibility.yml`), and fails if the output differs from the
-committed artifact. It also runs `shim/internal/nodeencode`'s Go test suite, which asserts the
-fork's output is byte-identical to upstream `typedjson.Encode`.
+The `syntaxProcess` linear-memory ABI transports exact byte payloads and a
+reversible record encoding. `shim/internal/syntaxwire` preserves all exported
+fields, nil/default values, arbitrary strings, and observable position behavior.
+`shim/internal/syntaxbridge` invokes upstream parsing and position operations.
+Private Go printing tests verify that reconstructed edited trees retain the
+information needed for the future public printer.
+
+The canonical binary is built by Linux/amd64 CI with the Go toolchain pinned in
+`shim/go.mod` and the checksum-pinned Binaryen version in
+`.github/workflows/wasm-reproducibility.yml`. Go build flags are
+`-buildvcs=false -trimpath -ldflags="-s -w -buildid="`; optimization uses
+`wasm-opt -Oz --enable-bulk-memory-opt --enable-nontrapping-float-to-int`.
+Use local builds for experiments. Commit the CI-produced artifact, then require
+CI to compare a fresh rebuild byte-for-byte with the committed binary. Historical
+normalized-parser benchmarks do not describe this interface's performance.

package/dist/analyze/ansi-c-escapes.d.ts

@@ -2,7 +2,7 @@
  * Decodes `$'...'` (Bash ANSI-C Quoting) escape sequences.
  *
  * mvdan/sh's parser does **not** perform this decoding: for a `SglQuoted`
- * word part with `dollar: true`, the normalized `value` field is the raw,
+ * word part with `Dollar: true`, the upstream `Value` field is the raw,
  * un-decoded source text between the quotes (verified empirically against
  * mvdan.cc/sh/v3 v3.13.1 — see `test/analyze-resolve-word.test.ts`'s module
  * comment for how this was confirmed). This module fills that gap using the

package/dist/analyze/ansi-c-escapes.js

@@ -2,7 +2,7 @@
  * Decodes `$'...'` (Bash ANSI-C Quoting) escape sequences.
  *
  * mvdan/sh's parser does **not** perform this decoding: for a `SglQuoted`
- * word part with `dollar: true`, the normalized `value` field is the raw,
+ * word part with `Dollar: true`, the upstream `Value` field is the raw,
  * un-decoded source text between the quotes (verified empirically against
  * mvdan.cc/sh/v3 v3.13.1 — see `test/analyze-resolve-word.test.ts`'s module
  * comment for how this was confirmed). This module fills that gap using the

package/dist/analyze/enumerate-commands.d.ts

@@ -1,4 +1,4 @@
-import type { ShNode } from '../types.js';
+import type { CallExpr, GoString, Node } from '../../generated/syntax-types.js';
 import type { WordResolution } from './resolve-word.js';
 /**
  * A single frame of the path from the root of the tree down to a
@@ -19,10 +19,10 @@ import type { WordResolution } from './resolve-word.js';
  *   `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`.
+ *   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
+ *   `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).
@@ -80,7 +80,7 @@ export type CommandContext = {
     readonly role: 'body' | 'cond';
 } | {
     readonly kind: 'function';
-    readonly name: string;
+    readonly name: GoString;
 } | {
     readonly kind: 'background';
 } | {
@@ -100,7 +100,7 @@ export type CommandContext = {
  */
 export interface CommandSite {
     /** The `CallExpr` node this site was found at. */
-    readonly node: ShNode;
+    readonly node: CallExpr;
     /**
      * `resolveWord` applied to the first word (`argv[0]`), with
      * `{ context: 'command-argument' }` — every `CallExpr` word is an
@@ -125,14 +125,14 @@ export interface CommandSite {
  * `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`.
+ * `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 (`node.range[0]`), so nested
+ * 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.
  *
@@ -144,14 +144,9 @@ export interface CommandSite {
  * 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 `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.
+ * @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`/`{ }`
@@ -161,5 +156,5 @@ export interface CommandSite {
  * it as `deny`.
  * @public
  */
-export declare function enumerateCommands(root: ShNode): CommandSite[];
+export declare function enumerateCommands(root: Node): CommandSite[];
 //# sourceMappingURL=enumerate-commands.d.ts.map

package/dist/analyze/enumerate-commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"enumerate-commands.d.ts","sourceRoot":"","sources":["../../src/analyze/enumerate-commands.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;CAAE,GAClE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEhC;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,oIAAoI;IACpI,QAAQ,CAAC,IAAI,EAAE,SAAS,cAAc,EAAE,CAAC;IACzC,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CAC7C;AA2aD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAU7D"}
+{"version":3,"file":"enumerate-commands.d.ts","sourceRoot":"","sources":["../../src/analyze/enumerate-commands.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAEV,QAAQ,EACR,QAAQ,EAER,IAAI,EAEL,MAAM,iCAAiC,CAAC;AAGzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;CAAE,GAClE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEhC;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,oIAAoI;IACpI,QAAQ,CAAC,IAAI,EAAE,SAAS,cAAc,EAAE,CAAC;IACzC,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CAC7C;AAiaD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,WAAW,EAAE,CAa3D"}