@vincemakes/kiso-tools-node 0.37.0 → 0.39.0

package/dist/corpus.d.ts

@@ -0,0 +1,96 @@
+/**
+ * THE SEARCH CORPUS — one definition of "which files a search may see",
+ * shared by `search_text` and `list_dir`'s glob.
+ *
+ * They disagreed before this existed: `list_dir` listed every dot entry
+ * and `search_text` skipped all of them. Two walkers is how that happens,
+ * so there is one.
+ *
+ * The rule is the user's own declaration. A `.gitignore` FILE at the
+ * workspace root switches the corpus on — not the presence of `.git`, and
+ * the walk never goes up. A `.gitignore` is the declaration wherever the
+ * repository root happens to be, which is what lets a monorepo
+ * subdirectory carrying its own file be treated properly instead of being
+ * penalised for not being a repository root; and `.git` says nothing the
+ * file does not. With no declaration there is nothing to trust, so the
+ * old conservative rule stands: every dot entry skipped.
+ *
+ * Two things are never searched, declaration or not:
+ *
+ *  - `.git`, which is machinery, not content.
+ *  - the CREDENTIAL SET below — files whose conventional purpose is to
+ *    hold credentials. A committed file is not a secret by the user's own
+ *    declaration, so `.github/` and `.eslintrc` ARE searchable; but an
+ *    incidental hit from a search for "KEY" is exposure without intent,
+ *    and that is what this prevents. An explicit `read_file` of any of
+ *    them is unchanged.
+ *
+ * `node_modules` is skipped unconditionally in both modes, as before. It
+ * is not a declaration question: DC-54 measured 296,924 files under a home
+ * directory, and a corpus that can reach a dependency tree is the freeze
+ * that finding was about.
+ */
+import { type Ignore } from "ignore";
+/** The walk stops here. `search_text` has always used 8; the glob inherits
+ *  it so a pattern cannot reach deeper than a search can. */
+export declare const CORPUS_MAX_DEPTH = 8;
+export declare function isCredentialName(name: string): boolean;
+export interface CorpusOptions {
+    workspaceRoot: string;
+    /** Default CORPUS_MAX_DEPTH. */
+    maxDepth?: number;
+    /** Stop after this many files. Default: no cap (search has its own
+     *  budget; the glob passes 200). */
+    maxEntries?: number;
+    /** DC-49 exclude roots — the user's own knob, unchanged. */
+    isExcluded?: (fullPath: string) => boolean;
+    /** Keep only these. Applied BEFORE the cap, so `maxEntries` bounds the
+     *  files returned and not the files walked past — capping the walk
+     *  first and filtering after would silently return fewer matches than
+     *  exist, which is the defect the cap note exists to prevent. */
+    accept?: (workspaceRelative: string) => boolean;
+    /** Start the walk here instead of at the root. The DECLARATION is still
+     *  read at `workspaceRoot` and paths are still relative to it. */
+    walkFrom?: string;
+}
+export interface CorpusWalk {
+    /** Workspace-relative, POSIX-separated. */
+    files: string[];
+    /** The walk stopped descending somewhere. DIFFERENT from the cap: the
+     *  remedy is "the file is deeper than a search reaches", not "narrow
+     *  the directory". Reported separately, and never claimed when it did
+     *  not happen — a walk that silently returns less is the same defect
+     *  as a read that silently returns 200 lines. */
+    cutByDepth: boolean;
+    /** The entry cap was reached. */
+    cutByCap: boolean;
+}
+/** One directory's `.gitignore`, and the directory it is relative to. */
+export interface Layer {
+    dir: string;
+    matcher: Ignore;
+}
+export declare function readLayer(dir: string): Layer | null;
+/** Ignored by ANY ancestor's file, each tested against the path relative
+ *  to the directory that declared it — which is what makes a nested
+ *  `.gitignore` apply to its own subtree and not above it. */
+export declare function ignoredBy(layers: readonly Layer[], full: string, isDir: boolean): boolean;
+/** The SHARED predicate. `search_text` walks its own tree (its walk is
+ *  interleaved with the budget and the matcher) and `walkCorpus` walks
+ *  here, but both ask THIS — which is the whole point of there being one
+ *  corpus rather than two walkers that agree by coincidence. */
+export declare function corpusSkips(declared: boolean, layers: readonly Layer[], full: string, name: string, isDir: boolean): boolean;
+/** The layers in force inside `dir`, given its parent's. */
+export declare function layersEntering(dir: string, parent: readonly Layer[]): readonly Layer[];
+export declare function walkCorpus(opts: CorpusOptions): CorpusWalk;
+/** A minimal glob → RegExp, anchored, over workspace-relative POSIX paths.
+ *
+ *  `*` any run except `/`, `?` one character except `/`, `**` any run
+ *  including `/`. A leading `** /` (without the space) matches zero or
+ *  more directories, so `**\/*.ts` finds a root-level `a.ts` — the
+ *  behaviour people expect and the one a naive translation gets wrong by
+ *  requiring at least one directory.
+ *
+ *  Everything else is literal, including the regex metacharacters a path
+ *  can legally contain. */
+export declare function globToRegExp(pattern: string): RegExp;

package/dist/corpus.js

@@ -0,0 +1,218 @@
+/**
+ * THE SEARCH CORPUS — one definition of "which files a search may see",
+ * shared by `search_text` and `list_dir`'s glob.
+ *
+ * They disagreed before this existed: `list_dir` listed every dot entry
+ * and `search_text` skipped all of them. Two walkers is how that happens,
+ * so there is one.
+ *
+ * The rule is the user's own declaration. A `.gitignore` FILE at the
+ * workspace root switches the corpus on — not the presence of `.git`, and
+ * the walk never goes up. A `.gitignore` is the declaration wherever the
+ * repository root happens to be, which is what lets a monorepo
+ * subdirectory carrying its own file be treated properly instead of being
+ * penalised for not being a repository root; and `.git` says nothing the
+ * file does not. With no declaration there is nothing to trust, so the
+ * old conservative rule stands: every dot entry skipped.
+ *
+ * Two things are never searched, declaration or not:
+ *
+ *  - `.git`, which is machinery, not content.
+ *  - the CREDENTIAL SET below — files whose conventional purpose is to
+ *    hold credentials. A committed file is not a secret by the user's own
+ *    declaration, so `.github/` and `.eslintrc` ARE searchable; but an
+ *    incidental hit from a search for "KEY" is exposure without intent,
+ *    and that is what this prevents. An explicit `read_file` of any of
+ *    them is unchanged.
+ *
+ * `node_modules` is skipped unconditionally in both modes, as before. It
+ * is not a declaration question: DC-54 measured 296,924 files under a home
+ * directory, and a corpus that can reach a dependency tree is the freeze
+ * that finding was about.
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import ignore, {} from "ignore";
+/** The walk stops here. `search_text` has always used 8; the glob inherits
+ *  it so a pattern cannot reach deeper than a search can. */
+export const CORPUS_MAX_DEPTH = 8;
+/** THE CREDENTIAL SET — files whose CONVENTIONAL PURPOSE is to hold
+ *  credentials. That class is the rule; the list is its application, and
+ *  the next candidate is judged by the class rather than by resemblance.
+ *  Changes to this list are RULINGS, not edits.
+ *
+ *  Enumerated rather than matched by prefix: `.env*` as a prefix would
+ *  also swallow `.environment` and `.envoy.yaml`, which are ordinary
+ *  files that happen to start the same way.
+ *
+ *  IN, and why:
+ *    `.env`, `.env.*`   the convention itself
+ *    `.envrc`           direnv — routinely `export AWS_SECRET_...`
+ *    `.netrc`           machine credentials, by definition
+ *    id_rsa, id_dsa,    private keys, by name. Their `.pub` counterparts
+ *    id_ecdsa,          are different names and stay searchable, which is
+ *    id_ed25519         correct: a public key is public.
+ *    *.pem              the same, by extension
+ *
+ *  OUT, deliberately, so the omissions are decisions and not oversights:
+ *    `.npmrc`   a config file by convention; tokens in it are normally
+ *               `${VAR}` placeholders, so excluding it would cost more
+ *               than it protects
+ *    `*.key`    too many non-secret uses to be a credential by name
+ *
+ *  An explicit `read_file` of ANY of these is unchanged. Reading on
+ *  purpose is the user's model doing what it was told; an incidental hit
+ *  from a search for "KEY" is exposure without intent, and only the
+ *  second is what this prevents. */
+const ENV_TEMPLATES = new Set([".env.example", ".env.sample", ".env.template"]);
+const CREDENTIAL_NAMES = new Set([".envrc", ".netrc", "id_rsa", "id_dsa", "id_ecdsa", "id_ed25519"]);
+export function isCredentialName(name) {
+    if (ENV_TEMPLATES.has(name))
+        return false;
+    if (name === ".env" || name.startsWith(".env."))
+        return true;
+    if (CREDENTIAL_NAMES.has(name))
+        return true;
+    return name.endsWith(".pem");
+}
+export function readLayer(dir) {
+    let text;
+    try {
+        text = readFileSync(join(dir, ".gitignore"), "utf8");
+    }
+    catch {
+        return null;
+    }
+    return { dir, matcher: ignore().add(text) };
+}
+/** Ignored by ANY ancestor's file, each tested against the path relative
+ *  to the directory that declared it — which is what makes a nested
+ *  `.gitignore` apply to its own subtree and not above it. */
+export function ignoredBy(layers, full, isDir) {
+    for (const layer of layers) {
+        const rel = relative(layer.dir, full).split(sep).join("/");
+        if (rel === "" || rel.startsWith("../"))
+            continue;
+        if (layer.matcher.ignores(isDir ? `${rel}/` : rel))
+            return true;
+    }
+    return false;
+}
+/** The SHARED predicate. `search_text` walks its own tree (its walk is
+ *  interleaved with the budget and the matcher) and `walkCorpus` walks
+ *  here, but both ask THIS — which is the whole point of there being one
+ *  corpus rather than two walkers that agree by coincidence. */
+export function corpusSkips(declared, layers, full, name, isDir) {
+    if (name === "node_modules" || name === ".git")
+        return true;
+    if (isCredentialName(name))
+        return true;
+    if (!declared)
+        return name.startsWith(".");
+    return ignoredBy(layers, full, isDir);
+}
+/** The layers in force inside `dir`, given its parent's. */
+export function layersEntering(dir, parent) {
+    const own = readLayer(dir);
+    return own === null ? parent : [...parent, own];
+}
+export function walkCorpus(opts) {
+    const root = opts.workspaceRoot;
+    const maxDepth = opts.maxDepth ?? CORPUS_MAX_DEPTH;
+    const maxEntries = opts.maxEntries ?? Number.POSITIVE_INFINITY;
+    const rootLayer = readLayer(root);
+    /** No declaration, nothing to trust: the pre-corpus rule, unchanged. */
+    const declared = rootLayer !== null;
+    const files = [];
+    let cutByDepth = false;
+    let cutByCap = false;
+    const walk = (dir, depth, layers) => {
+        if (cutByCap)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable directory: skipped, as before
+        }
+        const here = depth === 0 ? layers : layersEntering(dir, layers);
+        for (const entry of entries) {
+            if (cutByCap)
+                return;
+            const name = entry.name;
+            const full = join(dir, name);
+            const isDir = entry.isDirectory();
+            if (corpusSkips(declared, here, full, name, isDir))
+                continue;
+            if (isDir) {
+                if (opts.isExcluded?.(full) === true)
+                    continue;
+                if (depth + 1 > maxDepth) {
+                    cutByDepth = true;
+                    continue;
+                }
+                walk(full, depth + 1, here);
+                continue;
+            }
+            const rel = relative(root, full).split(sep).join("/");
+            if (opts.accept !== undefined && !opts.accept(rel))
+                continue;
+            if (files.length >= maxEntries) {
+                cutByCap = true;
+                return;
+            }
+            files.push(rel);
+        }
+    };
+    const start = opts.walkFrom ?? root;
+    // entering a subtree, the layers between root and it still apply
+    let startLayers = rootLayer === null ? [] : [rootLayer];
+    if (start !== root) {
+        let cur = root;
+        for (const part of relative(root, start).split(sep).filter(Boolean)) {
+            cur = join(cur, part);
+            startLayers = layersEntering(cur, startLayers);
+        }
+    }
+    walk(start, 0, startLayers);
+    return { files, cutByDepth, cutByCap };
+}
+/** A minimal glob → RegExp, anchored, over workspace-relative POSIX paths.
+ *
+ *  `*` any run except `/`, `?` one character except `/`, `**` any run
+ *  including `/`. A leading `** /` (without the space) matches zero or
+ *  more directories, so `**\/*.ts` finds a root-level `a.ts` — the
+ *  behaviour people expect and the one a naive translation gets wrong by
+ *  requiring at least one directory.
+ *
+ *  Everything else is literal, including the regex metacharacters a path
+ *  can legally contain. */
+export function globToRegExp(pattern) {
+    let out = "";
+    for (let i = 0; i < pattern.length; i += 1) {
+        const c = pattern[i];
+        if (c === "*") {
+            if (pattern[i + 1] === "*") {
+                // `**/` spans zero or more directories; a bare `**` spans anything
+                if (pattern[i + 2] === "/") {
+                    out += "(?:.*/)?";
+                    i += 2;
+                }
+                else {
+                    out += ".*";
+                    i += 1;
+                }
+            }
+            else
+                out += "[^/]*";
+            continue;
+        }
+        if (c === "?") {
+            out += "[^/]";
+            continue;
+        }
+        out += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${out}$`);
+}

package/dist/index.d.ts

@@ -145,6 +145,7 @@ export declare function readFileTool(opts: WorkspaceToolsOptions): Tool<{
 }>;
 export declare function listDirTool(opts: WorkspaceToolsOptions): Tool<{
     path?: string;
+    glob?: string;
 }>;
 /** The instrument behind gate (d): live workers and queue depth. */
 export declare function searchWorkerStats(): {

package/dist/index.js

@@ -24,11 +24,12 @@ import { Worker } from "node:worker_threads";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 import { tmpdir } from "node:os";
-import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { defineTool } from "@vincemakes/kiso-core";
 // WR-1/WR-1A — the revision-guard primitives (unit-tested in wr1a-coda):
 import { strippedShellEnv } from "./secret-env.js";
 import { contentRevision, normalizeRevision, postEffectEscape, precondition, publishNewFile, revalidateBeforeRename } from "./wr1.js";
+import { CORPUS_MAX_DEPTH, globToRegExp, walkCorpus } from "./corpus.js";
 import { describeSearchMiss } from "./search-miss.js";
 /**
  * TUI2-R1 (C) — THE SHELL PROGRESS SIDECAR.
@@ -69,6 +70,11 @@ export function shellProgressPath(sessionId, command) {
     const key = createHash("sha256").update(`${sessionId ?? ""} ${command}`).digest("hex").slice(0, 16);
     return join(SHELL_PROGRESS_DIR, `${key}.log`);
 }
+/** ACI-2: at most this many DISTINCT match lines are named in a refusal. */
+const ACI2_LINES_SHOWN = 5;
+/** Match offsets kept for that report. Past this the refusal says "more"
+ *  without a number rather than one it cannot stand behind. */
+const ACI2_OFFSETS_KEPT = 500;
 const OUTPUT_CAP = 100_000; // chars of output a tool result may carry
 const DEFAULT_SHELL_TIMEOUT_MS = 30_000;
 // the token round: the scoped-read defaults — read_file shows the head 200 lines
@@ -483,10 +489,13 @@ export function readFileTool(opts) {
 export function listDirTool(opts) {
     return defineTool({
         name: "list_dir",
-        description: "List the entries of a directory. Omit path to list the workspace root. Capped at 200 entries with an overflow note (narrow to a subdirectory for more).",
+        description: "List the entries of a directory, or with glob, search the tree recursively for workspace-relative paths matching it. Capped at 200 with an overflow note.",
         parameters: {
             type: "object",
-            properties: { path: { type: "string", description: "Workspace-relative directory to list" } },
+            properties: {
+                path: { type: "string", description: "Workspace-relative directory to list" },
+                glob: { type: "string", description: "Recursive search: * and ? within a segment, ** across them; matched against workspace-relative paths" },
+            },
             additionalProperties: false,
         },
         idempotent: true,
@@ -494,9 +503,35 @@ export function listDirTool(opts) {
         effects: { precommitSafe: true, concurrency: "shared" },
         promptSnippet: "list_dir — directory entries (the workspace ls)",
         promptGuidelines: ["narrow to a subdirectory when the listing caps at 200 entries"],
-        execute: async ({ path }) => {
+        execute: async ({ path, glob }) => {
             try {
                 const dir = resolveWithinRoot(opts.workspaceRoot, path ?? ".");
+                // ACI-8: with a pattern this is a recursive search over the
+                // SAME corpus `search_text` uses — one definition, so the two
+                // cannot drift the way they had.
+                if (glob !== undefined) {
+                    const re = globToRegExp(glob);
+                    const walk = walkCorpus({
+                        workspaceRoot: opts.workspaceRoot,
+                        walkFrom: dir,
+                        maxEntries: MAX_DIR_ENTRIES,
+                        accept: (rel) => re.test(rel),
+                        isExcluded: (full) => {
+                            const r = relative(opts.workspaceRoot, full).split(sep).join("/");
+                            return (opts.excludeRoots ?? []).some((ex) => r === ex || r.startsWith(`${ex}/`));
+                        },
+                    });
+                    const body = walk.files.length ? cap(walk.files.join("\n")) : `(no match for ${glob})`;
+                    // TWO truncations, different remedies, and neither claimed
+                    // when it did not happen: a walk that silently returns less
+                    // is the defect a note exists to prevent.
+                    const notes = [];
+                    if (walk.cutByCap)
+                        notes.push(`${MAX_DIR_ENTRIES} shown (narrow the pattern for more)`);
+                    if (walk.cutByDepth)
+                        notes.push(`the walk stopped at depth ${CORPUS_MAX_DEPTH} — anything deeper is not listed`);
+                    return { content: notes.length ? `${body}\n… ${notes.join("; ")}` : body, isError: false };
+                }
                 // DC-54 — TRUNCATED BEFORE IT BUILDS. It was a `.map` over
                 // EVERY entry with the 200-entry slice only after: a directory
                 // of 200,000 entries built 200,000 strings to show 200 of
@@ -877,10 +912,62 @@ export function writeFileTool(opts) {
         },
     });
 }
+/** ACI-2: every offset where `search` occurs, OVERLAPPING ones included —
+ *  "aa" occurs twice in "aaa", and the two resolutions differ, so the call
+ *  is ambiguous. A scan that steps past each match by its own length
+ *  reports one and edits blind. This is the ONLY scan: `count === 0` is the
+ *  missing pattern and `offsets[0]` is where a unique one resolved. */
+function occurrencesOf(text, search) {
+    const offsets = [];
+    let count = 0;
+    for (let at = text.indexOf(search); at !== -1;) {
+        count += 1;
+        if (offsets.length < ACI2_OFFSETS_KEPT)
+            offsets.push(at);
+        // The cursor must ADVANCE. indexOf("", n) clamps n to the string
+        // length and then returns the same offset forever — a synchronous
+        // spin no test timeout can interrupt. The single indexOf this
+        // replaced could not hang; a loop has to earn that.
+        const next = text.indexOf(search, at + 1);
+        if (next <= at)
+            break;
+        at = next;
+    }
+    return { count, offsets };
+}
+/** The distinct 1-based lines the (ASCENDING) offsets fall on, in ONE pass —
+ *  a line lookup per offset re-walks the file and a common pattern has
+ *  hundreds of them. Ascending order is what lets adjacent-dedupe stand in
+ *  for a set. */
+function linesOfOffsets(text, offsets) {
+    const lines = [];
+    let line = 1;
+    let i = 0;
+    for (const at of offsets) {
+        for (; i < at; i += 1)
+            if (text.charCodeAt(i) === 10)
+                line += 1;
+        if (lines[lines.length - 1] !== line)
+            lines.push(line);
+    }
+    return lines;
+}
+/** "line 4" / "lines 1, 2" / "lines 1, 2, 3, 4, 5 and 35 more" — the tail
+ *  counts LINES not yet named, never matches: a pattern hit ten times on
+ *  one line reads "line 1", because "and 9 more" would send the caller
+ *  looking for nine lines that are not there. `exhaustive` false means the
+ *  offsets themselves were capped, so the tail carries no number at all. */
+function describeMatchLines(text, offsets, exhaustive) {
+    const lines = linesOfOffsets(text, offsets);
+    const shown = lines.slice(0, ACI2_LINES_SHOWN);
+    const hidden = lines.length - shown.length;
+    const tail = !exhaustive ? " and more" : hidden > 0 ? ` and ${hidden} more` : "";
+    return `${shown.length === 1 && tail === "" ? "line" : "lines"} ${shown.join(", ")}${tail}`;
+}
 export function editFileTool(opts) {
     return defineTool({
         name: "edit_file",
-        description: "Edit a workspace file at its latest revision (expectedRevision). ONE of: search+replace (first exact occurrence), or edits (1-32 disjoint hunks resolved against the same snapshot, applied atomically).",
+        description: "Edit a workspace file at its latest revision (expectedRevision). ONE of: search+replace (must match exactly once), or edits (1-32 disjoint hunks resolved against the same snapshot, applied atomically).",
         parameters: {
             type: "object",
             properties: {
@@ -975,13 +1062,14 @@ export function editFileTool(opts) {
                 const text = bytes.toString("utf8");
                 // WR-1E2: EVERY hunk resolves against THIS snapshot — never the
                 // output of an earlier hunk. All spans are known before any
-                // staging; overlaps refuse (duplicate searches both resolve
-                // first-occurrence and therefore overlap — never retargeted).
+                // staging; overlaps refuse. Since ACI-2 a non-unique search is
+                // already refused above, so the overlap left to catch is two
+                // hunks aimed at the same unique text — never retargeted.
                 const spans = [];
                 for (let i = 0; i < hunks.length; i += 1) {
                     const h = hunks[i];
-                    const at = text.indexOf(h.search);
-                    if (at === -1) {
+                    const { count, offsets } = occurrencesOf(text, h.search);
+                    if (count === 0) {
                         // WR-1A ④: the WORLD lacks the pattern (the input is
                         // fine) and nothing ran — precondition; the note never
                         // rides an edit that wrote nothing.
@@ -994,7 +1082,17 @@ export function editFileTool(opts) {
                         const detail = describeSearchMiss(text, h.search);
                         return precondition(detail ? `${headline}\n${detail}` : headline);
                     }
-                    spans.push({ start: at, end: at + h.search.length, replace: h.replace });
+                    // ACI-2: more than one resolution is a QUESTION, not an edit.
+                    // Taking the first one wrote the wrong place and reported
+                    // success — the one failure shape a mutation tool must not
+                    // have. The refusal carries the count and the lines so the
+                    // call can be fixed without reading the file again.
+                    if (count > 1) {
+                        const lines = describeMatchLines(text, offsets, count <= ACI2_OFFSETS_KEPT);
+                        const where = hunks.length === 1 && edits === undefined ? lines : `hunk ${i + 1}, ${lines}`;
+                        return precondition(`edit_file: pattern matches ${count} places in ${path} (${where}) — include enough surrounding text to make it unique`);
+                    }
+                    spans.push({ start: offsets[0], end: offsets[0] + h.search.length, replace: h.replace });
                 }
                 const bySpan = [...spans].sort((a, b) => a.start - b.start);
                 for (let i = 1; i < bySpan.length; i += 1) {

package/dist/search-miss.js

@@ -62,7 +62,12 @@ export function describeSearchMiss(text, search) {
         const firstLine = search.split("\n", 1)[0] ?? "";
         return `  no part of it appears in the file — it begins "${fragment(firstLine)}"`;
     }
-    // First occurrence, matching the tool's own first-occurrence semantics.
+    // The FIRST place the prefix appears. Since ACI-2 the tool no longer
+    // has first-occurrence semantics to match, so the reason is now this
+    // function's own: a miss report needs one location and the earliest is
+    // the deterministic choice. A prefix occurring in several places is
+    // reported at the earliest of them, which can be further from where the
+    // caller was aiming than the report admits.
     const at = text.indexOf(search.slice(0, matched));
     const endOfMatch = at + matched;
     const line = lineAt(text, at);

package/dist/search-worker.js

@@ -17,7 +17,32 @@
  */
 import { open, readdir } from "node:fs/promises";
 import { basename, join, relative } from "node:path";
+import { corpusSkips, layersEntering, readLayer } from "./corpus.js";
 import { isMainThread, parentPort } from "node:worker_threads";
+/** ACI-5 — the excerpt WINDOWS THE MATCH instead of taking the line's head.
+ *
+ *  `line.trim().slice(0, 160)` answers "what does this line start with",
+ *  and the model asked "where is my pattern". Measured over 171 real
+ *  search results and 1,931 excerpt lines: 11.7% hit the 160-char cut and
+ *  6.1% did not contain the pattern they matched — a hit the model cannot
+ *  act on without spending a read to find out what it found.
+ *
+ *  A short line is returned exactly as before, markers and all absent, so
+ *  the common case is byte-identical. */
+const EXCERPT_RADIUS = 80;
+function excerptAround(line, regex) {
+    const trimmed = line.trim();
+    if (trimmed.length <= EXCERPT_RADIUS * 2)
+        return trimmed;
+    // A fresh non-global copy: `lastIndex` on a shared /g regex would make
+    // the excerpt depend on which line was scanned before it.
+    const found = new RegExp(regex.source, regex.flags.replace("g", "")).exec(trimmed);
+    const at = found ? found.index : 0;
+    const hit = found ? found[0].length : 0;
+    const start = Math.max(0, at - EXCERPT_RADIUS);
+    const end = Math.min(trimmed.length, at + hit + EXCERPT_RADIUS);
+    return `${start > 0 ? "…" : ""}${trimmed.slice(start, end)}${end < trimmed.length ? "…" : ""}`;
+}
 export async function runSearch(req) {
     const regex = new RegExp(req.pattern, req.flags);
     const matches = [];
@@ -81,7 +106,7 @@ export async function runSearch(req) {
                     // absolute path, so an absolute hit here is a result the
                     // model cannot feed back without rewriting it by hand.
                     if (matches.length < req.maxMatches)
-                        matches.push(`${relative(req.workspaceRoot, full) || basename(full)}:${i + 1}: ${line.trim().slice(0, 160)}`);
+                        matches.push(`${relative(req.workspaceRoot, full) || basename(full)}:${i + 1}: ${excerptAround(line, regex)}`);
                 }
             }
         }
@@ -89,7 +114,11 @@ export async function runSearch(req) {
             // unreadable file: skipped, like before
         }
     };
-    const walk = async (dir, depth) => {
+    // ACI-4/ACI-8: the corpus is declared by a `.gitignore` FILE at the
+    // workspace root — not by `.git`, and the walk never goes up.
+    const rootLayer = readLayer(req.root);
+    const declared = rootLayer !== null;
+    const walk = async (dir, depth, layers) => {
         if (depth > 8 || outOfBudget())
             return;
         let entries;
@@ -104,18 +133,20 @@ export async function runSearch(req) {
             }
             throw err;
         }
+        const here = depth === 0 ? layers : layersEntering(dir, layers);
         for (const entry of entries) {
             if (outOfBudget())
                 return;
-            if (entry.name.startsWith(".") || entry.name === "node_modules")
-                continue;
             const full = join(dir, entry.name);
-            if (entry.isDirectory()) {
+            const isDir = entry.isDirectory();
+            if (corpusSkips(declared, here, full, entry.name, isDir))
+                continue;
+            if (isDir) {
                 if (isExcluded(full)) {
                     excludedDirs += 1;
                     continue;
                 }
-                await walk(full, depth + 1);
+                await walk(full, depth + 1, here);
             }
             else if (entry.isFile())
                 await scanFile(full);
@@ -125,7 +156,7 @@ export async function runSearch(req) {
         if (req.single !== null)
             await scanFile(req.single);
         else
-            await walk(req.root, 0);
+            await walk(req.root, 0, rootLayer === null ? [] : [rootLayer]);
     }
     catch (err) {
         return { token: req.token, matches, totalMatches, filesSeen, skippedFiles, multiLink, unreadableDirs, excludedDirs, stopped, stoppedAt, error: err.message };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-tools-node",
-	"version": "0.37.0",
+	"version": "0.39.0",
 	"description": "kiso coding tools for Node hosts \u2014 read file, list directory, search text, write/edit file, shell command.",
 	"type": "module",
 	"license": "MIT",
@@ -25,7 +25,8 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@vincemakes/kiso-core": "0.37.0"
+		"@vincemakes/kiso-core": "0.39.0",
+		"ignore": "^7.0.9"
 	},
 	"devDependencies": {
 		"@types/node": "^26.1.2",