@struktoai/mirage-core/dist/shell/parse/names.d.ts

A Unified Virtual Filesystem For AI Agents

import type { TSNodeLike } from '../types.ts';
/**
 * Whether two facade nodes name the same tree node. The parser hands out
 * a fresh wrapper per lookup, so `===` alone cannot tell a node from a
 * re-read of it; identity rides `id` when the facade has one.
 */
export declare function sameNode(a: TSNodeLike, b: TSNodeLike): boolean;
/** Every node under `root`, `root` included, depth first. */
export declare function walkTree<T extends {
    readonly children: readonly T[];
}>(root: T): Generator<T>;
/**
 * Named nodes, skipping function_definition subtrees.
 *
 * A definition's body runs at invocation, not where it is defined, so
 * a read walk that descended into one would charge the defining line
 * for reads it never performs. The fill layer joins invoked bodies
 * back in through its own node set (`lineNodes`). `skip` names further
 * node types whose subtrees the caller walks on its own.
 */
export declare function walkNamedOutsideDefs(node: TSNodeLike, skip?: ReadonlySet<string>): Generator<TSNodeLike>;
/**
 * Every variable name a parsed program may read when it runs.
 *
 * A textual over-approximation over the whole tree, which is safe by
 * construction: the worst a spurious name costs is one fetch. Walked
 * everywhere -- command substitution bodies, redirect targets, heredoc
 * bodies, arithmetic -- with two exceptions that are writes, not reads
 * (an assignment's own name, unless it appends, since `+=` starts from
 * the value it extends; a for loop's variable), one that runs later
 * rather than now (a function definition's body, which the fill layer
 * joins back in at invocation), and one the grammar gives for free: a
 * single-quoted string tokenizes as `raw_string` with no children, so
 * `'$X'` never reads X.
 */
export declare function referencedNames(node: TSNodeLike): ReadonlySet<string>;
/**
 * The first word of every command a parsed program runs.
 *
 * What the whole-env scan and the CLI env-name lookup key on.
 * `command_name` covers ordinary commands wherever they sit; the
 * declaring builtins (`export`, `declare`, `local`, `readonly`,
 * `unset`) parse as their own node types whose head word is the first
 * anonymous token, so those are read directly. A function definition's
 * body is skipped: those commands run at invocation, where the fill
 * layer walks the stored body instead, and so is any `skip` type the
 * caller walks on its own.
 */
export declare function commandWords(node: TSNodeLike, skip?: ReadonlySet<string>): ReadonlySet<string>;
/**
 * The argument's text when the parser fixed it, else null.
 *
 * A plain word, a number, a raw string and a double-quoted string of
 * plain content each spell one literal; anything carrying an expansion
 * or a substitution is dynamic and reads as null.
 */
export declare function literalText(node: TSNodeLike): string | null;
export declare function commandArgs(node: TSNodeLike): TSNodeLike[];
/**
 * Every plain command's head word with its argument words.
 *
 * Head and arguments are reported as their literal text, or null for a
 * word no static read can spell (an expansion, a substitution), so a
 * caller matching names (the CLI env-name pruning) can tell "this word
 * is not there" from "this word is unknowable". A null head is the
 * stronger fact: the command that runs is not decidable before
 * expansion, so the fill pass treats the line as an opaque read.
 * Assignment prefixes and redirects are not arguments.
 */
export declare function commandInvocations(node: TSNodeLike): [string | null, (string | null)[]][];
/**
 * Identifier-shaped tokens in an arithmetic expression string.
 *
 * Bash evaluates a variable's value as an expression of its own
 * (`x="TOKEN + 1"; $((x))` reads TOKEN), so a caller chasing that
 * recursion needs the names a value may resolve. Over-approximates on
 * purpose: `0x1f` yields `x1f`, which reads nothing real and costs
 * nothing.
 */
export declare function identifierNames(text: string): ReadonlySet<string>;
/**
 * Names the program reads in an arithmetic context.
 *
 * Arithmetic resolution recurses through values (`name=TOKEN;
 * $((name))` reads TOKEN), so these names are the ones whose stored
 * values a fill plan must chase. The contexts mirror where the
 * executor calls `evaluateArith`: `$((...))` and `$[...]` expansions,
 * the `((...))` command, a c-style for's header, a subscript's index,
 * a `${v:offset:length}` offset, the `[[` numeric comparators, and
 * `let`'s operands. `test`/`[` are absent on purpose: the flat builtin
 * parses integers strictly, so a bare word there never resolves as a
 * variable.
 */
export declare function arithReads(node: TSNodeLike): ReadonlySet<string>;
/**
 * Every plain assignment's target with what its value may hold.
 *
 * Per assignment: the target name, the value's literal text (null when
 * no static read can spell it, empty for a bare `X=`), and, for a
 * dynamic value, the names it reads -- an arithmetic read of the
 * target may recurse into whichever of those values lands
 * (`n=$other; $((n))` reads what `other` holds). Subscripted targets
 * are skipped: an element write never replaces the whole value.
 */
export declare function assignmentValues(node: TSNodeLike): [string, string | null, ReadonlySet<string>][];
//# sourceMappingURL=names.d.ts.map