just-bash 2.5.4 → 2.6.0

package/dist/interpreter/expansion/array-pattern-ops.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Array Pattern Operations
+ *
+ * Handles pattern replacement and pattern removal for array expansions:
+ * - "${arr[@]/pattern/replacement}" - pattern replacement
+ * - "${arr[@]#pattern}" - prefix removal
+ * - "${arr[@]%pattern}" - suffix removal
+ */
+import type { WordPart } from "../../ast/types.js";
+import type { InterpreterContext } from "../types.js";
+import type { ArrayExpansionResult, ExpandPartFn, ExpandWordPartsAsyncFn } from "./array-word-expansion.js";
+/**
+ * Handle "${arr[@]/pattern/replacement}" and "${arr[*]/pattern/replacement}"
+ * Returns null if this handler doesn't apply.
+ */
+export declare function handleArrayPatternReplacement(ctx: InterpreterContext, wordParts: WordPart[], expandWordPartsAsync: ExpandWordPartsAsyncFn, expandPart: ExpandPartFn): Promise<ArrayExpansionResult>;
+/**
+ * Handle "${arr[@]#pattern}" and "${arr[*]#pattern}" - array pattern removal
+ * Returns null if this handler doesn't apply.
+ */
+export declare function handleArrayPatternRemoval(ctx: InterpreterContext, wordParts: WordPart[], expandWordPartsAsync: ExpandWordPartsAsyncFn, expandPart: ExpandPartFn): Promise<ArrayExpansionResult>;

package/dist/interpreter/expansion/array-prefix-suffix.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Array Expansion with Prefix/Suffix Handlers
+ *
+ * Handles array expansions that have adjacent text in double quotes:
+ * - "${prefix}${arr[@]#pattern}${suffix}" - pattern removal with prefix/suffix
+ * - "${prefix}${arr[@]/pattern/replacement}${suffix}" - pattern replacement with prefix/suffix
+ * - "${prefix}${arr[@]}${suffix}" - simple array expansion with prefix/suffix
+ * - "${arr[@]:-${default[@]}}" - array default/alternative values
+ */
+import type { WordPart } from "../../ast/types.js";
+import type { InterpreterContext } from "../types.js";
+/**
+ * Result type for array expansion handlers.
+ * `null` means the handler doesn't apply to this case.
+ */
+export type ArrayExpansionResult = {
+    values: string[];
+    quoted: boolean;
+} | null;
+/**
+ * Type for expandPart function reference
+ */
+export type ExpandPartFn = (ctx: InterpreterContext, part: WordPart) => Promise<string>;
+/**
+ * Type for expandWordPartsAsync function reference
+ */
+export type ExpandWordPartsAsyncFn = (ctx: InterpreterContext, parts: WordPart[]) => Promise<string>;
+/**
+ * Handle "${arr[@]:-${default[@]}}", "${arr[@]:+${alt[@]}}", and "${arr[@]:=default}"
+ * Also handles "${var:-${default[@]}}" where var is a scalar variable.
+ * When the default value contains an array expansion, each element should become a separate word.
+ */
+export declare function handleArrayDefaultValue(ctx: InterpreterContext, wordParts: WordPart[]): Promise<ArrayExpansionResult>;
+/**
+ * Handle "${prefix}${arr[@]#pattern}${suffix}" and "${prefix}${arr[@]/pat/rep}${suffix}"
+ * Array pattern operations with adjacent text in double quotes.
+ * Each array element has the pattern applied, then becomes a separate word
+ * with prefix joined to first and suffix joined to last.
+ */
+export declare function handleArrayPatternWithPrefixSuffix(ctx: InterpreterContext, wordParts: WordPart[], hasArrayAtExpansion: boolean, expandPart: ExpandPartFn, expandWordPartsAsync: ExpandWordPartsAsyncFn): Promise<ArrayExpansionResult>;
+/**
+ * Handle "${prefix}${arr[@]}${suffix}" - array expansion with adjacent text in double quotes.
+ * Each array element becomes a separate word, with prefix joined to first and suffix joined to last.
+ * This is similar to how "$@" works with prefix/suffix.
+ */
+export declare function handleArrayWithPrefixSuffix(ctx: InterpreterContext, wordParts: WordPart[], hasArrayAtExpansion: boolean, expandPart: ExpandPartFn): Promise<ArrayExpansionResult>;

package/dist/interpreter/expansion/array-slice-transform.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Array Slicing and Transform Operations
+ *
+ * Handles array expansion with slicing and transform operators:
+ * - "${arr[@]:offset}" and "${arr[@]:offset:length}" - array slicing
+ * - "${arr[@]@a}", "${arr[@]@P}", "${arr[@]@Q}" - transform operations
+ */
+import type { WordPart } from "../../ast/types.js";
+import type { InterpreterContext } from "../types.js";
+/**
+ * Result type for array expansion handlers.
+ * `null` means the handler doesn't apply to this case.
+ */
+export type ArrayExpansionResult = {
+    values: string[];
+    quoted: boolean;
+} | null;
+import type { ArithExpr } from "../../ast/types.js";
+/**
+ * Type for evaluateArithmetic function
+ */
+export type EvaluateArithmeticFn = (ctx: InterpreterContext, expr: ArithExpr, isExpansionContext?: boolean) => Promise<number>;
+/**
+ * Handle "${arr[@]:offset}" and "${arr[@]:offset:length}" - array slicing with multiple return values
+ * "${arr[@]:n:m}" returns m elements starting from index n as separate words
+ * "${arr[*]:n:m}" returns m elements starting from index n joined with IFS as one word
+ */
+export declare function handleArraySlicing(ctx: InterpreterContext, wordParts: WordPart[], evaluateArithmetic: EvaluateArithmeticFn): Promise<ArrayExpansionResult>;
+/**
+ * Handle "${arr[@]@a}", "${arr[@]@P}", "${arr[@]@Q}" - array Transform operations
+ * "${arr[@]@a}": Return attribute letter for each element (e.g., 'a' for indexed array)
+ * "${arr[@]@P}": Return each element's value (prompt expansion, limited implementation)
+ * "${arr[@]@Q}": Return each element quoted for shell reuse
+ * "${arr[*]@X}": Same as above but joined with IFS as one word
+ */
+export declare function handleArrayTransform(ctx: InterpreterContext, wordParts: WordPart[]): ArrayExpansionResult;

package/dist/interpreter/expansion/array-word-expansion.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Array Word Expansion Handlers
+ *
+ * Handles complex array expansion cases in word expansion:
+ * - "${arr[@]}" and "${arr[*]}" - array element expansion
+ * - "${arr[@]:-default}" - array with defaults
+ * - "${arr[@]:offset:length}" - array slicing
+ * - "${arr[@]/pattern/replacement}" - pattern replacement
+ * - "${arr[@]#pattern}" - pattern removal
+ * - "${arr[@]@op}" - transform operations
+ */
+import type { WordPart } from "../../ast/types.js";
+import type { InterpreterContext } from "../types.js";
+/**
+ * Result type for array expansion handlers.
+ * `null` means the handler doesn't apply to this case.
+ */
+export type ArrayExpansionResult = {
+    values: string[];
+    quoted: boolean;
+} | null;
+/**
+ * Helper type for expandWordPartsAsync function reference
+ */
+export type ExpandWordPartsAsyncFn = (ctx: InterpreterContext, parts: WordPart[]) => Promise<string>;
+/**
+ * Helper type for expandPart function reference
+ */
+export type ExpandPartFn = (ctx: InterpreterContext, part: WordPart) => Promise<string>;
+/**
+ * Handle simple "${arr[@]}" expansion without operations.
+ * Returns each array element as a separate word.
+ */
+export declare function handleSimpleArrayExpansion(ctx: InterpreterContext, wordParts: WordPart[]): ArrayExpansionResult;
+/**
+ * Handle namerefs pointing to array[@] - "${ref}" where ref='arr[@]'
+ * When a nameref points to array[@], expanding "$ref" should produce multiple words
+ */
+export declare function handleNamerefArrayExpansion(ctx: InterpreterContext, wordParts: WordPart[]): ArrayExpansionResult;

package/dist/interpreter/expansion/command-substitution.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Command Substitution Helpers
+ *
+ * Helper functions for handling command substitution patterns.
+ */
+import type { ScriptNode, WordNode } from "../../ast/types.js";
+/**
+ * Check if a command substitution body matches the $(<file) shorthand pattern.
+ * This is a special case where $(< file) is equivalent to $(cat file) but reads
+ * the file directly without spawning a subprocess.
+ *
+ * For this to match, the body must consist of:
+ * - One statement without operators (no && or ||)
+ * - One pipeline with one command
+ * - A SimpleCommand with no name, no args, no assignments
+ * - Exactly one input redirection (<)
+ *
+ * Note: The special $(<file) behavior only works when it's the ONLY element
+ * in the command substitution. $(< file; cmd) or $(cmd; < file) are NOT special.
+ */
+export declare function getFileReadShorthand(body: ScriptNode): {
+    target: WordNode;
+} | null;

package/dist/interpreter/expansion/glob-escape.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Glob Helper Functions
+ *
+ * Functions for handling glob patterns, escaping, and unescaping.
+ */
+/**
+ * Check if a string contains glob patterns, including extglob when enabled.
+ */
+export declare function hasGlobPattern(value: string, extglob: boolean): boolean;
+/**
+ * Unescape a glob pattern - convert escaped glob chars to literal chars.
+ * For example, [\]_ (escaped pattern) becomes [\\]_ (literal string).
+ *
+ * This is used when we need to take a pattern that was built with escaped
+ * glob characters and convert it back to a literal string (e.g., for
+ * no-match fallback when nullglob is off).
+ *
+ * Note: The input is expected to be a pattern string where backslashes escape
+ * the following character. For patterns like "test\\[*" (user input: test\[*)
+ * the output is "\\_" (with processed escapes), not [\\]_ (raw pattern).
+ */
+export declare function unescapeGlobPattern(pattern: string): string;
+/**
+ * Escape glob metacharacters in a string for literal matching.
+ * Includes extglob metacharacters: ( ) |
+ */
+export declare function escapeGlobChars(str: string): string;
+/**
+ * Escape regex metacharacters in a string for literal matching.
+ * Used when quoted patterns are used with =~ operator.
+ */
+export declare function escapeRegexChars(str: string): string;

package/dist/interpreter/expansion/indirect-expansion.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Indirect Array Expansion Handlers
+ *
+ * Handles "${!ref}" style indirect expansions where ref points to an array:
+ * - "${!ref}" where ref='arr[@]' or ref='arr[*]'
+ * - "${!ref:offset}" and "${!ref:offset:length}" - array slicing via indirection
+ * - "${!ref:-default}" and "${!ref:+alternative}" - default/alternative via indirection
+ * - "${ref+${!ref}}" - indirect in alternative value
+ */
+import type { ParameterExpansionPart, WordPart } from "../../ast/types.js";
+import type { InterpreterContext } from "../types.js";
+/**
+ * Result type for indirect expansion handlers.
+ * `null` means the handler doesn't apply to this case.
+ */
+export type IndirectExpansionResult = {
+    values: string[];
+    quoted: boolean;
+} | null;
+/**
+ * Type for expandParameterAsync function reference
+ */
+export type ExpandParameterAsyncFn = (ctx: InterpreterContext, part: ParameterExpansionPart, inDoubleQuotes?: boolean) => Promise<string>;
+/**
+ * Type for expandWordPartsAsync function reference
+ */
+export type ExpandWordPartsAsyncFn = (ctx: InterpreterContext, parts: WordPart[], inDoubleQuotes?: boolean) => Promise<string>;
+/**
+ * Handle "${!ref}" where ref='arr[@]' or ref='arr[*]' - indirect array expansion.
+ * This handles all the inner operation cases as well.
+ */
+export declare function handleIndirectArrayExpansion(ctx: InterpreterContext, wordParts: WordPart[], hasIndirection: boolean, expandParameterAsync: ExpandParameterAsyncFn, expandWordPartsAsync: ExpandWordPartsAsyncFn): Promise<IndirectExpansionResult>;
+/**
+ * Handle ${ref+${!ref}} or ${ref-${!ref}} - indirect in alternative/default value.
+ * This handles patterns like: ${hooksSlice+"${!hooksSlice}"} which should preserve element boundaries
+ */
+export declare function handleIndirectInAlternative(ctx: InterpreterContext, wordParts: WordPart[]): Promise<IndirectExpansionResult>;
+/**
+ * Handle ${!ref+${!ref}} or ${!ref-${!ref}} - indirect with innerOp in alternative/default value.
+ * This handles patterns like: ${!hooksSlice+"${!hooksSlice}"} which should preserve element boundaries
+ */
+export declare function handleIndirectionWithInnerAlternative(ctx: InterpreterContext, wordParts: WordPart[]): Promise<IndirectExpansionResult>;

package/dist/interpreter/expansion/parameter-ops.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Parameter Operation Handlers
+ *
+ * Handles individual parameter expansion operations:
+ * - DefaultValue, AssignDefault, UseAlternative, ErrorIfUnset
+ * - PatternRemoval, PatternReplacement
+ * - Length, Substring
+ * - CaseModification, Transform
+ * - Indirection, ArrayKeys, VarNamePrefix
+ */
+import type { CaseModificationOp, ErrorIfUnsetOp, InnerParameterOperation, ParameterExpansionPart, PatternRemovalOp, PatternReplacementOp, SubstringOp, WordNode, WordPart } from "../../ast/types.js";
+import type { InterpreterContext } from "../types.js";
+/**
+ * Type for expandWordPartsAsync function reference
+ */
+export type ExpandWordPartsAsyncFn = (ctx: InterpreterContext, parts: WordPart[], inDoubleQuotes?: boolean) => Promise<string>;
+/**
+ * Type for expandPart function reference
+ */
+export type ExpandPartFn = (ctx: InterpreterContext, part: WordPart, inDoubleQuotes?: boolean) => Promise<string>;
+/**
+ * Type for self-reference to expandParameterAsync
+ */
+export type ExpandParameterAsyncFn = (ctx: InterpreterContext, part: ParameterExpansionPart, inDoubleQuotes?: boolean) => Promise<string>;
+/**
+ * Context with computed values used across multiple operation handlers
+ */
+export interface ParameterOpContext {
+    value: string;
+    isUnset: boolean;
+    isEmpty: boolean;
+    effectiveValue: string;
+    inDoubleQuotes: boolean;
+}
+/**
+ * Handle DefaultValue operation: ${param:-word}
+ */
+export declare function handleDefaultValue(ctx: InterpreterContext, operation: {
+    word?: WordNode;
+    checkEmpty?: boolean;
+}, opCtx: ParameterOpContext, expandWordPartsAsync: ExpandWordPartsAsyncFn): Promise<string>;
+/**
+ * Handle AssignDefault operation: ${param:=word}
+ */
+export declare function handleAssignDefault(ctx: InterpreterContext, parameter: string, operation: {
+    word?: WordNode;
+    checkEmpty?: boolean;
+}, opCtx: ParameterOpContext, expandWordPartsAsync: ExpandWordPartsAsyncFn): Promise<string>;
+/**
+ * Handle ErrorIfUnset operation: ${param:?word}
+ */
+export declare function handleErrorIfUnset(ctx: InterpreterContext, parameter: string, operation: ErrorIfUnsetOp, opCtx: ParameterOpContext, expandWordPartsAsync: ExpandWordPartsAsyncFn): Promise<string>;
+/**
+ * Handle UseAlternative operation: ${param:+word}
+ */
+export declare function handleUseAlternative(ctx: InterpreterContext, operation: {
+    word?: WordNode;
+    checkEmpty?: boolean;
+}, opCtx: ParameterOpContext, expandWordPartsAsync: ExpandWordPartsAsyncFn): Promise<string>;
+/**
+ * Handle PatternRemoval operation: ${param#pattern}, ${param%pattern}
+ */
+export declare function handlePatternRemoval(ctx: InterpreterContext, value: string, operation: PatternRemovalOp, expandWordPartsAsync: ExpandWordPartsAsyncFn, expandPart: ExpandPartFn): Promise<string>;
+/**
+ * Handle PatternReplacement operation: ${param/pattern/replacement}
+ */
+export declare function handlePatternReplacement(ctx: InterpreterContext, value: string, operation: PatternReplacementOp, expandWordPartsAsync: ExpandWordPartsAsyncFn, expandPart: ExpandPartFn): Promise<string>;
+/**
+ * Handle Length operation: ${#param}
+ */
+export declare function handleLength(ctx: InterpreterContext, parameter: string, value: string): string;
+/**
+ * Handle Substring operation: ${param:offset:length}
+ */
+export declare function handleSubstring(ctx: InterpreterContext, parameter: string, value: string, operation: SubstringOp): Promise<string>;
+/**
+ * Handle CaseModification operation: ${param^pattern}, ${param,pattern}
+ */
+export declare function handleCaseModification(ctx: InterpreterContext, value: string, operation: CaseModificationOp, expandWordPartsAsync: ExpandWordPartsAsyncFn, expandParameterAsync: ExpandParameterAsyncFn): Promise<string>;
+/**
+ * Handle Transform operation: ${param@operator}
+ */
+export declare function handleTransform(ctx: InterpreterContext, parameter: string, value: string, isUnset: boolean, operation: {
+    operator: string;
+}): string;
+/**
+ * Handle Indirection operation: ${!param}
+ */
+export declare function handleIndirection(ctx: InterpreterContext, parameter: string, value: string, isUnset: boolean, operation: {
+    innerOp?: InnerParameterOperation;
+}, expandParameterAsync: ExpandParameterAsyncFn, inDoubleQuotes?: boolean): Promise<string>;
+/**
+ * Handle ArrayKeys operation: ${!arr[@]}, ${!arr[*]}
+ */
+export declare function handleArrayKeys(ctx: InterpreterContext, operation: {
+    array: string;
+    star: boolean;
+}): string;
+/**
+ * Handle VarNamePrefix operation: ${!prefix*}, ${!prefix@}
+ */
+export declare function handleVarNamePrefix(ctx: InterpreterContext, operation: {
+    prefix: string;
+    star: boolean;
+}): string;
+/**
+ * Compute whether the parameter value is "empty" for expansion purposes.
+ * This handles special cases for $*, $@, array[*], and array[@].
+ */
+export declare function computeIsEmpty(ctx: InterpreterContext, parameter: string, value: string, inDoubleQuotes: boolean): {
+    isEmpty: boolean;
+    effectiveValue: string;
+};

package/dist/interpreter/expansion/pattern-expansion.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Pattern Expansion
+ *
+ * Functions for expanding variables within glob/extglob patterns.
+ * Handles command substitution, variable expansion, and quoting within patterns.
+ */
+import type { InterpreterContext } from "../types.js";
+/**
+ * Check if a pattern string contains command substitution $(...)
+ */
+export declare function patternHasCommandSubstitution(pattern: string): boolean;
+/**
+ * Expand variables within a glob/extglob pattern string.
+ * This handles patterns like @($var|$other) where variables need expansion.
+ * Also handles quoted strings inside patterns (e.g., @(foo|'bar'|"$baz")).
+ * Preserves pattern metacharacters while expanding $var and ${var} references.
+ */
+export declare function expandVariablesInPattern(ctx: InterpreterContext, pattern: string): string;
+/**
+ * Async version of expandVariablesInPattern that handles command substitutions.
+ * This handles patterns like @($var|$(echo foo)) where command substitutions need expansion.
+ */
+export declare function expandVariablesInPatternAsync(ctx: InterpreterContext, pattern: string): Promise<string>;

package/dist/interpreter/expansion/pattern-removal.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Pattern Removal Helpers
+ *
+ * Functions for ${var#pattern}, ${var%pattern}, ${!prefix*} etc.
+ */
+import type { InterpreterContext } from "../types.js";
+/**
+ * Apply pattern removal (prefix or suffix strip) to a single value.
+ * Used by both scalar and vectorized array operations.
+ */
+export declare function applyPatternRemoval(value: string, regexStr: string, side: "prefix" | "suffix", greedy: boolean): string;
+/**
+ * Get variable names that match a given prefix.
+ * Used for ${!prefix*} and ${!prefix@} expansions.
+ * Handles arrays properly - includes array base names from __length markers,
+ * excludes internal storage keys like arr_0, arr__length.
+ */
+export declare function getVarNamesWithPrefix(ctx: InterpreterContext, prefix: string): string[];

package/dist/interpreter/expansion/pattern.d.ts

@@ -18,5 +18,6 @@
  * Convert a shell glob pattern to a regex string.
  * @param pattern - The glob pattern (*, ?, [...])
  * @param greedy - Whether * should be greedy (true for suffix matching, false for prefix)
+ * @param extglob - Whether to support extended glob patterns (@(...), *(...), +(...), ?(...), !(...))
  */
-export declare function patternToRegex(pattern: string, greedy: boolean): string;
+export declare function patternToRegex(pattern: string, greedy: boolean, extglob?: boolean): string;

package/dist/interpreter/expansion/positional-params.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Positional Parameter Expansion Handlers
+ *
+ * Handles $@ and $* expansion with various operations:
+ * - "${@:offset}" and "${*:offset}" - slicing
+ * - "${@/pattern/replacement}" - pattern replacement
+ * - "${@#pattern}" - pattern removal (strip)
+ * - "$@" and "$*" with adjacent text
+ */
+import type { WordPart } from "../../ast/types.js";
+import type { InterpreterContext } from "../types.js";
+/**
+ * Result type for positional parameter expansion handlers.
+ * `null` means the handler doesn't apply to this case.
+ */
+export type PositionalExpansionResult = {
+    values: string[];
+    quoted: boolean;
+} | null;
+import type { ArithExpr } from "../../ast/types.js";
+/**
+ * Type for evaluateArithmetic function
+ */
+export type EvaluateArithmeticFn = (ctx: InterpreterContext, expr: ArithExpr, isExpansionContext?: boolean) => Promise<number>;
+/**
+ * Type for expandPart function
+ */
+export type ExpandPartFn = (ctx: InterpreterContext, part: WordPart) => Promise<string>;
+/**
+ * Type for expandWordPartsAsync function
+ */
+export type ExpandWordPartsAsyncFn = (ctx: InterpreterContext, parts: WordPart[]) => Promise<string>;
+/**
+ * Handle "${@:offset}" and "${*:offset}" with Substring operations inside double quotes
+ * "${@:offset}": Each sliced positional parameter becomes a separate word
+ * "${*:offset}": All sliced params joined with IFS as ONE word
+ */
+export declare function handlePositionalSlicing(ctx: InterpreterContext, wordParts: WordPart[], evaluateArithmetic: EvaluateArithmeticFn, expandPart: ExpandPartFn): Promise<PositionalExpansionResult>;
+/**
+ * Handle "${@/pattern/replacement}" and "${* /pattern/replacement}" with PatternReplacement inside double quotes
+ * "${@/pattern/replacement}": Each positional parameter has pattern replaced, each becomes a separate word
+ * "${* /pattern/replacement}": All params joined with IFS, pattern replaced, becomes ONE word
+ */
+export declare function handlePositionalPatternReplacement(ctx: InterpreterContext, wordParts: WordPart[], expandPart: ExpandPartFn, expandWordPartsAsync: ExpandWordPartsAsyncFn): Promise<PositionalExpansionResult>;
+/**
+ * Handle "${@#pattern}" and "${*#pattern}" - positional parameter pattern removal (strip)
+ * "${@#pattern}": Remove shortest matching prefix from each parameter, each becomes a separate word
+ * "${@##pattern}": Remove longest matching prefix from each parameter
+ * "${@%pattern}": Remove shortest matching suffix from each parameter
+ * "${@%%pattern}": Remove longest matching suffix from each parameter
+ */
+export declare function handlePositionalPatternRemoval(ctx: InterpreterContext, wordParts: WordPart[], expandPart: ExpandPartFn, expandWordPartsAsync: ExpandWordPartsAsyncFn): Promise<PositionalExpansionResult>;
+/**
+ * Handle "$@" and "$*" with adjacent text inside double quotes, e.g., "-$@-"
+ * "$@": Each positional parameter becomes a separate word, with prefix joined to first
+ *       and suffix joined to last. If no params, produces nothing (or just prefix+suffix if present)
+ * "$*": All params joined with IFS as ONE word. If no params, produces one empty word.
+ */
+export declare function handleSimplePositionalExpansion(ctx: InterpreterContext, wordParts: WordPart[], expandPart: ExpandPartFn): Promise<PositionalExpansionResult>;

package/dist/interpreter/expansion/prompt.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Prompt expansion
+ *
+ * Handles prompt escape sequences for ${var@P} transformation and PS1/PS2/PS3/PS4.
+ */
+import type { InterpreterContext } from "../types.js";
+/**
+ * Expand prompt escape sequences (${var@P} transformation)
+ * Interprets backslash escapes used in PS1, PS2, PS3, PS4 prompt strings.
+ *
+ * Supported escapes:
+ * - \a - bell (ASCII 07)
+ * - \e - escape (ASCII 033)
+ * - \n - newline
+ * - \r - carriage return
+ * - \\ - literal backslash
+ * - \$ - $ for regular user, # for root (always $ here)
+ * - \[ and \] - non-printing sequence delimiters (removed)
+ * - \u - username
+ * - \h - short hostname (up to first .)
+ * - \H - full hostname
+ * - \w - current working directory
+ * - \W - basename of current working directory
+ * - \d - date (Weekday Month Day format)
+ * - \t - time HH:MM:SS (24-hour)
+ * - \T - time HH:MM:SS (12-hour)
+ * - \@ - time HH:MM AM/PM (12-hour)
+ * - \A - time HH:MM (24-hour)
+ * - \D{format} - strftime format
+ * - \s - shell name
+ * - \v - bash version (major.minor)
+ * - \V - bash version (major.minor.patch)
+ * - \j - number of jobs
+ * - \l - terminal device basename
+ * - \# - command number
+ * - \! - history number
+ * - \NNN - octal character code
+ */
+export declare function expandPrompt(ctx: InterpreterContext, value: string): string;

package/dist/interpreter/expansion/quoting.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Quoting helpers for word expansion
+ *
+ * Handles quoting values for shell reuse (${var@Q} transformation).
+ */
+/**
+ * Quote a value for safe reuse as shell input (${var@Q} transformation)
+ * Uses single quotes with proper escaping for special characters.
+ * Follows bash's quoting behavior:
+ * - Simple strings without quotes: 'value'
+ * - Strings with single quotes or control characters: $'value' with \' escaping
+ */
+export declare function quoteValue(value: string): string;

package/dist/interpreter/expansion/tilde.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tilde Expansion
+ *
+ * Functions for handling tilde (~) expansion in word expansion.
+ */
+import type { InterpreterContext } from "../types.js";
+/**
+ * Apply tilde expansion to a string.
+ * Used after brace expansion to handle cases like ~{/src,root} -> ~/src ~root -> /home/user/src /root
+ * Only expands ~ at the start of the string followed by / or end of string.
+ */
+export declare function applyTildeExpansion(ctx: InterpreterContext, value: string): string;

package/dist/interpreter/expansion/unquoted-expansion.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Unquoted Expansion Handlers
+ *
+ * Handles unquoted positional parameter and array expansions:
+ * - Unquoted $@ and $* (with and without prefix/suffix)
+ * - Unquoted ${arr[@]} and ${arr[*]}
+ * - Unquoted ${@:offset} and ${*:offset} slicing
+ * - Unquoted ${@#pattern} and ${*#pattern} pattern removal
+ * - Unquoted ${arr[@]/pattern/replacement} pattern replacement
+ * - Unquoted ${arr[@]#pattern} pattern removal
+ * - Unquoted ${!prefix@} and ${!prefix*} variable name prefix expansion
+ * - Unquoted ${!arr[@]} and ${!arr[*]} array keys expansion
+ */
+import type { ArithExpr, WordPart } from "../../ast/types.js";
+import type { InterpreterContext } from "../types.js";
+/**
+ * Result type for unquoted expansion handlers.
+ * `null` means the handler doesn't apply to this case.
+ */
+export type UnquotedExpansionResult = {
+    values: string[];
+    quoted: boolean;
+} | null;
+/**
+ * Type for expandPart function reference
+ */
+export type ExpandPartFn = (ctx: InterpreterContext, part: WordPart) => Promise<string>;
+/**
+ * Type for expandWordPartsAsync function reference
+ */
+export type ExpandWordPartsAsyncFn = (ctx: InterpreterContext, parts: WordPart[]) => Promise<string>;
+/**
+ * Type for evaluateArithmetic function
+ */
+export type EvaluateArithmeticFn = (ctx: InterpreterContext, expr: ArithExpr, isExpansionContext?: boolean) => Promise<number>;
+/**
+ * Handle unquoted ${array[@]/pattern/replacement} - apply to each element
+ * This handles ${array[@]/#/prefix} (prepend) and ${array[@]/%/suffix} (append)
+ */
+export declare function handleUnquotedArrayPatternReplacement(ctx: InterpreterContext, wordParts: WordPart[], expandWordPartsAsync: ExpandWordPartsAsyncFn, expandPart: ExpandPartFn): Promise<UnquotedExpansionResult>;
+/**
+ * Handle unquoted ${array[@]#pattern} - apply pattern removal to each element
+ * This handles ${array[@]#pattern} (strip shortest prefix), ${array[@]##pattern} (strip longest prefix)
+ * ${array[@]%pattern} (strip shortest suffix), ${array[@]%%pattern} (strip longest suffix)
+ */
+export declare function handleUnquotedArrayPatternRemoval(ctx: InterpreterContext, wordParts: WordPart[], expandWordPartsAsync: ExpandWordPartsAsyncFn, expandPart: ExpandPartFn): Promise<UnquotedExpansionResult>;
+/**
+ * Handle unquoted ${@#pattern} and ${*#pattern} - apply pattern removal to each positional parameter
+ * This handles ${@#pattern} (strip shortest prefix), ${@##pattern} (strip longest prefix)
+ * ${@%pattern} (strip shortest suffix), ${@%%pattern} (strip longest suffix)
+ */
+export declare function handleUnquotedPositionalPatternRemoval(ctx: InterpreterContext, wordParts: WordPart[], expandWordPartsAsync: ExpandWordPartsAsyncFn, expandPart: ExpandPartFn): Promise<UnquotedExpansionResult>;
+/**
+ * Handle unquoted ${@:offset} and ${*:offset} (with potential prefix/suffix)
+ */
+export declare function handleUnquotedPositionalSlicing(ctx: InterpreterContext, wordParts: WordPart[], evaluateArithmetic: EvaluateArithmeticFn, expandPart: ExpandPartFn): Promise<UnquotedExpansionResult>;
+/**
+ * Handle unquoted $@ and $* (simple, without operations)
+ */
+export declare function handleUnquotedSimplePositional(ctx: InterpreterContext, wordParts: WordPart[]): Promise<UnquotedExpansionResult>;
+/**
+ * Handle unquoted ${arr[@]} and ${arr[*]} (without operations)
+ */
+export declare function handleUnquotedSimpleArray(ctx: InterpreterContext, wordParts: WordPart[]): Promise<UnquotedExpansionResult>;
+/**
+ * Handle unquoted ${!prefix@} and ${!prefix*} (variable name prefix expansion)
+ */
+export declare function handleUnquotedVarNamePrefix(ctx: InterpreterContext, wordParts: WordPart[]): UnquotedExpansionResult;
+/**
+ * Handle unquoted ${!arr[@]} and ${!arr[*]} (array keys/indices expansion)
+ */
+export declare function handleUnquotedArrayKeys(ctx: InterpreterContext, wordParts: WordPart[]): UnquotedExpansionResult;
+/**
+ * Handle unquoted $@ or $* with prefix/suffix (e.g., =$@= or =$*=)
+ */
+export declare function handleUnquotedPositionalWithPrefixSuffix(ctx: InterpreterContext, wordParts: WordPart[], expandPart: ExpandPartFn): Promise<UnquotedExpansionResult>;

package/dist/interpreter/expansion/variable-attrs.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Variable Attributes
+ *
+ * Functions for getting variable attributes (${var@a} transformation).
+ */
+import type { InterpreterContext } from "../types.js";
+/**
+ * Get the attributes of a variable for ${var@a} transformation.
+ * Returns a string with attribute flags (e.g., "ar" for readonly array).
+ *
+ * Attribute flags (in order):
+ * - a: indexed array
+ * - A: associative array
+ * - i: integer
+ * - n: nameref
+ * - r: readonly
+ * - x: exported
+ */
+export declare function getVariableAttributes(ctx: InterpreterContext, name: string): string;