just-bash 1.0.0

package/dist/interpreter/control-flow.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Control Flow Execution
+ *
+ * Handles control flow constructs:
+ * - if/elif/else
+ * - for loops
+ * - C-style for loops
+ * - while loops
+ * - until loops
+ * - case statements
+ * - break/continue
+ */
+import type { CaseNode, CStyleForNode, ForNode, IfNode, UntilNode, WhileNode } from "../ast/types.js";
+import type { ExecResult } from "../types.js";
+import type { InterpreterContext } from "./types.js";
+export declare function executeIf(ctx: InterpreterContext, node: IfNode): Promise<ExecResult>;
+export declare function executeFor(ctx: InterpreterContext, node: ForNode): Promise<ExecResult>;
+export declare function executeCStyleFor(ctx: InterpreterContext, node: CStyleForNode): Promise<ExecResult>;
+export declare function executeWhile(ctx: InterpreterContext, node: WhileNode, stdin?: string): Promise<ExecResult>;
+export declare function executeUntil(ctx: InterpreterContext, node: UntilNode): Promise<ExecResult>;
+export declare function executeCase(ctx: InterpreterContext, node: CaseNode): Promise<ExecResult>;

package/dist/interpreter/errors.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Control Flow Errors
+ *
+ * Error classes used to implement shell control flow:
+ * - break: Exit loops
+ * - continue: Skip to next iteration
+ * - return: Exit functions
+ * - errexit: Exit on error (set -e)
+ * - nounset: Error on unset variables (set -u)
+ *
+ * All control flow errors carry stdout/stderr to accumulate output
+ * as they propagate through the execution stack.
+ */
+/**
+ * Base class for all control flow errors.
+ * Carries stdout/stderr to preserve output during propagation.
+ */
+declare abstract class ControlFlowError extends Error {
+    stdout: string;
+    stderr: string;
+    constructor(message: string, stdout?: string, stderr?: string);
+    /**
+     * Prepend output from the current context before re-throwing.
+     */
+    prependOutput(stdout: string, stderr: string): void;
+}
+/**
+ * Error thrown when break is called to exit loops.
+ */
+export declare class BreakError extends ControlFlowError {
+    levels: number;
+    readonly name = "BreakError";
+    constructor(levels?: number, stdout?: string, stderr?: string);
+}
+/**
+ * Error thrown when continue is called to skip to next iteration.
+ */
+export declare class ContinueError extends ControlFlowError {
+    levels: number;
+    readonly name = "ContinueError";
+    constructor(levels?: number, stdout?: string, stderr?: string);
+}
+/**
+ * Error thrown when return is called to exit a function.
+ */
+export declare class ReturnError extends ControlFlowError {
+    exitCode: number;
+    readonly name = "ReturnError";
+    constructor(exitCode?: number, stdout?: string, stderr?: string);
+}
+/**
+ * Error thrown when set -e (errexit) is enabled and a command fails.
+ */
+export declare class ErrexitError extends ControlFlowError {
+    readonly exitCode: number;
+    readonly name = "ErrexitError";
+    constructor(exitCode: number, stdout?: string, stderr?: string);
+}
+/**
+ * Error thrown when set -u (nounset) is enabled and an unset variable is referenced.
+ */
+export declare class NounsetError extends ControlFlowError {
+    varName: string;
+    readonly name = "NounsetError";
+    constructor(varName: string, stdout?: string);
+}
+/**
+ * Error thrown when exit builtin is called to terminate the script.
+ */
+export declare class ExitError extends ControlFlowError {
+    readonly exitCode: number;
+    readonly name = "ExitError";
+    constructor(exitCode: number, stdout?: string, stderr?: string);
+}
+/**
+ * Error thrown for arithmetic expression errors (e.g., floating point, invalid syntax).
+ * Returns exit code 1 instead of 2 (syntax error).
+ */
+export declare class ArithmeticError extends ControlFlowError {
+    readonly name = "ArithmeticError";
+    constructor(message: string, stdout?: string, stderr?: string);
+}
+/**
+ * Error thrown for bad substitution errors (e.g., ${#var:1:3}).
+ * Returns exit code 1.
+ */
+export declare class BadSubstitutionError extends ControlFlowError {
+    readonly name = "BadSubstitutionError";
+    constructor(message: string, stdout?: string, stderr?: string);
+}
+/**
+ * Error thrown when execution limits are exceeded (recursion depth, command count, loop iterations).
+ * This should ALWAYS be thrown before JavaScript's native RangeError kicks in.
+ * Exit code 126 indicates a limit was exceeded.
+ */
+export declare class ExecutionLimitError extends ControlFlowError {
+    readonly limitType: "recursion" | "commands" | "iterations";
+    readonly name = "ExecutionLimitError";
+    static readonly EXIT_CODE = 126;
+    constructor(message: string, limitType: "recursion" | "commands" | "iterations", stdout?: string, stderr?: string);
+}
+/**
+ * Type guard for errors that exit the current scope (return, break, continue).
+ * These need special handling vs errexit/nounset which terminate execution.
+ */
+export declare function isScopeExitError(error: unknown): error is BreakError | ContinueError | ReturnError;
+export {};

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

@@ -0,0 +1,39 @@
+/**
+ * Word Analysis
+ *
+ * Functions for analyzing word parts to determine:
+ * - Whether async execution is needed
+ * - What types of expansions are present
+ */
+import type { ParameterExpansionPart, WordNode, WordPart } from "../../ast/types.js";
+/**
+ * Check if a parameter expansion requires async execution
+ */
+export declare function paramExpansionNeedsAsync(part: ParameterExpansionPart): boolean;
+/**
+ * Check if a word part requires async execution
+ */
+export declare function partNeedsAsync(part: WordPart): boolean;
+/**
+ * Check if a word requires async execution
+ */
+export declare function wordNeedsAsync(word: WordNode): boolean;
+/**
+ * Check if a parameter expansion has quoted parts in its operation word
+ * e.g., ${v:-"AxBxC"} has a quoted default value
+ */
+export declare function hasQuotedOperationWord(part: ParameterExpansionPart): boolean;
+/**
+ * Result of analyzing word parts
+ */
+export interface WordPartsAnalysis {
+    hasQuoted: boolean;
+    hasCommandSub: boolean;
+    hasArrayVar: boolean;
+    hasArrayAtExpansion: boolean;
+    hasParamExpansion: boolean;
+}
+/**
+ * Analyze word parts for expansion behavior
+ */
+export declare function analyzeWordParts(parts: WordPart[]): WordPartsAnalysis;

package/dist/interpreter/expansion/brace-range.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Brace Range Expansion
+ *
+ * Handles numeric {1..10} and character {a..z} range expansion.
+ * These are pure functions with no external dependencies.
+ */
+/**
+ * Result of a brace range expansion.
+ * Either contains expanded values or a literal fallback for invalid ranges.
+ */
+export interface BraceRangeResult {
+    expanded: string[] | null;
+    literal: string;
+}
+/**
+ * Unified brace range expansion helper.
+ * Handles both numeric and character ranges, returning either expanded values
+ * or a literal string for invalid ranges.
+ */
+export declare function expandBraceRange(start: number | string, end: number | string, step: number | undefined, startStr?: string, endStr?: string): BraceRangeResult;

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

@@ -0,0 +1,22 @@
+/**
+ * Pattern Matching
+ *
+ * Converts shell glob patterns to regex equivalents for pattern matching
+ * in parameter expansion (${var%pattern}, ${var/pattern/replacement}, etc.)
+ * and case statements.
+ *
+ * ## Error Handling
+ *
+ * This module follows bash's behavior for invalid patterns:
+ * - Invalid character ranges (e.g., `[z-a]`) result in regex compilation failure
+ * - Unknown POSIX classes (e.g., `[:foo:]`) produce empty match groups
+ * - Unclosed character classes (`[abc`) are treated as literal `[`
+ *
+ * Callers should wrap regex compilation in try/catch to handle invalid patterns.
+ */
+/**
+ * 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)
+ */
+export declare function patternToRegex(pattern: string, greedy: boolean): string;

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

@@ -0,0 +1,27 @@
+/**
+ * Variable Access
+ *
+ * Handles variable value retrieval, including:
+ * - Special variables ($?, $$, $#, $@, $*, $0)
+ * - Array access (${arr[0]}, ${arr[@]}, ${arr[*]})
+ * - Positional parameters ($1, $2, ...)
+ * - Regular variables
+ */
+import type { InterpreterContext } from "../types.js";
+/**
+ * Get all elements of an array stored as arrayName_0, arrayName_1, etc.
+ * Returns an array of [index/key, value] tuples, sorted by index/key.
+ * For associative arrays, uses string keys.
+ */
+export declare function getArrayElements(ctx: InterpreterContext, arrayName: string): Array<[number | string, string]>;
+/**
+ * Check if a variable is an array (has elements stored as name_0, name_1, etc.)
+ */
+export declare function isArray(ctx: InterpreterContext, name: string): boolean;
+/**
+ * Get the value of a variable, optionally checking nounset.
+ * @param ctx - The interpreter context
+ * @param name - The variable name
+ * @param checkNounset - Whether to check for nounset (default true)
+ */
+export declare function getVariable(ctx: InterpreterContext, name: string, checkNounset?: boolean, _insideDoubleQuotes?: boolean): string;

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

@@ -0,0 +1,24 @@
+/**
+ * Word Splitting
+ *
+ * IFS-based word splitting for unquoted expansions.
+ */
+import type { WordPart } from "../../ast/types.js";
+import type { InterpreterContext } from "../types.js";
+/**
+ * Type for the expandPart function that will be injected
+ */
+export type ExpandPartFn = (ctx: InterpreterContext, part: WordPart) => Promise<string>;
+/**
+ * Smart word splitting that respects expansion boundaries.
+ *
+ * E.g., with IFS=x: ${v:-AxBxC}x should give "A B Cx" (literal x attaches to last field)
+ * E.g., with IFS=x: y${v:-AxBxC}z should give "yA B Cz" (literals attach to first/last fields)
+ *
+ * @param ctx - Interpreter context
+ * @param wordParts - Word parts to expand and split
+ * @param _ifsChars - IFS characters (unused, kept for API compatibility)
+ * @param ifsPattern - Regex-escaped IFS pattern for splitting
+ * @param expandPartFn - Function to expand individual parts (injected to avoid circular deps)
+ */
+export declare function smartWordSplit(ctx: InterpreterContext, wordParts: WordPart[], _ifsChars: string, ifsPattern: string, expandPartFn: ExpandPartFn): Promise<string[]>;

package/dist/interpreter/expansion.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Word Expansion
+ *
+ * Handles shell word expansion including:
+ * - Variable expansion ($VAR, ${VAR})
+ * - Command substitution $(...)
+ * - Arithmetic expansion $((...))
+ * - Tilde expansion (~)
+ * - Brace expansion {a,b,c}
+ * - Glob expansion (*, ?, [...])
+ */
+import type { WordNode } from "../ast/types.js";
+import type { InterpreterContext } from "./types.js";
+export { getArrayElements, getVariable } from "./expansion/variable.js";
+/**
+ * Check if an entire word is fully quoted
+ */
+export declare function isWordFullyQuoted(word: WordNode): boolean;
+/**
+ * Escape glob metacharacters in a string for literal matching
+ */
+export declare function escapeGlobChars(str: string): string;
+export declare function expandWord(ctx: InterpreterContext, word: WordNode): Promise<string>;
+export declare function expandWordWithGlob(ctx: InterpreterContext, word: WordNode): Promise<{
+    values: string[];
+    quoted: boolean;
+}>;

package/dist/interpreter/functions.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Function Handling
+ *
+ * Handles shell function definition and invocation:
+ * - Function definition (adding to function table)
+ * - Function calls (with positional parameters and local scopes)
+ */
+import type { FunctionDefNode } from "../ast/types.js";
+import type { ExecResult } from "../types.js";
+import type { InterpreterContext } from "./types.js";
+export declare function executeFunctionDef(ctx: InterpreterContext, node: FunctionDefNode): ExecResult;
+export declare function callFunction(ctx: InterpreterContext, func: FunctionDefNode, args: string[]): Promise<ExecResult>;

package/dist/interpreter/helpers/array.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Array helper functions for the interpreter.
+ */
+import type { InterpreterContext } from "../types.js";
+/**
+ * Get all indices of an array, sorted in ascending order.
+ * Arrays are stored as `name_0`, `name_1`, etc. in the environment.
+ */
+export declare function getArrayIndices(ctx: InterpreterContext, arrayName: string): number[];
+/**
+ * Clear all elements of an array from the environment.
+ */
+export declare function clearArray(ctx: InterpreterContext, arrayName: string): void;
+/**
+ * Get all keys of an associative array.
+ * For associative arrays, keys are stored as `name_key` where key is a string.
+ */
+export declare function getAssocArrayKeys(ctx: InterpreterContext, arrayName: string): string[];
+/**
+ * Remove surrounding quotes from a key string.
+ * Handles 'key' and "key" → key
+ */
+export declare function unquoteKey(key: string): string;

package/dist/interpreter/helpers/condition.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Condition execution helper for the interpreter.
+ *
+ * Handles executing condition statements with proper inCondition state management.
+ * Used by if, while, and until loops.
+ */
+import type { StatementNode } from "../../ast/types.js";
+import type { InterpreterContext } from "../types.js";
+export interface ConditionResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * Execute condition statements with inCondition flag set.
+ * This prevents errexit from triggering during condition evaluation.
+ *
+ * @param ctx - Interpreter context
+ * @param statements - Condition statements to execute
+ * @returns Accumulated stdout, stderr, and final exit code
+ */
+export declare function executeCondition(ctx: InterpreterContext, statements: StatementNode[]): Promise<ConditionResult>;

package/dist/interpreter/helpers/errors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Error helper functions for the interpreter.
+ */
+/**
+ * Extract message from an unknown error value.
+ * Handles both Error instances and other thrown values.
+ */
+export declare function getErrorMessage(error: unknown): string;

package/dist/interpreter/helpers/file-tests.d.ts

@@ -0,0 +1,33 @@
+import type { InterpreterContext } from "../types.js";
+/**
+ * File test operators supported by bash
+ * Unary operators that test file properties
+ */
+declare const FILE_TEST_OPERATORS: readonly ["-e", "-a", "-f", "-d", "-r", "-w", "-x", "-s", "-L", "-h", "-k", "-g", "-u", "-G", "-O", "-b", "-c", "-p", "-S", "-t", "-N"];
+export type FileTestOperator = (typeof FILE_TEST_OPERATORS)[number];
+export declare function isFileTestOperator(op: string): op is FileTestOperator;
+/**
+ * Evaluates a file test operator (-e, -f, -d, etc.) against a path.
+ * Returns a boolean result.
+ *
+ * @param ctx - Interpreter context with filesystem access
+ * @param operator - The file test operator (e.g., "-f", "-d", "-e")
+ * @param operand - The path to test (will be resolved relative to cwd)
+ */
+export declare function evaluateFileTest(ctx: InterpreterContext, operator: string, operand: string): Promise<boolean>;
+/**
+ * Binary file test operators for comparing two files
+ */
+declare const BINARY_FILE_TEST_OPERATORS: readonly ["-nt", "-ot", "-ef"];
+export type BinaryFileTestOperator = (typeof BINARY_FILE_TEST_OPERATORS)[number];
+export declare function isBinaryFileTestOperator(op: string): op is BinaryFileTestOperator;
+/**
+ * Evaluates a binary file test operator (-nt, -ot, -ef) comparing two files.
+ *
+ * @param ctx - Interpreter context with filesystem access
+ * @param operator - The operator (-nt, -ot, -ef)
+ * @param left - Left operand (file path)
+ * @param right - Right operand (file path)
+ */
+export declare function evaluateBinaryFileTest(ctx: InterpreterContext, operator: string, left: string, right: string): Promise<boolean>;
+export {};

package/dist/interpreter/helpers/ifs.d.ts

@@ -0,0 +1,43 @@
+/**
+ * IFS (Internal Field Separator) Handling
+ *
+ * Centralized utilities for IFS-based word splitting used by:
+ * - Word expansion (unquoted variable expansion)
+ * - read builtin
+ * - ${!prefix*} and ${!arr[*]} expansions
+ */
+/**
+ * Get the effective IFS value from environment.
+ * Returns DEFAULT_IFS if IFS is undefined, or the actual value (including empty string).
+ */
+export declare function getIfs(env: Record<string, string>): string;
+/**
+ * Check if IFS is set to empty string (disables word splitting).
+ */
+export declare function isIfsEmpty(env: Record<string, string>): boolean;
+/**
+ * Build a regex-safe pattern from IFS characters for use in character classes.
+ * E.g., for IFS=" \t\n", returns " \\t\\n" (escaped for [pattern] use)
+ */
+export declare function buildIfsCharClassPattern(ifs: string): string;
+/**
+ * Get the first character of IFS (used for joining with $* and ${!prefix*}).
+ * Returns space if IFS is undefined, empty string if IFS is empty.
+ */
+export declare function getIfsSeparator(env: Record<string, string>): string;
+/**
+ * Split a string by IFS, handling leading/trailing IFS properly.
+ * Returns words and their start positions in the original string.
+ *
+ * @param value - String to split
+ * @param ifs - IFS characters to split on
+ * @returns Object with words array and wordStarts array
+ */
+export declare function splitByIfs(value: string, ifs: string): {
+    words: string[];
+    wordStarts: number[];
+};
+/**
+ * Strip trailing IFS characters from a string.
+ */
+export declare function stripTrailingIfs(value: string, ifs: string): string;

package/dist/interpreter/helpers/loop.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Loop Error Handling Helpers
+ *
+ * Consolidates the repeated error handling logic used in all loop constructs
+ * (for, c-style for, while, until).
+ */
+export type LoopAction = "break" | "continue" | "rethrow" | "error";
+export interface LoopErrorResult {
+    action: LoopAction;
+    stdout: string;
+    stderr: string;
+    exitCode?: number;
+    error?: unknown;
+}
+/**
+ * Handle errors thrown during loop body execution.
+ *
+ * @param error - The caught error
+ * @param stdout - Current accumulated stdout
+ * @param stderr - Current accumulated stderr
+ * @param loopDepth - Current loop nesting depth from ctx.state.loopDepth
+ * @returns Result indicating what action the loop should take
+ */
+export declare function handleLoopError(error: unknown, stdout: string, stderr: string, loopDepth: number): LoopErrorResult;

package/dist/interpreter/helpers/numeric-compare.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Numeric comparison helper for conditionals.
+ * Handles -eq, -ne, -lt, -le, -gt, -ge operators.
+ */
+export type NumericOp = "-eq" | "-ne" | "-lt" | "-le" | "-gt" | "-ge";
+/**
+ * Check if an operator is a numeric comparison operator.
+ */
+export declare function isNumericOp(op: string): op is NumericOp;
+/**
+ * Compare two numbers using a numeric comparison operator.
+ */
+export declare function compareNumeric(op: NumericOp, left: number, right: number): boolean;

package/dist/interpreter/helpers/readonly.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Readonly variable helpers.
+ *
+ * Consolidates readonly variable logic used in declare, export, local, etc.
+ */
+import type { ExecResult } from "../../types.js";
+import type { InterpreterContext } from "../types.js";
+/**
+ * Mark a variable as readonly.
+ */
+export declare function markReadonly(ctx: InterpreterContext, name: string): void;
+/**
+ * Check if a variable is readonly and return an error if so.
+ * Returns null if the variable is not readonly (can be modified).
+ *
+ * @param ctx - Interpreter context
+ * @param name - Variable name
+ * @param command - Command name for error message (default: "bash")
+ * @returns Error result if readonly, null otherwise
+ */
+export declare function checkReadonlyError(ctx: InterpreterContext, name: string, command?: string): ExecResult | null;

package/dist/interpreter/helpers/regex.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Regex helper functions for the interpreter.
+ */
+/**
+ * Escape a string for use as a literal in a regex pattern.
+ * All regex special characters are escaped.
+ */
+export declare function escapeRegex(str: string): string;

package/dist/interpreter/helpers/result.d.ts

@@ -0,0 +1,54 @@
+/**
+ * ExecResult factory functions for cleaner code.
+ *
+ * These helpers reduce verbosity and improve readability when
+ * constructing ExecResult objects throughout the interpreter.
+ */
+import type { ExecResult } from "../../types.js";
+/**
+ * A successful result with no output.
+ * Use this for commands that succeed silently.
+ */
+export declare const OK: ExecResult;
+/**
+ * Create a successful result with optional stdout.
+ *
+ * @param stdout - Output to include (default: "")
+ * @returns ExecResult with exitCode 0
+ */
+export declare function success(stdout?: string): ExecResult;
+/**
+ * Create a failure result with stderr message.
+ *
+ * @param stderr - Error message to include
+ * @param exitCode - Exit code (default: 1)
+ * @returns ExecResult with the specified exitCode
+ */
+export declare function failure(stderr: string, exitCode?: number): ExecResult;
+/**
+ * Create a result with all fields specified.
+ *
+ * @param stdout - Standard output
+ * @param stderr - Standard error
+ * @param exitCode - Exit code
+ * @returns ExecResult with all fields
+ */
+export declare function result(stdout: string, stderr: string, exitCode: number): ExecResult;
+/**
+ * Convert a boolean test result to an ExecResult.
+ * Useful for test/conditional commands where true = exit 0, false = exit 1.
+ *
+ * @param passed - Boolean test result
+ * @returns ExecResult with exitCode 0 if passed, 1 otherwise
+ */
+export declare function testResult(passed: boolean): ExecResult;
+/**
+ * Throw an ExecutionLimitError for execution limits (recursion, iterations, commands).
+ *
+ * @param message - Error message describing the limit exceeded
+ * @param limitType - Type of limit exceeded
+ * @param stdout - Accumulated stdout to include
+ * @param stderr - Accumulated stderr to include
+ * @throws ExecutionLimitError always
+ */
+export declare function throwExecutionLimit(message: string, limitType: "recursion" | "iterations" | "commands", stdout?: string, stderr?: string): never;

package/dist/interpreter/helpers/statements.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Statement execution helpers for the interpreter.
+ *
+ * Consolidates the common pattern of executing a list of statements
+ * and accumulating their output.
+ */
+import type { StatementNode } from "../../ast/types.js";
+import type { ExecResult } from "../../types.js";
+import type { InterpreterContext } from "../types.js";
+/**
+ * Execute a list of statements and accumulate their output.
+ * Handles scope exit errors (break, continue, return) and errexit properly.
+ *
+ * @param ctx - Interpreter context
+ * @param statements - Statements to execute
+ * @param initialStdout - Initial stdout to prepend (default "")
+ * @param initialStderr - Initial stderr to prepend (default "")
+ * @returns Accumulated stdout, stderr, and final exit code
+ */
+export declare function executeStatements(ctx: InterpreterContext, statements: StatementNode[], initialStdout?: string, initialStderr?: string): Promise<ExecResult>;

package/dist/interpreter/helpers/string-compare.d.ts

@@ -0,0 +1,22 @@
+/**
+ * String comparison helpers for conditionals.
+ *
+ * Consolidates string comparison logic (=, ==, !=) used in:
+ * - [[ ]] conditional expressions (with optional pattern matching)
+ * - test/[ ] command (literal comparison only)
+ */
+export type StringCompareOp = "=" | "==" | "!=";
+/**
+ * Check if an operator is a string comparison operator.
+ */
+export declare function isStringCompareOp(op: string): op is StringCompareOp;
+/**
+ * Compare two strings using the specified operator.
+ *
+ * @param op - The comparison operator (=, ==, !=)
+ * @param left - Left operand
+ * @param right - Right operand
+ * @param usePattern - If true, use glob pattern matching for equality (default: false)
+ * @returns True if the comparison succeeds
+ */
+export declare function compareStrings(op: StringCompareOp, left: string, right: string, usePattern?: boolean): boolean;

package/dist/interpreter/helpers/string-tests.d.ts

@@ -0,0 +1,13 @@
+/**
+ * String test helper for conditionals.
+ * Handles -z (empty) and -n (non-empty) operators.
+ */
+export type StringTestOp = "-z" | "-n";
+/**
+ * Check if an operator is a string test operator.
+ */
+export declare function isStringTestOp(op: string): op is StringTestOp;
+/**
+ * Evaluate a string test operator.
+ */
+export declare function evaluateStringTest(op: StringTestOp, value: string): boolean;

package/dist/interpreter/helpers/variable-tests.d.ts

@@ -0,0 +1,9 @@
+import type { InterpreterContext } from "../types.js";
+/**
+ * Evaluates the -v (variable is set) test.
+ * Handles both simple variables and array element access with negative indices.
+ *
+ * @param ctx - Interpreter context with environment variables
+ * @param operand - The variable name to test, may include array subscript (e.g., "arr[0]", "arr[-1]")
+ */
+export declare function evaluateVariableTest(ctx: InterpreterContext, operand: string): boolean;

package/dist/interpreter/helpers/word-parts.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Word Part Helper Functions
+ *
+ * Provides common operations on WordPart types to eliminate duplication
+ * across expansion.ts and word-parser.ts.
+ */
+import type { WordPart } from "../../ast/types.js";
+/**
+ * Get the literal string value from a word part.
+ * Returns the value for Literal, SingleQuoted, and Escaped parts.
+ * Returns null for complex parts that require expansion.
+ */
+export declare function getLiteralValue(part: WordPart): string | null;
+/**
+ * Check if a word part is "quoted" - meaning glob characters should be treated literally.
+ * A part is quoted if it is:
+ * - SingleQuoted
+ * - Escaped
+ * - DoubleQuoted (entirely quoted)
+ * - Literal with empty value (doesn't affect quoting)
+ */
+export declare function isQuotedPart(part: WordPart): boolean;