sh-ast 0.0.0 → 0.2.0

package/dist/sh-ast.d.ts

@@ -0,0 +1,1346 @@
+/**
+ * Options accepted by {@link parseSync}.
+ *
+ * @public
+ */
+export declare interface ParseOptions {
+    /**
+     * The shell dialect to parse against.
+     * @defaultValue `"bash"`
+     */
+    readonly dialect?: ShellDialect;
+    /**
+     * Filename used only to annotate error messages and positions; the source
+     * is never read from disk.
+     * @defaultValue `"input.sh"`
+     */
+    readonly filename?: string;
+}
+
+/**
+ * Synchronously parses shell source into a normalized AST.
+ *
+ * The first call instantiates the WASM shim synchronously (Node-only); the
+ * instance is reused across subsequent calls, so repeated calls do not
+ * re-instantiate (see design/ARCHITECTURE.md).
+ *
+ * Throws {@link ShParseError} on a shell syntax error, carrying the position
+ * mvdan/sh reported: `.line` is 1-based exactly as mvdan/sh reports it;
+ * `.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 — see {@link ShParseErrorInfo.column}). That unconverted, raw
+ * position appears only inside `.message`, which is mvdan/sh's own
+ * formatted string, verbatim. Throws {@link ShInvalidDialectError} when
+ * {@link ParseOptions.dialect} is not a supported dialect. Throws
+ * {@link ShInternalError} for failures that should never happen given
+ * a correctly-behaving shim (malformed envelope, unexpected root node
+ * type, shim contract violations). Throws {@link ShParseMaxDepthError} if
+ * `text`'s conservatively estimated structural nesting depth exceeds the
+ * limit this bridge accepts — checked, and thrown, *before* `text` is ever
+ * handed to the WASM shim, since mvdan/sh's own parser has no recovery path
+ * for exhausting its stack on pathological nesting (see that error's doc
+ * comment and `parse-depth-guard.ts`).
+ *
+ * @public
+ */
+export declare function parseSync(text: string, options?: ParseOptions): ShFile;
+
+/**
+ * A 1-based line/column position. Columns are UTF-16 code units, matching
+ * JavaScript string indexing (see {@link ShNode.range}).
+ *
+ * @public
+ */
+export declare interface Position {
+    readonly line: number;
+    readonly column: number;
+}
+
+/**
+ * Thrown by `sh-ast/analyze`'s `resolveArgv0` when a caller-supplied
+ * `options.transparentWrappers` array contains a malformed `WrapperSpec`
+ * entry — e.g. a non-array or empty `names`, or a flag field that isn't an
+ * array of strings. Fails closed with a clear, specific message at the
+ * point the malformed table is supplied, rather than letting the bad shape
+ * reach flag-matching logic and surface as a confusing native `TypeError`
+ * (or, worse, a silently wrong match) far from its actual cause.
+ *
+ * @public
+ */
+export declare class ShAnalyzeInvalidWrapperSpecError extends ShAstError {
+    readonly code = "SH_AST_ANALYZE_INVALID_WRAPPER_SPEC";
+    constructor(message: string);
+}
+
+/**
+ * Thrown by `sh-ast/analyze`'s `enumerateCommands` when a tree's genuinely
+ * nested structure — subshells within subshells, chained command/process
+ * substitutions, deeply nested `if`/`case`/loop/function/`time`/`{ }`
+ * bodies, deeply chained `elif` — exceeds its defensive recursion-depth
+ * guard. **Not** thrown for a long *linear* chain (`|`/`|&`/`&&`/`||` of
+ * any realistic length): `enumerateCommands` traverses those iteratively,
+ * so chain length alone never grows this guard's depth counter — only
+ * genuine tree nesting does.
+ *
+ * `enumerateCommands` deliberately fails closed here rather than returning
+ * a truncated, partial result: a partial `CommandSite[]` silently omits
+ * real command sites, which is a false negative for a permission-hook-style
+ * consumer that treats "command not found in the enumeration" as "nothing
+ * to worry about" — an explicit, documented throw is safer than a silent
+ * under-report. Gate-style consumers should treat this error as `deny`,
+ * not fall back to "no commands found, so allow".
+ *
+ * @public
+ */
+export declare class ShAnalyzeMaxDepthError extends ShAstError {
+    readonly code = "SH_AST_ANALYZE_MAX_DEPTH";
+    /** The maximum nesting depth `enumerateCommands` supports; the same value every time (not caller-configurable). */
+    readonly maxDepth: number;
+    constructor(maxDepth: number);
+}
+
+/**
+ * The union of every normalized node type this bridge can produce.
+ *
+ * @public
+ */
+declare type ShAnyNode =
+| ShArithmCmdNode
+| ShArithmExpNode
+| ShArrayElemNode
+| ShArrayExprNode
+| ShAssignNode
+| ShBinaryArithmNode
+| ShBinaryCmdNode
+| ShBinaryTestNode
+| ShBlockNode
+| ShBraceExpNode
+| ShCStyleLoopNode
+| ShCallExprNode
+| ShCaseClauseNode
+| ShCaseItemNode
+| ShCmdSubstNode
+| ShCommentNode
+| ShCoprocClauseNode
+| ShDblQuotedNode
+| ShDeclClauseNode
+| ShExpansionNode
+| ShExtGlobNode
+| ShFileNode
+| ShFlagsArithmNode
+| ShForClauseNode
+| ShFuncDeclNode
+| ShIfClauseNode
+| ShLetClauseNode
+| ShLitNode
+| ShParamExpNode
+| ShParenArithmNode
+| ShParenTestNode
+| ShProcSubstNode
+| ShRedirectNode
+| ShReplaceNode
+| ShSglQuotedNode
+| ShSliceNode
+| ShStmtNode
+| ShSubshellNode
+| ShTestClauseNode
+| ShTestDeclNode
+| ShTimeClauseNode
+| ShUnaryArithmNode
+| ShUnaryTestNode
+| ShWhileClauseNode
+| ShWordNode
+| ShWordIterNode;
+
+/**
+ * mvdan/sh's `syntax.ArithmCmd`, normalized.
+ *
+ * @public
+ */
+declare interface ShArithmCmdNode {
+    readonly type: 'ArithmCmd';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly x?: ShArithmExprNode;
+}
+
+/**
+ * mvdan/sh's `syntax.ArithmExp`, normalized.
+ *
+ * @public
+ */
+declare interface ShArithmExpNode {
+    readonly type: 'ArithmExp';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly x?: ShArithmExprNode;
+}
+
+/**
+ * The union of concrete node types mvdan/sh's `syntax.ArithmExpr` interface can
+ * hold.
+ *
+ * @public
+ */
+declare type ShArithmExprNode =
+ShBinaryArithmNode | ShFlagsArithmNode | ShParenArithmNode | ShUnaryArithmNode | ShWordNode;
+
+/**
+ * mvdan/sh's `syntax.ArrayElem`, normalized.
+ *
+ * @public
+ */
+declare interface ShArrayElemNode {
+    readonly type: 'ArrayElem';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly comments: readonly ShCommentNode[];
+    readonly index?: ShArithmExprNode;
+    readonly value?: ShWordNode;
+}
+
+/**
+ * mvdan/sh's `syntax.ArrayExpr`, normalized.
+ *
+ * @public
+ */
+declare interface ShArrayExprNode {
+    readonly type: 'ArrayExpr';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly elems: readonly ShArrayElemNode[];
+    readonly last: readonly ShCommentNode[];
+}
+
+/**
+ * mvdan/sh's `syntax.Assign`, normalized.
+ *
+ * @public
+ */
+declare interface ShAssignNode {
+    readonly type: 'Assign';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly array?: ShArrayExprNode;
+    readonly index?: ShArithmExprNode;
+    readonly name?: ShLitNode;
+    readonly value?: ShWordNode;
+}
+
+/**
+ * Common base class for every error this package throws — originally just
+ * {@link sh-ast#parseSync | parseSync}'s errors, now also the
+ * `sh-ast/analyze` layer's (see {@link ShAnalyzeMaxDepthError},
+ * {@link ShAnalyzeInvalidWrapperSpecError}). Provides a stable, documented
+ * `code` discriminator (e.g. `"SH_AST_PARSE_ERROR"`) alongside the usual
+ * `instanceof` narrowing, so consumers can branch on failure kind
+ * programmatically without parsing `.message` strings. Never thrown directly
+ * — only via its concrete subclasses
+ * ({@link sh-ast#ShParseError | ShParseError},
+ * {@link sh-ast#ShInvalidDialectError | ShInvalidDialectError},
+ * {@link sh-ast#ShInternalError | ShInternalError},
+ * {@link ShAnalyzeMaxDepthError},
+ * {@link sh-ast#ShParseMaxDepthError | ShParseMaxDepthError},
+ * {@link ShAnalyzeInvalidWrapperSpecError}).
+ *
+ * Re-exported from `sh-ast/analyze` as well as the root `sh-ast` entry
+ * point (see #23) — every subclass thrown by `sh-ast/analyze`'s own
+ * functions extends this, so a consumer of that subpath alone can
+ * `catch`/reference the base without also importing from root.
+ *
+ * @public
+ */
+export declare abstract class ShAstError extends Error {
+    /**
+     * Stable, machine-readable discriminator for this error kind. Distinct
+     * per subclass and will not change once published.
+     */
+    abstract readonly code: string;
+}
+
+/**
+ * mvdan/sh's `syntax.BinaryArithm`, normalized.
+ *
+ * @public
+ */
+declare interface ShBinaryArithmNode {
+    readonly type: 'BinaryArithm';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly x?: ShArithmExprNode;
+    readonly y?: ShArithmExprNode;
+}
+
+/**
+ * mvdan/sh's `syntax.BinaryCmd`, normalized.
+ *
+ * @public
+ */
+declare interface ShBinaryCmdNode {
+    readonly type: 'BinaryCmd';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly x?: ShStmtNode;
+    readonly y?: ShStmtNode;
+}
+
+/**
+ * mvdan/sh's `syntax.BinaryTest`, normalized.
+ *
+ * @public
+ */
+declare interface ShBinaryTestNode {
+    readonly type: 'BinaryTest';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly x?: ShTestExprNode;
+    readonly y?: ShTestExprNode;
+}
+
+/**
+ * mvdan/sh's `syntax.Block`, normalized.
+ *
+ * @public
+ */
+declare interface ShBlockNode {
+    readonly type: 'Block';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly last: readonly ShCommentNode[];
+    readonly stmts: readonly ShStmtNode[];
+}
+
+/**
+ * mvdan/sh's `syntax.BraceExp`, normalized.
+ *
+ * @public
+ */
+declare interface ShBraceExpNode {
+    readonly type: 'BraceExp';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly elems: readonly ShWordNode[];
+}
+
+/**
+ * mvdan/sh's `syntax.CallExpr`, normalized.
+ *
+ * @public
+ */
+declare interface ShCallExprNode {
+    readonly type: 'CallExpr';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly args: readonly ShWordNode[];
+    readonly assigns: readonly ShAssignNode[];
+}
+
+/**
+ * mvdan/sh's `syntax.CaseClause`, normalized.
+ *
+ * @public
+ */
+declare interface ShCaseClauseNode {
+    readonly type: 'CaseClause';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly items: readonly ShCaseItemNode[];
+    readonly last: readonly ShCommentNode[];
+    readonly word?: ShWordNode;
+}
+
+/**
+ * mvdan/sh's `syntax.CaseItem`, normalized.
+ *
+ * @public
+ */
+declare interface ShCaseItemNode {
+    readonly type: 'CaseItem';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly comments: readonly ShCommentNode[];
+    readonly last: readonly ShCommentNode[];
+    readonly patterns: readonly ShWordNode[];
+    readonly stmts: readonly ShStmtNode[];
+}
+
+/**
+ * mvdan/sh's `syntax.CmdSubst`, normalized.
+ *
+ * @public
+ */
+declare interface ShCmdSubstNode {
+    readonly type: 'CmdSubst';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly last: readonly ShCommentNode[];
+    readonly stmts: readonly ShStmtNode[];
+}
+
+/**
+ * The union of concrete node types mvdan/sh's `syntax.Command` interface can
+ * hold.
+ *
+ * @public
+ */
+declare type ShCommandNode =
+| ShArithmCmdNode
+| ShBinaryCmdNode
+| ShBlockNode
+| ShCallExprNode
+| ShCaseClauseNode
+| ShCoprocClauseNode
+| ShDeclClauseNode
+| ShForClauseNode
+| ShFuncDeclNode
+| ShIfClauseNode
+| ShLetClauseNode
+| ShSubshellNode
+| ShTestClauseNode
+| ShTestDeclNode
+| ShTimeClauseNode
+| ShWhileClauseNode;
+
+/**
+ * mvdan/sh's `syntax.Comment`, normalized.
+ *
+ * @public
+ */
+declare interface ShCommentNode {
+    readonly type: 'Comment';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+}
+
+/**
+ * mvdan/sh's `syntax.CoprocClause`, normalized.
+ *
+ * @public
+ */
+declare interface ShCoprocClauseNode {
+    readonly type: 'CoprocClause';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly name?: ShWordNode;
+    readonly stmt?: ShStmtNode;
+}
+
+/**
+ * mvdan/sh's `syntax.CStyleLoop`, normalized.
+ *
+ * @public
+ */
+declare interface ShCStyleLoopNode {
+    readonly type: 'CStyleLoop';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly cond?: ShArithmExprNode;
+    readonly init?: ShArithmExprNode;
+    readonly post?: ShArithmExprNode;
+}
+
+/**
+ * mvdan/sh's `syntax.DblQuoted`, normalized.
+ *
+ * @public
+ */
+declare interface ShDblQuotedNode {
+    readonly type: 'DblQuoted';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly parts: readonly ShWordPartNode[];
+}
+
+/**
+ * mvdan/sh's `syntax.DeclClause`, normalized.
+ *
+ * @public
+ */
+declare interface ShDeclClauseNode {
+    readonly type: 'DeclClause';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly args: readonly ShAssignNode[];
+    readonly variant?: ShLitNode;
+}
+
+/**
+ * Shell dialect (mvdan/sh `LangVariant`) to parse against. Mapped to
+ * `LangVariant` by string name via `LangVariant.Set()` — never by numeric
+ * value, since the bit-flag encoding of `LangVariant` is not a stable
+ * contract across mvdan/sh versions. See design/ARCHITECTURE.md, "Parse
+ * errors and dialects".
+ *
+ * @public
+ */
+export declare type ShellDialect = 'bash' | 'posix' | 'mksh' | 'bats' | 'zsh';
+
+/**
+ * mvdan/sh's `syntax.Expansion`, normalized.
+ *
+ * @public
+ */
+declare interface ShExpansionNode {
+    readonly type: 'Expansion';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly word?: ShWordNode;
+}
+
+/**
+ * mvdan/sh's `syntax.ExtGlob`, normalized.
+ *
+ * @public
+ */
+declare interface ShExtGlobNode {
+    readonly type: 'ExtGlob';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly pattern?: ShLitNode;
+}
+
+/**
+ * The root node of a parsed shell script.
+ *
+ * @public
+ */
+export declare interface ShFile extends ShNode {
+    readonly type: 'File';
+    readonly stmts: readonly ShNode[];
+}
+
+/**
+ * mvdan/sh's `syntax.File`, normalized.
+ *
+ * @public
+ */
+declare interface ShFileNode {
+    readonly type: 'File';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly last: readonly ShCommentNode[];
+    readonly stmts: readonly ShStmtNode[];
+}
+
+/**
+ * mvdan/sh's `syntax.FlagsArithm`, normalized.
+ *
+ * @public
+ */
+declare interface ShFlagsArithmNode {
+    readonly type: 'FlagsArithm';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly flags?: ShLitNode;
+    readonly x?: ShArithmExprNode;
+}
+
+/**
+ * mvdan/sh's `syntax.ForClause`, normalized.
+ *
+ * @public
+ */
+declare interface ShForClauseNode {
+    readonly type: 'ForClause';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly do: readonly ShStmtNode[];
+    readonly dolast: readonly ShCommentNode[];
+    readonly loop?: ShLoopNode;
+}
+
+/**
+ * mvdan/sh's `syntax.FuncDecl`, normalized.
+ *
+ * @public
+ */
+declare interface ShFuncDeclNode {
+    readonly type: 'FuncDecl';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly body?: ShStmtNode;
+    readonly name?: ShLitNode;
+    readonly names: readonly ShLitNode[];
+}
+
+/**
+ * mvdan/sh's `syntax.IfClause`, normalized.
+ *
+ * @public
+ */
+declare interface ShIfClauseNode {
+    readonly type: 'IfClause';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly cond: readonly ShStmtNode[];
+    readonly condlast: readonly ShCommentNode[];
+    readonly else?: ShIfClauseNode;
+    readonly last: readonly ShCommentNode[];
+    readonly then: readonly ShStmtNode[];
+    readonly thenlast: readonly ShCommentNode[];
+}
+
+/**
+ * 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 ShInternalError extends ShAstError {
+    readonly code = "SH_AST_INTERNAL";
+    constructor(message: string);
+}
+
+/**
+ * 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 ShAstError {
+    readonly code = "SH_AST_INVALID_DIALECT";
+    /** The rejected dialect value, exactly as passed to {@link parseSync}. */
+    readonly dialect: string;
+    constructor(dialect: string, supportedDialects: readonly ShellDialect[]);
+}
+
+/**
+ * mvdan/sh's `syntax.LetClause`, normalized.
+ *
+ * @public
+ */
+declare interface ShLetClauseNode {
+    readonly type: 'LetClause';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly exprs: readonly ShArithmExprNode[];
+}
+
+/**
+ * mvdan/sh's `syntax.Lit`, normalized.
+ *
+ * @public
+ */
+declare interface ShLitNode {
+    readonly type: 'Lit';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+}
+
+/**
+ * The union of concrete node types mvdan/sh's `syntax.Loop` interface can
+ * hold.
+ *
+ * @public
+ */
+declare type ShLoopNode = ShCStyleLoopNode | ShWordIterNode;
+
+/**
+ * A normalized AST node produced by {@link sh-ast#parseSync | parseSync}.
+ *
+ * `range` and `loc` are expressed in UTF-16 code units, so
+ * `code.slice(node.range[0], node.range[1])` reproduces the node's exact
+ * source text — even though mvdan/sh itself reports byte offsets and
+ * byte-counting columns internally (see design/ARCHITECTURE.md's
+ * "Serialization contract"). Every other field copied over from mvdan/sh's
+ * typedjson tree keeps its original value but with the field name
+ * lowercased (`Stmts` becomes `stmts`, `CondLast` becomes `condlast`, etc.).
+ *
+ * Also re-exported from `sh-ast/analyze` (see #23) — the subpath's public
+ * surface consumes and exposes `ShNode`, so a consumer can reference the type
+ * without also importing from the root `sh-ast` entry point.
+ *
+ * @public
+ */
+export declare interface ShNode {
+    readonly type: string;
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: Position;
+        readonly end: Position;
+    };
+    [field: string]: unknown;
+}
+
+export declare namespace ShNodes {
+    export {
+        ShArithmCmdNode,
+        ShArithmExpNode,
+        ShArrayElemNode,
+        ShArrayExprNode,
+        ShAssignNode,
+        ShBinaryArithmNode,
+        ShBinaryCmdNode,
+        ShBinaryTestNode,
+        ShBlockNode,
+        ShBraceExpNode,
+        ShCStyleLoopNode,
+        ShCallExprNode,
+        ShCaseClauseNode,
+        ShCaseItemNode,
+        ShCmdSubstNode,
+        ShCommentNode,
+        ShCoprocClauseNode,
+        ShDblQuotedNode,
+        ShDeclClauseNode,
+        ShExpansionNode,
+        ShExtGlobNode,
+        ShFileNode,
+        ShFlagsArithmNode,
+        ShForClauseNode,
+        ShFuncDeclNode,
+        ShIfClauseNode,
+        ShLetClauseNode,
+        ShLitNode,
+        ShParamExpNode,
+        ShParenArithmNode,
+        ShParenTestNode,
+        ShProcSubstNode,
+        ShRedirectNode,
+        ShReplaceNode,
+        ShSglQuotedNode,
+        ShSliceNode,
+        ShStmtNode,
+        ShSubshellNode,
+        ShTestClauseNode,
+        ShTestDeclNode,
+        ShTimeClauseNode,
+        ShUnaryArithmNode,
+        ShUnaryTestNode,
+        ShWhileClauseNode,
+        ShWordNode,
+        ShWordIterNode,
+        ShArithmExprNode,
+        ShCommandNode,
+        ShLoopNode,
+        ShTestExprNode,
+        ShWordPartNode,
+        ShAnyNode,
+        ShNodeTypeName
+    }
+}
+
+/**
+ * Every normalized node `type` string this bridge can produce.
+ *
+ * @public
+ */
+declare type ShNodeTypeName =
+| 'ArithmCmd'
+| 'ArithmExp'
+| 'ArrayElem'
+| 'ArrayExpr'
+| 'Assign'
+| 'BinaryArithm'
+| 'BinaryCmd'
+| 'BinaryTest'
+| 'Block'
+| 'BraceExp'
+| 'CStyleLoop'
+| 'CallExpr'
+| 'CaseClause'
+| 'CaseItem'
+| 'CmdSubst'
+| 'Comment'
+| 'CoprocClause'
+| 'DblQuoted'
+| 'DeclClause'
+| 'Expansion'
+| 'ExtGlob'
+| 'File'
+| 'FlagsArithm'
+| 'ForClause'
+| 'FuncDecl'
+| 'IfClause'
+| 'LetClause'
+| 'Lit'
+| 'ParamExp'
+| 'ParenArithm'
+| 'ParenTest'
+| 'ProcSubst'
+| 'Redirect'
+| 'Replace'
+| 'SglQuoted'
+| 'Slice'
+| 'Stmt'
+| 'Subshell'
+| 'TestClause'
+| 'TestDecl'
+| 'TimeClause'
+| 'UnaryArithm'
+| 'UnaryTest'
+| 'WhileClause'
+| 'Word'
+| 'WordIter';
+
+/**
+ * mvdan/sh's `syntax.ParamExp`, normalized.
+ *
+ * @public
+ */
+declare interface ShParamExpNode {
+    readonly type: 'ParamExp';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly exp?: ShExpansionNode;
+    readonly flags?: ShLitNode;
+    readonly index?: ShArithmExprNode;
+    readonly modifiers: readonly ShLitNode[];
+    readonly nestedparam?: ShWordPartNode;
+    readonly param?: ShLitNode;
+    readonly repl?: ShReplaceNode;
+    readonly slice?: ShSliceNode;
+}
+
+/**
+ * mvdan/sh's `syntax.ParenArithm`, normalized.
+ *
+ * @public
+ */
+declare interface ShParenArithmNode {
+    readonly type: 'ParenArithm';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly x?: ShArithmExprNode;
+}
+
+/**
+ * mvdan/sh's `syntax.ParenTest`, normalized.
+ *
+ * @public
+ */
+declare interface ShParenTestNode {
+    readonly type: 'ParenTest';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly x?: ShTestExprNode;
+}
+
+/**
+ * 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 ShAstError {
+    readonly code = "SH_AST_PARSE_ERROR";
+    readonly line: number;
+    readonly column: number;
+    readonly filename: string;
+    constructor(message: string, info: ShParseErrorInfo);
+}
+
+/**
+ * Position info attached to a {@link ShParseError}.
+ *
+ * @public
+ */
+export declare 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 `text`'s conservatively estimated
+ * structural nesting depth (subshells, command/process substitutions,
+ * `if`/`case`/loop/function bodies, `{ }` blocks, backtick or `$(...)`
+ * command substitution, `$((...))` arithmetic — see
+ * `parse-depth-guard.ts`'s module doc for the exact heuristic) exceeds the
+ * limit `parseSync` accepts. Thrown *before* `text` is ever handed to the
+ * WASM shim: mvdan/sh's own recursive-descent parser has no recovery path
+ * for exhausting its call stack on pathologically deep input (a stack
+ * overflow deep inside the shared WASM instance is not a normal, catchable
+ * JS error the way a parse syntax error is), so this bridge estimates the
+ * risk up front and fails closed with a typed error instead of ever making
+ * that call — the shared WASM instance is therefore never put at risk of
+ * wedging on this class of input; a `parseSync` call right after catching
+ * this error works exactly as it would if this input had never been
+ * attempted.
+ *
+ * Like {@link ShAnalyzeMaxDepthError}, this is pathological-input
+ * protection, not a normal-usage ceiling: a legitimately deep (but
+ * realistic) script parses fine. The estimate can *over*-count relative to
+ * mvdan/sh's real grammar (rejecting some legitimate-but-unusually-deep
+ * input) but is designed to never *under*-count relative to it — see
+ * `parse-depth-guard.ts` for the documented false-positive sources this
+ * trades off against ever letting a genuinely crash-inducing input
+ * through.
+ *
+ * @public
+ */
+export declare class ShParseMaxDepthError extends ShAstError {
+    readonly code = "SH_AST_PARSE_MAX_DEPTH";
+    /** The maximum structural nesting depth `parseSync` accepts; the same value every time (not caller-configurable). */
+    readonly maxDepth: number;
+    /**
+     * The conservatively estimated nesting depth that tripped the guard.
+     * Not necessarily `text`'s "true" nesting depth under a real parse — see
+     * {@link ShParseMaxDepthError}'s doc comment — only ever `> maxDepth`.
+     */
+    readonly estimatedDepth: number;
+    constructor(maxDepth: number, estimatedDepth: number);
+}
+
+/**
+ * mvdan/sh's `syntax.ProcSubst`, normalized.
+ *
+ * @public
+ */
+declare interface ShProcSubstNode {
+    readonly type: 'ProcSubst';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly last: readonly ShCommentNode[];
+    readonly stmts: readonly ShStmtNode[];
+}
+
+/**
+ * mvdan/sh's `syntax.Redirect`, normalized.
+ *
+ * @public
+ */
+declare interface ShRedirectNode {
+    readonly type: 'Redirect';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly hdoc?: ShWordNode;
+    readonly n?: ShLitNode;
+    readonly word?: ShWordNode;
+}
+
+/**
+ * mvdan/sh's `syntax.Replace`, normalized.
+ *
+ * @public
+ */
+declare interface ShReplaceNode {
+    readonly type: 'Replace';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly orig?: ShWordNode;
+    readonly with?: ShWordNode;
+}
+
+/**
+ * mvdan/sh's `syntax.SglQuoted`, normalized.
+ *
+ * @public
+ */
+declare interface ShSglQuotedNode {
+    readonly type: 'SglQuoted';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+}
+
+/**
+ * mvdan/sh's `syntax.Slice`, normalized.
+ *
+ * @public
+ */
+declare interface ShSliceNode {
+    readonly type: 'Slice';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly length?: ShArithmExprNode;
+    readonly offset?: ShArithmExprNode;
+}
+
+/**
+ * mvdan/sh's `syntax.Stmt`, normalized.
+ *
+ * @public
+ */
+declare interface ShStmtNode {
+    readonly type: 'Stmt';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly cmd?: ShCommandNode;
+    readonly comments: readonly ShCommentNode[];
+    readonly redirs: readonly ShRedirectNode[];
+}
+
+/**
+ * mvdan/sh's `syntax.Subshell`, normalized.
+ *
+ * @public
+ */
+declare interface ShSubshellNode {
+    readonly type: 'Subshell';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly last: readonly ShCommentNode[];
+    readonly stmts: readonly ShStmtNode[];
+}
+
+/**
+ * mvdan/sh's `syntax.TestClause`, normalized.
+ *
+ * @public
+ */
+declare interface ShTestClauseNode {
+    readonly type: 'TestClause';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly x?: ShTestExprNode;
+}
+
+/**
+ * mvdan/sh's `syntax.TestDecl`, normalized.
+ *
+ * @public
+ */
+declare interface ShTestDeclNode {
+    readonly type: 'TestDecl';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly body?: ShStmtNode;
+    readonly description?: ShWordNode;
+}
+
+/**
+ * The union of concrete node types mvdan/sh's `syntax.TestExpr` interface can
+ * hold.
+ *
+ * @public
+ */
+declare type ShTestExprNode = ShBinaryTestNode | ShParenTestNode | ShUnaryTestNode | ShWordNode;
+
+/**
+ * mvdan/sh's `syntax.TimeClause`, normalized.
+ *
+ * @public
+ */
+declare interface ShTimeClauseNode {
+    readonly type: 'TimeClause';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly stmt?: ShStmtNode;
+}
+
+/**
+ * mvdan/sh's `syntax.UnaryArithm`, normalized.
+ *
+ * @public
+ */
+declare interface ShUnaryArithmNode {
+    readonly type: 'UnaryArithm';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly x?: ShArithmExprNode;
+}
+
+/**
+ * mvdan/sh's `syntax.UnaryTest`, normalized.
+ *
+ * @public
+ */
+declare interface ShUnaryTestNode {
+    readonly type: 'UnaryTest';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly x?: ShTestExprNode;
+}
+
+/**
+ * mvdan/sh's `syntax.WhileClause`, normalized.
+ *
+ * @public
+ */
+declare interface ShWhileClauseNode {
+    readonly type: 'WhileClause';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly cond: readonly ShStmtNode[];
+    readonly condlast: readonly ShCommentNode[];
+    readonly do: readonly ShStmtNode[];
+    readonly dolast: readonly ShCommentNode[];
+}
+
+/**
+ * mvdan/sh's `syntax.WordIter`, normalized.
+ *
+ * @public
+ */
+declare interface ShWordIterNode {
+    readonly type: 'WordIter';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly items: readonly ShWordNode[];
+    readonly name?: ShLitNode;
+}
+
+/**
+ * mvdan/sh's `syntax.Word`, normalized.
+ *
+ * @public
+ */
+declare interface ShWordNode {
+    readonly type: 'Word';
+    readonly range: readonly [number, number];
+    readonly loc: {
+        readonly start: { readonly line: number; readonly column: number };
+        readonly end: { readonly line: number; readonly column: number };
+    };
+    [field: string]: unknown;
+    readonly parts: readonly ShWordPartNode[];
+}
+
+/**
+ * The union of concrete node types mvdan/sh's `syntax.WordPart` interface can
+ * hold.
+ *
+ * @public
+ */
+declare type ShWordPartNode =
+| ShArithmExpNode
+| ShBraceExpNode
+| ShCmdSubstNode
+| ShDblQuotedNode
+| ShExtGlobNode
+| ShLitNode
+| ShParamExpNode
+| ShProcSubstNode
+| ShSglQuotedNode;
+
+/**
+ * Maps each normalized node `type` to the field names (lowercased, matching
+ * the normalized node shape produced by `normalize`) whose values hold child
+ * nodes.
+ *
+ * Generated from mvdan/sh's `syntax` package struct definitions by
+ * `tools/gen-visitor-keys` (see design/ARCHITECTURE.md, "The schema table is
+ * generated, not hand-written") — this module only re-exports the generated
+ * table under the public name, frozen. {@link walk} does not depend on this
+ * table for correctness — it discovers children structurally — so any gap
+ * here (there shouldn't be one; the kitchen-sink golden test guards it)
+ * affects only external consumers that choose to traverse via this table.
+ *
+ * Frozen (including each per-type field-name array) so immutability of this
+ * shared, module-scoped table is a contract, not just a convention any
+ * importer happens to honor.
+ *
+ * @public
+ */
+export declare const visitorKeys: Readonly<Record<string, readonly string[]>>;
+
+/**
+ * Visits every node in a normalized tree, pre-order (parent before
+ * children), starting at `node`.
+ *
+ * Children are discovered structurally: any field on a visited node whose
+ * value is itself a normalized node (or an array of normalized nodes) is
+ * treated as a child. This is deliberately not driven off {@link
+ * visitorKeys} — the spike's hand-written visitor-keys table missed
+ * `DeclClause.Variant` (see design/ARCHITECTURE.md) and silently
+ * under-walked the tree, and `visitorKeys` remains hand-maintained pending a
+ * schema generator (tracked separately). Walking structurally means this
+ * function's completeness never depends on that table's accuracy.
+ *
+ * @public
+ */
+export declare function walk(node: ShNode, visit: (node: ShNode, parent: ShNode | null) => void): void;
+
+export { }