sh-ast 0.0.0 → 0.1.0

package/dist/analyze.d.ts

@@ -0,0 +1,390 @@
+/**
+ * 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: 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 declare 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[];
+
+ /**
+  * A 1-based line/column position. Columns are UTF-16 code units, matching
+  * JavaScript string indexing (see {@link ShNode.range}).
+  *
+  * @public
+  */
+ declare interface Position {
+     readonly line: number;
+     readonly column: number;
+ }
+
+ /**
+  * Determines whether a `Word` node is statically a known string, and if
+  * so, what that string is — the atom of shell-AST static analysis (e.g.
+  * "is this word literally `rm`"). A word is static iff every part is a
+  * literal after shell unquoting: a bare `Lit` (backslash escapes
+  * processed), a `SglQuoted` (including `$'...'` ANSI-C escapes decoded),
+  * or a `DblQuoted` containing only literal parts (and not itself a
+  * `$"..."` locale translation) — including concatenations of these (`'r'm`
+  * resolves to `"rm"`). A word containing any expansion (`ParamExp`,
+  * `CmdSubst`, `ArithmExp`, `ProcSubst`), a triggering unquoted `~` (see
+  * `options.context`), an unquoted glob metacharacter/bracket
+  * expression/`ExtGlob`, a `$"..."` locale translation, or an unrepresentable
+  * `$'\U...'` escape is `static: false` with a reason — never an error, and
+  * never a safety judgment (see {@link WordResolution}).
+  *
+  * @param word - A `Word` node, e.g. `parseSync(...).stmts[0].cmd.args[0]`.
+  * @param options - See {@link ResolveWordOptions}.
+  * @throws TypeError if `word.type` is not `"Word"` — a programmer-error
+  * misuse of the API, not a "malformed shell source" case (well-formed
+  * shell source, however dynamic, never throws; see {@link WordResolution}).
+  *
+  * @public
+  */
+ export declare function resolveWord(word: ShNode, options?: ResolveWordOptions): WordResolution;
+
+ /**
+  * Options controlling {@link resolveWord}'s tilde-expansion detection.
+  *
+  * @public
+  */
+ export declare interface ResolveWordOptions {
+     /**
+      * Which Bash grammar position `word` occupies — the two positions Bash
+      * §3.5.2 ("Tilde Expansion") documents distinct tilde-expansion triggers
+      * for:
+      *
+      * - `'command-argument'` — an ordinary simple-command argument word (e.g.
+      *   `echo <word>`). Only a *word-initial* unquoted `~` triggers tilde
+      *   expansion; an unquoted `~` elsewhere in the word (including right
+      *   after a `:`) is an ordinary character (`echo a:~b` prints `a:~b`
+      *   literally in real bash).
+      * - `'assignment-value'` — the value side of a shell assignment (e.g.
+      *   `PATH=<word>`, an `Assign` node's `value`). Bash additionally
+      *   tilde-expands an unquoted `~` immediately following an unquoted `:`
+      *   anywhere in the value (`PATH=/foo:~/bar` expands the `~/bar`
+      *   segment) — this is documented for `PATH`-like colon-separated
+      *   assignment values specifically.
+      *
+      * **Default: `'assignment-value'` semantics apply whenever this option is
+      * omitted.** `resolveWord` takes a bare `Word` node with no grammar
+      * context attached, so it cannot see whether its caller extracted that
+      * word from a command argument or an assignment value — omitting this
+      * option is deliberately treated as the *more conservative* of the two
+      * (the one that reports `'tilde'` in more cases), so a caller that
+      * doesn't know or care about the distinction never under-reports a real
+      * tilde-expansion site. Pass `'command-argument'` explicitly to opt into
+      * the narrower, word-initial-only check that matches real bash's
+      * behavior for ordinary arguments.
+      *
+      * @see https://www.gnu.org/software/bash/manual/bash.html#Tilde-Expansion
+      */
+     readonly context?: 'command-argument' | 'assignment-value';
+ }
+
+ /**
+  * Thrown by `sh-ast/analyze`'s `enumerateCommands` when a tree's genuinely
+  * nested structure — subshells within subshells, chained command/process
+  * substitutions, deeply nested `if`/`case`/loop/function/`time`/`{ }`
+  * bodies, deeply chained `elif` — exceeds its defensive recursion-depth
+  * guard. **Not** thrown for a long *linear* chain (`|`/`|&`/`&&`/`||` of
+  * any realistic length): `enumerateCommands` traverses those iteratively,
+  * so chain length alone never grows this guard's depth counter — only
+  * genuine tree nesting does.
+  *
+  * `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 ShBridgeError {
+     readonly code = "ESLINT_SH_ANALYZE_MAX_DEPTH";
+     /** The maximum nesting depth `enumerateCommands` supports; the same value every time (not caller-configurable). */
+     readonly maxDepth: number;
+     constructor(maxDepth: number);
+ }
+
+ /**
+  * Common base class for every error this package throws — originally just
+  * {@link parseSync}'s errors, now also the `sh-ast/analyze` layer's (see
+  * {@link ShAnalyzeMaxDepthError}). Provides a stable, documented `code`
+  * discriminator (e.g. `"ESLINT_SH_PARSE_ERROR"`) alongside the usual
+  * `instanceof` narrowing, so consumers can branch on failure kind
+  * programmatically without parsing `.message` strings. Never thrown
+  * directly — only via its concrete subclasses ({@link ShParseError},
+  * {@link ShInvalidDialectError}, {@link ShBridgeInternalError},
+  * {@link ShAnalyzeMaxDepthError}).
+  *
+  * @public
+  */
+ declare abstract class ShBridgeError extends Error {
+     /**
+      * Stable, machine-readable discriminator for this error kind. Distinct
+      * per subclass and will not change once published.
+      */
+     abstract readonly code: string;
+ }
+
+ /**
+  * A normalized AST node produced by {@link parseSync}.
+  *
+  * `range` and `loc` are expressed in UTF-16 code units, so
+  * `code.slice(node.range[0], node.range[1])` reproduces the node's exact
+  * source text — even though mvdan/sh itself reports byte offsets and
+  * byte-counting columns internally (see design/ARCHITECTURE.md's
+  * "Serialization contract"). Every other field copied over from mvdan/sh's
+  * typedjson tree keeps its original value but with the field name
+  * lowercased (`Stmts` becomes `stmts`, `CondLast` becomes `condlast`, etc.).
+  *
+  * @public
+  */
+ declare interface ShNode {
+     readonly type: string;
+     readonly range: readonly [number, number];
+     readonly loc: {
+         readonly start: Position;
+         readonly end: Position;
+     };
+     [field: string]: unknown;
+ }
+
+ /**
+  * The result of statically resolving a `Word` node's text. Reports facts
+  * only — never a safety verdict, never a hardcoded command/wrapper list.
+  * `static: false` ("unknowable") is a first-class, valid result, not an
+  * error condition.
+  *
+  * @public
+  */
+ export declare type WordResolution = {
+     /** The word is a compile-time-known string. */
+     readonly static: true;
+     /** The word's exact resolved text (quotes and escapes removed). */
+     readonly text: string;
+ } | {
+     /** The word's value depends on program state, the environment, or the filesystem. */
+     readonly static: false;
+     /** Why this word cannot be statically resolved. */
+     readonly reason: WordResolutionReason;
+ };
+
+ /**
+  * Why a {@link resolveWord} result is `static: false`: the word's exact
+  * text cannot be determined from source alone.
+  *
+  * - `'expansion'` — the word contains a `ParamExp` (`$x`, `${x}`), a
+  *   `CmdSubst` (command substitution, either `$(...)` or backtick form), an
+  *   `ArithmExp` (`$((expr))`), or a `ProcSubst` (`<(cmd)`/`>(cmd)`) part:
+  *   its value depends on program state (variables, command output, process
+  *   substitution) that only exists at run time.
+  * - `'tilde'` — an unquoted, unescaped `~` triggers Bash tilde expansion
+  *   (Bash Reference Manual §3.5.2, "Tilde Expansion") at the start of the
+  *   word, or — when `resolveWord`'s `context` option is `'assignment-value'`
+  *   or omitted — immediately after an unquoted `:` anywhere in the word too
+  *   (§3.5.2 also documents this for assignment-statement values, e.g.
+  *   `PATH=/foo:~/bar`). Either way: statically shaped, but its value
+  *   depends on the filesystem/environment (`$HOME`, NSS user database
+  *   lookups) at run time. See `resolveWord`'s `context` parameter doc for
+  *   the full command-argument-vs-assignment-value distinction.
+  * - `'glob'` — the word contains an unquoted, unescaped glob metacharacter
+  *   (`*`/`?`), an unquoted bracket expression (`[...]` — an unquoted `[`
+  *   with a later unquoted `]` in the same word, POSIX 2.13.1 / Bash
+  *   Reference Manual §3.5.8.1, "Pattern Matching"), or an `ExtGlob` part
+  *   (Bash Reference Manual §3.5.8, "Filename Expansion"): its value depends
+  *   on which filesystem entries exist at run time.
+  * - `'brace'` — the word contains a `BraceExp` part (`{a,b}`/`{1..10}`,
+  *   Bash Reference Manual §3.5.1, "Brace Expansion"). mvdan/sh v3.13.1 only
+  *   ever produces this node type when its caller applies `syntax.SplitBraces`
+  *   to the parsed tree; this bridge's shim does not call it, so today a
+  *   brace expression like `{a,b}` reaches {@link resolveWord} as an
+  *   ordinary `Lit` (indistinguishable, in the AST this bridge produces,
+  *   from literal `{`/`,`/`}` characters) rather than as a `BraceExp` part.
+  *   This reason is handled here for forward-compatibility with that node
+  *   type and is not reachable through {@link resolveWord} today.
+  * - `'locale'` — the word contains a `$"..."` locale-translated string
+  *   (Bash Reference Manual §3.1.2.5, "Locale-Specific Translation"): its
+  *   value is looked up in the current locale's translation catalog at run
+  *   time via `gettext`, regardless of whether its contents also contain an
+  *   expansion. `'locale'` takes precedence over any `'expansion'` a
+  *   `$"..."` word's *contents* would otherwise report — the `DblQuoted`
+  *   node's own `dollar` flag is checked before its children are visited at
+  *   all, so e.g. `$"hi $x"` reports `'locale'`, never `'expansion'`.
+  * - `'unsupported'` — the word contains a `$'...'` (ANSI-C quoted) `\u`/`\U`
+  *   escape whose value has no corresponding Unicode character (greater than
+  *   `U+10FFFF`, e.g. `$'\UFFFFFFFF'`): real bash's output for this case is
+  *   an undocumented, non-UTF-8 byte sequence with no exact representation
+  *   as a JavaScript string (see `ansi-c-escapes.ts`'s
+  *   `MAX_UNICODE_CODE_POINT` doc comment for the empirical detail) — this
+  *   package declines to claim a `static: true` text bash never actually
+  *   produces.
+  *
+  * This union may grow in a **minor** release — new mvdan/sh word-part node
+  * types, or new statically-shaped-but-dynamic categories, can add new reason
+  * strings without that being a breaking change. It is deliberately not
+  * sealed against extension elsewhere in the codebase. A reason string this
+  * version of the package doesn't yet know about only ever accompanies
+  * `static: false`, never changes the meaning of `static: true`, so runtime
+  * consumers that only branch on `.static` are safe by construction across
+  * such additions; an exhaustive compile-time `switch` over `.reason` should
+  * still include a `default` case to stay forward-compatible.
+  *
+  * @public
+  */
+ export declare type WordResolutionReason = 'expansion' | 'tilde' | 'glob' | 'brace' | 'locale' | 'unsupported';
+
+ export { }

package/dist/deep-freeze.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Recursively freezes `value` and every object/array it (transitively)
+ * contains, so a frozen shared table's immutability holds at every level —
+ * not just its own top-level keys — rather than relying on every caller to
+ * treat it as read-only by convention.
+ *
+ * Generic, structural recursion over an unknown shape needs a cast to index
+ * into `value`'s own properties; contained to this one small, well-tested
+ * utility rather than spread across every table that uses it.
+ *
+ * @internal
+ */
+export declare function deepFreeze<T>(value: T): Readonly<T>;
+//# sourceMappingURL=deep-freeze.d.ts.map

package/dist/deep-freeze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-freeze.d.ts","sourceRoot":"","sources":["../src/deep-freeze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAWnD"}

package/dist/deep-freeze.js

@@ -0,0 +1,25 @@
+/**
+ * Recursively freezes `value` and every object/array it (transitively)
+ * contains, so a frozen shared table's immutability holds at every level —
+ * not just its own top-level keys — rather than relying on every caller to
+ * treat it as read-only by convention.
+ *
+ * Generic, structural recursion over an unknown shape needs a cast to index
+ * into `value`'s own properties; contained to this one small, well-tested
+ * utility rather than spread across every table that uses it.
+ *
+ * @internal
+ */
+export function deepFreeze(value) {
+    if (value !== null && (typeof value === 'object' || typeof value === 'function')) {
+        for (const key of Object.getOwnPropertyNames(value)) {
+            const prop = value[key];
+            if (prop !== null && typeof prop === 'object') {
+                deepFreeze(prop);
+            }
+        }
+        Object.freeze(value);
+    }
+    return value;
+}
+//# sourceMappingURL=deep-freeze.js.map

package/dist/deep-freeze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-freeze.js","sourceRoot":"","sources":["../src/deep-freeze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CAAI,KAAQ;IACpC,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,UAAU,CAAC,EAAE,CAAC;QACjF,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,GAAI,KAAiC,CAAC,GAAG,CAAC,CAAC;YACrD,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC9C,UAAU,CAAC,IAAI,CAAC,CAAC;YACnB,CAAC;QACH,CAAC;QACD,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,115 @@
+import type { ShellDialect } from './types.js';
+/**
+ * Common base class for every error this package throws — originally just
+ * {@link parseSync}'s errors, now also the `sh-ast/analyze` layer's (see
+ * {@link ShAnalyzeMaxDepthError}). Provides a stable, documented `code`
+ * discriminator (e.g. `"ESLINT_SH_PARSE_ERROR"`) alongside the usual
+ * `instanceof` narrowing, so consumers can branch on failure kind
+ * programmatically without parsing `.message` strings. Never thrown
+ * directly — only via its concrete subclasses ({@link ShParseError},
+ * {@link ShInvalidDialectError}, {@link ShBridgeInternalError},
+ * {@link ShAnalyzeMaxDepthError}).
+ *
+ * @public
+ */
+export declare abstract class ShBridgeError extends Error {
+    /**
+     * Stable, machine-readable discriminator for this error kind. Distinct
+     * per subclass and will not change once published.
+     */
+    abstract readonly code: string;
+}
+/**
+ * Position info attached to a {@link ShParseError}.
+ *
+ * @public
+ */
+export interface ShParseErrorInfo {
+    /** 1-based line number, exactly as reported by mvdan/sh. */
+    line: number;
+    /**
+     * 1-based column number, in **UTF-16 code units** — converted from
+     * mvdan/sh's own byte-counting column so it agrees with
+     * {@link ShNode.loc}'s columns (mvdan/sh reports `column` as a byte count
+     * on the source line, not a UTF-16 code unit count; see
+     * design/ARCHITECTURE.md's "Byte→UTF-16 conversion"). For ASCII-only
+     * source text this is numerically identical to mvdan/sh's own column.
+     */
+    column: number;
+    /** The filename used for the parse (see {@link ParseOptions.filename}). */
+    filename: string;
+}
+/**
+ * Thrown by {@link parseSync} when shell source fails to parse. Carries the
+ * real position mvdan/sh reported — never 1:1 placeholders: `.line` is
+ * 1-based exactly as mvdan/sh reports it, and `.column` is converted to
+ * UTF-16 code units so it agrees with {@link ShNode.loc}'s columns (mvdan/sh
+ * itself reports `column` as a byte count on the source line — see
+ * {@link ShParseErrorInfo.column}). The unconverted, raw byte-column
+ * position appears only inside `.message`, mvdan/sh's own formatted string,
+ * verbatim.
+ *
+ * @public
+ */
+export declare class ShParseError extends ShBridgeError {
+    readonly code = "ESLINT_SH_PARSE_ERROR";
+    readonly line: number;
+    readonly column: number;
+    readonly filename: string;
+    constructor(message: string, info: ShParseErrorInfo);
+}
+/**
+ * Thrown by {@link parseSync} when {@link ParseOptions.dialect} is not one
+ * of the supported {@link ShellDialect} values. Carries the rejected value
+ * as `.dialect`; `.message` lists the supported dialects. A foreseeable,
+ * actionable user mistake — never an instance of {@link ShParseError}.
+ *
+ * @public
+ */
+export declare class ShInvalidDialectError extends ShBridgeError {
+    readonly code = "ESLINT_SH_INVALID_DIALECT";
+    /** The rejected dialect value, exactly as passed to {@link parseSync}. */
+    readonly dialect: string;
+    constructor(dialect: string, supportedDialects: readonly ShellDialect[]);
+}
+/**
+ * Thrown by {@link parseSync} for failures that should never happen given a
+ * correctly-behaving WASM shim: a malformed result envelope, an unexpected
+ * root node type, or any other shim contract violation. Distinct from
+ * {@link ShInvalidDialectError} and {@link ShParseError}, both of which
+ * indicate a foreseeable, actionable user mistake rather than an internal
+ * defect.
+ *
+ * @public
+ */
+export declare class ShBridgeInternalError extends ShBridgeError {
+    readonly code = "ESLINT_SH_BRIDGE_INTERNAL";
+    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 ShBridgeError {
+    readonly code = "ESLINT_SH_ANALYZE_MAX_DEPTH";
+    /** The maximum nesting depth `enumerateCommands` supports; the same value every time (not caller-configurable). */
+    readonly maxDepth: number;
+    constructor(maxDepth: number);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;;GAYG;AACH,8BAAsB,aAAc,SAAQ,KAAK;IAC/C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,YAAa,SAAQ,aAAa;IAC7C,QAAQ,CAAC,IAAI,2BAA2B;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB;CAOpD;AAED;;;;;;;GAOG;AACH,qBAAa,qBAAsB,SAAQ,aAAa;IACtD,QAAQ,CAAC,IAAI,+BAA+B;IAC5C,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,SAAS,YAAY,EAAE;CAOxE;AAED;;;;;;;;;GASG;AACH,qBAAa,qBAAsB,SAAQ,aAAa;IACtD,QAAQ,CAAC,IAAI,+BAA+B;gBAEhC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,sBAAuB,SAAQ,aAAa;IACvD,QAAQ,CAAC,IAAI,iCAAiC;IAC9C,mHAAmH;IACnH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM;CAO7B"}

package/dist/errors.js

@@ -0,0 +1,106 @@
+/**
+ * Common base class for every error this package throws — originally just
+ * {@link parseSync}'s errors, now also the `sh-ast/analyze` layer's (see
+ * {@link ShAnalyzeMaxDepthError}). Provides a stable, documented `code`
+ * discriminator (e.g. `"ESLINT_SH_PARSE_ERROR"`) alongside the usual
+ * `instanceof` narrowing, so consumers can branch on failure kind
+ * programmatically without parsing `.message` strings. Never thrown
+ * directly — only via its concrete subclasses ({@link ShParseError},
+ * {@link ShInvalidDialectError}, {@link ShBridgeInternalError},
+ * {@link ShAnalyzeMaxDepthError}).
+ *
+ * @public
+ */
+export class ShBridgeError extends Error {
+}
+/**
+ * Thrown by {@link parseSync} when shell source fails to parse. Carries the
+ * real position mvdan/sh reported — never 1:1 placeholders: `.line` is
+ * 1-based exactly as mvdan/sh reports it, and `.column` is converted to
+ * UTF-16 code units so it agrees with {@link ShNode.loc}'s columns (mvdan/sh
+ * itself reports `column` as a byte count on the source line — see
+ * {@link ShParseErrorInfo.column}). The unconverted, raw byte-column
+ * position appears only inside `.message`, mvdan/sh's own formatted string,
+ * verbatim.
+ *
+ * @public
+ */
+export class ShParseError extends ShBridgeError {
+    code = 'ESLINT_SH_PARSE_ERROR';
+    line;
+    column;
+    filename;
+    constructor(message, info) {
+        super(message);
+        this.name = 'ShParseError';
+        this.line = info.line;
+        this.column = info.column;
+        this.filename = info.filename;
+    }
+}
+/**
+ * Thrown by {@link parseSync} when {@link ParseOptions.dialect} is not one
+ * of the supported {@link ShellDialect} values. Carries the rejected value
+ * as `.dialect`; `.message` lists the supported dialects. A foreseeable,
+ * actionable user mistake — never an instance of {@link ShParseError}.
+ *
+ * @public
+ */
+export class ShInvalidDialectError extends ShBridgeError {
+    code = 'ESLINT_SH_INVALID_DIALECT';
+    /** The rejected dialect value, exactly as passed to {@link parseSync}. */
+    dialect;
+    constructor(dialect, supportedDialects) {
+        super(`bridge: unrecognized shell dialect "${dialect}"; supported dialects are: ${supportedDialects.join(', ')}`);
+        this.name = 'ShInvalidDialectError';
+        this.dialect = dialect;
+    }
+}
+/**
+ * Thrown by {@link parseSync} for failures that should never happen given a
+ * correctly-behaving WASM shim: a malformed result envelope, an unexpected
+ * root node type, or any other shim contract violation. Distinct from
+ * {@link ShInvalidDialectError} and {@link ShParseError}, both of which
+ * indicate a foreseeable, actionable user mistake rather than an internal
+ * defect.
+ *
+ * @public
+ */
+export class ShBridgeInternalError extends ShBridgeError {
+    code = 'ESLINT_SH_BRIDGE_INTERNAL';
+    constructor(message) {
+        super(message);
+        this.name = 'ShBridgeInternalError';
+    }
+}
+/**
+ * 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 class ShAnalyzeMaxDepthError extends ShBridgeError {
+    code = 'ESLINT_SH_ANALYZE_MAX_DEPTH';
+    /** The maximum nesting depth `enumerateCommands` supports; the same value every time (not caller-configurable). */
+    maxDepth;
+    constructor(maxDepth) {
+        super(`enumerateCommands: exceeded the maximum supported structural nesting depth (${String(maxDepth)} frames) — refusing to return a partial result. Treat this as a deny signal, not "no commands found".`);
+        this.name = 'ShAnalyzeMaxDepthError';
+        this.maxDepth = maxDepth;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,OAAgB,aAAc,SAAQ,KAAK;CAMhD;AAuBD;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,YAAa,SAAQ,aAAa;IACpC,IAAI,GAAG,uBAAuB,CAAC;IAC/B,IAAI,CAAS;IACb,MAAM,CAAS;IACf,QAAQ,CAAS;IAE1B,YAAY,OAAe,EAAE,IAAsB;QACjD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAChC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IAC7C,IAAI,GAAG,2BAA2B,CAAC;IAC5C,0EAA0E;IACjE,OAAO,CAAS;IAEzB,YAAY,OAAe,EAAE,iBAA0C;QACrE,KAAK,CACH,uCAAuC,OAAO,8BAA8B,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3G,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IAC7C,IAAI,GAAG,2BAA2B,CAAC;IAE5C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,sBAAuB,SAAQ,aAAa;IAC9C,IAAI,GAAG,6BAA6B,CAAC;IAC9C,mHAAmH;IAC1G,QAAQ,CAAS;IAE1B,YAAY,QAAgB;QAC1B,KAAK,CACH,+EAA+E,MAAM,CAAC,QAAQ,CAAC,uGAAuG,CACvM,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF"}