sh-ast 0.0.0 → 0.1.0

package/dist/analyze/decode-lit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode-lit.js","sourceRoot":"","sources":["../../src/analyze/decode-lit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,mBAAmB,GAAwB,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAErE,uGAAuG;AACvG,MAAM,kBAAkB,GAAwB,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAwBpE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,QAAQ,GAAG,EAAE,CAAC;IAClB,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;QACtB,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,EAAE,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACxB,IAAI,IAAI,IAAI,CAAC;YACb,CAAC,IAAI,CAAC,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAChC,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;QACD,IAAI,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAC/B,QAAQ,IAAI,EAAE,CAAC;QACjB,CAAC;QACD,IAAI,IAAI,EAAE,CAAC;QACX,CAAC,IAAI,CAAC,CAAC;IACT,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AACrC,CAAC;AAED,uFAAuF;AACvF,MAAM,mBAAmB,GAAwB,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;AAEhF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;QACtB,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,EAAE,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACxB,IAAI,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAClC,IAAI,IAAI,IAAI,CAAC;gBACb,CAAC,IAAI,CAAC,CAAC;gBACP,SAAS;YACX,CAAC;YACD,oEAAoE;YACpE,IAAI,IAAI,EAAE,CAAC;YACX,CAAC,IAAI,CAAC,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,IAAI,EAAE,CAAC;QACX,CAAC,IAAI,CAAC,CAAC;IACT,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

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

@@ -0,0 +1,159 @@
+import type { ShNode } from '../types.js';
+import type { WordResolution } from './resolve-word.js';
+/**
+ * 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 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';
+};
+/**
+ * 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 interface CommandSite {
+    /** The `CallExpr` node this site was found at. */
+    readonly node: ShNode;
+    /**
+     * `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[];
+}
+/**
+ * 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 (`node.range[0]`), 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 `ShNode` — typically a `File` from `parseSync`, but any
+ * subtree (a `Stmt`, a `Command`, or even a bare `Word`) is handled.
+ * @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: ShNode): CommandSite[];
+//# sourceMappingURL=enumerate-commands.d.ts.map

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

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAU7D"}

package/dist/analyze/enumerate-commands.js

@@ -0,0 +1,390 @@
+import { ShAnalyzeMaxDepthError } from '../errors.js';
+import { isShNodeShape, nodeArray, stringField } from './node-helpers.js';
+import { resolveWord } from './resolve-word.js';
+/**
+ * mvdan/sh v3.13.1's `syntax.BinCmdOperator` token values for `BinaryCmd.Op`
+ * — `AndStmt` (`&&`), `OrStmt` (`||`), `Pipe` (`|`), `PipeAll` (`|&`). These
+ * are not part of any documented wire contract (`normalize()` copies
+ * mvdan/sh's raw numeric token straight through — see design/ARCHITECTURE.md
+ * open question 4), so they're pinned here by empirical observation against
+ * this bridge's own shim rather than derived from an upstream constant, and
+ * locked in by a canary test (`enumerate-commands.test.ts`, "binary command
+ * operator identification") that would fail loudly if a future mvdan/sh
+ * version renumbered them.
+ */
+const BIN_CMD_OP_AND = 11;
+const BIN_CMD_OP_OR = 12;
+const BIN_CMD_OP_PIPE = 13;
+const BIN_CMD_OP_PIPE_ALL = 14;
+function isPipeOp(op) {
+    return op === BIN_CMD_OP_PIPE || op === BIN_CMD_OP_PIPE_ALL;
+}
+/**
+ * The maximum number of *genuinely nested* structural frames (subshells,
+ * command/process substitutions, `if`/`case`/loop/function/`time`/`{ }`
+ * bodies, chained `elif`) {@link enumerateCommands} descends through before
+ * throwing {@link ShAnalyzeMaxDepthError} — a defensive backstop against
+ * pathological/adversarial input (a native stack overflow is an
+ * uncontrolled crash, not a catchable error). A long *linear* chain
+ * (`|`/`&&`/`||` of any length) never grows this counter — see
+ * `flattenPipelineStages`'s and `visitBinaryCmd`'s doc comments — only real
+ * nesting does.
+ *
+ * This value is deliberately *not* a round, "generous"-sounding number
+ * like 10,000: measured empirically (synthetic nested-`Subshell` trees,
+ * this repo's actual `vitest` worker environment, default Node/V8 stack
+ * size — see `analyze-enumerate-commands.test.ts`'s depth-guard describe
+ * block), this module's own recursive descent through a real
+ * `Subshell`-in-`Subshell` chain hits a raw, uncatchable
+ * `RangeError: Maximum call stack size exceeded` starting somewhere around
+ * depth 1,000–1,500 (the exact point varies run to run — it's a hard
+ * native-stack limit, not a clean threshold). A depth guard set at 10,000
+ * would never actually fire: the real crash happens first. 500 leaves
+ * roughly 2–3x headroom below the *lowest* observed native-crash depth,
+ * while still comfortably exceeding any realistic hand-written script's
+ * nesting (this is pathological-input protection, not a normal-usage
+ * ceiling).
+ */
+const MAX_STRUCTURAL_DEPTH = 500;
+function pushContext(context, frame) {
+    return [...context, frame];
+}
+/**
+ * Scans `value` — a word, an assignment, a test/arithmetic expression, a
+ * redirect, or an array of any of these — for `CmdSubst`/`ProcSubst`
+ * boundaries reachable from it, however deeply nested (through
+ * `DblQuoted`, `ParamExp`'s `Exp`/`Repl`/`Slice`/`nestedparam`, array
+ * elements, arithmetic operands, …), and hands each one found off to
+ * {@link visitStmtList} with the corresponding context frame pushed. This is
+ * a plain structural walk (discover children the same way {@link walk}
+ * does) rather than a hand-modeled traversal of every one of mvdan/sh's
+ * expression-shaped fields, because that set is large and not the part of
+ * the grammar this module's context-aware descent is about — the
+ * *command*-bearing structure (`BinaryCmd`, `IfClause`, loops, …) is
+ * hand-modeled in {@link visitCommand}; this helper's only job is finding
+ * where a word-shaped subtree stops being "just an expression" and starts
+ * containing statements again.
+ *
+ * `depth` is {@link visitStmt}'s structural-nesting counter, passed through
+ * unchanged for the generic per-field walk (a purely expression-shaped
+ * subtree — e.g. deeply nested `ParamExp` — is a different, out-of-scope
+ * risk from the command-structural nesting {@link MAX_STRUCTURAL_DEPTH}
+ * guards against) and incremented by one only when a `CmdSubst`/`ProcSubst`
+ * boundary is crossed, since that's a genuine additional level of
+ * command-bearing nesting (see {@link ShAnalyzeMaxDepthError}'s doc
+ * comment).
+ */
+function scanForHiddenCommands(value, context, sites, depth) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            scanForHiddenCommands(item, context, sites, depth);
+        return;
+    }
+    if (!isShNodeShape(value))
+        return;
+    if (value.type === 'CmdSubst') {
+        visitStmtList(nodeArray(value.stmts), pushContext(context, { kind: 'cmdSubst' }), sites, depth + 1);
+        return;
+    }
+    if (value.type === 'ProcSubst') {
+        visitStmtList(nodeArray(value.stmts), pushContext(context, { kind: 'procSubst' }), sites, depth + 1);
+        return;
+    }
+    for (const field of Object.values(value)) {
+        scanForHiddenCommands(field, context, sites, depth);
+    }
+}
+function visitStmtList(stmts, context, sites, depth) {
+    for (const stmt of stmts)
+        visitStmt(stmt, context, sites, depth);
+}
+/**
+ * Visits one `Stmt`. Every genuinely-nested recursive path through this
+ * module funnels through here (directly, or via {@link visitStmtList}) —
+ * see {@link MAX_STRUCTURAL_DEPTH}'s doc comment — so this is where the
+ * depth guard is enforced: a `depth` that has grown past
+ * {@link MAX_STRUCTURAL_DEPTH} throws {@link ShAnalyzeMaxDepthError} rather
+ * than recursing further.
+ */
+function visitStmt(stmt, context, sites, depth) {
+    if (depth > MAX_STRUCTURAL_DEPTH) {
+        throw new ShAnalyzeMaxDepthError(MAX_STRUCTURAL_DEPTH);
+    }
+    let stmtContext = context;
+    if (stmt.negated === true)
+        stmtContext = pushContext(stmtContext, { kind: 'negated' });
+    if (stmt.background === true)
+        stmtContext = pushContext(stmtContext, { kind: 'background' });
+    scanForHiddenCommands(stmt.redirs, stmtContext, sites, depth);
+    const cmd = stmt.cmd;
+    if (isShNodeShape(cmd))
+        visitCommand(cmd, stmtContext, sites, depth);
+}
+/**
+ * Recovers the left-to-right stages of a `|`/`|&` pipeline from `cmd` (a
+ * `BinaryCmd` whose own `Op` is already known to be a pipe-family
+ * operator). mvdan/sh nests these left-associatively — `a | b | c` is
+ * `BinaryCmd(x: Stmt{BinaryCmd(x: a, y: b)}, y: Stmt{c})` — so a chain of
+ * `n` stages is `n - 1` levels of nested `BinaryCmd`. Recovering stages
+ * walks that left ("x") spine with an explicit work stack instead of
+ * recursing per level, so a pipeline of any realistic length (this module
+ * is tested to 5,000+ stages) uses O(1) native call-stack frames here,
+ * regardless of `n` — the array-backed stack lives on the heap, not the
+ * call stack. The work-stack ordering (push `y` then `x`, i.e. `x` on top)
+ * mirrors what the original recursive left-to-right depth-first walk did
+ * (fully expand `x` before `y`), including the — per this bridge's own
+ * left-associative-only model — hypothetical case of a further pipe-family
+ * `BinaryCmd` on the `y` side. Mixed `|`/`|&` chains flatten into a single
+ * pipeline (this bridge doesn't distinguish "stderr also piped" in
+ * {@link CommandContext} — only stage position).
+ */
+function flattenPipelineStages(cmd) {
+    const stages = [];
+    const workStack = [cmd.y, cmd.x];
+    while (workStack.length > 0) {
+        const operandStmt = workStack.pop();
+        if (!isShNodeShape(operandStmt))
+            continue;
+        const innerCmd = operandStmt.cmd;
+        if (isShNodeShape(innerCmd) && innerCmd.type === 'BinaryCmd' && isPipeOp(innerCmd.op)) {
+            // Push `y` then `x` so `x` — the side that keeps the chain going in
+            // the left-associative case — is popped (processed) first.
+            workStack.push(innerCmd.y, innerCmd.x);
+        }
+        else {
+            stages.push(operandStmt);
+        }
+    }
+    return stages;
+}
+/**
+ * Visits a non-pipe-family `BinaryCmd` (`&&`/`||`, or a future operator
+ * this module doesn't specifically recognize). Like pipelines, `&&`/`||`
+ * chains nest left-associatively — `a && b && c` is
+ * `BinaryCmd(x: Stmt{BinaryCmd(x: a, y: b)}, y: Stmt{c})`, and a mixed
+ * `a && b || c` chain is still a single left-nested spine
+ * (`(a && b) || c`) — so a long chain is walked iteratively here too,
+ * exactly mirroring {@link flattenPipelineStages}'s technique: descend the
+ * left ("x") spine with a `while` loop instead of recursion, collecting
+ * each level's right ("y") operand (and which context frame, if any, it
+ * gets — `'and'`/`'or'`, or none for an unrecognized operator, matching
+ * the original per-level logic) along the way, stopping either at a plain
+ * (non-`BinaryCmd`) leftmost operand or at a pipe-family `BinaryCmd` (a
+ * different sub-structure, visited via the ordinary `visitStmt` →
+ * `visitCommand` → `visitBinaryCmd` dispatch below — a single, bounded
+ * recursive step, not per-chain-length).
+ *
+ * Every operand this function ultimately visits (the collected right-hand
+ * operands and the leftmost operand) is one genuine structural hop away
+ * from this `BinaryCmd` node, so each gets `depth + 1` — the *same*
+ * incremented value for every one of them, regardless of chain length:
+ * they're siblings under this node's flattened spine, not nested inside
+ * one another, so the depth counter must not grow with stage count (only
+ * {@link flattenPipelineStages}'s sibling pipeline stages get the same
+ * treatment, for the same reason).
+ */
+function visitBinaryCmd(cmd, context, sites, depth) {
+    const op = cmd.op;
+    if (isPipeOp(op)) {
+        const stages = flattenPipelineStages(cmd);
+        stages.forEach((stage, index) => {
+            visitStmt(stage, pushContext(context, { kind: 'pipeline', stage: index }), sites, depth + 1);
+        });
+        return;
+    }
+    const rightOperands = [];
+    let spine = cmd;
+    for (;;) {
+        const spineOp = spine.op;
+        const frame = spineOp === BIN_CMD_OP_AND
+            ? { kind: 'and', side: 'right' }
+            : spineOp === BIN_CMD_OP_OR
+                ? { kind: 'or', side: 'right' }
+                : undefined;
+        const y = spine.y;
+        if (isShNodeShape(y))
+            rightOperands.push({ stmt: y, frame });
+        const x = spine.x;
+        if (!isShNodeShape(x))
+            break;
+        const innerCmd = x.cmd;
+        if (isShNodeShape(innerCmd) && innerCmd.type === 'BinaryCmd' && !isPipeOp(innerCmd.op)) {
+            spine = innerCmd;
+            continue;
+        }
+        // `x` is the leftmost operand: not a further same-family BinaryCmd
+        // link, so this is where the spine walk ends — visit it with the
+        // *outer* (unmodified) context, exactly as the original recursive
+        // implementation visited `cmd.x`.
+        visitStmt(x, context, sites, depth + 1);
+        break;
+    }
+    for (const { stmt, frame } of rightOperands) {
+        visitStmt(stmt, frame ? pushContext(context, frame) : context, sites, depth + 1);
+    }
+}
+function visitIfClause(clause, context, sites, depth) {
+    visitStmtList(nodeArray(clause.cond), pushContext(context, { kind: 'if', branch: 'cond' }), sites, depth);
+    visitStmtList(nodeArray(clause.then), pushContext(context, { kind: 'if', branch: 'then' }), sites, depth);
+    const elseClause = clause.else;
+    if (isShNodeShape(elseClause)) {
+        // A chained `elif` — mvdan/sh models it as `IfClause.Else` pointing to
+        // another `IfClause` — is one more genuine level of nesting than
+        // `cond`/`then` above, so it gets its own `depth + 1` (a long `elif`
+        // chain must still trip {@link MAX_STRUCTURAL_DEPTH}, since — unlike
+        // `&&`/`||`/pipelines — this module does not special-case flattening
+        // it).
+        visitIfClause(elseClause, pushContext(context, { kind: 'if', branch: 'else' }), sites, depth + 1);
+    }
+}
+function visitCommand(cmd, context, sites, depth) {
+    switch (cmd.type) {
+        case 'CallExpr': {
+            scanForHiddenCommands(cmd.assigns, context, sites, depth);
+            scanForHiddenCommands(cmd.args, context, sites, depth);
+            const args = nodeArray(cmd.args);
+            if (args.length > 0) {
+                const argv = args.map((word) => resolveWord(word, { context: 'command-argument' }));
+                sites.push({ node: cmd, argv0: argv[0], argv, context });
+            }
+            return;
+        }
+        case 'BinaryCmd':
+            visitBinaryCmd(cmd, context, sites, depth);
+            return;
+        case 'Block':
+            // Transparent grouping (`{ ...; }`) — no context frame, but still one
+            // genuine level of structural nesting for depth-guard purposes (a
+            // pathological `{ { { ... } } }` chain must still trip the guard).
+            visitStmtList(nodeArray(cmd.stmts), context, sites, depth + 1);
+            return;
+        case 'Subshell':
+            visitStmtList(nodeArray(cmd.stmts), pushContext(context, { kind: 'subshell' }), sites, depth + 1);
+            return;
+        case 'IfClause':
+            visitIfClause(cmd, context, sites, depth + 1);
+            return;
+        case 'CaseClause': {
+            scanForHiddenCommands(cmd.word, context, sites, depth);
+            for (const item of nodeArray(cmd.items)) {
+                scanForHiddenCommands(item.patterns, context, sites, depth);
+                visitStmtList(nodeArray(item.stmts), pushContext(context, { kind: 'case' }), sites, depth + 1);
+            }
+            return;
+        }
+        case 'ForClause': {
+            scanForHiddenCommands(cmd.loop, context, sites, depth);
+            visitStmtList(nodeArray(cmd.do), pushContext(context, { kind: 'loop', role: 'body' }), sites, depth + 1);
+            return;
+        }
+        case 'WhileClause': {
+            visitStmtList(nodeArray(cmd.cond), pushContext(context, { kind: 'loop', role: 'cond' }), sites, depth + 1);
+            visitStmtList(nodeArray(cmd.do), pushContext(context, { kind: 'loop', role: 'body' }), sites, depth + 1);
+            return;
+        }
+        case 'FuncDecl': {
+            const nameNode = cmd.name;
+            const nameText = isShNodeShape(nameNode) ? stringField(nameNode, 'value') : '';
+            const body = cmd.body;
+            if (isShNodeShape(body)) {
+                visitStmt(body, pushContext(context, { kind: 'function', name: nameText }), sites, depth + 1);
+            }
+            return;
+        }
+        case 'CoprocClause': {
+            scanForHiddenCommands(cmd.name, context, sites, depth);
+            const stmt = cmd.stmt;
+            if (isShNodeShape(stmt)) {
+                visitStmt(stmt, pushContext(context, { kind: 'coproc' }), sites, depth + 1);
+            }
+            return;
+        }
+        case 'DeclClause':
+            scanForHiddenCommands(cmd.args, context, sites, depth);
+            return;
+        case 'LetClause':
+            scanForHiddenCommands(cmd.exprs, context, sites, depth);
+            return;
+        case 'TestClause':
+            scanForHiddenCommands(cmd.x, context, sites, depth);
+            return;
+        case 'ArithmCmd':
+            scanForHiddenCommands(cmd.x, context, sites, depth);
+            return;
+        case 'TestDecl': {
+            scanForHiddenCommands(cmd.description, context, sites, depth);
+            const body = cmd.body;
+            if (isShNodeShape(body))
+                visitStmt(body, context, sites, depth + 1);
+            return;
+        }
+        case 'TimeClause': {
+            // Transparent (`time cmd`) — no context frame, but still one genuine
+            // level of structural nesting for depth-guard purposes.
+            const stmt = cmd.stmt;
+            if (isShNodeShape(stmt))
+                visitStmt(stmt, context, sites, depth + 1);
+            return;
+        }
+        default:
+            // Not one of mvdan/sh's `syntax.Command` variants — e.g. a `Word` or
+            // `Assign` passed directly as `enumerateCommands`' root, or a future
+            // Command type this module doesn't know yet. Fall back to scanning it
+            // as an expression subtree rather than silently finding nothing.
+            scanForHiddenCommands(cmd, context, sites, depth);
+    }
+}
+/**
+ * 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 (`node.range[0]`), 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 `ShNode` — typically a `File` from `parseSync`, but any
+ * subtree (a `Stmt`, a `Command`, or even a bare `Word`) is handled.
+ * @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 function enumerateCommands(root) {
+    const sites = [];
+    if (root.type === 'File') {
+        visitStmtList(nodeArray(root.stmts), [], sites, 0);
+    }
+    else if (root.type === 'Stmt') {
+        visitStmt(root, [], sites, 0);
+    }
+    else {
+        visitCommand(root, [], sites, 0);
+    }
+    return [...sites].sort((a, b) => a.node.range[0] - b.node.range[0]);
+}
+//# sourceMappingURL=enumerate-commands.js.map

package/dist/analyze/enumerate-commands.js.map

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

package/dist/analyze/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `sh-ast/analyze` — the static-analysis layer built on top of the
+ * normalized AST from the package root. Its first primitive,
+ * {@link resolveWord}, answers "is this word statically a known string,
+ * and if so which?" — the question every downstream lint rule or command
+ * inventory asks first. Its second, {@link enumerateCommands}, answers
+ * "where are all the commands, and how is each one reached?" — finding
+ * every `CallExpr` anywhere in the tree, including ones hidden inside
+ * command/process substitutions nested in words. Facts only: no policy, no
+ * hardcoded command/wrapper lists (see {@link WordResolution}'s and
+ * {@link CommandSite}'s doc comments).
+ */
+export { resolveWord } from './resolve-word.js';
+export type { ResolveWordOptions, WordResolution, WordResolutionReason } from './resolve-word.js';
+export { enumerateCommands } from './enumerate-commands.js';
+export type { CommandContext, CommandSite } from './enumerate-commands.js';
+export { ShAnalyzeMaxDepthError } from '../errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/analyze/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analyze/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAElG,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAK3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC"}

package/dist/analyze/index.js

@@ -0,0 +1,27 @@
+/**
+ * `sh-ast/analyze` — the static-analysis layer built on top of the
+ * normalized AST from the package root. Its first primitive,
+ * {@link resolveWord}, answers "is this word statically a known string,
+ * and if so which?" — the question every downstream lint rule or command
+ * inventory asks first. Its second, {@link enumerateCommands}, answers
+ * "where are all the commands, and how is each one reached?" — finding
+ * every `CallExpr` anywhere in the tree, including ones hidden inside
+ * command/process substitutions nested in words. Facts only: no policy, no
+ * hardcoded command/wrapper lists (see {@link WordResolution}'s and
+ * {@link CommandSite}'s doc comments).
+ */
+export { resolveWord } from './resolve-word.js';
+export { enumerateCommands } from './enumerate-commands.js';
+// Re-exported from the root errors module so a consumer of enumerateCommands
+// can `import { ShAnalyzeMaxDepthError } from 'sh-ast/analyze'` without also
+// reaching into the root `sh-ast` entry point.
+export { ShAnalyzeMaxDepthError } from '../errors.js';
+// `ShNode` (resolveWord's parameter type) is deliberately *not* re-exported
+// here: it's the root `sh-ast` entry point's type (see `sh-ast`'s own
+// `index.ts`), and every caller of `resolveWord` already has a `ShNode` in
+// hand from `parseSync`/`walk` there. This is a known, intentional
+// "ae-forgotten-export" in this subpath's api-report — `sh-ast/analyze`
+// consumes the root layer's type without re-exporting it, rather than
+// re-exporting it (and its own transitive doc-linked types) just to
+// silence API Extractor.
+//# sourceMappingURL=index.js.map

package/dist/analyze/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/analyze/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG5D,6EAA6E;AAC7E,6EAA6E;AAC7E,+CAA+C;AAC/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAEtD,4EAA4E;AAC5E,sEAAsE;AACtE,2EAA2E;AAC3E,mEAAmE;AACnE,wEAAwE;AACxE,sEAAsE;AACtE,oEAAoE;AACpE,yBAAyB"}