@sema-agent/core 7.47.0 → 7.49.0

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

@@ -0,0 +1,80 @@
+/**
+ * Where a text the read plan (`shell-read-plan.ts`) plans starts: a nested text's start — its names, the deny floors the
+ * words handing it on carry, the user its shell runs as, its standard input and its working directory — and where each
+ * segment's standard input comes from. A nested plan parsed against the declarations' working directory is re-based onto
+ * the segment it sits in ({@link rebasePlan}), unless it starts in a working directory of its own.
+ */
+import type { LexedSegment } from "../../shell/lex.js";
+import type { BindingTable, FloorValue, InheritedFunctions, NameReader } from "./shell-read-bindings.js";
+import type { TargetUser } from "./program-read-model.js";
+import type { StdinText } from "./shell-reentry-text.js";
+import type { ReadCandidate, ShellReadPlan } from "./shell-read-plan.js";
+/** Where a nested text starts its names: a substitution body inherits the table of the segment it sits in (a subshell
+ *  holds every variable of the shell that forks it); a text the shell runs later or elsewhere (a code body, `eval`'s
+ *  text, a child shell's `-c`) starts from the text's own start — every name unknown, `HOME` the declared home unless
+ *  the enclosing text binds it anywhere. `boundAnywhere` answers for the enclosing texts. */
+export interface PlanStart {
+    readonly initial: NameReader;
+    readonly boundAnywhere: (name: string) => boolean;
+    /** `HOME` may already hold something other than the declared home where the nested text starts. */
+    readonly homeTouched: boolean;
+    /** The attributes, name references and deny floors in force where the nested text starts. */
+    readonly inherited: BindingTable["inherited"];
+    /** The working directories it starts in, where they are not the enclosing segment's (a login shell starts in its user's
+     *  home; `"unmodelled"` — a home the text does not settle). */
+    readonly bases?: readonly string[] | "unmodelled";
+    /** The thread of the shell that runs the text, where the text runs in that shell or a fork of it ({@link HeldThread}). */
+    readonly thread?: HeldThread;
+    /** What the shell around the text holds where the text runs in that shell or a fork of it — a literal `eval` text, a
+     *  substitution body, a text run later (a `trap` action): each function and builtin key as it stands there
+     *  ({@link InheritedFunctions}). A text a new process runs (a child shell's `-c`) holds none: every builtin enabled, no function. */
+    readonly names?: InheritedFunctions;
+    /** What arrives on its own standard input (the input of the shell running it). */
+    readonly stdin?: readonly StdinText[];
+}
+/** The thread of the shell that runs a text, at the segment that hands it on: a literal `eval` text is not a new plan but the next
+ *  segment of the same thread, so it starts in all of it and hands the working directory and the physical mode back; a substitution
+ *  body (a fork) and a text run later start in what the shell holds and hand nothing back. `functions`: the names a call may mean
+ *  (the shell's definition heads and the ones an `eval` text defines), `unread` those whose bodies the nested plan has not read — an
+ *  `eval` text reads the shell's bodies through the names they bind, every other text has none of them in front of it. */
+export interface HeldThread {
+    readonly physical: boolean;
+    readonly functions: ReadonlySet<string>;
+    readonly unread: ReadonlySet<string>;
+}
+/** What a shell holds at a segment, for a text that runs in it or in a fork of it ({@link PlanStart.names}): each function and builtin key
+ *  as it stands there, and the names a call to one of its functions may change — the ones the text reads a call of: an `eval` text names
+ *  the shell's functions (`bound`: what a call to one of them changes); a substitution body and a text run later read none of their bodies
+ *  (the shell's functions are {@link HeldThread.unread} there: a call to one makes every name unknown), so they name none. */
+export declare function heldAt(table: BindingTable, bound?: InheritedFunctions["bound"]): InheritedFunctions;
+/** What a segment says of the start of a text it hands a shell to run later: the deny floors of the words it holds as
+ *  written, the user the shell runs as ({@link TargetUser}), and the shell's standard input. */
+export interface NestedStart {
+    readonly floors?: ReadonlyMap<string, readonly FloorValue[]>;
+    readonly as?: TargetUser;
+    readonly stdin?: readonly StdinText[];
+}
+/** Where a text run later starts ({@link NestedStart}): the later start, with the shell's standard input, the floors of the
+ *  words that hand it on, and — run as another user — that user's `HOME` (the caller's, the target's, or either) and, for
+ *  a login shell, the target's home as its working directory. */
+export declare function startedAt(later: PlanStart, at: NestedStart | undefined): PlanStart;
+/** A planner that plans each text once per start: a segment read in several readings hands most of its nested texts (a
+ *  substitution's body, a launched shell's text) on alike in every reading. */
+export declare function plannedOnce<K, P>(plan: (text: string, kind: K, at?: NestedStart) => P): (text: string, kind: K, at?: NestedStart) => P;
+/**
+ * What arrives on each segment's standard input: the pipe it is reached through (`piped`, what the segment before it
+ * prints); else the input of the group (`{ …; }`, `( … )`) it stands in — a group a pipe feeds hands each member that
+ * pipe; else the input the text itself was handed (`start`: a shell's `-c` text reads that shell's standard input).
+ */
+export declare function stdinFeeds(segments: readonly LexedSegment[], start: readonly StdinText[], piped: (si: number) => readonly StdinText[]): (si: number) => readonly StdinText[];
+/**
+ * A nested plan (a substitution body, a here-document's substitution, a launcher's command string) was parsed
+ * against the declarations' working directory; the segment it sits in may stand elsewhere (`cd sub && cat <<EOF
+ * $(cat secret)`), so its relative candidates are re-based onto the ENCLOSING segment's bases — every base the
+ * nested text derived from the start is carried over by prefix, an unsettled enclosing base leaves every
+ * relative candidate unplaced, and absolute candidates are untouched. Recursive: a nested plan's own nested plans
+ * derive from the same start. A candidate left unplaced is judged where the text stood when it lost track (its floor,
+ * {@link ReadCandidate.floorBases}): the places the nested text was in move with it like its bases, and an enclosing segment that
+ * lost its base itself hands on its own floor (`floor`).
+ */
+export declare function rebasePlan(plan: ShellReadPlan, from: string, to: ReadCandidate["bases"], floor?: readonly string[]): ShellReadPlan;

package/dist/tools/fs/shell-read-start.js

@@ -0,0 +1,99 @@
+const NO_NAMES = new Set();
+export function heldAt(table, bound = NO_NAMES) {
+    return { start: (key) => table.stateOf(key), bound };
+}
+const ROOT_HOMES = ["/root", "/var/root"];
+export function startedAt(later, at) {
+    if (at === undefined)
+        return later;
+    const fed = at.stdin !== undefined && at.stdin.length > 0 ? { ...later, stdin: at.stdin } : later;
+    const withFloors = at.floors === undefined || at.floors.size === 0 ? fed : { ...fed, inherited: { ...fed.inherited, floors: joinedFloors(fed.inherited.floors, at.floors) } };
+    const as = at.as;
+    if (as === undefined || as.home === "caller")
+        return withFloors;
+    const homes = as.name === "root" ? ROOT_HOMES : undefined;
+    const target = homes === undefined ? "unknown" : homes.map((spelled) => ({ spelled }));
+    const caller = later.initial("HOME");
+    const home = as.home === "target" ? target : caller === "unknown" || target === "unknown" ? "unknown" : [...caller, ...target];
+    return {
+        ...withFloors,
+        initial: (name) => (name === "HOME" ? home : withFloors.initial(name)),
+        homeTouched: true,
+        ...(as.login ? { bases: homes ?? "unmodelled" } : {}),
+    };
+}
+export function plannedOnce(plan) {
+    const planned = new Map();
+    return (text, kind, at) => {
+        const key = JSON.stringify([kind, text, [...(at?.floors ?? [])], at?.as, at?.stdin]);
+        if (!planned.has(key))
+            planned.set(key, plan(text, kind, at));
+        return planned.get(key);
+    };
+}
+function joinedFloors(a, b) {
+    const out = new Map(a);
+    for (const [name, floors] of b)
+        out.set(name, [...(out.get(name) ?? []), ...floors]);
+    return out;
+}
+export function stdinFeeds(segments, start, piped) {
+    const opener = [];
+    const enclosing = [];
+    const open = [];
+    segments.forEach((segment, si) => {
+        enclosing[si] = open.at(-1);
+        let opens = false;
+        for (const t of segment.tokens) {
+            if ((t.kind === "group" && t.op === "(") || (t.kind === "word" && t.raw === "{")) {
+                open.push(si);
+                opens = true;
+            }
+            else if ((t.kind === "group" && t.op === ")") || (t.kind === "word" && t.raw === "}"))
+                open.pop();
+        }
+        opener[si] = opens ? si : enclosing[si];
+    });
+    const fedAt = (si) => {
+        if (si > 0 && segments[si].connector === "|")
+            return [...new Map(piped(si).map((s) => [JSON.stringify(s), s])).values()];
+        const group = opener[si] !== si ? opener[si] : enclosing[si];
+        return group !== undefined ? fedAt(group) : start;
+    };
+    return fedAt;
+}
+export function rebasePlan(plan, from, to, floor) {
+    if (to !== "unmodelled" && to.length === 1 && to[0] === from)
+        return plan;
+    const fromSep = from.endsWith("/") || from.endsWith("\\") ? from : `${from}/`;
+    const moveInto = (into, b) => {
+        if (b === from)
+            return [...into];
+        if (b.startsWith(fromSep))
+            return into.map((t) => `${t.endsWith("/") || t.endsWith("\\") ? t : `${t}/`}${b.slice(fromSep.length)}`);
+        return [b];
+    };
+    const moveBase = (b) => (to === "unmodelled" ? [] : moveInto(to, b));
+    const floorAt = to === "unmodelled" ? floor : to;
+    const moveFloor = (bases, into) => [...new Set(bases.flatMap((b) => moveInto(into, b)))];
+    const moveCandidate = (c) => {
+        if (c.bases === "unmodelled")
+            return c.floorBases === undefined || floorAt === undefined ? c : { ...c, floorBases: moveFloor(c.floorBases, floorAt) };
+        if (c.bases.length === 0)
+            return c;
+        if (to === "unmodelled")
+            return floor === undefined ? { ...c, bases: "unmodelled" } : { ...c, bases: "unmodelled", floorBases: moveFloor(c.bases, floor) };
+        return { ...c, bases: [...new Set(c.bases.flatMap(moveBase))] };
+    };
+    return {
+        ...plan,
+        segments: plan.segments.map((s) => ({
+            ...s,
+            reads: s.reads.map(moveCandidate),
+            redirects: s.redirects.map((r) => (r.target === undefined ? r : { ...r, target: moveCandidate(r.target) })),
+            ...(s.baseMove !== undefined ? { baseMove: { target: typeof s.baseMove.target === "string" ? s.baseMove.target : moveCandidate(s.baseMove.target) } } : {}),
+            bases: s.bases === "unmodelled" || to === "unmodelled" ? "unmodelled" : [...new Set(s.bases.flatMap(moveBase))],
+            nested: s.nested.map((n) => rebasePlan(n, from, to, floor)),
+        })),
+    };
+}

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

@@ -18,7 +18,7 @@ export interface Read {
     readonly raw: string;
     readonly folded: string;
     /** A pattern's names are matched by this spelling where it is not {@link folded} (a class the judge widens, read as
-     *  any one character — {@link LexedWord.judged}, {@link patternOf}); `folded` stays the name opened where none match. */
+     *  any one character — {@link LexedWord.judged}, {@link judgedSpellingOf}); `folded` stays the name opened where none match. */
     readonly pattern?: string;
     readonly expands: WordExpands;
     /** The names the word refers to were read through the table: its expansion IS the spelling above (and, where the
@@ -38,17 +38,46 @@ export interface Read {
 /** The reads of a segment's words against the binding table at that segment (`homeDir` = the declared home, the
  *  state `HOME` starts in). A word that refers to no name, or only to a `HOME` the text has not touched (`~/x`, placed
  *  by the establishment at the declared home), reads as written. */
-export declare function readsOf(words: readonly LexedWord[], table: BindingTable | undefined, homeDir: string | undefined): Read[];
+export declare function readsOf(words: readonly LexedWord[], table: BindingTable | undefined, homeDir: string | undefined, split?: boolean): Read[];
+/** One reading of a segment: the binding table with each name its words read held to ONE value (or, past
+ *  {@link READINGS_MAX}, made unknown — every value it held stays a deny-floor spelling, {@link BindingTable.floorOf}),
+ *  the reads of its argv against it ({@link readsOf}), and the argv the shell hands the program in it — a word whose
+ *  names settle into one value that is no pattern is that value, as a literal word (a reader of the program position,
+ *  of a launcher's fields, of a program's options reads it as it reads a literal word); any other word as written, its
+ *  names' deny floors in `floors` (a shell that re-reads the word — `sh -c`, `eval`, a launcher's shell — starts with
+ *  them: the word names in that text what it names here). */
+export interface SegmentReading {
+    readonly table: BindingTable;
+    readonly reads: readonly Read[];
+    readonly argv: readonly LexedWord[];
+    readonly floors: ReadonlyMap<string, readonly FloorValue[]>;
+}
+/**
+ * The readings of one segment's words (its argv and its redirection targets): the names they read through the table that
+ * may hold several values here, in the order the words read them (the program position first), each held to one value
+ * per reading — every combination while the readings stay within {@link READINGS_MAX}, so the program position, a
+ * launcher's fields, a re-entered text and an operand are spelled from the same values (`$P` read twice takes one value
+ * in a reading: the shell expands both alike); a name past that bound is unknown in every reading — its word as written,
+ * every value it held a deny floor — never a sample of its combinations. A segment whose names hold one value each has
+ * one reading.
+ */
+export declare function segmentReadingsOf(argv: readonly LexedWord[], targets: readonly LexedWord[], table: BindingTable, homeDir: string | undefined): SegmentReading[];
 /** The spelling a reader names a value by, read directly as a path — for a pattern, the name the program opens where it
  *  matches nothing: its text, a leading `~` spelled as the literal tilde it is ({@link literalTildeSpelling}, the lexer's
  *  spelling of a written one) — the shell never tilde-expands what a quoted piece or an expansion produced, so a value that
  *  starts with `~` starts with a literal one (`X=/w; rm \~$X/*` reads `./~/w/*`, as `rm \~/w/*` does). A shell that
  *  re-parses the value reads {@link programTextOf} instead. */
 export declare const spellingOf: (v: BoundValue) => string;
-/** The spelling a pattern value's names are matched by, where it is not {@link spellingOf}: its runs as a reader judges
- *  them (a class the judge widens as `?`, the lexer's `WordExpansion.pattern.judged`) — a candidate's
- *  `pattern`. */
-export declare function patternOf(v: BoundValue): string | undefined;
+/** The pattern a PART of a pattern word is matched by (an option value attached to its option word, `--file=["!"a]*`; an
+ *  assignment-shaped word's value, `if=["!"a]*`): the word's own judged spelling (`pattern`) past the text in front of
+ *  the part — bash expands the WHOLE word, so the names the part may take are those the word's widened spelling reaches
+ *  (a superset: a name is judged whether or not the word in front of it matches too). `undefined` where the word carries
+ *  none, the part is not the end of the word's spelling, or the text in front holds a widened class itself (its judged
+ *  spelling no longer lines up). */
+export declare function partPattern(word: {
+    readonly folded: string;
+    readonly pattern?: string;
+}, part: string): string | undefined;
 /** A candidate under another name (a value of several, a backup, a copy's child): the word's `pattern` matched the word,
  *  not that name — the name is matched by its own text. */
 export declare function renamed<C extends {

package/dist/tools/fs/shell-read-word.js

@@ -1,13 +1,13 @@
 import { argvOf, lexShell, literalTildeSpelling, UNRESOLVED_SENTENCE } from "../../shell/lex.js";
 import { expansionInWord, extglobOpenerIn, globInWord, homeExpansionOf } from "./bash-readonly-classifier.js";
-import { wordFloorValues, wordValues } from "./shell-read-bindings.js";
-export function readsOf(words, table, homeDir) {
+import { floorOf, judgedSpellingOf, namesIn, wordFloorValues, wordValues } from "./shell-read-bindings.js";
+export function readsOf(words, table, homeDir, split = false) {
     return words.map((word) => {
-        const refersToName = word.pieces.some((p) => p.expansion?.kind === "parameter");
+        const refersToName = word.pieces.some((p) => p.expansion?.kind === "parameter") || namesIn(word).length > 0;
         const asWritten = { word, raw: word.raw, folded: word.folded, ...(word.judged !== undefined ? { pattern: word.judged } : {}) };
         if (!refersToName && table?.homeTouched !== true)
             return { ...asWritten, expands: expandsOf(word) };
-        const values = wordValues(word, table, false);
+        const values = wordValues(word, table, false, undefined, split);
         if (values === undefined)
             return { ...asWritten, expands: expandsOf(word) };
         if (values === "unknown") {
@@ -18,7 +18,7 @@ export function readsOf(words, table, homeDir) {
         const refersToHome = word.pieces.some((p) => p.expansion?.kind === "tilde" || (p.expansion?.kind === "parameter" && p.expansion.name === "HOME"));
         const declared = refersToHome && homeDir !== undefined && table?.homeTouched === true ? wordValues(word, table, false, new Map([["HOME", [{ spelled: homeDir }]]])) : undefined;
         const floor = declared !== undefined && declared !== "unknown" && declared[0] !== undefined ? spellingOf(declared[0]) : undefined;
-        const pattern = patternOf(values[0]);
+        const pattern = judgedSpellingOf(values[0]);
         return {
             word,
             raw: word.raw,
@@ -31,12 +31,92 @@ export function readsOf(words, table, homeDir) {
         };
     });
 }
+const READINGS_MAX = 64;
+export function segmentReadingsOf(argv, targets, table, homeDir) {
+    const several = new Map();
+    for (const word of [...argv, ...targets]) {
+        for (const name of namesReadIn(word, table)) {
+            const state = table.stateOf(name);
+            if (state !== "unknown" && state.length > 1)
+                several.set(name, state);
+        }
+    }
+    let overlays = [new Map()];
+    const past = [];
+    for (const [name, values] of several) {
+        if (past.length > 0 || overlays.length * values.length > READINGS_MAX) {
+            past.push(name);
+            continue;
+        }
+        overlays = overlays.flatMap((o) => values.map((v) => new Map(o).set(name, [v])));
+    }
+    for (const o of overlays)
+        for (const name of past)
+            o.set(name, "unknown");
+    return overlays.map((overlay) => {
+        const reading = overlay.size === 0 ? table : overlaidTable(table, overlay);
+        const fielded = readsOf(argv, reading, homeDir, true).flatMap((r) => {
+            const fields = r.values?.length === 1 ? r.values[0].fields : undefined;
+            return fields === undefined ? [r] : fields.map((f) => ({ word: argumentWordOf(f, f) ?? r.word, raw: f, folded: spellingOf({ spelled: f }), expands: false, settled: true, values: [{ spelled: f }] }));
+        });
+        const floors = new Map();
+        for (const r of fielded) {
+            if (r.settled === true)
+                continue;
+            for (const p of r.word.pieces) {
+                const name = p.expansion?.kind === "parameter" ? p.expansion.name : undefined;
+                if (name === undefined)
+                    continue;
+                const held = reading.stateOf(name);
+                const floor = [...(held === "unknown" ? [] : held.map(floorOf)), ...reading.floorOf(name)];
+                if (floor.length > 0)
+                    floors.set(name, floor);
+            }
+        }
+        return { table: reading, reads: fielded, argv: fielded.map((r) => valuedWord(r.word, r)), floors };
+    });
+}
+function namesReadIn(word, table) {
+    return [...namesIn(word), ...(table.homeTouched && word.pieces.some((p) => p.expansion?.kind === "tilde" && p.expansion.body === "~") ? ["HOME"] : [])];
+}
+function overlaidTable(table, overlay) {
+    return {
+        stateOf: (name) => overlay.get(name) ?? table.stateOf(name),
+        isInteger: (name) => table.isInteger(name),
+        ifsTouched: table.ifsTouched,
+        homeTouched: table.homeTouched,
+        rebound: table.rebound,
+        providedByShell: (name) => table.providedByShell(name),
+        functionState: (name) => table.functionState(name),
+        builtinState: (name) => table.builtinState(name),
+        floorOf: (name) => {
+            const held = table.stateOf(name);
+            return overlay.get(name) !== "unknown" || held === "unknown" ? table.floorOf(name) : [...table.floorOf(name), ...held.map(floorOf)];
+        },
+        inherited: table.inherited,
+    };
+}
+function valuedWord(word, r) {
+    const v = r.values?.length === 1 ? r.values[0] : undefined;
+    if (word.assignment !== undefined || v === undefined || v.glob === true || v.spelled === word.folded)
+        return word;
+    return argumentWordOf(v.spelled, r.raw) ?? word;
+}
+function argumentWordOf(text, raw) {
+    const quoted = text.replace(/[^A-Za-z0-9_./+@:%=,-]/g, (c) => (c === "'" ? "\\'" : `'${c}'`));
+    const lexed = lexShell(`: ${quoted === "" ? "''" : quoted}`);
+    const words = "parseFailure" in lexed || lexed.segments.length !== 1 ? undefined : argvOf(lexed.segments[0]);
+    return words?.length === 2 ? { ...words[1], raw } : undefined;
+}
 export const spellingOf = (v) => literalTildeSpelling(v.spelled);
-export function patternOf(v) {
-    if (v.glob !== true)
+export function partPattern(word, part) {
+    if (word.pattern === undefined || part === word.folded || !word.folded.endsWith(part))
+        return undefined;
+    const front = word.folded.slice(0, word.folded.length - part.length);
+    if (!word.pattern.startsWith(front))
         return undefined;
-    const judged = literalTildeSpelling(v.parts.map((p) => (p.pattern ? p.judged : p.text)).join(""));
-    return judged === spellingOf(v) ? undefined : judged;
+    const judged = word.pattern.slice(front.length);
+    return judged === part ? undefined : judged;
 }
 export function renamed(c, spelled) {
     const { pattern: _matched, ...rest } = c;

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

@@ -0,0 +1,156 @@
+/**
+ * THE WORKING-DIRECTORY THREAD — where a command stands at each of its segments, and what `PWD` / `OLDPWD` hold there.
+ * ONE walk (`shell-read-plan.ts` drives it, segment by segment, beside the binding thread) over a CLOSED word set that
+ * moves the base ({@link BaseShift}): `cd` in its forms — a bare relative target searched through `CDPATH` first, `cd -`
+ * going to `OLDPWD`, a bare `cd` to `HOME`, `-P` / `set -P` leaving `PWD` a spelling the text does not hold — `pushd` /
+ * `popd` with the stack the text pushed, and a literal `eval` text read as the text it is, in this shell. Any other text
+ * that may move the base where the plan cannot follow it (`source`, a non-literal `eval`, a computed program word, a
+ * call into a function body or a code body that may move, an option the stack reading does not follow) LOSES it: what
+ * stands after it cannot be placed. A move inside a subshell, a pipeline member or a function body nobody called is read
+ * as a move too — a candidate SET, more places, never fewer (a move may also fail: the unmoved place stays a candidate
+ * unless an `&&` run proves the move ran).
+ */
+import type { Bare } from "./shell-read-argv.js";
+import type { BindingTable, WorkingDirectoryState } from "./shell-read-bindings.js";
+import type { Read } from "./shell-read-word.js";
+import { type LexedWord } from "../../shell/lex.js";
+import { type FunctionCall } from "./shell-read-functions.js";
+/** A working directory the shell could be standing in, with the latest move this candidate assumes did NOT run
+ *  (`skippedCd`), and what the shell holds there: `pwd` — what `PWD` spells (absent: not the base's spelling — a physical
+ *  move, or a start the plan does not place), `old` — what `OLDPWD` holds (absent: what the shell inherited, unknown),
+ *  `stack` — the directories the text pushed and has not popped, top first (absent: the text changed the stack in a way
+ *  this walk does not follow; what lies below the text's own entries is the shell's, unknown). */
+export interface BaseCandidate {
+    readonly base: string;
+    readonly skippedCd: number;
+    readonly pwd?: string;
+    readonly old?: string;
+    readonly dirStack?: readonly string[];
+}
+/** How one segment moves the base — the closed word set. `cd`: a `cd` (`push`: a `pushd DIR`) to a target, the
+ *  declared-home spelling of an unsettled target for the deny floor; `swap`: `pushd` with no directory; `pop`: `popd`;
+ *  `stack`: the stack changes and the base does not (`pushd -n`, `popd -n`, `dirs -c`); `eval`: a literal `eval` text;
+ *  `lost`: a move this walk does not follow. */
+export type BaseShift = {
+    readonly kind: "cd";
+    readonly target: Bare | "home" | "previous";
+    readonly physical: boolean;
+    readonly push?: true;
+} | {
+    readonly kind: "swap" | "pop" | "stack" | "lost";
+} | {
+    readonly kind: "eval";
+    readonly text: string;
+};
+/** What the walk asks of the plan around it: the declared home (a `~` target), whether the text binds a name anywhere
+ *  (`OLDPWD` — then `cd -` reads the table's value; `PWD` — then a move's `OLDPWD` is not the base the candidate stood
+ *  in), and where a literal `eval` text started at a candidate ends ({@link WorkdirThread.end}). */
+export interface WorkdirContext {
+    readonly homeDir?: string;
+    readonly textBinds: (name: string) => boolean;
+    readonly evalEnd: (text: string, from: BaseCandidate, table: BindingTable) => {
+        readonly end: readonly BaseCandidate[] | "unmodelled";
+        readonly physical: boolean;
+    };
+}
+/** One segment's move as the walk applies it: the shift, whether an `&&` run proves it ran, the first segment of the
+ *  reader's `&&` run, the names there, and whether `cdable_vars` may be on (a bare name may be a variable's value). */
+export interface ShiftAt {
+    readonly shift: BaseShift;
+    readonly provable: boolean;
+    readonly andRunStart: number;
+    readonly table: CommandTable;
+    readonly cdable: boolean;
+}
+/** The names at a `cd` segment with the command's own prefix assignments in force (`HOME=/ cd`), and which names those are. */
+export interface CommandTable extends BindingTable {
+    readonly commandSets: ReadonlySet<string>;
+}
+export declare class WorkdirThread {
+    /** The start is where the shell stands (not a placeholder a nested plan is re-based from): `PWD` reads it. */
+    private readonly readable;
+    private candidates;
+    private lostAt;
+    /** The reachable bases at the moment the walk lost track — the deny floor of a word it cannot place. */
+    private floors;
+    /** `set -P` (or `-o physical`) may be on — a text it began in, an `eval` text that set it — : a later move leaves `PWD` a physical
+     *  spelling the text does not hold, and a `..` in a target resolves links the plan cannot see. */
+    private physical;
+    /** The last segment whose move was applied or lost track ({@link WorkingDirectoryState.movedAt}). */
+    private movedAt;
+    constructor(start: readonly BaseCandidate[] | readonly string[] | "unmodelled", 
+    /** The start is where the shell stands (not a placeholder a nested plan is re-based from): `PWD` reads it. */
+    readable: boolean, 
+    /** The physical mode may already be on where the text starts (an `eval` text run in a shell that set it). */
+    startsPhysical?: boolean);
+    get lost(): boolean;
+    get floorBases(): readonly string[] | undefined;
+    /** The candidates a reader whose `&&` run starts at `andRunStart` may stand in. */
+    reachable(andRunStart: number): readonly BaseCandidate[];
+    /** Where the text ends: every candidate, or `unmodelled`. */
+    end(): readonly BaseCandidate[] | "unmodelled";
+    /** What `PWD` / `OLDPWD` hold for a reader whose `&&` run starts at `andRunStart`. */
+    where(andRunStart: number): WorkingDirectoryState;
+    /** `set -P` / `set -o physical`: from here on a move's `PWD` is a physical spelling. */
+    setPhysical(): void;
+    /** Where the text ends the physical mode may be on (an `eval` text hands it back to the shell that ran it). */
+    get mayBePhysical(): boolean;
+    /** Stop placing anything from segment `at` on: the reachable bases (and a target's floor spellings) become the deny floor. */
+    lose(at: number, reachable: readonly BaseCandidate[], floorTargets?: readonly string[]): void;
+    /** Apply segment `si`'s move. */
+    shift(si: number, at: ShiftAt, ctx: WorkdirContext): void;
+    /** Where one candidate goes: the places (the CDPATH entries a bare target is searched through, then the target itself),
+     *  each with the `PWD`, `OLDPWD` and stack the move leaves — or `lost`. */
+    private movedFrom;
+}
+/** Does bash search `CDPATH` for this `cd` target: not an absolute one, not `.` / `..`, not one starting `./` / `../`? */
+export declare function searchesCdPath(dir: string): boolean;
+/** The base shift of a `cd` / `pushd` / `popd` / `dirs` segment, read off its arguments as the program receives them (and
+ *  the move the plan reports for it: a `cd` target, or `unmodelled` for a stack move it cannot name), or `undefined` for
+ *  another program. `targetOf` turns the target word into its candidate (and records it as a read where the caller does). */
+export declare function baseShiftOf(program: string, args: readonly Read[], targetOf: (r: Read) => Bare): {
+    shift: BaseShift;
+    reported?: Bare | "home" | "previous" | "unmodelled";
+} | undefined;
+/** May this text move the base of the shell that runs it: a program of the closed set or one running text in this shell,
+ *  a computed program word, a call into one of `functions` — or text the lexer cannot read? */
+export declare function textMayMove(text: string, functions: ReadonlySet<string>): boolean;
+/** Does this text turn the physical mode on in the shell that runs it? An `eval` text that does is no text to skip. */
+export declare function textSetsPhysical(text: string): boolean;
+/** The table a `cd` / `pushd` reads `HOME`, `CDPATH` and `OLDPWD` from: the segment's own, with each prefix assignment in
+ *  front of the builtin (`HOME=/ cd`, `CDPATH=/ cd usr`) holding its value there — it is in the builtin's environment. A
+ *  prefix value naming an earlier prefix's name (`HOME=/ CDPATH=$HOME cd usr`) reads it as bash 5 does (the earlier
+ *  assignment applied) and as bash 3.2 does (the value before the command): both. */
+export declare function withCommandEnvironment(table: BindingTable, argv: readonly LexedWord[]): CommandTable;
+/** Does this text call one of `functions` (a program word naming one) — or is it text the lexer cannot read? */
+export declare function textCalls(text: string, functions: ReadonlySet<string>): boolean;
+/** May a segment with these words move the base ({@link textMayMove})? */
+export declare function segmentMayMove(argv: readonly LexedWord[], functions: ReadonlySet<string>): boolean;
+/** What the walk reads of a whole text before it walks it: the text's functions (the names a program word can be one of;
+ *  whether it IS one at a segment is the binding thread's answer, `callAt`); per segment whether it may move the base
+ *  ({@link segmentMayMove}), may call a function, runs code bodies later (`trap`, `alias`, …), turns on the physical mode
+ *  (`set -P`, `set -o physical`); whether a function body may move the base; where `cdable_vars` goes on. */
+export interface TextMoves {
+    readonly functions: ReadonlySet<string>;
+    /** The names whose bodies the plan has not read (an `eval` text defined them). */
+    readonly unread: ReadonlySet<string>;
+    readonly mayMove: readonly boolean[];
+    /** Segment `si` may call a function (read before the walk, to bound where bodies run). */
+    readonly mayCallAt: readonly boolean[];
+    /** Segment `si` may run a function body: it may call one, hands a code body to run later, or runs text the plan does not read. */
+    readonly runsBodyAt: readonly boolean[];
+    readonly bodiesAt: readonly (readonly string[])[];
+    readonly physicalAt: readonly boolean[];
+    readonly cdableFrom: number;
+    readonly bodyMoves: boolean;
+    /** The function segment `si`'s program word names where the walk stands (`table`) — {@link functionCallOf}. */
+    callAt(si: number, table: BindingTable): FunctionCall | undefined;
+    /** The segment may call a function a literal `eval` text defined: its body is not read — it may move the base and bind any name. */
+    callsUnread(si: number, table: BindingTable): boolean;
+    /** The segment runs a body that may move the base where the walk cannot follow it: a call when a body may move or whose body is not read, a code body that may move or call one. */
+    losesBaseAt(si: number, table: BindingTable): boolean;
+}
+export declare function textMovesOf(defined: ReadonlySet<string>, argvs: readonly (readonly LexedWord[])[], inFunctionBody: (si: number) => boolean, inherited?: {
+    readonly functions: ReadonlySet<string>;
+    readonly unread: ReadonlySet<string>;
+}): TextMoves;