just-bash 2.5.4 → 2.6.0

package/dist/interpreter/simple-command-assignments.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Simple Command Assignment Handling
+ *
+ * Handles variable assignments in simple commands:
+ * - Array assignments: VAR=(a b c)
+ * - Subscript assignments: VAR[idx]=value
+ * - Scalar assignments with nameref resolution
+ */
+import type { SimpleCommandNode } from "../ast/types.js";
+import type { ExecResult } from "../types.js";
+import type { InterpreterContext } from "./types.js";
+/**
+ * Result of processing assignments in a simple command
+ */
+export interface AssignmentResult {
+    /** Whether to continue to the next statement (skip command execution) */
+    continueToNext: boolean;
+    /** Accumulated xtrace output for assignments */
+    xtraceOutput: string;
+    /** Temporary assignments for prefix bindings (FOO=bar cmd) */
+    tempAssignments: Record<string, string | undefined>;
+    /** Error result if assignment failed */
+    error?: ExecResult;
+}
+/**
+ * Process all assignments in a simple command.
+ * Returns assignment results including temp bindings and any errors.
+ */
+export declare function processAssignments(ctx: InterpreterContext, node: SimpleCommandNode): Promise<AssignmentResult>;

package/dist/interpreter/subshell-group.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Subshell, Group, and Script Execution
+ *
+ * Handles execution of subshells (...), groups { ...; }, and user scripts
+ */
+import type { GroupNode, ScriptNode, StatementNode, SubshellNode } from "../ast/types.js";
+import type { ExecResult } from "../types.js";
+import type { InterpreterContext } from "./types.js";
+/**
+ * Type for executeStatement callback
+ */
+export type ExecuteStatementFn = (stmt: StatementNode) => Promise<ExecResult>;
+/**
+ * Execute a subshell node (...).
+ * Creates an isolated execution environment that doesn't affect the parent.
+ */
+export declare function executeSubshell(ctx: InterpreterContext, node: SubshellNode, stdin: string, executeStatement: ExecuteStatementFn): Promise<ExecResult>;
+/**
+ * Execute a group node { ...; }.
+ * Runs commands in the current execution environment.
+ */
+export declare function executeGroup(ctx: InterpreterContext, node: GroupNode, stdin: string, executeStatement: ExecuteStatementFn): Promise<ExecResult>;
+/**
+ * Type for executeScript callback
+ */
+export type ExecuteScriptFn = (node: ScriptNode) => Promise<ExecResult>;
+/**
+ * Execute a user script file found in PATH.
+ * This handles executable files that don't have registered command handlers.
+ * The script runs in a subshell-like environment with its own positional parameters.
+ */
+export declare function executeUserScript(ctx: InterpreterContext, scriptPath: string, args: string[], stdin: string, executeScript: ExecuteScriptFn): Promise<ExecResult>;

package/dist/interpreter/type-command.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Type Command Implementation
+ *
+ * Implements the `type` builtin command and related functionality:
+ * - type [-afptP] name...
+ * - command -v/-V name...
+ *
+ * Also includes helpers for function source serialization.
+ */
+import type { IFileSystem } from "../fs/interface.js";
+import type { CommandRegistry, ExecResult } from "../types.js";
+import type { InterpreterState } from "./types.js";
+/**
+ * Context needed for type command operations
+ */
+export interface TypeCommandContext {
+    state: InterpreterState;
+    fs: IFileSystem;
+    commands: CommandRegistry;
+}
+/**
+ * Handle the `type` builtin command.
+ * type [-afptP] name...
+ */
+export declare function handleType(ctx: TypeCommandContext, args: string[], findFirstInPath: (name: string) => Promise<string | null>, findCommandInPath: (name: string) => Promise<string[]>): Promise<ExecResult>;
+/**
+ * Handle `command -v` and `command -V` flags
+ * -v: print the name or path of the command (simple output)
+ * -V: print a description like `type` does (verbose output)
+ */
+export declare function handleCommandV(ctx: TypeCommandContext, names: string[], _showPath: boolean, verboseDescribe: boolean): Promise<ExecResult>;
+/**
+ * Find the first occurrence of a command in PATH.
+ * Returns the full path if found, null otherwise.
+ * Only returns executable files, not directories.
+ */
+export declare function findFirstInPath(ctx: TypeCommandContext, name: string): Promise<string | null>;

package/dist/interpreter/types.d.ts

@@ -6,6 +6,23 @@ import type { IFileSystem } from "../fs/interface.js";
 import type { ExecutionLimits } from "../limits.js";
 import type { SecureFetch } from "../network/index.js";
 import type { CommandRegistry, ExecResult, TraceCallback } from "../types.js";
+/**
+ * Completion specification for a command, set by the `complete` builtin.
+ */
+export interface CompletionSpec {
+    /** Word list for -W option */
+    wordlist?: string;
+    /** Function name for -F option */
+    function?: string;
+    /** Command to run for -C option */
+    command?: string;
+    /** Completion options (nospace, filenames, etc.) */
+    options?: string[];
+    /** Actions to perform (from -A option) */
+    actions?: string[];
+    /** Whether this is a default completion (-D) */
+    isDefault?: boolean;
+}
 export interface ShellOptions {
     /** set -e: Exit immediately if a command exits with non-zero status */
     errexit: boolean;
@@ -17,44 +34,261 @@ export interface ShellOptions {
     xtrace: boolean;
     /** set -v: Print shell input lines as they are read (verbose) */
     verbose: boolean;
+    /** set -o posix: POSIX mode for stricter compliance */
+    posix: boolean;
+    /** set -a: Export all variables */
+    allexport: boolean;
+    /** set -C: Prevent overwriting files with redirection */
+    noclobber: boolean;
+    /** set -f: Disable filename expansion (globbing) */
+    noglob: boolean;
+    /** set -n: Read commands but do not execute them (syntax check mode) */
+    noexec: boolean;
+    /** set -o vi: Use vi-style line editing (mutually exclusive with emacs) */
+    vi: boolean;
+    /** set -o emacs: Use emacs-style line editing (mutually exclusive with vi) */
+    emacs: boolean;
 }
-export interface InterpreterState {
-    env: Record<string, string>;
-    cwd: string;
-    previousDir: string;
-    functions: Map<string, FunctionDefNode>;
+export interface ShoptOptions {
+    /** shopt -s extglob: Enable extended globbing patterns @(), *(), +(), ?(), !() */
+    extglob: boolean;
+    /** shopt -s dotglob: Include dotfiles in glob expansion */
+    dotglob: boolean;
+    /** shopt -s nullglob: Return empty for non-matching globs instead of literal pattern */
+    nullglob: boolean;
+    /** shopt -s failglob: Fail if glob pattern has no matches */
+    failglob: boolean;
+    /** shopt -s globstar: Enable ** recursive glob patterns */
+    globstar: boolean;
+    /** shopt -s globskipdots: Skip . and .. in glob patterns (default: true in bash >=5.2) */
+    globskipdots: boolean;
+    /** shopt -s nocaseglob: Case-insensitive glob matching */
+    nocaseglob: boolean;
+    /** shopt -s nocasematch: Case-insensitive pattern matching in [[ ]] and case */
+    nocasematch: boolean;
+    /** shopt -s expand_aliases: Enable alias expansion */
+    expand_aliases: boolean;
+    /** shopt -s lastpipe: Run last command of pipeline in current shell context */
+    lastpipe: boolean;
+    /** shopt -s xpg_echo: Make echo interpret backslash escapes by default (like echo -e) */
+    xpg_echo: boolean;
+}
+/**
+ * Tracks variable type attributes (declare -i, -l, -u, -n, -a, -A, etc.)
+ * and export status. These affect how variables are read, written, and expanded.
+ */
+export interface VariableAttributeState {
+    /** Set of variable names that are readonly */
+    readonlyVars?: Set<string>;
+    /** Set of variable names that are associative arrays */
+    associativeArrays?: Set<string>;
+    /** Set of variable names that are namerefs (declare -n) */
+    namerefs?: Set<string>;
+    /**
+     * Set of nameref variable names that were "bound" to valid targets at creation time.
+     * A bound nameref will always resolve through to its target, even if the target
+     * is later unset. An unbound nameref (target didn't exist at creation) acts like
+     * a regular variable, returning its raw value.
+     */
+    boundNamerefs?: Set<string>;
+    /**
+     * Set of nameref variable names that were created with an invalid target.
+     * Invalid namerefs always read/write their value directly, never resolving.
+     * For example, after `ref=1; typeset -n ref`, ref has an invalid target "1".
+     */
+    invalidNamerefs?: Set<string>;
+    /** Set of variable names that have integer attribute (declare -i) */
+    integerVars?: Set<string>;
+    /** Set of variable names that have lowercase attribute (declare -l) */
+    lowercaseVars?: Set<string>;
+    /** Set of variable names that have uppercase attribute (declare -u) */
+    uppercaseVars?: Set<string>;
+    /** Set of exported variable names */
+    exportedVars?: Set<string>;
+    /** Set of temporarily exported variable names (for prefix assignments like FOO=bar cmd) */
+    tempExportedVars?: Set<string>;
+    /**
+     * Stack of sets tracking variables exported within each local scope.
+     * When a function returns and a local scope is popped, if a variable was
+     * exported only in that scope (not before entering), the export attribute
+     * should be removed. This enables bash's scoped export behavior where
+     * `local V=x; export V` only exports the local, not the global.
+     */
+    localExportedVars?: Set<string>[];
+    /** Set of variable names that have been declared but not assigned a value */
+    declaredVars?: Set<string>;
+}
+/**
+ * Tracks the complex local variable scoping machinery.
+ * Bash's local variable behavior is intricate: variables are dynamically scoped,
+ * can be declared multiple times in nested contexts, and have different unset
+ * behaviors depending on whether the unset happens in the declaring scope.
+ */
+export interface LocalScopingState {
+    /** Stack of local variable scopes (one Map per function call) */
     localScopes: Map<string, string | undefined>[];
+    /**
+     * Tracks at which call depth each local variable was declared.
+     * Used for bash-specific unset scoping behavior:
+     * - local-unset (same scope): value-unset (clears value, keeps local cell)
+     * - dynamic-unset (different scope): cell-unset (removes local cell, exposes outer value)
+     */
+    localVarDepth?: Map<string, number>;
+    /**
+     * Stack of saved values for each local variable, supporting bash's localvar-nest behavior.
+     * Each entry contains the saved (outer) value and the scope index where it was saved.
+     * This allows multiple nested `local` declarations of the same variable (e.g., in nested evals)
+     * to each have their own cell that can be unset independently.
+     */
+    localVarStack?: Map<string, Array<{
+        value: string | undefined;
+        scopeIndex: number;
+    }>>;
+    /**
+     * Map of variable names to scope index where they were fully unset.
+     * Used to prevent tempenv restoration after all local cells are removed.
+     * Entries are cleared when their scope returns.
+     */
+    fullyUnsetLocals?: Map<string, number>;
+    /**
+     * Stack of temporary environment bindings from prefix assignments (e.g., FOO=bar cmd).
+     * Each entry maps variable names to their saved (underlying) values.
+     * Used for bash-specific unset behavior: when unsetting a variable that has a
+     * tempenv binding, the unset should reveal the underlying value, not completely
+     * remove the variable.
+     */
+    tempEnvBindings?: Map<string, string | undefined>[];
+    /**
+     * Set of tempenv variable names that have been explicitly written to within
+     * the current function context (after the prefix assignment, before local).
+     * Used to distinguish between "fresh" tempenvs (local-unset = value-unset)
+     * and "mutated" tempenvs (local-unset reveals the mutated value).
+     */
+    mutatedTempEnvVars?: Set<string>;
+    /**
+     * Set of tempenv variable names that have been accessed (read or written)
+     * within the current function context. Used to determine if a tempenv was
+     * "observed" before a local declaration.
+     */
+    accessedTempEnvVars?: Set<string>;
+}
+/**
+ * Tracks the function call stack and source file nesting.
+ * This state powers the FUNCNAME, BASH_LINENO, and BASH_SOURCE arrays,
+ * and determines the behavior of `return` in different contexts.
+ */
+export interface CallStackState {
+    /** Function definitions (name -> AST node) */
+    functions: Map<string, FunctionDefNode>;
+    /** Current function call depth (for recursion limits and local scoping) */
     callDepth: number;
     /** Current source script nesting depth (for return in sourced scripts) */
     sourceDepth: number;
-    commandCount: number;
-    lastExitCode: number;
-    /** Last argument of previous command, for $_ expansion */
-    lastArg: string;
-    /** Time when shell started (for $SECONDS) */
-    startTime: number;
-    /** PID of last background job (for $!) */
-    lastBackgroundPid: number;
-    /** Current line number being executed (for $LINENO) */
-    currentLine: number;
-    /** Shell options (set -e, etc.) */
-    options: ShellOptions;
+    /** Stack of call line numbers for BASH_LINENO */
+    callLineStack?: number[];
+    /** Stack of function names for FUNCNAME */
+    funcNameStack?: string[];
+    /** Stack of source files for BASH_SOURCE (tracks where functions were defined) */
+    sourceStack?: string[];
+    /** Current source file context (for function definitions) */
+    currentSource?: string;
+}
+/**
+ * Tracks loop nesting and condition context.
+ * Used to implement break/continue commands and to suppress errexit
+ * in condition contexts (if, while, until, ||, &&).
+ */
+export interface ControlFlowState {
     /** True when executing condition for if/while/until (errexit doesn't apply) */
     inCondition: boolean;
     /** Current loop nesting depth (for break/continue) */
     loopDepth: number;
     /** True if this subshell was spawned from within a loop context (for break/continue to exit subshell) */
     parentHasLoopContext?: boolean;
+    /** True when the last executed statement's exit code is "safe" for errexit purposes
+     *  (e.g., from a &&/|| chain where the failure wasn't the final command) */
+    errexitSafe?: boolean;
+}
+/**
+ * Tracks process IDs, timing, and execution counts.
+ * Powers special variables like $$, $BASHPID, $!, and $SECONDS.
+ */
+export interface ProcessState {
+    /** Total commands executed (for execution limits) */
+    commandCount: number;
+    /** Time when shell started (for $SECONDS) */
+    startTime: number;
+    /** PID of last background job (for $!) */
+    lastBackgroundPid: number;
+    /** Current BASHPID (changes in subshells, unlike $$) */
+    bashPid: number;
+    /** Counter for generating unique virtual PIDs for subshells */
+    nextVirtualPid: number;
+}
+/**
+ * Tracks file descriptors and stdin content for I/O operations.
+ * Used for process substitution, here-documents, and compound command stdin.
+ */
+export interface IOState {
     /** Stdin available for commands in compound commands (groups, subshells, while loops with piped input) */
     groupStdin?: string;
-    /** Set of variable names that are readonly */
-    readonlyVars?: Set<string>;
+    /** File descriptors for process substitution and here-docs */
+    fileDescriptors?: Map<number, string>;
+    /** Next available file descriptor for {varname}>file allocation (starts at 10) */
+    nextFd?: number;
+}
+/**
+ * Captures errors that occur during parameter expansion.
+ * Some expansion errors need to be reported after expansion completes,
+ * with their exit codes and stderr preserved.
+ */
+export interface ExpansionState {
     /** Exit code from expansion errors (arithmetic, etc.) - overrides command exit code */
     expansionExitCode?: number;
     /** Stderr from expansion errors */
     expansionStderr?: string;
-    /** Set of variable names that are associative arrays */
-    associativeArrays?: Set<string>;
+}
+/**
+ * Complete interpreter state for bash script execution.
+ *
+ * This interface is composed from focused sub-interfaces:
+ * - {@link VariableAttributeState} - Variable type attributes (readonly, integer, etc.)
+ * - {@link LocalScopingState} - Local variable scoping machinery
+ * - {@link CallStackState} - Function calls and source file tracking
+ * - {@link ControlFlowState} - Loop nesting and condition context
+ * - {@link ProcessState} - PIDs, timing, execution counts
+ * - {@link IOState} - File descriptors and stdin
+ * - {@link ExpansionState} - Expansion error capture
+ */
+export interface InterpreterState extends VariableAttributeState, LocalScopingState, CallStackState, ControlFlowState, ProcessState, IOState, ExpansionState {
+    /** Environment variables (exported to commands) */
+    env: Record<string, string>;
+    /** Current working directory */
+    cwd: string;
+    /** Previous directory (for `cd -`) */
+    previousDir: string;
+    /** Exit code of last executed command */
+    lastExitCode: number;
+    /** Last argument of previous command, for $_ expansion */
+    lastArg: string;
+    /** Current line number being executed (for $LINENO) */
+    currentLine: number;
+    /** Shell options (set -e, etc.) */
+    options: ShellOptions;
+    /** Shopt options (shopt -s, etc.) */
+    shoptOptions: ShoptOptions;
+    /** Completion specifications set by the `complete` builtin */
+    completionSpecs?: Map<string, CompletionSpec>;
+    /** Directory stack for pushd/popd/dirs */
+    directoryStack?: string[];
+    /** Hash table for PATH command lookup caching */
+    hashTable?: Map<string, string>;
+    /**
+     * Suppress verbose mode output (set -v) when inside command substitutions.
+     * bash only prints verbose output for the main script, not for commands
+     * inside $(...) or backticks.
+     */
+    suppressVerbose?: boolean;
 }
 export interface InterpreterContext {
     state: InterpreterState;

package/dist/parser/arithmetic-parser.d.ts

@@ -10,7 +10,9 @@
  * All functions take a Parser instance as the first argument for shared state access.
  */
 import type { ArithExpr, ArithmeticExpressionNode } from "../ast/types.js";
+import { parseArithNumber } from "./arithmetic-primaries.js";
 import type { Parser } from "./parser.js";
+export { parseArithNumber };
 /**
  * Parse an arithmetic expression string into an AST node
  */
@@ -19,7 +21,3 @@ export declare function parseArithExpr(p: Parser, input: string, pos: number): {
     expr: ArithExpr;
     pos: number;
 };
-/**
- * Parse a number string with various bases (decimal, hex, octal, base#num)
- */
-export declare function parseArithNumber(str: string): number;

package/dist/parser/arithmetic-primaries.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Helper functions for parsing primary arithmetic expressions
+ */
+import type { ArithExpr } from "../ast/types.js";
+import type { Parser } from "./parser.js";
+/**
+ * Skip whitespace in arithmetic expression input.
+ * Also handles line continuations (backslash followed by newline).
+ */
+export declare function skipArithWhitespace(input: string, pos: number): number;
+/**
+ * Assignment operators in arithmetic expressions
+ */
+export declare const ARITH_ASSIGN_OPS: readonly ["=", "+=", "-=", "*=", "/=", "%=", "<<=", ">>=", "&=", "|=", "^="];
+/**
+ * Parse a number string with various bases (decimal, hex, octal, base#num)
+ * Returns NaN for invalid numbers.
+ */
+export declare function parseArithNumber(str: string): number;
+/**
+ * Parse nested arithmetic expression: $((expr))
+ */
+export declare function parseNestedArithmetic(parseArithExpr: (p: Parser, input: string, pos: number) => {
+    expr: ArithExpr;
+    pos: number;
+}, p: Parser, input: string, currentPos: number): {
+    expr: ArithExpr;
+    pos: number;
+} | null;
+/**
+ * Parse ANSI-C quoting: $'...'
+ * Returns the numeric value of the string content
+ */
+export declare function parseAnsiCQuoting(input: string, currentPos: number): {
+    expr: ArithExpr;
+    pos: number;
+} | null;
+/**
+ * Parse localization quoting: $"..."
+ * Returns the numeric value of the string content
+ */
+export declare function parseLocalizationQuoting(input: string, currentPos: number): {
+    expr: ArithExpr;
+    pos: number;
+} | null;

package/dist/parser/compound-parser.d.ts

@@ -5,10 +5,24 @@
  */
 import { type CaseNode, type CStyleForNode, type ForNode, type GroupNode, type IfNode, type SubshellNode, type UntilNode, type WhileNode } from "../ast/types.js";
 import type { Parser } from "./parser.js";
-export declare function parseIf(p: Parser): IfNode;
-export declare function parseFor(p: Parser): ForNode | CStyleForNode;
-export declare function parseWhile(p: Parser): WhileNode;
-export declare function parseUntil(p: Parser): UntilNode;
-export declare function parseCase(p: Parser): CaseNode;
-export declare function parseSubshell(p: Parser): SubshellNode | CStyleForNode;
-export declare function parseGroup(p: Parser): GroupNode;
+export declare function parseIf(p: Parser, options?: {
+    skipRedirections?: boolean;
+}): IfNode;
+export declare function parseFor(p: Parser, options?: {
+    skipRedirections?: boolean;
+}): ForNode | CStyleForNode;
+export declare function parseWhile(p: Parser, options?: {
+    skipRedirections?: boolean;
+}): WhileNode;
+export declare function parseUntil(p: Parser, options?: {
+    skipRedirections?: boolean;
+}): UntilNode;
+export declare function parseCase(p: Parser, options?: {
+    skipRedirections?: boolean;
+}): CaseNode;
+export declare function parseSubshell(p: Parser, options?: {
+    skipRedirections?: boolean;
+}): SubshellNode | CStyleForNode;
+export declare function parseGroup(p: Parser, options?: {
+    skipRedirections?: boolean;
+}): GroupNode;

package/dist/parser/expansion-parser.d.ts

@@ -7,4 +7,10 @@ import { type WordPart } from "../ast/types.js";
 import type { Parser } from "./parser.js";
 export declare function parseWordParts(p: Parser, value: string, quoted?: boolean, singleQuoted?: boolean, isAssignment?: boolean, hereDoc?: boolean, 
 /** When true, single quotes are treated as literal characters, not quote delimiters */
-singleQuotesAreLiteral?: boolean): WordPart[];
+singleQuotesAreLiteral?: boolean, 
+/** When true, brace expansion is disabled (used in [[ ]] conditionals) */
+noBraceExpansion?: boolean, 
+/** When true, all backslash escapes create Escaped nodes (for regex patterns in [[ =~ ]]) */
+regexPattern?: boolean, 
+/** When true, \} is treated as escaped } (used in parameter expansion default values) */
+inParameterExpansion?: boolean): WordPart[];

package/dist/parser/lexer.d.ts

@@ -63,6 +63,7 @@ export declare enum TokenType {
     NAME = "NAME",// Valid variable name
     NUMBER = "NUMBER",// For redirections like 2>&1
     ASSIGNMENT_WORD = "ASSIGNMENT_WORD",// VAR=value
+    FD_VARIABLE = "FD_VARIABLE",// {varname} before redirect operator
     COMMENT = "COMMENT",
     HEREDOC_CONTENT = "HEREDOC_CONTENT"
 }
@@ -78,6 +79,14 @@ export interface Token {
     quoted?: boolean;
     singleQuoted?: boolean;
 }
+/**
+ * Error thrown when the lexer encounters invalid input
+ */
+export declare class LexerError extends Error {
+    line: number;
+    column: number;
+    constructor(message: string, line: number, column: number);
+}
 /**
  * Lexer class
  */
@@ -88,6 +97,7 @@ export declare class Lexer {
     private column;
     private tokens;
     private pendingHeredocs;
+    private dparenDepth;
     constructor(input: string);
     /**
      * Tokenize the entire input
@@ -95,6 +105,13 @@ export declare class Lexer {
     tokenize(): Token[];
     private skipWhitespace;
     private nextToken;
+    /**
+     * Look ahead from position after (( to determine if this is nested subshells
+     * like ((cmd) || (cmd2)) rather than arithmetic like ((1+2)).
+     *
+     * Returns true if it looks like nested subshells (command invocation).
+     */
+    private looksLikeNestedSubshells;
     private makeToken;
     private readComment;
     private readWord;
@@ -132,4 +149,44 @@ export declare class Lexer {
      * This is used when {} contains something but it's not a valid brace expansion.
      */
     private scanLiteralBraceWord;
+    /**
+     * Scan an extglob pattern starting at the opening parenthesis.
+     * Extglob patterns are: @(...), *(...), +(...), ?(...), !(...)
+     * The operator (@, *, +, ?, !) is already consumed; we start at the (.
+     * Returns the content including parentheses, or null if not a valid extglob.
+     */
+    private scanExtglobPattern;
+    /**
+     * Scan for FD variable syntax: {varname} immediately followed by a redirect operator.
+     * This is the bash 4.1+ feature where {fd}>file allocates an FD and stores it in variable.
+     * Returns the variable name and end position if found, null otherwise.
+     *
+     * Valid patterns:
+     * - {varname}>file, {varname}>>file, {varname}>|file
+     * - {varname}<file, {varname}<<word, {varname}<<<word
+     * - {varname}<>file
+     * - {varname}>&N, {varname}<&N
+     * - {varname}>&-, {varname}<&- (close FD)
+     */
+    private scanFdVariable;
+    /**
+     * Scan ahead from a $(( position to determine if it should be treated as
+     * $( ( subshell ) ) instead of $(( arithmetic )).
+     * This handles cases like:
+     *   echo $(( echo 1
+     *   echo 2
+     *   ) )
+     * which should be a command substitution containing a subshell, not arithmetic.
+     *
+     * @param startPos - position at the second ( (i.e., at input[startPos] === "(")
+     * @returns true if this is a subshell (closes with ) )), false if arithmetic (closes with )))
+     */
+    private dollarDparenIsSubshell;
+    /**
+     * Scan ahead from a (( position to determine if it closes with ) ) (nested subshells)
+     * or )) (arithmetic). We need to track paren depth and quotes to find the matching close.
+     * @param startPos - position after the (( (i.e., at the first char of content)
+     * @returns true if it closes with ) ) (space between parens), false otherwise
+     */
+    private dparenClosesWithSpacedParens;
 }

package/dist/parser/parser-substitution.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Command and Arithmetic Substitution Parsing Helpers
+ *
+ * Contains pure string analysis functions and substitution parsing utilities
+ * extracted from the main parser.
+ */
+import { type CommandSubstitutionPart, type ScriptNode } from "../ast/types.js";
+/**
+ * Type for a parser factory function that creates new parser instances.
+ * Used to avoid circular dependencies.
+ */
+export type ParserFactory = () => {
+    parse(input: string): ScriptNode;
+};
+/**
+ * Type for an error reporting function.
+ */
+export type ErrorFn = (message: string) => never;
+/**
+ * Check if $(( at position `start` in `value` is a command substitution with nested
+ * subshell rather than arithmetic expansion. This uses similar logic to the lexer's
+ * dparenClosesWithSpacedParens but operates on a string within a word/expansion.
+ *
+ * The key heuristics are:
+ * 1. If it closes with `) )` (separated by whitespace or content), it's a subshell
+ * 2. If at depth 1 we see `||`, `&&`, or single `|`, it's a command context
+ * 3. If it closes with `))`, it's arithmetic
+ *
+ * @param value The string containing the expansion
+ * @param start Position of the `$` in `$((` (so `$((` is at start..start+2)
+ * @returns true if this should be parsed as command substitution, false for arithmetic
+ */
+export declare function isDollarDparenSubshell(value: string, start: number): boolean;
+/**
+ * Parse a command substitution starting at the given position.
+ * Handles $(...) syntax with proper depth tracking for nested substitutions.
+ *
+ * @param value The string containing the substitution
+ * @param start Position of the `$` in `$(`
+ * @param createParser Factory function to create a new parser instance
+ * @param error Error reporting function
+ * @returns The parsed command substitution part and the ending index
+ */
+export declare function parseCommandSubstitutionFromString(value: string, start: number, createParser: ParserFactory, error: ErrorFn): {
+    part: CommandSubstitutionPart;
+    endIndex: number;
+};
+/**
+ * Parse a backtick command substitution starting at the given position.
+ * Handles `...` syntax with proper escape processing.
+ *
+ * @param value The string containing the substitution
+ * @param start Position of the opening backtick
+ * @param inDoubleQuotes Whether the backtick is inside double quotes
+ * @param createParser Factory function to create a new parser instance
+ * @param error Error reporting function
+ * @returns The parsed command substitution part and the ending index
+ */
+export declare function parseBacktickSubstitutionFromString(value: string, start: number, inDoubleQuotes: boolean, createParser: ParserFactory, error: ErrorFn): {
+    part: CommandSubstitutionPart;
+    endIndex: number;
+};