@sema-agent/core 7.51.2 → 7.53.0

package/dist/tools/fs/program-read-model.d.ts

@@ -172,9 +172,18 @@ export interface OptionSpec {
      *  `date -s`), `executes` a command (`find -exec`), or `none` — neither, which the binary gate witnesses for every
      *  option that states it (the read-only form of a program admits only such options). Absent: not stated. */
     readonly effect?: "writes" | "executes" | "none";
-    /** The option's value names a FILE the program reads its OPERANDS from (`find -files0-from`, `tar -T`): what it walks
-     *  or opens is not in the command line. */
+    /** The option's value names a FILE the program reads its OPERANDS from (`find -files0-from`, `tar -T`) — or, a switch, says they
+     *  arrive on its standard input (`ack -x`): what it walks or opens is not in the command line, so a segment that selects it has
+     *  reads the station cannot establish ({@link deliversOperands}); the list file itself is a read like any other and meets the deny
+     *  rows as itself. */
     readonly delivers?: "operands";
+    /** The option's value is a PLACE the program's walk works in or compares (`tar -C DIR`, `diff --from-file=DIR`): a root of a
+     *  recursive form, whichever way the value is spelled. Absent: a path value is a file the program READS (a config, ignore or
+     *  exclusion file, an archive, a pattern file) or an entry it examines — judged as itself, never a root, so it does not count
+     *  as the root the walk was given (`rg --ignore-file ig pat` walks `.`). A list the operands come from ({@link delivers}) is a
+     *  root of a recursive form too, in either spelling: the program works on what the list names, not on the working directory
+     *  (and, the names not being in the text, the segment is not vouched: {@link deliversOperands}). */
+    readonly walks?: true;
     /** The option's value bounds the program's output, in bytes or in lines (`head -c` / `head -n`). */
     readonly bounds?: "bytes" | "lines";
     /** The option's value is what the row's LAST operand would otherwise be (`cp -t <dir>`), so every operand is an
@@ -236,6 +245,12 @@ export interface Grammar {
     /** With no operand, this implementation walks the working directory (`grep -r pat`); absent, it walks nothing (it
      *  reads its standard input, or refuses to run). */
     readonly walksCwdWithoutOperand?: true;
+    /** Whether this implementation reads an unambiguous PREFIX of a long option's name as that option (`getopt_long`, Perl's
+     *  Getopt::Long: `grep --max 1`, `tar --dir d`). Absent = it does; `false` = only the exact name is an option and a prefix
+     *  is an unrecognised flag that runs nothing (ripgrep's parser: `rg --ignore-f x` is an error while `rg --ignore` is the
+     *  switch). Every reader that matches a long name against the table asks this one fact, so a name a row leaves undeclared is
+     *  never read as the abbreviation of a declared one in a program that does not take abbreviations. */
+    readonly acceptsAbbreviations?: boolean;
     /** The traditional FIRST-argument form `<sign><number><letters>` (`tail +0f`, `tail -1f`): the signs this
      *  implementation reads it with, and the option each letter names. */
     readonly obsoleteFirst?: {
@@ -412,9 +427,11 @@ export declare function movesBaseByStack(name: string): boolean;
 /** The LONG-OPTION name carried by a token (`--file=p` → `file`, `--reg` → `reg`); `undefined` for anything that is
  *  not a long option with a non-empty name (`--`, `--=x`, a short option). */
 export declare function longOptionNameOf(tok: string): string | undefined;
-/** Is `name` a spelling (possibly ABBREVIATED) of the long option `full`? Every prefix counts — `getopt_long`'s
- *  ambiguity is not modelled, and each caller makes that over-approximation land on its own safe side. */
-export declare function isLongOptionAbbrevOf(name: string, full: string): boolean;
+/** Is `name` a spelling of the long option `full`? The exact name always; a proper prefix — an abbreviation — only where the
+ *  program takes them (`accepts`: {@link Grammar.acceptsAbbreviations}, or {@link Merged.abbreviable} of a merged name). Every
+ *  prefix counts there — `getopt_long`'s ambiguity is not modelled, and each caller makes that over-approximation land on its
+ *  own safe side. This is the one place a long name is matched against another. */
+export declare function isLongOptionSpellingOf(name: string, full: string, accepts: boolean): boolean;
 /** The languages whose program text the read station parses (the rest is program text it does not read). */
 export declare const READ_LANGUAGES: ReadonlySet<string>;
 /**
@@ -472,6 +489,8 @@ export interface FirstOperandSlot {
     readonly role: ArgRole;
     readonly suppliedByLetters: string;
     readonly suppliedByLongNames: readonly string[];
+    /** The long names of {@link suppliedByLongNames} a prefix of which supplies it too ({@link Grammar.acceptsAbbreviations}). */
+    readonly abbreviableLongNames: readonly string[];
     /** The other letters that take a value in every implementation: in a cluster, the rest of the token is theirs. */
     readonly valueLetters: string;
 }
@@ -480,7 +499,7 @@ export declare function firstOperandSlot(row: ProgramRow | undefined, view?: Vie
  *  a letter that delivers the slot supplies it, and the first OTHER letter that takes a value owns the rest of the
  *  token (`grep -Dread x f`: `read` is `-D`'s value, its `e` delivers nothing); a letter the row does not declare is
  *  stepped over (it may be a switch), as digits are (grep's obsolete numeric context spec: `-2ebeta`). A long option
- *  supplies it by abbreviation. Over-triggering makes the first operand a CHECKED path candidate, the safe side. */
+ *  supplies it by its name, or by a prefix of it where the program takes abbreviations. Over-triggering makes the first operand a CHECKED path candidate, the safe side. */
 export declare function suppliesFirstOperandSlot(slot: FirstOperandSlot, tok: string): boolean;
 /** The row's options stand anywhere in its argv in every implementation (`find`'s predicates past its paths), so the
  *  "is a dash-word past the first operand still an option" ambiguity does not exist for it. */
@@ -544,6 +563,7 @@ type Event<R> =
     readonly role: R;
     readonly consumed: boolean;
     readonly spec?: OptionSpec;
+    readonly unsettled?: true;
 }
 /** An operand, the `ordinal`-th. `slot` = the first-operand slot's role when the slot applies; `role` = the role the
  *  row declares for an operand at this position past the slot (a URL, a name it only examines); `dash` = the word is
@@ -559,13 +579,25 @@ type Event<R> =
 export type ArgEvent = Event<ArgRole>;
 export type ArgRoleEvent = Event<ArgRole | undefined>;
 /** The candidate extraction's walk (the program word excluded). `firstOperandSlot: false` reads every operand as an
- *  ordinary one. */
+ *  ordinary one. `ownedValues`: a bare option of a traversing program that may take the NEXT word as its value
+ *  ({@link bareOptionValueOf}) hands that word over as a value read both ways (`consumed: false`) — what the roots of a
+ *  recursive form are read from. */
 export declare function readArgs(row: ProgramRow | undefined, words: readonly ArgWord[], opts: {
     readonly firstOperandSlot: boolean | "program-text";
+    readonly ownedValues?: true;
 }): ArgEvent[];
 /** The role walk: the SAME walk, every declared option read by its declared arity and role. What the binary gate
  *  predicts a binary opens is read off these events. */
 export declare function readArgRoles(row: ProgramRow, args: readonly string[]): ArgRoleEvent[];
+/**
+ * Does this invocation take the program's OPERANDS from a list file ({@link OptionSpec.delivers}: `ack --files-from LIST`,
+ * `tar -T LIST`, `find -files0-from LIST`)? What the program then walks or opens is written in a file this reading does not
+ * open — no root of it is in the command. The reading of a check that only ever refuses or asks ({@link selectedOptions} over the
+ * merged row: a word spelled as the option counts, an abbreviation that reaches it counts, a value spelled like it counts). The
+ * traditional key word is every letter of it an option — each value-taking letter takes one of the arguments that follow, in
+ * order, so none owns the rest of the word (`tar cfT out.tar list` takes `list` for `T`).
+ */
+export declare function deliversOperands(row: ProgramRow | undefined, args: readonly string[]): boolean;
 /**
  * Does this invocation walk its operands' subtrees AND hand back their CONTENTS? Detection over-approximates: a flag
  * misread as recursive costs one ask, an under-read hides a traversal. A value-taking letter owns its value only where
@@ -596,6 +628,33 @@ export declare function declaresOption(row: ProgramRow, pred: (spec: OptionSpec)
  * count must still see. getopt's cluster rule: the FIRST value-taking letter owns the rest of the token.
  */
 export declare function takesSeparatedDatum(row: ProgramRow | undefined, tok: string): boolean;
+/**
+ * The value the NEXT word may be, for an option token written BARE (no value attached) — the one place the "which word does this
+ * option own" question of a cluster or an optional count is answered. Each grammar of the row reads the token as getopt does (a
+ * cluster: a letter the row does not declare is a switch, the first value-taking letter owns the rest of the token, so the next
+ * word only when it ends the token; a long name: the name or, where the grammar takes abbreviations, any name it abbreviates,
+ * `--name=` carries its own value):
+ *  · a REQUIRED value is the next word wherever the option is read — the extraction's slot reading fails to see it where the token
+ *    is a cluster with a letter the row leaves undeclared (`rg -nA 2 pat`: rg / ag / ack declare no switches), and `tok` is then
+ *    read the speculative way;
+ *  · an OPTIONAL count (the value only attached) is the next word to a parser that reads an optional integer (Getopt::Long's `:i`:
+ *    ack's `-A` / `-B` / `-C`) or a required one (GNU grep's `--context`) when that word is spelled like a count, and an operand to
+ *    a parser that reads it attached-only (getopt_long's optional argument: ag's long names, BSD grep) — the row files it
+ *    attached-only, the reading that consumes nothing.
+ *  · a long name the row declares NOWHERE (not as a name, nor — in a grammar that takes abbreviations — as the abbreviation of one)
+ *    may take the next word: the row cannot say it does not (`rg --hostname-bin x pat`, whose option runs a program, is left
+ *    undeclared on purpose; `rg --ignore pat sub`, a switch of rg that is no abbreviation of `--ignore-file` there) — the word's value role is
+ *    {@link UNDECLARED_VALUE}, no more than "names no file", as it is also read as whatever it is on its own. A long name with its
+ *    value attached owns nothing, and one the row declares as a switch owns nothing.
+ * A SHORT letter the row leaves undeclared owns no word: the rows of rg / ag / ack declare no switches, so every word behind `-i`
+ * would otherwise be one — the letter is read as the switch it is in rg (whose table of value letters is complete). The extraction
+ * reads the word both ways (`consumed: false` — as the value, and as whatever it is on its own). Served to the contents walkers
+ * (`readArgs` `ownedValues`), whose rows carry no single-dash WORD options (`find -name`): a cluster here is always letters.
+ */
+export declare function bareOptionValueOf(row: ProgramRow, tok: string, next: string | undefined): {
+    readonly role: ArgRole;
+    readonly spec?: OptionSpec;
+} | undefined;
 /**
  * Does this option word carry, ATTACHED, the value `-` for an option whose value is a file the program opens or names
  * (`grep -f-`, `diff --from-file=-`, `diff -X-`) — or for a spelling the row does not account for? Such a word makes the
@@ -623,7 +682,8 @@ interface OptionScan {
  * Every option spec an argv selects. A short cluster is read as getopt reads it, scanning left to right: a declared
  * letter is selected; a value-taking letter owns the rest of the token (and the next word, when it ends the token); a
  * letter the row does not declare is read as a switch and the scan goes on. A long option is every name its spelling
- * can abbreviate (the exact name alone where there is one); a dash word its exact name. Two readings:
+ * can abbreviate where the grammar takes abbreviations (the exact name alone where there is one, and always in a grammar
+ * that takes none); a dash word its exact name. Two readings:
  *  · over ONE implementation's view ({@link implementationsOf}): what that program selects — a separated value is
  *    stepped over, `--` ends the options, and so does the first operand where the grammar stops there;
  *  · over the row (every implementation merged): every word is read as the option it SPELLS — a value spelled like an

package/dist/tools/fs/program-read-model.js

@@ -77,8 +77,9 @@ export function longOptionNameOf(tok) {
     const name = eq >= 0 ? body.slice(0, eq) : body;
     return name.length > 0 ? name : undefined;
 }
-export function isLongOptionAbbrevOf(name, full) {
-    return full.startsWith(name);
+const abbreviates = (g) => g.acceptsAbbreviations !== false;
+export function isLongOptionSpellingOf(name, full, accepts) {
+    return full === name || (accepts && full.startsWith(name));
 }
 const MERGED = new WeakMap();
 function mergedTable(row, table) {
@@ -93,10 +94,11 @@ function mergedTable(row, table) {
     const out = new Map();
     const names = new Set(row.grammars.flatMap((g) => Object.keys(g[table] ?? {})));
     for (const name of names) {
-        const specs = row.grammars.map((g) => g[table]?.[name]).filter((s) => s !== undefined);
+        const declaring = row.grammars.filter((g) => g[table]?.[name] !== undefined);
+        const specs = declaring.map((g) => g[table][name]);
         const arities = new Set(specs.map((s) => s.arity));
         const widest = specs.reduce((a, b) => (roleRank(b.value) > roleRank(a.value) ? b : a));
-        out.set(name, { arity: arities.size === 1 ? specs[0].arity : "disputed", spec: widest, takesValueEverywhere: specs.every((s) => s.arity === 1), ownsRestEverywhere: specs.every((s) => s.arity !== 0), takesValueSomewhere: specs.some((s) => s.arity === 1) });
+        out.set(name, { arity: arities.size === 1 ? specs[0].arity : "disputed", spec: widest, takesValueEverywhere: specs.every((s) => s.arity === 1), ownsRestEverywhere: specs.every((s) => s.arity !== 0), takesValueSomewhere: specs.some((s) => s.arity === 1), abbreviable: declaring.some(abbreviates) });
     }
     byTable.set(table, out);
     return out;
@@ -141,27 +143,28 @@ function viewTable(row, table, view) {
     for (const [name, m] of mergedTable(row, table)) {
         const role = m.spec.value;
         const spec = m.spec;
+        const abbreviable = m.abbreviable;
         if (view === "roles") {
             if (m.arity === 0)
-                out.set(name, { arity: 0, spec });
+                out.set(name, { arity: 0, spec, abbreviable });
             else if (m.arity === 1)
-                out.set(name, { arity: 1, spec, ...(role !== undefined ? { role } : {}) });
+                out.set(name, { arity: 1, spec, abbreviable, ...(role !== undefined ? { role } : {}) });
             else if (m.arity === "suffix")
-                out.set(name, { arity: "suffix", spec, ...(role !== undefined ? { role } : {}) });
+                out.set(name, { arity: "suffix", spec, abbreviable, ...(role !== undefined ? { role } : {}) });
             else if (m.arity === "attached" || (m.arity === "disputed" && table === "long"))
-                out.set(name, { arity: "attached", spec, ...(role !== undefined ? { role } : {}) });
+                out.set(name, { arity: "attached", spec, abbreviable, ...(role !== undefined ? { role } : {}) });
             continue;
         }
         if (m.arity === 0)
-            out.set(name, { arity: 0, spec });
+            out.set(name, { arity: 0, spec, abbreviable });
         else if (m.arity === "disputed") {
             if (table === "long" && preciseRole(role))
-                out.set(name, { arity: "attached", role: role, spec });
+                out.set(name, { arity: "attached", role: role, spec, abbreviable });
         }
         else if (m.arity === 1 && preciseRole(role))
-            out.set(name, { arity: 1, role: role, spec });
+            out.set(name, { arity: 1, role: role, spec, abbreviable });
         else if (m.arity === "attached" && table === "long" && preciseRole(role))
-            out.set(name, { arity: "attached", role: role, spec });
+            out.set(name, { arity: "attached", role: role, spec, abbreviable });
     }
     return out;
 }
@@ -184,7 +187,7 @@ function readOptionIn(row, tok, view, next) {
                 return attached !== undefined ? { form: "attached", value: attached, role: exact.role, spec: exact.spec } : { form: "no-value" };
             return attached === undefined ? { form: "no-value" } : { form: "unexplained" };
         }
-        const reach = [...longs.entries()].filter(([full]) => isLongOptionAbbrevOf(long, full));
+        const reach = [...longs.entries()].filter(([full, s]) => isLongOptionSpellingOf(long, full, s.abbreviable));
         const valueNames = reach.filter(([, s]) => s.arity === 1 || (attached !== undefined && s.arity === "attached"));
         const plainNames = reach.filter(([, s]) => s.arity === 0 || (attached === undefined && s.arity === "attached"));
         if (valueNames.length === 0)
@@ -247,13 +250,13 @@ export function firstOperandSlot(row, view = "candidates") {
     const shorts = [...mergedTable(row, "short")];
     const letters = shorts.filter(([, m]) => m.spec.fillsSlot === true).map(([l]) => l).join("");
     const valueLetters = shorts.filter(([, m]) => m.spec.fillsSlot !== true && m.ownsRestEverywhere).map(([l]) => l).join("");
-    const longs = [...mergedTable(row, "long")].filter(([, m]) => m.spec.fillsSlot === true).map(([n]) => n);
-    return { role, suppliedByLetters: letters, suppliedByLongNames: longs, valueLetters };
+    const supplying = [...mergedTable(row, "long")].filter(([, m]) => m.spec.fillsSlot === true);
+    return { role, suppliedByLetters: letters, suppliedByLongNames: supplying.map(([n]) => n), abbreviableLongNames: supplying.filter(([, m]) => m.abbreviable).map(([n]) => n), valueLetters };
 }
 export function suppliesFirstOperandSlot(slot, tok) {
     if (tok.startsWith("--")) {
         const long = longOptionNameOf(tok);
-        return long !== undefined && slot.suppliedByLongNames.some((full) => isLongOptionAbbrevOf(long, full));
+        return long !== undefined && slot.suppliedByLongNames.some((full) => isLongOptionSpellingOf(long, full, slot.abbreviableLongNames.includes(full)));
     }
     if (!tok.startsWith("-"))
         return false;
@@ -442,11 +445,16 @@ export function objectPathsOf(value) {
     }
     return out;
 }
-function walkArgs(row, words, readOption, slot, readsRole) {
+function walkArgs(row, words, readOption, slot, readsRole, ownedValue) {
     const out = [];
+    const valueAt = new Set();
     const folded = words.map((w) => w.folded);
-    const eoo = folded.indexOf("--");
-    const slotSupplied = slot !== undefined && (eoo === -1 ? folded : folded.slice(0, eoo)).some((t) => suppliesFirstOperandSlot(slot, t));
+    const unsettling = (at, anyOption) => (folded[at] === "--" || (anyOption && folded[at].startsWith("-") && folded[at] !== "-") ? { unsettled: true } : {});
+    const plain = slot === undefined ? [] : walkArgs(row, words, readOption, undefined, readsRole);
+    const eoo = plain.find((e) => e.kind === "end-of-options")?.at ?? -1;
+    const operandsPast = new Set(plain.flatMap((e) => (e.kind === "dash-word-operand" ? [e.at] : [])));
+    const notOptions = new Set(plain.flatMap((e) => (e.kind === "value" && (e.consumed || operandsPast.has(e.of)) ? [e.at] : [])));
+    const slotSupplied = slot !== undefined && folded.some((t, k) => (eoo === -1 || k < eoo) && !notOptions.has(k) && suppliesFirstOperandSlot(slot, t));
     const permutes = !optionsStandAnywhere(row);
     const dashRead = row?.operands?.dash === "file" ? "file" : "stdin";
     const plus = row?.grammars.some((g) => g.plusOptions === true) === true;
@@ -467,11 +475,21 @@ function walkArgs(row, words, readOption, slot, readsRole) {
             const both = sawOperand && permutes;
             if (both) {
                 out.push({ kind: "dash-word-operand", at: k });
-                if (r.form === "separated" && k + 1 < words.length)
-                    out.push({ kind: "value", at: k + 1, of: k, role: r.role, consumed: false, ...(r.spec !== undefined ? { spec: r.spec } : {}) });
+                if (r.form === "separated" && k + 1 < words.length) {
+                    out.push({ kind: "value", at: k + 1, of: k, role: r.role, consumed: false, ...(r.spec !== undefined ? { spec: r.spec } : {}), ...unsettling(k + 1, false) });
+                    valueAt.add(k + 1);
+                }
             }
+            const owned = r.form === "no-value" || r.form === "unexplained" ? (valueAt.has(k) ? undefined : ownedValue?.(t, folded[k + 1])) : undefined;
+            const maybeValue = () => {
+                if (owned !== undefined && k + 1 < words.length) {
+                    out.push({ kind: "value", at: k + 1, of: k, role: owned.role, consumed: false, ...(owned.spec !== undefined ? { spec: owned.spec } : {}), ...unsettling(k + 1, true) });
+                    valueAt.add(k + 1);
+                }
+            };
             if (r.form === "no-value") {
                 out.push({ kind: "option", at: k, reading: "no-value" });
+                maybeValue();
                 continue;
             }
             if (r.form === "attached") {
@@ -485,6 +503,7 @@ function walkArgs(row, words, readOption, slot, readsRole) {
                 continue;
             }
             out.push({ kind: "option", at: k, reading: "speculative" });
+            maybeValue();
             continue;
         }
         const inSlot = slot !== undefined && !slotSupplied && !sawOperand;
@@ -497,11 +516,34 @@ function walkArgs(row, words, readOption, slot, readsRole) {
 }
 export function readArgs(row, words, opts) {
     const slot = opts.firstOperandSlot === false ? undefined : firstOperandSlot(row);
-    return walkArgs(row, words, (tok) => readOptionSlot(row, tok), opts.firstOperandSlot === "program-text" && slot?.role.kind !== "program-text" ? undefined : slot, preciseRole);
+    const owned = opts.ownedValues === true && row?.traversal?.discloses === "contents"
+        ? (tok, next) => {
+            const v = bareOptionValueOf(row, tok, next);
+            return v !== undefined && preciseRole(v.role) ? v : undefined;
+        }
+        : undefined;
+    return walkArgs(row, words, (tok) => readOptionSlot(row, tok), opts.firstOperandSlot === "program-text" && slot?.role.kind !== "program-text" ? undefined : slot, preciseRole, owned);
 }
 export function readArgRoles(row, args) {
     return walkArgs(row, args.map((folded) => ({ folded })), (tok, next) => readOptionRole(row, tok, next), firstOperandSlot(row, "roles"), () => true);
 }
+function keyWordIndex(row, args) {
+    if (row.traversal?.keyWordLetters === undefined)
+        return undefined;
+    const at = args.findIndex((t) => t.length > 0);
+    return at >= 0 && /^[A-Za-z]+$/.test(args[at]) ? at : undefined;
+}
+export function deliversOperands(row, args) {
+    if (row === undefined)
+        return false;
+    const key = keyWordIndex(row, args);
+    if (key !== undefined) {
+        const shorts = mergedTable(row, "short");
+        if ([...args[key]].some((ch) => shorts.get(ch)?.spec.delivers === "operands"))
+            return true;
+    }
+    return selectedOptions(row, key === undefined ? args : args.filter((_, k) => k !== key)).some((s) => s.delivers === "operands");
+}
 export function selectsContentsTraversal(row, args) {
     const model = row?.traversal;
     if (row === undefined || model === undefined || model.discloses !== "contents")
@@ -509,8 +551,8 @@ export function selectsContentsTraversal(row, args) {
     if (model.always === true)
         return true;
     if (model.keyWordLetters !== undefined) {
-        const first = args.find((t) => t.length > 0);
-        if (first !== undefined && !first.startsWith("-") && /^[A-Za-z]+$/.test(first) && [...first].some((ch) => model.keyWordLetters.includes(ch)))
+        const at = keyWordIndex(row, args);
+        if (at !== undefined && [...args[at]].some((ch) => model.keyWordLetters.includes(ch)))
             return true;
     }
     const shorts = mergedTable(row, "short");
@@ -531,11 +573,11 @@ export function selectsContentsTraversal(row, args) {
             const long = longOptionNameOf(t);
             if (long === undefined)
                 continue;
-            if ([...longs].some(([full, m]) => m.spec.selects === "traversal" && isLongOptionAbbrevOf(long, full)))
+            if ([...longs].some(([full, m]) => m.spec.selects === "traversal" && isLongOptionSpellingOf(long, full, m.abbreviable)))
                 return true;
             for (const [full, m] of longs) {
                 const recursive = m.spec.selectsWhenValue;
-                if (recursive === undefined || !isLongOptionAbbrevOf(long, full))
+                if (recursive === undefined || !isLongOptionSpellingOf(long, full, m.abbreviable))
                     continue;
                 const eq = t.indexOf("=");
                 const v = eq >= 0 ? t.slice(eq + 1) : args[k + 1];
@@ -580,7 +622,7 @@ export function valuesAreLiteral(row, args) {
     const longs = mergedTable(row, "long");
     const negates = (t) => {
         const name = t.startsWith("--no-") ? longOptionNameOf(t)?.slice(3) : undefined;
-        return name !== undefined && name.length > 0 && [...longs].some(([full, m]) => m.spec.literalValues === true && isLongOptionAbbrevOf(name, full));
+        return name !== undefined && name.length > 0 && [...longs].some(([full, m]) => m.spec.literalValues === true && isLongOptionSpellingOf(name, full, m.abbreviable));
     };
     if (args.some(negates))
         return false;
@@ -599,7 +641,7 @@ export function valuesAreLiteral(row, args) {
             if (long === undefined || t.includes("="))
                 continue;
             const exact = longs.get(long);
-            const hits = exact !== undefined ? [exact] : [...longs].filter(([full]) => isLongOptionAbbrevOf(long, full)).map(([, m]) => m);
+            const hits = exact !== undefined ? [exact] : [...longs].filter(([full, m]) => isLongOptionSpellingOf(long, full, m.abbreviable)).map(([, m]) => m);
             if (hits.length === 1 && hits[0].spec.literalValues === true)
                 return true;
             continue;
@@ -629,7 +671,7 @@ export function takesSeparatedDatum(row, tok) {
         if (tok.includes("="))
             return false;
         const name = longOptionNameOf(tok);
-        return name !== undefined && [...mergedTable(row, "long")].some(([full, m]) => isLongOptionAbbrevOf(name, full) && m.takesValueSomewhere && isDatumValue(m));
+        return name !== undefined && [...mergedTable(row, "long")].some(([full, m]) => isLongOptionSpellingOf(name, full, m.abbreviable) && m.takesValueSomewhere && isDatumValue(m));
     }
     if (!/^-[A-Za-z0-9]/.test(tok))
         return false;
@@ -644,6 +686,43 @@ export function takesSeparatedDatum(row, tok) {
     }
     return false;
 }
+const COUNT_SPELLING = /^[+-]?[0-9_]+$/;
+const UNDECLARED_VALUE = { kind: "datum", form: "label" };
+export function bareOptionValueOf(row, tok, next) {
+    if (next === undefined || !tok.startsWith("-") || tok === "-" || tok === "--")
+        return undefined;
+    if (tok.startsWith("--") && !tok.includes("=")) {
+        const name = longOptionNameOf(tok);
+        if (name !== undefined && ![...mergedTable(row, "long")].some(([full, m]) => isLongOptionSpellingOf(name, full, m.abbreviable)))
+            return { role: UNDECLARED_VALUE };
+    }
+    const owns = (s) => s.value !== undefined && (s.arity === 1 || (s.arity === "attached" && s.value.kind === "datum" && s.value.form === "count" && COUNT_SPELLING.test(next)));
+    for (const g of row.grammars) {
+        let found;
+        if (tok.startsWith("--")) {
+            const name = longOptionNameOf(tok);
+            if (name === undefined || tok.includes("="))
+                continue;
+            const exact = g.long[name];
+            const reach = exact !== undefined ? [exact] : Object.entries(g.long).filter(([full]) => isLongOptionSpellingOf(name, full, abbreviates(g))).map(([, s]) => s);
+            if (reach.length > 0 && reach.every(owns))
+                found = reach[0];
+        }
+        else {
+            for (let i = 1; i < tok.length; i++) {
+                const spec = g.short[tok[i]];
+                if (spec === undefined || spec.arity === 0)
+                    continue;
+                if (i === tok.length - 1 && owns(spec))
+                    found = spec;
+                break;
+            }
+        }
+        if (found?.value !== undefined)
+            return { role: found.value, spec: found };
+    }
+    return undefined;
+}
 export function attachedStdinFile(row, tok) {
     if (row === undefined)
         return false;
@@ -654,7 +733,7 @@ export function attachedStdinFile(row, tok) {
             return false;
         const longs = mergedTable(row, "long");
         const exact = longs.get(name);
-        const reach = exact !== undefined ? [exact] : [...longs].filter(([full]) => isLongOptionAbbrevOf(name, full)).map(([, m]) => m);
+        const reach = exact !== undefined ? [exact] : [...longs].filter(([full, m]) => isLongOptionSpellingOf(name, full, m.abbreviable)).map(([, m]) => m);
         return reach.length === 0 || reach.some((m) => m.arity !== 0 && isFileValue(m.spec));
     }
     if (!/^-[A-Za-z0-9]/.test(tok))
@@ -747,7 +826,7 @@ function scanOptions(row, args, one) {
                 continue;
             const eq = t.indexOf("=");
             const exact = longs.get(name);
-            const hits = exact !== undefined ? [[name, exact]] : [...longs].filter(([full]) => isLongOptionAbbrevOf(name, full));
+            const hits = exact !== undefined ? [[name, exact]] : [...longs].filter(([full, m]) => isLongOptionSpellingOf(name, full, m.abbreviable));
             for (const [full, m] of hits)
                 select(m.spec, `--${full}`);
             const [full, only] = hits[0] ?? [];
@@ -1173,7 +1252,7 @@ function programTextUnder(g, args) {
     let endOfOptions = false;
     let firstOperand;
     const longs = Object.entries(g.long);
-    const reach = (long, pick) => longs.some(([full, s]) => pick(s) && isLongOptionAbbrevOf(long, full));
+    const reach = (long, pick) => longs.some(([full, s]) => pick(s) && isLongOptionSpellingOf(long, full, abbreviates(g)));
     for (let k = 0; k < args.length; k++) {
         const tok = args[k];
         if (!endOfOptions && tok === "--") {
@@ -1318,7 +1397,7 @@ export function messageWords(program, words, programIndex) {
         if (w.startsWith("--")) {
             const eq = w.indexOf("=");
             const name = w.slice(2, eq < 0 ? undefined : eq);
-            const takers = longValues.filter(([n]) => n.startsWith(name));
+            const takers = longValues.filter(([n]) => isLongOptionSpellingOf(name, n, abbreviates(sub)));
             const message = (name.length > 0 && takers.length > 0 && takers.every(([, s]) => isMessage(s))) || isMessage(sub.long[name]);
             if (eq >= 0) {
                 if (message)

package/dist/tools/fs/program-read-model.rows.js

@@ -32,6 +32,7 @@ const MOUNT = { kind: "mount-source", form: "mount" };
 const OBJECT_PATH = { kind: "object-path" };
 const text = (language) => ({ kind: "program-text", language });
 const file = (language) => ({ kind: "program-file", language });
+const WALKS = { walks: true };
 const SWITCH = { arity: 0 };
 const QUERY = { arity: 0, mode: "queries" };
 const val = (value, extra = {}) => ({ arity: 1, ...(value !== undefined ? { value } : {}), ...extra });
@@ -114,9 +115,9 @@ const grepRow = (key) => ({
 });
 const diff = {
     key: "diff",
-    grammars: implementations(grammar({ C: val(COUNT), D: val(LABEL), F: val(PATTERN), I: val(PATTERN), L: val(LABEL), S: val(NAMES), U: val(COUNT), W: val(COUNT), X: val(READ), x: val(NAME_PATTERN), ...switches("abBcdeEHilnNpqstTuvwyZ"), ...switches("r", { selects: "traversal" }) }, {
-        exclude: val(NAME_PATTERN), "exclude-from": val(READ), "from-file": val(READ), "horizon-lines": val(COUNT), ifdef: val(LABEL), "ignore-matching-lines": val(PATTERN),
-        label: val(LABEL), "show-function-line": val(PATTERN), "starting-file": val(NAMES), tabsize: val(COUNT), "to-file": val(READ), width: val(COUNT),
+    grammars: implementations(grammar({ C: val(COUNT), D: val(LABEL), F: val(PATTERN), I: val(PATTERN), L: val(LABEL), S: val(NAME_PATTERN), U: val(COUNT), W: val(COUNT), X: val(READ), x: val(NAME_PATTERN), ...switches("abBcdeEHilnNpqstTuvwyZ"), ...switches("r", { selects: "traversal" }) }, {
+        exclude: val(NAME_PATTERN), "exclude-from": val(READ), "from-file": val(READ, WALKS), "horizon-lines": val(COUNT), ifdef: val(LABEL), "ignore-matching-lines": val(PATTERN),
+        label: val(LABEL), "show-function-line": val(PATTERN), "starting-file": val(NAME_PATTERN), tabsize: val(COUNT), "to-file": val(READ, WALKS), width: val(COUNT),
         color: optional(LABEL), context: optional(COUNT), unified: optional(COUNT),
         ...longSwitches(["brief", "ed", "expand-tabs", "ignore-all-space", "ignore-blank-lines", "ignore-case", "ignore-space-change", "ignore-tab-expansion", "ignore-trailing-space", "initial-tab", "minimal", "new-file", "normal", "paginate", "report-identical-files", "rcs", "show-c-function", "side-by-side", "speed-large-files", "suppress-blank-empty", "text"]), ...BANNERS,
         ...longSwitches(["recursive"], { selects: "traversal" }),
@@ -163,8 +164,8 @@ const date = {
 };
 const tar = {
     key: "tar",
-    grammars: [grammar({ b: val(COUNT), C: val(NAMES), f: val(READ), T: val(READ, { delivers: "operands" }), X: val(READ), g: val(), ...switches("adhjJkmOpPStvwWxzZ"), ...switches("cru", { selects: "traversal" }) }, {
-            "blocking-factor": val(COUNT), directory: val(NAMES), exclude: val(NAME_PATTERN), "exclude-from": val(READ), file: val(READ), "files-from": val(READ, { delivers: "operands" }), "strip-components": val(COUNT),
+    grammars: [grammar({ b: val(COUNT), C: val(NAMES, WALKS), f: val(READ), T: val(READ, { delivers: "operands" }), X: val(READ), g: val(), ...switches("adhjJkmOpPStvwWxzZ"), ...switches("cru", { selects: "traversal" }) }, {
+            "blocking-factor": val(COUNT), directory: val(NAMES, WALKS), exclude: val(NAME_PATTERN), "exclude-from": val(READ), file: val(READ), "files-from": val(READ, { delivers: "operands" }), "strip-components": val(COUNT),
             ...longSwitches(["absolute-names", "dereference", "extract", "get", "interactive", "keep-old-files", "list", "preserve-permissions", "sparse", "to-stdout", "touch", "verbose", "verify"]), ...BANNERS,
             ...longSwitches(["append", "create", "update"], { selects: "traversal" }),
         })],
@@ -230,13 +231,32 @@ const ls = {
     traversal: { discloses: "names" },
     witness: BINARY,
 };
-const walker = (key, discloses, dashFile) => ({
+const namesWalker = (key) => ({ key, grammars: [], operands: { dash: "file", rest: NAMES }, traversal: { discloses: "names", always: true }, witness: BINARY });
+const contentsWalker = (key, short, long, extra = {}) => ({
     key,
-    grammars: discloses === "contents" ? [grammar({}, {}, { walksCwdWithoutOperand: true })] : [],
-    ...(dashFile ? { operands: { dash: "file", ...(discloses === "names" ? { rest: NAMES } : {}) } } : {}),
-    traversal: { discloses, always: true },
+    grammars: [grammar(short, long, { walksCwdWithoutOperand: true, ...extra })],
+    operands: { positional: [PATTERN] },
+    traversal: { discloses: "contents", always: true },
     witness: BINARY,
 });
+const rg = contentsWalker("rg", { e: val(PATTERN, { fillsSlot: true }), f: val(READ, { fillsSlot: true }), ...values("ABCdjmM", COUNT), ...values("ErtT", LABEL), g: val(NAME_PATTERN) }, {
+    regexp: val(PATTERN, { fillsSlot: true }), file: val(READ, { fillsSlot: true }),
+    files: { arity: 0, fillsSlot: true },
+    ...Object.fromEntries(["after-context", "before-context", "context", "max-count", "max-depth", "max-columns", "threads"].map((n) => [n, val(COUNT)])),
+    ...Object.fromEntries(["color", "colors", "context-separator", "dfa-size-limit", "encoding", "engine", "field-context-separator", "field-match-separator", "generate", "hyperlink-format", "max-filesize", "path-separator", "regex-size-limit", "replace", "sort", "sortr", "type", "type-add", "type-clear", "type-not"].map((n) => [n, val(LABEL)])),
+    glob: val(NAME_PATTERN), iglob: val(NAME_PATTERN), "pre-glob": val(NAME_PATTERN), "ignore-file": val(READ),
+    ...BANNERS,
+}, { acceptsAbbreviations: false });
+const ag = contentsWalker("ag", { g: val(PATTERN, { fillsSlot: true }), G: val(PATTERN), m: val(COUNT), p: val(READ), A: val(COUNT), B: val(COUNT), C: val(COUNT) }, {
+    "file-search-regex": val(PATTERN), "max-count": val(COUNT), "path-to-ignore": val(READ),
+    after: optional(COUNT), before: optional(COUNT), context: optional(COUNT),
+    ...BANNERS,
+});
+const ack = contentsWalker("ack", { f: { arity: 0, fillsSlot: true }, m: val(COUNT), A: optional(COUNT), B: optional(COUNT), C: optional(COUNT), x: { arity: 0, delivers: "operands" } }, {
+    match: val(PATTERN, { fillsSlot: true }), "max-count": val(COUNT), ackrc: val(READ), "files-from": val(READ, { delivers: "operands" }),
+    "after-context": optional(COUNT), "before-context": optional(COUNT), context: optional(COUNT),
+    ...BANNERS,
+});
 const BANNER_LONGS = ["--version", "--help", "--usage", "-version", "-help"];
 function interpreterGrammar(language, g) {
     const short = {};
@@ -591,7 +611,7 @@ const block = (key, g = []) => ({ key, grammars: g, syntax: "block", witness: SY
 const BLOCK_GRAMMARS = { "[[": [grammar({ v: val(BINDS_NAME) })] };
 export const PROGRAM_ROWS = [
     head, tail, cut, grepRow("grep"), grepRow("egrep"), grepRow("fgrep"), diff, cmp, sed, date, tar, find, curl,
-    ls, walker("du", "names", true), walker("rg", "contents", false), walker("tree", "names", true), walker("ag", "contents", false), walker("ack", "contents", false),
+    ls, namesWalker("du"), rg, namesWalker("tree"), ag, ack,
     interpreter("perl", "perl", PERL, "file", true),
     interpreter("ruby", "ruby", RUBY, "file", true),
     interpreter("python", "python", PYTHON, "file", true, { modules: { timeit: text("python") } }),

package/dist/tools/fs/read-deny-home.d.ts

@@ -95,18 +95,34 @@ export interface HomeViewSource {
      *  once and shared by every path below it. */
     views(signal?: AbortSignal, env?: HomeViewEnv): HomeViews;
 }
-/** A judgment's views. `of` answers the view only where it differs from the path as spelled; `undefined` otherwise, and
- *  wherever it cannot be read: no `fileIdentity` seat, no home, a level of the path whose identity fails (the path is
- *  judged as spelled, never wider). A level that does not exist (a write's missing tail) takes its parent's view.
- *  `leaf: "file"` skips the path's own identity (a file is never a directory on the chain). */
+/** A judgment's views. `of` answers one path's {@link HomeView}: no view where there is nothing to read (no `fileIdentity`
+ *  seat, no home, a seat that declares the surface absent — the path is judged as spelled); the view where it differs from
+ *  the path as spelled; and `unread` wherever a lookup the view stands on gave no answer. A level that does not exist (a
+ *  write's missing tail) takes its parent's view. `leaf: "file"` skips the path's own identity (a file is never a directory
+ *  on the chain). */
 export interface HomeViews {
     of(path: string, opts?: {
         readonly leaf?: "file";
-    }): Promise<string | undefined>;
-    /** The paths whose identity lookup gave no answer in this judgment (a throw, a timeout, an error that is no conclusive "not
-     *  there"): for them `of` answered `undefined` for want of a reading, not because there is no view — a consumer that
-     *  must not vouch past an unread view (the shell station) reads this after its lookups. Live: grows as `of` is asked. */
-    readonly unread: readonly string[];
+    }): Promise<HomeView>;
+}
+/** One path's home view as a judge reads it:
+ *  · `view` — the path respelled through a home's own directory chain, present only where it differs from the spelling;
+ *  · `unread` — the first lookup the view stands on that gave no answer (an identity lookup that threw, timed out or failed
+ *    with an error that is no conclusive "not there": a level of a home's chain — the index of every path is then partial —
+ *    or a level of the path itself), present wherever one did, and inherited by every path below it.
+ *  An `unread` answer is no reading: the path's view is not "none", it is unknown, so a judge that places the home-anchored
+ *  rows by the view has not finished — every judge refuses to vouch past it ({@link homeViewUnreadSentence}). */
+export interface HomeView {
+    readonly view?: string;
+    readonly unread?: string;
+}
+/** The one sentence a judgment that met an unread home view ({@link HomeView.unread}) refuses with — `subject` the path the
+ *  call judged, `face` the deny table it was judged against. */
+export declare function homeViewUnreadSentence(subject: string, unread: string, face?: "read" | "write"): string;
+/** The refusal a traversal raises when an entry it walks met an unread home view: the whole call is refused (what the walk
+ *  would serve was not judged), with the one sentence. */
+export declare class HomeViewUnreadError extends Error {
+    constructor(subject: string, unread: string);
 }
 /** A judge that carries the home views of the placement its rows were compiled at. */
 export interface HomeViewsCarrier {