@sema-agent/core 7.51.1 → 7.52.0

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 {

package/dist/tools/fs/read-deny-home.js

@@ -260,6 +260,15 @@ async function readAuxiliaryHome(env, home, opts, signal) {
         sayAuxiliary("a probe did not answer", opts.configRoot === true ? "config_root" : "auxiliary");
     return reading;
 }
+export function homeViewUnreadSentence(subject, unread, face = "read") {
+    return `"${subject}" could not be judged against the ${face} deny list: "${unread}" cannot be identified against the home directories the home-anchored rows are placed under, so whether such a row covers it is unknown; refused — a deny judgment that did not finish is not a pass. Retry once the environment answers identity lookups.`;
+}
+export class HomeViewUnreadError extends Error {
+    constructor(subject, unread) {
+        super(homeViewUnreadSentence(subject, unread));
+        this.name = "HomeViewUnreadError";
+    }
+}
 function homeViewSourceOver(env, auxiliary) {
     const declared = declaredHomeOf(env);
     let declaredChain;
@@ -285,12 +294,10 @@ function homeViewSourceOver(env, auxiliary) {
             const at = judgmentEnv ?? env;
             const identity = at.fileIdentity;
             let index;
-            const unread = [];
             const indexOf = () => (index ??= (async () => {
-                const chains = [await readDeclared(at), ...(await Promise.all(auxiliary)).map((a) => a.chain)];
-                for (const at of chains.flatMap((c) => c.unread))
-                    if (!unread.includes(at))
-                        unread.push(at);
+                const declaredChain = await readDeclared(at);
+                const chains = [declaredChain, ...(await Promise.all(auxiliary)).map((a) => a.chain)];
+                const unread = declaredChain.unread[0];
                 const out = new Map();
                 for (const { own } of chains)
                     if (own !== undefined && !out.has(own.id))
@@ -299,7 +306,7 @@ function homeViewSourceOver(env, auxiliary) {
                     for (const { dir, id } of ancestors)
                         if (!out.has(id))
                             out.set(id, dir);
-                return out.size > 0 ? out : undefined;
+                return { ...(out.size > 0 ? { ids: out } : {}), ...(unread !== undefined ? { unread } : {}) };
             })());
             const views = new Map();
             const viewOf = (path, leafIsFile) => {
@@ -308,25 +315,26 @@ function homeViewSourceOver(env, auxiliary) {
                 if (v === undefined) {
                     v = (async () => {
                         const index = await indexOf();
-                        if (index === undefined || typeof identity !== "function")
-                            return undefined;
+                        const chain = index.unread !== undefined ? { unread: index.unread } : {};
+                        if (index.ids === undefined || typeof identity !== "function")
+                            return chain;
                         if (!leafIsFile) {
                             const id = await identityOf(at, identity, path, signal);
                             if (identityUnread(id))
-                                return void unread.push(path);
+                                return { unread: path };
                             if (id?.ok === true) {
-                                const at = index.get(id.value);
-                                if (at !== undefined)
-                                    return at;
+                                const dir = index.ids.get(id.value);
+                                if (dir !== undefined)
+                                    return { ...chain, view: dir };
                             }
                             else if (id?.error.code === "not_supported")
-                                return undefined;
+                                return chain;
                         }
                         const parent = normalizeAbsPathLexically(`${path}/..`);
                         if (parent === path)
-                            return undefined;
+                            return chain;
                         const up = await viewOf(parent, false);
-                        return up === undefined ? undefined : joinForFamily(pathFamilyOf({ root: path }), up, path.slice(parent.length).replace(/^[\\/]+/, ""));
+                        return up.view === undefined ? up : { ...up, view: joinForFamily(pathFamilyOf({ root: path }), up.view, path.slice(parent.length).replace(/^[\\/]+/, "")) };
                     })();
                     views.set(key, v);
                 }
@@ -335,12 +343,11 @@ function homeViewSourceOver(env, auxiliary) {
             return {
                 async of(path, opts) {
                     if (typeof identity !== "function" || (declared === undefined && auxiliary.length === 0) || !isAbsoluteForFamily("own", path))
-                        return undefined;
+                        return {};
                     const spelled = normalizeAbsPathLexically(path);
-                    const view = await viewOf(spelled, opts?.leaf === "file");
-                    return view === undefined || view === spelled ? undefined : view;
+                    const { view, unread } = await viewOf(spelled, opts?.leaf === "file");
+                    return { ...(view !== undefined && view !== spelled ? { view } : {}), ...(unread !== undefined ? { unread } : {}) };
                 },
-                unread,
             };
         },
     };
@@ -379,6 +386,7 @@ export function readDenyOver(current, homeViews) {
             return current().rgProbeGlobs;
         },
         unexcludableUnder: (scope) => current().unexcludableUnder?.(scope) ?? false,
+        rowUnderRoot: (scope) => current().rowUnderRoot?.(scope) ?? null,
         rowAtOrBelow: (path) => current().rowAtOrBelow?.(path) ?? null,
         homeViews: homeViews ?? { views: (signal) => current().homeViews.views(signal) },
     };
@@ -464,15 +472,8 @@ export function readDenyPlacedLater(unplaced, place) {
     const homeViews = {
         views(signal, judgmentEnv) {
             let views;
-            const unread = [];
             return {
-                of: async (path, opts) => {
-                    const inner = await (views ??= settled().then((m) => m.homeViews.views(signal, judgmentEnv)));
-                    const view = await inner.of(path, opts);
-                    unread.splice(0, unread.length, ...inner.unread);
-                    return view;
-                },
-                unread,
+                of: async (path, opts) => (await (views ??= settled().then((m) => m.homeViews.views(signal, judgmentEnv)))).of(path, opts),
             };
         },
     };