Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
fix(deep): honor --only-dir in the concept pass (#252) (#262)
Frankie-Xu3fe4218c6fc7
diff --git a/src/cli.ts b/src/cli.tsindex 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 @@ programif (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.tsindex 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<Buiconst 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 interrupteddiff --git a/src/context/check.ts b/src/context/check.tsindex 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 belowdiff --git a/src/engine.ts b/src/engine.tsindex 9b6511f7..5ec74472 100644--- a/src/engine.ts+++ b/src/engine.ts@@ -28,6 +28,8 @@ export type { BuildResult, BuildProgress, CheckResult, GraphBuildResult, GraphChexport 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.tsnew file mode 100644index 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 });+ }+});