Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

fix(deep): honor --only-dir in the concept pass (#252) (#262)

Frankie-Xu3fe4218c6fc7
diff --git a/src/cli.ts b/src/cli.ts
index c83afea6..969100a3 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -331,7 +331,8 @@ program
)
.option(
"--only-dir <path>",
- "only index files under this repo-relative path — repeatable; persisted, so a later build " +
+ "only index files under this repo-relative path — repeatable; the wiring walk and the --deep " +
+ "concept pass both honor it. Recorded in the graph fingerprint so a later build " +
"(and the hooks/refresh path) walks the same set; everything outside the list is skipped",
(val: string, prev: string[]) => [...prev, val],
[] as string[],
@@ -462,6 +463,7 @@ program
if (deep) {
const c = await engine.init(dir, {
extensions: opts.extensions,
+ onlyDirs,
onProgress: ({ phase, index, total, file }) =>
process.stderr.write(
`\r${phase === "summarize" ? "reading" : "writing"} concepts ${index + 1}/${total}: ${file.slice(0, 40).padEnd(40)}`,
diff --git a/src/context/build.ts b/src/context/build.ts
index ff2a9d0d..957289c5 100644
--- a/src/context/build.ts
+++ b/src/context/build.ts
@@ -14,6 +14,8 @@
import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync } from "node:fs";
import { join, resolve } from "node:path";
import { walkDir } from "../ingest/fs.js";
+import { filterByOnlyDirs } from "../graph/source-files.js";
+import { readFingerprint } from "../graph/fingerprint.js";
import { contentHash } from "../util/id.js";
import { relPosix } from "../util/paths.js";
import { readSourceFile } from "../util/source.js";
@@ -60,6 +62,10 @@ export interface BuildOptions {
contextDir?: string;
/** Extensions to treat as code. Default: {@link CODE_EXTENSIONS}. */
extensions?: string[];
+ /** Repo-relative directory prefixes to limit the concept pass (`--only-dir`).
+ * Same prefix semantics as the wiring walk. When omitted, falls back to the
+ * whitelist recorded in the graph fingerprint (mirrors `checkGraph`). */
+ onlyDirs?: string[];
/** Human label for the model, recorded in the manifest (e.g. "openrouter:openai/gpt-4o-mini"). */
model: string;
summarizer: Summarizer;
@@ -86,6 +92,35 @@ export interface BuildResult {
fatal?: string;
}
+/** CLI/API `--only-dir` wins; otherwise the whitelist recorded in the graph
+ * fingerprint — the same source `checkGraph` / `probeDrift` use, so a later
+ * `--deep` without the flag still skips files the wiring pass excluded. */
+function resolveOnlyDirs(outDir: string, explicit?: readonly string[]): Set<string> | undefined {
+ const list = explicit && explicit.length > 0 ? explicit : (readFingerprint(outDir)?.onlyDirs ?? []);
+ return list.length > 0 ? new Set(list) : undefined;
+}
+
+/**
+ * Files the concept pass summarizes (and `checkContext` re-hashes): the same
+ * walk as before (`--include-dir` / submodule flags from state, minus the
+ * output dir), then {@link filterByOnlyDirs}. Shared so build and check cannot
+ * disagree about what "current" means under a whitelist.
+ */
+export function listContextFiles(
+ root: string,
+ outDir: string,
+ exts: readonly string[],
+ explicitOnlyDirs?: readonly string[],
+): string[] {
+ const walked = walkDir(root, readIncludeDirs(root), {
+ followSubmodules: readFollowSubmodules(root),
+ followNestedRepos: readFollowNestedRepos(root),
+ })
+ .filter((f) => exts.some((e) => f.toLowerCase().endsWith(e)))
+ .filter((f) => !f.startsWith(outDir));
+ return filterByOnlyDirs(walked, root, resolveOnlyDirs(outDir, explicitOnlyDirs));
+}
+
/** The gitignored LLM-call cache: per-file summaries + per-batch synthesis. */
interface BuildCache {
summaries: Record<string, { hash: string; summary: string }>;
@@ -114,12 +149,9 @@ export async function buildContext(dir: string, opts: BuildOptions): Promise<Bui
const exts = opts.extensions ?? CODE_EXTENSIONS;
// Read the same persisted walk choices as the Tier-1 wiring graph, so the
// Tier-2 concept pipeline sees exactly the same directories and submodules.
- const files = walkDir(root, readIncludeDirs(root), {
- followSubmodules: readFollowSubmodules(root),
- followNestedRepos: readFollowNestedRepos(root),
- })
- .filter((f) => exts.some((e) => f.toLowerCase().endsWith(e)))
- .filter((f) => !f.startsWith(outDir));
+ // `--only-dir` is applied with the same prefix match as wiring (CLI/API, else
+ // the fingerprint) so out-of-scope files are never summarized or synthesized.
+ const files = listContextFiles(root, outDir, exts, opts.onlyDirs);
const cache = loadCache(outDir);
// Flush the summary cache to disk during phase 1 so a build interrupted
diff --git a/src/context/check.ts b/src/context/check.ts
index 3784eb5d..0090a001 100644
--- a/src/context/check.ts
+++ b/src/context/check.ts
@@ -14,12 +14,10 @@
*/
import { existsSync } from "node:fs";
import { resolve } from "node:path";
-import { walkDir } from "../ingest/fs.js";
import { contentHash } from "../util/id.js";
import { relPosix } from "../util/paths.js";
import { readSourceFile } from "../util/source.js";
-import { readFollowNestedRepos, readFollowSubmodules, readIncludeDirs } from "../util/state.js";
-import { CODE_EXTENSIONS } from "./build.js";
+import { CODE_EXTENSIONS, listContextFiles } from "./build.js";
import { contextDirFor, readManifest, readNodes } from "./node-file.js";
export interface CheckResult {
@@ -58,15 +56,11 @@ export function checkContext(dir: string, opts: CheckOptions = {}): CheckResult
}
// Current code files on disk (same persisted directory/submodule choices
- // `init` used), so this freshness check never disagrees with buildContext
- // about what "current" means.
+ // `init` used, including the `--only-dir` whitelist from the fingerprint),
+ // so this freshness check never disagrees with buildContext about what
+ // "current" means.
const current = new Map<string, string>(); // rel → hash
- for (const file of walkDir(root, readIncludeDirs(root), {
- followSubmodules: readFollowSubmodules(root),
- followNestedRepos: readFollowNestedRepos(root),
- })) {
- if (file.startsWith(outDir)) continue;
- if (!exts.some((e) => file.toLowerCase().endsWith(e))) continue;
+ for (const file of listContextFiles(root, outDir, exts)) {
try {
const source = readSourceFile(file);
if (source === null) continue; // unsupported encoding (e.g. UTF-16BE) → treat as removed below
diff --git a/src/engine.ts b/src/engine.ts
index 9b6511f7..5ec74472 100644
--- a/src/engine.ts
+++ b/src/engine.ts
@@ -28,6 +28,8 @@ export type { BuildResult, BuildProgress, CheckResult, GraphBuildResult, GraphCh
export interface InitOptions {
/** Code extensions to include. Default: {@link CODE_EXTENSIONS}. */
extensions?: string[];
+ /** Repo-relative directory prefixes to limit the concept pass (`--only-dir`). */
+ onlyDirs?: string[];
/** Progress callback for long builds. */
onProgress?: (info: BuildProgress) => void;
}
@@ -62,6 +64,7 @@ export class Graft {
return buildContext(dir, {
contextDir: this.cfg.contextDir,
extensions: opts.extensions,
+ onlyDirs: opts.onlyDirs,
model: this.modelLabel(),
summarizer: this.summarizer(),
synthesizer: this.synthesizer(),
diff --git a/test/context-only-dir.test.ts b/test/context-only-dir.test.ts
new file mode 100644
index 00000000..b9c29229
--- /dev/null
+++ b/test/context-only-dir.test.ts
@@ -0,0 +1,167 @@
+/**
+ * #252 — `graft build --deep --only-dir` must not walk the whole repo.
+ *
+ * Tier-1 wiring already honors `--only-dir` (`filterByOnlyDirs`). The Tier-2
+ * concept pass (`buildContext`) and its freshness check (`checkContext`) must
+ * enumerate the same whitelist — otherwise out-of-scope files get summarized
+ * and pulled into concept synthesis, and `graft check` reports them as added.
+ *
+ * No LLM: a recording summarizer is the queue. Wiring assertions reuse
+ * `buildGraph` so this file cannot drift from `graph-only-dir.test.ts`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { buildContext } from "../src/context/build.js";
+import { checkContext } from "../src/context/check.js";
+import { buildGraph } from "../src/graph/build.js";
+import { readGraph, wiringPath } from "../src/graph/write.js";
+import { Graft } from "../src/engine.js";
+import { fakeProviders, tmpRepo } from "./helpers.js";
+import type { FileSummary, Summarizer, Synthesizer } from "../src/index.js";
+
+function repoWithOutOfScope(): string {
+ const d = tmpRepo("ctx-only-dir");
+ mkdirSync(join(d, "src"), { recursive: true });
+ mkdirSync(join(d, "tools"), { recursive: true });
+ mkdirSync(join(d, "docs"), { recursive: true });
+ writeFileSync(join(d, "src", "a.ts"), "// [[In Scope]]\nexport const a = 1;\n");
+ writeFileSync(join(d, "tools", "b.ts"), "// [[Out Of Scope Tools]]\nexport const b = 2;\n");
+ // `.md` is not a concept-pass extension; a source file under docs/ is the
+ // evidence-copy case from #252 (backend sources kept under docs/**).
+ writeFileSync(join(d, "docs", "c.ts"), "// [[Out Of Scope Docs]]\nexport const c = 3;\n");
+ return d;
+}
+
+function recording(): {
+ summarized: string[];
+ synthesized: string[];
+ summarizer: Summarizer;
+ synthesizer: Synthesizer;
+} {
+ const summarized: string[] = [];
+ const synthesized: string[] = [];
+ const inner = fakeProviders();
+ return {
+ summarized,
+ synthesized,
+ summarizer: {
+ async summarize(code: string, opts: { path: string }) {
+ summarized.push(opts.path);
+ return inner.summarizer.summarize(code, opts);
+ },
+ },
+ synthesizer: {
+ async synthesize(files: FileSummary[]) {
+ for (const f of files) synthesized.push(f.path);
+ return inner.synthesizer.synthesize(files);
+ },
+ },
+ };
+}
+
+function manifestPaths(dir: string): string[] {
+ const manifest = JSON.parse(readFileSync(join(dir, "graft", "manifest.json"), "utf8")) as {
+ files: Array<{ path: string }>;
+ };
+ return manifest.files.map((f) => f.path).sort();
+}
+
+test("#252: buildContext --only-dir src does not summarize or synthesize out-of-scope files", async () => {
+ const dir = repoWithOutOfScope();
+ const rec = recording();
+ try {
+ const r = await buildContext(dir, {
+ model: "fake",
+ summarizer: rec.summarizer,
+ synthesizer: rec.synthesizer,
+ onlyDirs: ["src"],
+ });
+ assert.deepEqual(r.errors, []);
+ assert.deepEqual([...rec.summarized].sort(), ["src/a.ts"]);
+ assert.deepEqual([...rec.synthesized].sort(), ["src/a.ts"]);
+ assert.deepEqual(manifestPaths(dir), ["src/a.ts"]);
+ assert.ok(!rec.summarized.includes("tools/b.ts"));
+ assert.ok(!rec.summarized.includes("docs/c.ts"));
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("#252: multiple onlyDirs keep prefix semantics (src + tools, not docs)", async () => {
+ const dir = repoWithOutOfScope();
+ const rec = recording();
+ try {
+ await buildContext(dir, {
+ model: "fake",
+ summarizer: rec.summarizer,
+ synthesizer: rec.synthesizer,
+ onlyDirs: ["src", "tools"],
+ });
+ assert.deepEqual([...rec.summarized].sort(), ["src/a.ts", "tools/b.ts"]);
+ assert.ok(!rec.summarized.includes("docs/c.ts"));
+ assert.deepEqual(manifestPaths(dir), ["src/a.ts", "tools/b.ts"]);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("#252: concept pass falls back to the fingerprint whitelist when onlyDirs is omitted", async () => {
+ const dir = repoWithOutOfScope();
+ const rec = recording();
+ try {
+ await buildGraph(dir, { onlyDirs: ["src"] });
+ await buildContext(dir, {
+ model: "fake",
+ summarizer: rec.summarizer,
+ synthesizer: rec.synthesizer,
+ });
+ assert.deepEqual([...rec.summarized].sort(), ["src/a.ts"], "fingerprint onlyDirs must gate the concept walk");
+ assert.deepEqual(manifestPaths(dir), ["src/a.ts"]);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("#252: checkContext does not report excluded files as coverage after a limited deep build", async () => {
+ const dir = repoWithOutOfScope();
+ try {
+ await buildGraph(dir, { onlyDirs: ["src"] });
+ await buildContext(dir, { model: "fake", ...fakeProviders(), onlyDirs: ["src"] });
+ const check = checkContext(dir);
+ assert.equal(check.ok, true, `expected clean check, got ${JSON.stringify(check)}`);
+ assert.ok(!check.coverage.includes("tools/b.ts"));
+ assert.ok(!check.coverage.includes("docs/c.ts"));
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("#252: Graft.init forwards onlyDirs (the --deep CLI path)", async () => {
+ const dir = repoWithOutOfScope();
+ const rec = recording();
+ try {
+ const engine = new Graft({ summarizer: rec.summarizer, synthesizer: rec.synthesizer });
+ await engine.init(dir, { onlyDirs: ["src"] });
+ assert.deepEqual([...rec.summarized].sort(), ["src/a.ts"]);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("#252: wiring still indexes only the whitelist when both layers run", async () => {
+ const dir = repoWithOutOfScope();
+ try {
+ await buildContext(dir, { model: "fake", ...fakeProviders(), onlyDirs: ["src"] });
+ await buildGraph(dir, { onlyDirs: ["src"] });
+ const graph = readGraph(wiringPath(join(dir, "graft")));
+ assert.ok(graph, "expected a wiring graph");
+ const paths = new Set(graph!.nodes.map((n) => n.path));
+ assert.ok(paths.has("src/a.ts"), "src stays in the wiring graph");
+ assert.ok(!paths.has("tools/b.ts"), "tools must stay out of wiring");
+ assert.ok(!paths.has("docs/c.ts"), "docs must stay out of wiring");
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});