@sema-agent/core 7.45.0 → 7.46.0

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

@@ -4,24 +4,38 @@
  * (the home-directory word spelled with the declared home, as bash hands it to the program), and what the shell
  * does to the word before the program sees it.
  */
-import { type LexedCommand, type LexedToken, type LexedWord, type WordPiece } from "../../shell/lex.js";
+import { type LexedCommand, type LexedWord, type WordPiece } from "../../shell/lex.js";
+import { type BindingTable, type BoundValue } from "./shell-read-bindings.js";
 /** `"glob"` = an unquoted pathname-expansion character; `"unresolvable"` = the shell rewrites the word (a brace,
  *  variable or command substitution) so its text is not the path. The read candidate's own field, spelled here. */
 export type WordExpands = false | "glob" | "unresolvable";
-/** A word as the candidate readers name it: the lexer's word, the two spellings (the home-directory word spelled
- *  with the declared home — {@link homeExpansionOf} — as bash hands it to the program), and what the shell does
- *  to it before the program sees it. */
+/** A word as the candidate readers name it: the lexer's word, the spelling the program receives — the names the word
+ *  refers to read through the binding table ({@link wordValues}: `"$F"` after `F=/x` is `/x`) — and what the shell does to
+ *  it before the program sees it. */
 export interface Read {
     readonly word: LexedWord;
     readonly raw: string;
     readonly folded: string;
     readonly expands: WordExpands;
-    /** The word spells the declared home: its one expansion IS the spelling above. */
-    readonly homeSpelled?: true;
+    /** The names the word refers to were read through the table: its expansion IS the spelling above (and, where the
+     *  names may hold several values, {@link values}). */
+    readonly settled?: true;
+    /** Every spelling the word may expand to (the first is {@link folded}); present only where there are several. */
+    readonly values?: readonly string[];
+    /** The word refers to `HOME` and `HOME` may hold something other than the declared home here: the spelling the
+     *  word has with the declared home, for the deny judge alone. */
+    readonly homeFloor?: string;
+    /** The word's names are unknown here, but their bindings left spellings for the deny judge (an array's elements):
+     *  what the word may then spell, for the deny judge alone. */
+    readonly floorValues?: readonly BoundValue[];
 }
-export declare function readsOf(words: readonly LexedWord[], home: string | undefined): 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[];
 /** The shell REWRITES this read's word before the program sees it (a parameter, command, process, arithmetic or
- *  brace expansion, or the character of one) — the home word excepted, whose one expansion is its spelling. */
+ *  brace expansion, or the character of one) — a word whose names the table settled excepted: its expansion is its
+ *  spelling. */
 export declare const rewritten: (r: Read) => boolean;
 /** The reading of a text that came out of a word (a sed script's file operand): one shell word, or unresolvable. */
 export declare function readOfText(text: string): Read;
@@ -31,35 +45,24 @@ export declare function readOfText(text: string): Read;
  *  the word is assignment-shaped (`A="$HOME/x"`, `dd if="$HOME/x"`: the candidate is the value, quotes kept);
  *  `undefined` for any other (`~user`, a word that is no home word). */
 export declare function spelledWithHome(spelled: string, raw: string, home: string): string | undefined;
-/** A function definition's head names nothing that runs here and is dropped from a segment's tokens, in place:
- *  `NAME ( )` (an identifier), 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. */
-export declare function dropDefinitionHeads(tokens: LexedToken[]): void;
 /** Why a lexed text's reads cannot all be named — the plan's `unreadable` floor, or `undefined`: the first word whose
  *  value the text does not contain (an unresolved word), or an unquoted extended-glob opener anywhere a word, a
  *  redirection target or a here-document delimiter stands (`pack@(age.json)`, `<<@(x)`). After `shopt -s extglob`
  *  bash expands the pattern (or reads another delimiter) where the lexer reads a split word, so what the text opens is
  *  not what the plan names: the whole text asks, and a deny hit anywhere still refuses. `globs: false` = the text is an
- *  arithmetic expression (`$((2*(3+4)))`), which bash evaluates and never globs. */
+ *  arithmetic expression (`$((2*(3+4)))`), which bash evaluates and never globs. A compound assignment's value is no
+ *  such word: the assignment reads nothing. */
 export declare function unreadableSentenceOf(lexed: LexedCommand, text: string, globs?: boolean): string | undefined;
-/** The elements of a compound array value `(e1 [k]=e2 …)`, read with the one lexer as the words bash assigns (a
- *  `[k]=` subscript prefix dropped): each is a value spelling the deny judge reads, as a scalar value is. The list is
- *  words across lines and comments, so every segment's words count, whatever else a segment carries (a word bash
- *  would reject leaves its siblings readable). None when the list does not lex — the value stays the unread list. */
-export declare function compoundArrayElements(value: {
-    readonly raw: string;
-}): readonly (Read & {
-    readonly denyOnly?: true;
-})[];
 /** An `$((…))` body the shell reads as ARITHMETIC: one parenthesised group spanning the whole body (`(2*(3+4))`),
  *  its bounds read off the lexer's structure — a quoted, escaped or commented parenthesis is text, not a bound — across
  *  the segments the lexer cuts at `&&` `||` `&` `|` and line breaks (operators arithmetic shares with the shell).
  *  `$((cat x); :)` opens the same way but its first group closes early: a command substitution holding a subshell. */
 export declare function isArithmeticBody(body: string): boolean;
-/** What the shell does to a word (or an assignment's value) before the program sees it, read off its pieces. */
+/** What the shell does to a word (or an assignment's value) before the program sees it, read off its pieces: the
+ *  lexer's expansion facts alone. A quoted text that an evaluator or an interpreter later RUNS (an arithmetic
+ *  subscript, an inline program) is no rewrite of the word: the slot it stands in says what it is (the program read
+ *  model's role for it, and the arithmetic rule of `shell-read-bindings.ts`). A substitution is an expansion PIECE
+ *  (command / process / arithmetic), never the placeholder text it leaves in the folded spelling. */
 export declare function expandsOf(w: {
     readonly pieces: readonly WordPiece[];
-    readonly raw: string;
-    readonly folded: string;
 }): WordExpands;

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

@@ -1,14 +1,34 @@
-import { argvOf, lexShell, literalTildeSpelling, UNRESOLVED_SENTENCE } from "../../shell/lex.js";
+import { argvOf, lexShell, UNRESOLVED_SENTENCE } from "../../shell/lex.js";
 import { expansionInWord, extglobOpenerIn, globInWord, homeExpansionOf } from "./bash-readonly-classifier.js";
-export function readsOf(words, home) {
+import { wordFloorValues, wordValues } from "./shell-read-bindings.js";
+export function readsOf(words, table, homeDir) {
     return words.map((word) => {
-        const spelled = home === undefined ? undefined : homeExpansionOf(word, home)?.spelled;
-        if (spelled !== undefined)
-            return { word, raw: spelled, folded: spelled, expands: false, homeSpelled: true };
-        return { word, raw: word.raw, folded: word.folded, expands: expandsOf(word) };
+        const refersToName = word.pieces.some((p) => p.expansion?.kind === "parameter");
+        if (!refersToName && table?.homeTouched !== true)
+            return { word, raw: word.raw, folded: word.folded, expands: expandsOf(word) };
+        const values = wordValues(word, table, false);
+        if (values === undefined)
+            return { word, raw: word.raw, folded: word.folded, expands: expandsOf(word) };
+        if (values === "unknown") {
+            const floors = refersToName ? wordFloorValues(word, table) : [];
+            return { word, raw: word.raw, folded: word.folded, expands: refersToName ? "unresolvable" : expandsOf(word), ...(floors.length > 0 ? { floorValues: floors } : {}) };
+        }
+        const glob = values.some((v) => v.glob === true) || globInWord(word);
+        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]?.spelled : undefined;
+        return {
+            word,
+            raw: word.raw,
+            folded: values[0].spelled,
+            expands: glob ? "glob" : false,
+            settled: true,
+            ...(values.length > 1 ? { values: values.map((v) => v.spelled) } : {}),
+            ...(floor !== undefined && !values.every((v) => v.spelled === floor) ? { homeFloor: floor } : {}),
+        };
     });
 }
-export const rewritten = (r) => r.homeSpelled !== true && expansionInWord(r.word);
+export const rewritten = (r) => r.settled !== true && expansionInWord(r.word);
 export function readOfText(text) {
     const l = lexShell(text);
     const words = "parseFailure" in l || l.segments.length !== 1 ? [] : argvOf(l.segments[0]);
@@ -28,46 +48,18 @@ export function spelledWithHome(spelled, raw, home) {
     const w = readOfText(raw).word;
     return homeExpansionOf(w.assignment !== undefined ? { ...w, pieces: w.assignment.value.pieces } : w, home)?.spelled;
 }
-export function dropDefinitionHeads(tokens) {
-    for (let k = 0; k + 1 < tokens.length; k++) {
-        const [a, b, c, d] = [tokens[k], tokens[k + 1], tokens[k + 2], tokens[k + 3]];
-        if (a.kind === "word" && a.raw === "function" && a.atCommandPosition && b.kind === "word")
-            tokens.splice(k--, c?.kind === "group" && c.op === "(" && d?.kind === "group" && d.op === ")" ? 4 : 2);
-    }
-    for (let k = 0; k + 2 < tokens.length; k++) {
-        const [a, b, c] = [tokens[k], tokens[k + 1], tokens[k + 2]];
-        if (a.kind === "word" && b.kind === "group" && b.op === "(" && c.kind === "group" && c.op === ")" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(a.folded))
-            tokens.splice(k, 3);
-    }
-}
 export function unreadableSentenceOf(lexed, text, globs = true) {
     for (const segment of lexed.segments) {
         for (const token of segment.tokens) {
             const word = token.kind === "word" ? token : token.kind === "redirect" ? token.target : undefined;
+            if (word?.unresolved === "compound_array_value" && word.assignment?.form === "compound")
+                continue;
             if (word?.unresolved !== undefined)
                 return UNRESOLVED_SENTENCE[word.unresolved];
         }
     }
     return globs && extglobOpenerIn(lexed, text) ? "an extended pattern (`?(…)` `*(…)` `+(…)` `@(…)` `!(…)`) is one this reader does not expand" : undefined;
 }
-export function compoundArrayElements(value) {
-    const inner = /^\(([\s\S]*)\)$/.exec(value.raw)?.[1];
-    const l = inner === undefined ? undefined : lexShell(inner);
-    if (l === undefined || "parseFailure" in l)
-        return [];
-    return l.segments.flatMap((sg) => argvOf(sg)).flatMap((element) => {
-        const sub = /^\[[^\]]*\]\+?=/.exec(element.raw)?.[0];
-        const value = sub === undefined ? undefined : readOfText(`V=${element.raw.slice(sub.length)}`).word.assignment?.value;
-        const word = value === undefined ? element : { ...element, raw: value.raw, folded: value.folded, pieces: value.pieces };
-        const tilde = word.pieces.some((q) => q.expansion?.kind === "tilde");
-        const read = { word, raw: word.raw, folded: tilde ? word.folded : literalTildeSpelling(word.folded), expands: expandsOf(word) };
-        const prefix = /^\[[^\]]*\]\+?=/.exec(element.folded)?.[0];
-        if (prefix === undefined)
-            return [read];
-        const spelled = element.pieces.some((q) => q.expansion?.kind === "tilde") ? element.folded.slice(prefix.length) : literalTildeSpelling(element.folded.slice(prefix.length));
-        return [read, { word: element, raw: element.raw, folded: spelled, expands: expandsOf(element), denyOnly: true }];
-    });
-}
 export function isArithmeticBody(body) {
     const l = body.startsWith("(") && body.endsWith(")") ? lexShell(body) : undefined;
     if (l === undefined || "parseFailure" in l)
@@ -87,7 +79,7 @@ export function isArithmeticBody(body) {
     return false;
 }
 export function expandsOf(w) {
-    if (expansionInWord(w) || /[`()]/.test(w.raw))
+    if (expansionInWord(w))
         return "unresolvable";
     if (globInWord(w))
         return "glob";

package/dist/tools/fs/shell-read-write-targets.d.ts

@@ -1,25 +1,15 @@
 /**
  * WRITE TARGETS — which words of a shell segment a program writes, under which names, and at which seat, read off the
- * plan's text alone (no filesystem): the `>`-family redirections and a `sed` script's `w` files, the operands of the
- * write commands ({@link SHELL_WRITE_COMMANDS}), a copy's or a move's destination children (GNU's argument grammar), an
- * in-place `sed`'s backups, and the seat each is written at ({@link WriteSeat}: the directory entry, or where the path
- * lands). The establisher (`shell-read-establish.ts`) places what this module names; the judge reads the result on the
- * deny table's write face; the station's `writesPlaced` fact reads the option readers exported here.
+ * plan's text alone (no filesystem): the `>`-family redirections and a `sed` script's `w` files, and the words the
+ * segment's program writes by the program read model's ROLES (`writeReadings`: an operand or option value whose role
+ * writes, the operands an option made edited in place, a copy's destination and its children, an in-place edit's
+ * backups), at the seats the role and the selected options name ({@link WriteSeat}: the directory entry, or where the
+ * path lands). The establisher (`shell-read-establish.ts`) places what this module names; the judge reads the result
+ * on the deny table's write face. No table of programs or options lives here: what a program writes is its row's.
  */
 import type { ReadCandidate, ShellReadSegment } from "./shell-read-plan.js";
-/**
- * The commands whose operands are WRITE targets — the reference implementation's path-checked commands whose operation
- * is a write or a create (`mkdir` / `touch` create; `rm` / `rmdir` / `mv` / `cp` / `tee` write; `sed` writes when it
- * edits in place). Every operand counts (a `cp` source is judged as a write too, as the reference judges it): the write
- * face only ever REFUSES, so a word read as a target it is not costs a refusal of a command that names a denied path.
- */
-export declare const SHELL_WRITE_COMMANDS: readonly ["mkdir", "touch", "rm", "rmdir", "mv", "cp", "tee", "sed"];
-/**
- * Does an option WORD spell this option — the long name or any abbreviation of it GNU getopt accepts (`--in-p`, `--fi`,
- * `--par`: an unambiguous prefix, `=value` allowed), or the short letter alone or inside a bundle (`-i`, `-ni`, `-i.bak`)?
- * Read in the tightening direction: a prefix that another long option shares still counts (the program would refuse it).
- */
-export declare function spellsOption(word: string, long: string, short: string): boolean;
+import { type WriteSeat } from "./program-read-model.js";
+export type { WriteSeat } from "./program-read-model.js";
 /** A word of a program's argv: its raw spelling (the plan's candidates are keyed by it) and its folded spelling. */
 export interface ArgWord {
     readonly raw: string;
@@ -27,41 +17,6 @@ export interface ArgWord {
 }
 /** The words a segment hands its program — the argv after the program word (a launcher's own words are not the program's). */
 export declare function programArgs(segment: ShellReadSegment): ArgWord[];
-/**
- * One program's option GRAMMAR, as its getopt reads it: the short letters taking a REQUIRED value (the rest of the word,
- * or the next word), those taking an OPTIONAL one (the rest of the word only), and the long names taking a required value
- * (any unambiguous prefix; `=` or the next word) — absent for a program with no long options (a `--name` word is then an
- * error the program stops on, and names nothing here). The GNU and BSD programs of one name read the same argv
- * differently (`sed -l` takes a value in GNU and none in BSD; `cp -S` a suffix in GNU and none in BSD), so every question
- * below reads the argv under BOTH grammars and takes the union of what they name.
- */
-export interface OptionGrammar {
-    readonly required: string;
-    readonly optional: string;
-    readonly longRequired?: readonly string[];
-}
-/** One option read off an argv: a short letter or a long name as written (a prefix), and its value when it has one. */
-interface OptionRead {
-    readonly name: string;
-    readonly long: boolean;
-    readonly value?: ArgWord;
-}
-/** An argv read under one grammar: its options in order, and its operands (every word after `--` included). Options are
- *  read anywhere among the operands, as GNU getopt permutes them — for a BSD getopt, which stops at the first operand,
- *  that is a superset of its options (the tightening direction). */
-export declare function readArgv(words: readonly ArgWord[], grammar: OptionGrammar): {
-    readonly options: readonly OptionRead[];
-    readonly operands: readonly ArgWord[];
-};
-/** What a `sed` invocation's option words say about writing, under either grammar ({@link SED_GRAMMARS}): whether it edits
- *  in place (`-i` / `-I` / `--in-place`), the backup suffixes it is given (their values; an empty value keeps no backup),
- *  and whether GNU `--follow-symlinks` is on. */
-export interface SedOptions {
-    readonly inPlace: boolean;
-    readonly suffixes: readonly string[];
-    readonly followsLinks: boolean;
-}
-export declare function sedOptionsOf(segment: ShellReadSegment): SedOptions;
 /**
  * The BACKUP names an in-place `sed` gives the file it knows as `name` — both readings a suffix has: GNU sed replaces every
  * `*` in the suffix with the name (`bak/*` on `d/f` is `bak/d/f`, `/elsewhere/*` is `/elsewhere/d/f`) and appends a suffix
@@ -69,20 +24,16 @@ export declare function sedOptionsOf(segment: ShellReadSegment): SedOptions;
  * the working directory like the operand itself, so a suffix carrying a separator places the backup wherever it points.
  */
 export declare function sedBackupNames(name: string, suffix: string): string[];
-/**
- * WHERE a write reaches a path it names. `landing` — the path followed through every link to where it lands: the program
- * opens the path and writes through it. `entry` — the directory entry itself, the canonical parent joined with the last
- * name: the program renames over the entry, unlinks it or replaces it, and a link there is not followed (a name ending in
- * a separator, `.` or `..` resolves itself, so it lands).
- */
-export type WriteSeat = "landing" | "entry";
 /** One candidate handed to the judge. `seats`: where a write target is established ({@link WriteSeat}; absent ⇒ it lands —
  *  every read does). `written`: the seats among `seats` the program itself WRITES the target at (absent ⇒ all of them;
  *  `[]` ⇒ none — a copy's source, judged on the write face as a write path and read by the program); the write guards are
  *  asked about these alone. `child`: a copy's or a move's destination child, written only where the destination is a
- *  directory when the program runs. `followed`: a GNU sed `--follow-symlinks` backup — its names are {@link sedBackupNames}
- *  of the operand's FOLLOWED name, which only the filesystem answers (the candidate's own spelling is the operand's as
- *  written, the identity the pre-spawn re-check compares). */
+ *  directory when the program runs. `followed`: an in-place edit's backup where the operand is edited where it LANDS — its
+ *  names are {@link sedBackupNames} of the operand's FOLLOWED name, which only the filesystem answers (the candidate's own
+ *  spelling is the operand's as written, the identity the pre-spawn re-check compares). `onlyIfExists`: written only under
+ *  SOME implementation's reading of the command, and only by editing an existing file — the program edits nothing that is
+ *  not there, so where the filesystem confirms this candidate missing nothing is written (a lexical establishment cannot
+ *  confirm it, and keeps the write). */
 export interface JudgedCandidate {
     readonly candidate: ReadCandidate;
     readonly seats?: readonly WriteSeat[];
@@ -92,9 +43,9 @@ export interface JudgedCandidate {
         readonly operand: ReadCandidate;
         readonly suffix: string;
     };
+    readonly onlyIfExists?: ReadCandidate;
 }
 /** Every candidate a segment hands the judge: its reads minus the write targets, plus its `cd` target (the plan already
  *  lists it among the reads), plus its WRITE targets for the write face ({@link writeTargetsOf}), plus the deny-floor
  *  shadow of every unplaced home word ({@link denyFloorShadowsOf}) on both faces. */
 export declare function judgedCandidatesOf(segment: ShellReadSegment): readonly JudgedCandidate[];
-export {};

package/dist/tools/fs/shell-read-write-targets.js

@@ -1,134 +1,106 @@
 import { denyFloorShadowsOf } from "./shell-read-judge.js";
-export const SHELL_WRITE_COMMANDS = Object.freeze(["mkdir", "touch", "rm", "rmdir", "mv", "cp", "tee", "sed"]);
-const WRITE_COMMAND_SET = new Set(SHELL_WRITE_COMMANDS);
-export function spellsOption(word, long, short) {
-    if (word.startsWith("--")) {
-        const name = word.slice(2).split("=")[0];
-        return name.length > 0 && long.startsWith(name);
-    }
-    return new RegExp(`^-[A-Za-z]*${short}`).test(word);
-}
+import { implementationsOf, programRow, selectedOptions, writeReadings } from "./program-read-model.js";
+import { programBasename, readProgramPosition } from "./bash-program-position.js";
 export function programArgs(segment) {
     const words = segment.argv.map((w) => ({ raw: w.raw, spelled: w.folded }));
     const at = words.findIndex((w) => w.spelled === segment.verb?.name);
     return at < 0 ? [] : words.slice(at + 1);
 }
-const SED_GRAMMARS = [
-    { required: "efl", optional: "i", longRequired: ["expression", "file", "line-length"] },
-    { required: "efiI", optional: "" },
-];
-const COPY_GRAMMARS = [
-    { required: "St", optional: "", longRequired: ["target-directory", "suffix", "no-preserve", "sparse"] },
-    { required: "", optional: "" },
-];
-export function readArgv(words, grammar) {
-    const options = [];
-    const operands = [];
-    let endOfOptions = false;
-    for (let k = 0; k < words.length; k++) {
-        const w = words[k];
-        const s = w.spelled;
-        if (endOfOptions || !s.startsWith("-") || s === "-") {
-            operands.push(w);
-            continue;
-        }
-        if (s === "--") {
-            endOfOptions = true;
-            continue;
-        }
-        if (s.startsWith("--")) {
-            const eq = s.indexOf("=");
-            const name = s.slice(2, eq < 0 ? undefined : eq);
-            if (grammar.longRequired === undefined || name.length === 0)
-                continue;
-            const value = eq >= 0 ? { raw: w.raw, spelled: s.slice(eq + 1) } : grammar.longRequired.some((long) => long.startsWith(name)) ? words[++k] : undefined;
-            options.push({ name, long: true, ...(value !== undefined ? { value } : {}) });
-            continue;
-        }
-        for (let c = 1; c < s.length; c++) {
-            const letter = s[c];
-            const rest = s.slice(c + 1);
-            if (grammar.required.includes(letter)) {
-                const value = rest.length > 0 ? { raw: w.raw, spelled: rest } : words[++k];
-                options.push({ name: letter, long: false, ...(value !== undefined ? { value } : {}) });
-                break;
-            }
-            if (grammar.optional.includes(letter)) {
-                options.push({ name: letter, long: false, ...(rest.length > 0 ? { value: { raw: w.raw, spelled: rest } } : {}) });
-                break;
-            }
-            options.push({ name: letter, long: false });
-        }
-    }
-    return { options, operands };
-}
-export function sedOptionsOf(segment) {
-    const words = programArgs(segment);
-    let inPlace = false;
-    let followsLinks = false;
-    const suffixes = new Set();
-    for (const grammar of SED_GRAMMARS) {
-        for (const o of readArgv(words, grammar).options) {
-            if (o.long ? "in-place".startsWith(o.name) : o.name === "i" || o.name === "I") {
-                inPlace = true;
-                if (o.value !== undefined && o.value.spelled.length > 0)
-                    suffixes.add(o.value.spelled);
-            }
-            if (o.long && "follow-symlinks".startsWith(o.name))
-                followsLinks = true;
-        }
-    }
-    return { inPlace, suffixes: [...suffixes], followsLinks };
-}
 export function sedBackupNames(name, suffix) {
     const appended = `${name}${suffix}`;
     return suffix.includes("*") ? [suffix.replace(/\*/g, () => name), appended] : [appended];
 }
-const OPERAND_SEATS = {
-    touch: (s) => (programArgs(s).some((w) => w.spelled.startsWith("-") && spellsOption(w.spelled, "no-dereference", "h")) ? ["landing", "entry"] : ["landing"]),
-    rm: () => ["entry"],
-    rmdir: () => ["entry"],
-    sed: (s) => (sedOptionsOf(s).followsLinks ? ["landing"] : ["entry"]),
-    mv: () => ["landing", "entry"],
-    cp: () => ["landing", "entry"],
-};
-const SOURCE_WRITTEN = { cp: [], mv: ["entry"] };
-function sedBackupTargets(segment) {
-    const { suffixes, followsLinks } = sedOptionsOf(segment);
-    if (suffixes.length === 0)
-        return [];
-    const files = segment.reads.filter((c) => c.provenance === "operand" && c.expands === false);
-    return files.flatMap((f) => suffixes.flatMap((suffix) => followsLinks
-        ? [{ candidate: { ...f, spelled: `${f.spelled}${suffix}`, face: "write" }, seats: ["entry"], followed: { operand: f, suffix } }]
-        : sedBackupNames(f.spelled, suffix).map((spelled) => ({ candidate: { ...f, spelled, face: "write" }, seats: ["entry"] }))));
+const WORD_PROVENANCES = new Set(["operand", "unlisted_word", "option_value"]);
+function writeOwnersOf(segment) {
+    const pos = readProgramPosition(segment.argv);
+    const word = (i) => ({ raw: segment.argv[i].raw, spelled: segment.argv[i].folded });
+    const owners = [];
+    pos.launchers.forEach((l, i) => {
+        const row = programRow(l.name);
+        const end = pos.launchers[i + 1]?.index ?? pos.program?.index ?? segment.argv.length;
+        if (row !== undefined)
+            owners.push({ row, words: Array.from({ length: Math.max(0, end - l.index - 1) }, (_, k) => word(l.index + 1 + k)), program: false });
+    });
+    const program = pos.program !== undefined ? programRow(programBasename(pos.program.name)) : undefined;
+    if (program !== undefined && segment.verb !== undefined)
+        owners.push({ row: program, words: programArgs(segment), program: true });
+    return owners;
 }
-function copyReadingsOf(segment) {
+function writeTargetsOf(segment) {
     const out = [];
-    for (const grammar of COPY_GRAMMARS) {
-        const { options, operands } = readArgv(programArgs(segment), grammar);
-        const sources = [...operands];
-        const dest = options.findLast((o) => o.value !== undefined && (o.long ? "target-directory".startsWith(o.name) : o.name === "t"))?.value ?? sources.pop();
-        if (dest !== undefined)
-            out.push({ dest, sources });
+    const write = (c, seats, written, child, onlyIfExists) => void out.push({ candidate: { ...c, face: "write" }, ...(seats !== undefined ? { seats } : {}), ...(written !== undefined ? { written } : {}), ...(child === true ? { child } : {}), ...(onlyIfExists !== undefined ? { onlyIfExists } : {}) });
+    for (const r of segment.redirects)
+        if (r.direction === "out" && r.target !== undefined)
+            write(r.target);
+    for (const c of segment.reads)
+        if (c.provenance === "write_redirect_target")
+            write(c);
+    const owners = writeOwnersOf(segment).map(({ row, words, program }) => {
+        const args = words.map((w) => w.spelled);
+        const all = writeReadings(row, args);
+        const moved = [...new Set(implementationsOf(row).flatMap((view) => selectedOptions(view, args, "one-implementation")).flatMap((o) => o.writesAt ?? []))];
+        return { words, program, all, readings: all.filter((r) => r.written.length > 0 || (r.unexplained && r.operandRole !== undefined)), override: moved.length > 0 ? moved : undefined };
+    });
+    const edited = new Map();
+    for (const c of segment.reads) {
+        if (!WORD_PROVENANCES.has(c.provenance))
+            continue;
+        const placed = owners.filter((o) => o.words.some((w) => w.raw === c.raw));
+        const fallback = placed.length === 0 ? owners.filter((o) => o.program) : [];
+        for (const o of [...placed, ...fallback]) {
+            if (o.readings.length === 0)
+                continue;
+            const at = new Set(o.words.flatMap((w, i) => (w.raw === c.raw ? [i] : [])));
+            const roles = [];
+            let readings = 0;
+            let unexplained = false;
+            for (const r of o.readings) {
+                const unplaced = (r.unexplained || at.size === 0) && r.operandRole !== undefined;
+                const found = unplaced ? [r.operandRole] : r.written.filter((w) => at.has(w.at)).map((w) => w.role);
+                if (found.length === 0)
+                    continue;
+                roles.push(...found);
+                readings += 1;
+                unexplained ||= unplaced;
+            }
+            if (roles.length === 0)
+                continue;
+            const stated = roles.some((role) => (o.override ?? role.seats) !== undefined);
+            const seats = stated ? [...new Set(roles.flatMap((role) => o.override ?? role.seats ?? ["landing"]))] : undefined;
+            const written = unexplained || roles.some((role) => role.writtenAt === undefined) ? undefined : [...new Set(roles.flatMap((role) => role.writtenAt ?? []))];
+            const speculative = readings < o.all.length && roles.every((role) => role.effect === "edit-in-place") ? c : undefined;
+            write(c, seats, written, undefined, speculative);
+            if (roles.some((role) => role.effect === "edit-in-place") && c.expands === false)
+                edited.set(o, [...(edited.get(o) ?? []), { candidate: c, ...(speculative !== undefined ? { onlyIfExists: speculative } : {}) }]);
+        }
+    }
+    for (const o of owners) {
+        for (const c of copyDestinationChildren(segment, o.words, o.readings))
+            write(c, ["landing", "entry"], undefined, true);
+        out.push(...backupTargetsOf(edited.get(o) ?? [], o.readings, o.override));
     }
     return out;
 }
-function copySourceWordsOf(segment) {
-    const readings = copyReadingsOf(segment);
-    if (readings.length < COPY_GRAMMARS.length || programArgs(segment).some((w) => w.spelled.startsWith("-")))
-        return new Set();
-    const [first, ...rest] = readings.map((r) => new Set(r.sources.map((w) => w.raw)));
-    const dests = new Set(readings.map((r) => r.dest.raw));
-    return new Set([...first].filter((raw) => !dests.has(raw) && rest.every((s) => s.has(raw))));
+function backupTargetsOf(edited, readings, override) {
+    const suffixes = [...new Set(readings.flatMap((r) => r.suffixes))];
+    const follows = override !== undefined && !override.includes("entry");
+    return edited.flatMap(({ candidate: f, onlyIfExists }) => suffixes.flatMap((suffix) => follows
+        ? [{ candidate: { ...f, spelled: `${f.spelled}${suffix}`, face: "write" }, seats: ["entry"], followed: { operand: f, suffix }, ...(onlyIfExists !== undefined ? { onlyIfExists } : {}) }]
+        : sedBackupNames(f.spelled, suffix).map((spelled) => ({ candidate: { ...f, spelled, face: "write" }, seats: ["entry"], ...(onlyIfExists !== undefined ? { onlyIfExists } : {}) }))));
 }
-function copyDestinationChildren(segment) {
-    const candidateOf = (raw) => segment.reads.find((c) => c.raw === raw && (c.provenance === "unlisted_word" || c.provenance === "operand"));
+function copyDestinationChildren(segment, words, readings) {
+    const candidateOf = (raw) => segment.reads.find((c) => c.raw === raw && WORD_PROVENANCES.has(c.provenance));
     const children = new Map();
-    for (const { dest, sources } of copyReadingsOf(segment)) {
+    for (const r of readings) {
+        if (r.copy === undefined)
+            continue;
+        const destWord = words[r.copy.destination.at];
+        const dest = { raw: destWord.raw, spelled: r.copy.destination.value ?? destWord.spelled };
         const destCandidate = candidateOf(dest.raw);
         if (destCandidate !== undefined && destCandidate.expands !== false)
             continue;
-        for (const src of sources) {
+        for (const at of r.copy.sources) {
+            const src = words[at];
             const source = candidateOf(src.raw);
             if (source !== undefined && source.expands !== false)
                 continue;
@@ -140,31 +112,6 @@ function copyDestinationChildren(segment) {
     }
     return [...children.values()];
 }
-function writeTargetsOf(segment) {
-    const out = [];
-    const write = (c, seats, written, child) => void out.push({ candidate: { ...c, face: "write" }, ...(seats !== undefined ? { seats } : {}), ...(written !== undefined ? { written } : {}), ...(child === true ? { child } : {}) });
-    for (const r of segment.redirects)
-        if (r.direction === "out" && r.target !== undefined)
-            write(r.target);
-    for (const c of segment.reads)
-        if (c.provenance === "write_redirect_target")
-            write(c);
-    const verb = segment.verb?.basename;
-    if (verb !== undefined && WRITE_COMMAND_SET.has(verb) && (verb !== "sed" || sedOptionsOf(segment).inPlace)) {
-        const seats = OPERAND_SEATS[verb]?.(segment);
-        const sourceWritten = SOURCE_WRITTEN[verb];
-        const sources = sourceWritten !== undefined ? copySourceWordsOf(segment) : undefined;
-        for (const c of segment.reads)
-            if (c.provenance === "operand" || c.provenance === "unlisted_word" || c.provenance === "option_value")
-                write(c, seats, sources?.has(c.raw) === true ? sourceWritten : undefined);
-        if (verb === "cp" || verb === "mv")
-            for (const c of copyDestinationChildren(segment))
-                write(c, seats, undefined, true);
-        if (verb === "sed")
-            out.push(...sedBackupTargets(segment));
-    }
-    return out;
-}
 export function judgedCandidatesOf(segment) {
     const reads = segment.reads.filter((c) => c.provenance !== "write_redirect_target");
     const writes = writeTargetsOf(segment);

package/dist/tools/fs/shell-reentry-text.d.ts

@@ -1,10 +1,42 @@
 /**
  * The shell text a program hands back to the shell: the text a shell program runs INSTEAD of its argv (`sh -c S`,
- * `eval S` — {@link reentryText}), and the code bodies a builtin keeps AMONG its operands to run later
- * ({@link codeBodies}). The plan marks a segment carrying either as a shell re-entry (`shell-read-plan.ts`); this
- * module is the one reader of which operand that text is.
+ * `eval S`, or its standard input where the argv names no script — {@link reentryText}), and the code bodies a builtin
+ * keeps AMONG its operands to run later ({@link codeBodies}). The plan marks a segment carrying either as a shell
+ * re-entry (`shell-read-plan.ts`); this module is the one reader of which operand — or which input — that text is.
+ */
+import { type LexedSegment, type LexedWord } from "../../shell/lex.js";
+/**
+ * The code bodies a builtin keeps among its operands, one per body; empty for every other program. The program read
+ * model's row says where the body is: the action of a `trap` (its first operand after the options), the value of an
+ * `alias` definition, the shell-text option of `mapfile` / `readarray` / `compgen` (`-C`; compgen runs it at once, to
+ * list completions). The text is re-entry text as `eval`'s operand is — the segment re-enters the shell, the command's
+ * read set is not established, and each body is its own nested plan whose deny hits still refuse (one unreadable body
+ * cannot hide another's). What a body does when it runs is not read from the text, so a body of any content asks: a
+ * harmless `trap 'echo bye' EXIT` in front of a read asks as `eval 'echo bye'` does. The builtin's own words stay the
+ * candidates they are for any unlisted program. An absent body is no re-entry (`trap - SIG` resets, `trap '' SIG`
+ * ignores, `mapfile` without `-C`); an EMPTY alias value or `-C` value is still one. Over-reading is the direction
+ * taken: a display option (`trap -p SIG`) and a lone operand (`trap SIG`) still count their operand as the body.
  */
-/** The code bodies a builtin keeps among its operands, one per body; empty for every other program. */
 export declare function codeBodies(basename: string, args: readonly string[]): readonly string[];
-/** The shell text a re-entry program runs: `sh -c S` (the `c` letter's value), `eval` (its words joined). */
-export declare function reentryText(basename: string, args: readonly string[]): string | undefined;
+/** The shell text a re-entry program runs, by its row: the shell-text value its walk reads for a shell (`-c`'s), its
+ *  words joined for `eval`, its non-option words for `parallel`; none for `source` / `.` (a script file operand), for a
+ *  shell whose first operand (a script file) or `--` comes before any text, or for a program that is no re-entry. Where
+ *  the argv names no text and the program runs its standard input ({@link scriptSourceOf}: the row runs it unnamed, or
+ *  the script file named is standard input), the text is `stdin` — one text that may arrive there, as the caller spells it. */
+export declare function reentryText(basename: string, args: readonly string[], stdin?: string): string | undefined;
+/** The argv index of the SCRIPT FILE a shell runs where its argv carries no text ({@link scriptSourceOf}). */
+export declare function scriptFileAt(basename: string, args: readonly string[]): number | undefined;
+/** One text that may arrive on a segment's standard input: `from` = its source as written (a here-document's body,
+ *  `<<<WORD`, `<FILE`, `<&N`, the segment the pipe comes from); `literal` = the text, where the command spells it. */
+export interface StdinText {
+    readonly from: string;
+    readonly literal?: string;
+}
+/** What may arrive on a segment's standard input: each here-document (its descriptor is not read: every one counts) —
+ *  its body, literal when quoted or when nothing in it expands — each here-string (literal when its word is), `<` file
+ *  or `<&` descriptor written to no other descriptor, and the pipe it is reached through (`piped`) unless one of those
+ *  three replaces it. */
+export declare function stdinTextsOf(segment: LexedSegment, piped: StdinText | undefined): StdinText[];
+/** What one segment (its argv) writes into the pipe after it: the text a printer spells ({@link printedText}) when its
+ *  program word and every argument are literal, else only the segment as written. */
+export declare function pipedTextOf(segment: LexedSegment, argv: readonly LexedWord[]): StdinText;