@sema-agent/core 7.45.0 → 7.46.0

package/dist/tools/fs/shell-read-bindings.d.ts

@@ -0,0 +1,273 @@
+/**
+ * THE BINDING RULE — which shell names a command text binds, and to what, read off the one lexer's facts and the
+ * program read model's roles. A word that expands a name (`"$F"`, `${F}`, a `~` reading `HOME`) names a path only
+ * through what the text bound that name to; this module answers "what may `F` hold here", and nothing else.
+ *
+ * Two halves:
+ *  · {@link bindingEffectOf} — what ONE segment does to the names: binds a name to a value (an assignment statement, a
+ *    declaration builtin's `NAME=value`, a `for` list), makes a name unknown (a builtin whose operand role binds a name,
+ *    an assigning expansion `${N:=…}`, an arithmetic assignment, a code body that runs later), gives a name an ATTRIBUTE
+ *    (integer, a case change, an array, read-only: a later assignment to it stores something other than its text, or
+ *    nothing), or makes EVERY name unknown (a name reference, `eval`, `source`, a computed name, an unquoted
+ *    here-document `${`), and resets every name to the state it starts the text in (a function body: it runs at its
+ *    call, against that table);
+ *  · {@link BindingThread} — the effects threaded through the segments the way the plan threads the working directory
+ *    (`shell-read-plan.ts`): a value bound in a segment that may not have run before a reader (an `&&` / `||` run, a
+ *    branch, a loop body, a subshell, a pipeline member, a background job) joins the values the name held before
+ *    instead of replacing them. A function body runs at its call, which the plan does not follow (a function may be
+ *    called anywhere after its definition): a name the body binds is unreadable to every reader past the body, whatever
+ *    is assigned to it later, and to every reader in another body — unless the body declared it with a plain `local`.
+ *    An attribute and a name reference hold for every segment they may RUN before: a later one, one in a function body
+ *    (it runs at its call), one in the same loop body (a later beat).
+ *
+ * A name the text does not settle is UNKNOWN, and a word expanding an unknown name stays a word the shell rewrites (its
+ * read cannot be established). `HOME` is an ordinary name whose state at the start of a text is the declared home.
+ * The shell's own variables (the ones bash sets, holds read-only or evaluates itself) are never bound from text.
+ */
+import { type LexedRedirect, type LexedSegment, type LexedToken, type LexedWord } from "../../shell/lex.js";
+import { type DeclaredAttribute } from "./program-read-model.js";
+/** A value a name may hold: the text it holds, and whether that text is a PATTERN whose matches are the values (a `for`
+ *  list word the shell globs before the loop binds it). */
+export interface BoundValue {
+    readonly spelled: string;
+    readonly glob?: true;
+}
+/** What a name holds at one point of a text: its possible values, or `"unknown"`. */
+type NameState = readonly BoundValue[] | "unknown";
+/**
+ * The variables bash keeps itself — it sets them (`PWD`, `REPLY`, `OPTARG`, `BASH_REMATCH`, …), holds them read-only
+ * (`SHELLOPTS`, `BASHOPTS`, `BASH_VERSINFO`: an assignment to one is refused), or evaluates every value assigned to them
+ * as ARITHMETIC (the integer variables: `OPTIND`, `RANDOM`, `LINENO`, `HISTCMD`, `BASHPID`, …; the reference
+ * implementation's table of them, `zsh`'s included, is read whole: a member that is not one in this shell costs a
+ * question, never a read). Their value is never the text that bound it.
+ */
+export declare const SHELL_INTEGER_VARIABLES: ReadonlySet<string>;
+/** Is this a variable bash keeps itself ({@link SHELL_INTEGER_VARIABLES}, or one it sets)? */
+export declare function shellKeepsName(name: string): boolean;
+/** One binding a segment makes: a name and what it now holds (`unknown` = made unknown). `prefix`: a prefix assignment
+ *  to a special builtin, which may or may not outlive the command. `loopVar`: a `for` loop's variable, held through
+ *  its body. */
+export interface Binding {
+    readonly name: string;
+    readonly state: NameState;
+    readonly prefix?: true;
+    readonly loopVar?: true;
+    /** `local`: a plain `local NAME…` — in a function body the name is the body's own and never leaves it. `unread`: a
+     *  declaration builtin with an option word (`declare -g`, `local -p`, `local -r`): which scope it binds in is not
+     *  read, so it is neither the body's own name nor covered by an earlier `local`. */
+    readonly scope?: "local" | "unread";
+    /** Spellings the name may hold that the deny judge still reads where the name is otherwise unknown (an array's
+     *  elements: what `${A[k]}` expands to is one of them). */
+    readonly floor?: readonly BoundValue[];
+}
+/** An attribute a declaration gives a name — or every name (`name` absent: the declaration computed it): a later
+ *  assignment to it is evaluated as arithmetic (`integer`), stores a case change or an array element (`transformed`), or
+ *  is refused (`frozen`) — it binds something other than its text. */
+export interface NameAttribute {
+    readonly name?: string;
+    readonly kind: Exclude<DeclaredAttribute, "reference" | "unsettled">;
+}
+/** What ONE segment does to the names. `all`: every name made unknown (`unknown`), or reset to its state at the start
+ *  of the text (`reset` — a function body). `attributes`: the attributes it gives ({@link NameAttribute}). `references`:
+ *  a name reference was declared — from here on an assignment to any name may write through it, so no name holds what
+ *  the text assigned. `inFunction`: the builtin assigns only inside a function body (`local`) — outside one bash refuses
+ *  the command, and its bindings hold nothing the text says. */
+export interface BindingEffect {
+    readonly bindings: readonly Binding[];
+    readonly all?: "unknown" | "reset";
+    readonly attributes?: readonly NameAttribute[];
+    readonly references?: true;
+    readonly inFunction?: true;
+}
+/** How one value word reads against the table, the earlier assignments of the same segment applied (bash assigns left
+ *  to right): its possible values, or `unknown`. */
+export type ValueReader = (word: Pick<LexedWord, "pieces">, quoted: boolean, overlay: ReadonlyMap<string, NameState>) => NameState;
+/** The segment's shape the effect needs beside its words: a function definition head was dropped from it. */
+export interface SegmentShape {
+    readonly definesFunction: boolean;
+}
+/** The argv projection of a lexed segment: structure that names nothing that runs here is dropped — a subshell
+ *  parenthesis, a bare `{` / `}`, a function definition's head (`NAME ()`, and `function NAME [()]` with a name of
+ *  any spelling, {@link dropDefinitionHeads}), a `case` arm's pattern ({@link dropCasePattern}), and the block words
+ *  at the head. */
+export interface ProjectedSegment extends SegmentShape {
+    readonly argv: readonly LexedWord[];
+    readonly redirects: readonly LexedRedirect[];
+    readonly grouped: boolean;
+}
+export declare function projectSegment(segment: LexedSegment): ProjectedSegment;
+/** A function definition's head names nothing that runs here and is dropped from a segment's tokens, in place:
+ *  `NAME ( )` ({@link isDefinitionName}), and `function NAME [( )]` — a bare `function` at command position, a name of any
+ *  spelling. The lexer puts the body's compound command back at command position after the head, so a definition
+ *  nested in a body is dropped the same way; after a drop the token that moved up is looked at again. Answers where the
+ *  heads stood: entry `k` counts the heads dropped right before the token now at `k` (the last entry, past the last
+ *  token, a head whose body opens in a later segment). */
+export declare function dropDefinitionHeads(tokens: LexedToken[]): readonly number[];
+/**
+ * What a word holds through the names it refers to — `$NAME`, `${NAME}`, a leading `~` (the value of `HOME`):
+ *  · `undefined` — it refers to no name (it reads as written);
+ *  · its values — every combination of the values its names may hold here (a piece the shell globs keeps its written
+ *    pattern, and the value is then a pattern);
+ *  · `"unknown"` — a name it refers to is not settled here, it carries an expansion no name answers (a modifier, a
+ *    substitution, a brace list, `~user`), an UNQUOTED expansion's value is not one word or `IFS` may have changed
+ *    (`quoted` = the whole word is read as one value: an assignment's value, which is never split), or it would list
+ *    more than {@link WORD_VALUES_MAX} values.
+ * `table.stateOf` is read after `overlay` (the names the same segment bound earlier).
+ */
+export declare function wordValues(word: Pick<LexedWord, "pieces">, table: BindingTable | undefined, quoted: boolean, overlay?: ReadonlyMap<string, NameState>): readonly BoundValue[] | "unknown" | undefined;
+/**
+ * The spellings a word the table leaves unknown may still take through the deny floors of the names it refers to
+ * ({@link BindingTable.floorOf}) — `${A[k]}`, `${A[@]}`, `$A` reading an array's elements — or through their values where
+ * known: for the deny judge alone. Empty where some name it refers to leaves neither.
+ */
+export declare function wordFloorValues(word: Pick<LexedWord, "pieces">, table: BindingTable | undefined): readonly BoundValue[];
+/** What a VALUE word holds (an assignment's value, a `for` list word): {@link wordValues}, or — a word referring to no
+ *  name — its own text (a word the shell globs is a pattern; one carrying any other expansion holds what the text does
+ *  not say). */
+export declare function valueOf(word: Pick<LexedWord, "pieces">, table: BindingTable | undefined, quoted: boolean, overlay?: ReadonlyMap<string, NameState>): NameState;
+/**
+ * What ONE segment does to the names (see the module header). `argv` = the segment's argv projection (structure
+ * dropped); `readValue` folds a value word against the table (a reader that answers `unknown` gives the names alone).
+ */
+export declare function bindingEffectOf(segment: LexedSegment, argv: readonly LexedWord[], shape: SegmentShape, readValue: ValueReader): BindingEffect;
+/**
+ * The names an ARITHMETIC text may assign: every identifier in a text that carries an assignment operator (`=` that is no
+ * comparison, `+=` and its kin, `++`, `--`) — read whole, not parsed: a name only compared there is made unknown too.
+ */
+export declare function arithmeticAssignedNames(text: string): string[];
+/** The names a text binds anywhere (every segment, every name the binding rule reads), or `all` where it may bind any
+ *  name — for a body that runs later. Unreadable text binds any. */
+export declare function namesBoundIn(text: string, depth?: number): ReadonlySet<string> | "all";
+/**
+ * Does this text bind `HOME` anywhere (or every name)? — the question a reader that spells the declared home for `~` /
+ * `$HOME` asks of a text it reads as ONE unit (the read-only classifier's segments). The read station asks the
+ * threaded question instead ({@link BindingThread}).
+ */
+export declare function textBindsHome(text: string): boolean;
+/** What a name holds at one point of a text, asked by name ({@link BindingTable.stateOf}). */
+export type NameReader = (name: string) => NameState;
+/** What holds for the names where a nested text starts, given by the text around it: the attributes
+ *  ({@link NameAttribute}) and whether a name reference was declared — a substitution body starts with what may run
+ *  before its segment, a text run later or elsewhere (a code body, `eval`'s text, a child shell's `-c`) with all the
+ *  text around it gives. */
+export interface InheritedNames {
+    readonly attributes: readonly NameAttribute[];
+    readonly references: boolean;
+}
+/** What the thread answers for one reader: what a name may hold, and whether a name carries the integer attribute. */
+export interface BindingTable {
+    stateOf(name: string): NameState;
+    /** Values assigned to this name are evaluated as arithmetic. */
+    isInteger(name: string): boolean;
+    /** The text may have changed `IFS` before this point: an unquoted expansion is split on what the text does not say. */
+    readonly ifsTouched: boolean;
+    /** `HOME` may hold something other than the declared home here. */
+    readonly homeTouched: boolean;
+    /** Every spelling any binding of this name before here left for the deny judge alone ({@link Binding.floor}). */
+    floorOf(name: string): readonly BoundValue[];
+    /** What a substitution body here starts with. */
+    readonly inherited: InheritedNames;
+}
+/**
+ * The effects of a text's segments, threaded the way the plan threads its working directory: a reader at segment `j`
+ * sees the latest binding of a name, and, where that binding may not have run before `j`, the bindings before it too.
+ * A binding is CERTAIN for `j` when no block holding it (a branch, a loop, a group) closes or switches branch between it
+ * and `j` — a block it precedes may come and go — its segment is no pipeline member, background job or prefix
+ * assignment, and — reached through `&&` / `||` — it lies in `j`'s own `&&` run (`andRunStart`: the same index the
+ * working-directory thread reads).
+ *
+ * A function body runs at its call, and the plan does not follow calls (a function may be called anywhere after its
+ * definition — through a wrapper word, `eval`, `trap`, `source`, another function): a name bound in a body is
+ * {@link Unreadable} to every reader past the body, a later assignment included, and to every reader in another body;
+ * the body's own readers follow its own order. A name the body declares with a plain `local` (before the binding,
+ * where the declaration certainly ran) never leaves it.
+ *
+ * An attribute ({@link NameAttribute}) and a name reference hold for every segment they may RUN before — a later one,
+ * one in a function body, one in the same loop body: an assignment there binds something other than its text.
+ */
+export declare class BindingThread {
+    private readonly segments;
+    /** What each segment binds, its names alone (a value is the reader's to read). */
+    private readonly named;
+    /** The state a name starts the text in (and is reset to by a function body): the declared home for `HOME`. */
+    private readonly initial;
+    /** Names any segment of the text binds (a function body run later reads a `HOME` bound anywhere as unknown). */
+    private readonly boundAnywhere;
+    /** Each loop head's segment and its matching `done`'s. */
+    private readonly loops;
+    /** `HOME` may already hold something other than the declared home where the text starts (a substitution body
+     *  inside a text that bound it). */
+    private readonly homeStartsTouched;
+    private readonly entries;
+    /** The attributes the text gives ({@link BindingEffect.attributes}), and where — read off its names alone, before any
+     *  reader: one given later in the text may run first. */
+    private readonly attributesAt;
+    /** Names no assignment makes readable again ({@link Unreadable}). */
+    private readonly unreadable;
+    /** The block nesting each segment moves ({@link blockStructure}). */
+    private readonly blocks;
+    /** Segments that are a pipeline member or run in the background. */
+    private readonly detached;
+    constructor(segments: readonly LexedSegment[], 
+    /** What each segment binds, its names alone (a value is the reader's to read). */
+    named: readonly BindingEffect[], 
+    /** The state a name starts the text in (and is reset to by a function body): the declared home for `HOME`. */
+    initial: (name: string) => NameState, 
+    /** Names any segment of the text binds (a function body run later reads a `HOME` bound anywhere as unknown). */
+    boundAnywhere: (name: string) => boolean, 
+    /** Each loop head's segment and its matching `done`'s. */
+    loops: ReadonlyMap<number, number>, 
+    /** `HOME` may already hold something other than the declared home where the text starts (a substitution body
+     *  inside a text that bound it). */
+    homeStartsTouched?: boolean, 
+    /** What holds where the text starts: given before its first segment. */
+    inherited?: InheritedNames);
+    /** What a text nested at segment `j` starts with ({@link InheritedNames}) — `j` absent: a text run later, which every
+     *  segment may run before. */
+    inheritedAt(j?: number): InheritedNames;
+    /** What segment `at` makes unreadable: in a function body, the names it binds (unless the body declared them `local`
+     *  where the declaration certainly ran) — every name where it may bind any; a name reference, every name. */
+    private unreadableBy;
+    /** May segment `x` run before segment `e` runs (`x` being `e`: before a later run of it): `x` comes first in the text,
+     *  `e` stands in a function body (the body runs at its call, after any segment, and may run again), or both stand in
+     *  one loop's body (a later beat runs `x` again first). */
+    private mayRunBefore;
+    /** Did the body certainly declare this name `local` before segment `at`: an earlier segment of the body, run on its
+     *  own (no `&&` / `||`, no pipeline member or background job), in a block still open at `at`. */
+    private declaredLocal;
+    /** Does the block that holds segment `at`'s words stay open (no closing word, no switch of branch) through `j`? */
+    private heldThrough;
+    /** Apply segment `at`'s effect. `andRun`: the segment was reached through `&&` / `||`. `loopEnd`: for a loop variable,
+     *  the index of the loop's end. */
+    apply(at: number, effect: BindingEffect, andRun: boolean, loopEnd?: number): void;
+    /** Has the function body a binding at segment `at` was made in closed by segment `j`? */
+    private leftBody;
+    /** Make these names unknown from segment `at` on (a loop body that binds them may have run before any of its beats). */
+    kill(at: number, names: Iterable<string> | "all"): void;
+    /** The table a reader at segment `j` sees; `andRunStart` = the first segment of `j`'s `&&` run. */
+    tableAt(j: number, andRunStart: number): BindingTable;
+}
+/** A segment that opens with `((`: an arithmetic command (or a subshell in a subshell — the tokens are the same). */
+export declare function isArithmeticCommand(segment: LexedSegment): boolean;
+/** The `[[` operators whose operands the arithmetic evaluator reads (`[[ x -eq y ]]`; `[` / `test` compare integers
+ *  without evaluating them). */
+export declare const ARITHMETIC_TEST_OPERATORS: ReadonlySet<string>;
+/** The substitutions a parameter expansion's body hands the arithmetic evaluator: its subscript (`${a[…]}`) and the
+ *  offset and length of a substring expansion (`${x:off:len}` — the shell expands them, then evaluates them). */
+export declare function parameterBodySubstitutions(name: string, body: string, table: BindingTable | undefined): string[];
+/**
+ * The substitutions the shell's ARITHMETIC evaluator runs while it evaluates `text`: every `$(…)`, backquote or process
+ * substitution inside an array SUBSCRIPT of it (`a[$(…)]` — quoted or not: the evaluator re-reads the text it is
+ * handed), and — for each name the text refers to whose value the table holds — the same of that value (the evaluator
+ * evaluates a variable's value as arithmetic too, through any chain of names). A name the table does not settle
+ * contributes the literal values its bindings left (an array's elements) and nothing else: any other value is data the
+ * text does not hold. A name already on the chain is a cycle (bash refuses
+ * it). Each body is shell text the evaluator re-enters; past the reader's budget of values the text itself is handed
+ * back as a body, so the segment re-enters text it did not follow (unestablished, never silent).
+ */
+export declare function arithmeticSubstitutions(text: string, table: BindingTable | undefined, chain?: ReadonlySet<string>, budget?: {
+    left: number;
+}): string[];
+/** The text of every `[…]` subscript in an arithmetic text (nested brackets balanced; an unclosed one runs to the end). */
+export declare function subscriptsOf(text: string): string[];
+export {};