Skip to content

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

feat: add --only-dir whitelist to graft build (#149)

贾旭卿e6dd2905badf
diff --git a/node_modules b/node_modules
deleted file mode 120000
index 9cf9293f..00000000
--- a/node_modules
+++ /dev/null
@@ -1 +0,0 @@
-/Users/shrishdwivedi/Documents/Context graphs/context-graph-engine/node_modules
\ No newline at end of file
diff --git a/src/cli.ts b/src/cli.ts
index b05617ac..9c58253a 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -38,6 +38,7 @@ import { formatNonInteractiveHelp, formatPlan, runPicker } from "./cli-picker.js
import { homedir } from "node:os";
import { formatUpgradeReport, formatVersionReport, getNpmViewVersion, readCurrentVersion, runUpgrade } from "./cli-meta.js";
import { patchBuildConfig, type BuildConfig } from "./util/state.js";
+import { normalizePathPrefix } from "./util/paths.js";
import { formatUpdateNudge, maybeRefreshInBackground, readUpdateCache, refreshUpdateCache, writeStamp } from "./upkeep.js";
import {
errorCode,
@@ -319,6 +320,13 @@ program
(val: string, prev: string[]) => [...prev, val],
[] as string[],
)
+ .option(
+ "--only-dir <path>",
+ "only index files under this repo-relative path — repeatable; persisted, 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[],
+ )
.option("--no-gitignore", "skip writing graft/ into .gitignore (same as GRAFT_NO_GITIGNORE=1)")
.option("--no-ignore", "skip writing .ignore for ripgrep re-admit (same as GRAFT_NO_IGNORE=1)")
.action(async (
@@ -331,6 +339,7 @@ program
lsp?: boolean;
allowPartial?: boolean;
includeDir?: string[];
+ onlyDir?: string[];
followSubmodules?: boolean;
gitignore?: boolean;
ignore?: boolean;
@@ -368,6 +377,23 @@ program
}
buildConfigPatch.includeDirs = opts.includeDir;
}
+ // The whitelist is NOT persisted to `.graft/config.json`: it belongs with the
+ // graph (the fingerprint records it at build time), never in the source repo,
+ // so a `--only-dir` build leaves no trace under the repo being indexed.
+ let onlyDirs: string[] | undefined;
+ if (opts.onlyDir && opts.onlyDir.length > 0) {
+ // --only-dir takes a repo-relative path prefix, normalized to the same
+ // posix, no-`./`, no-trailing-slash form `--in` uses, so the prefix match
+ // is exact. A prefix that normalizes to "" (a bare "/" or ".") is rejected:
+ // it would mean "match nothing" or "match everything", neither of which is
+ // a deliberate whitelist.
+ const normalized = opts.onlyDir.map((p) => normalizePathPrefix(p)).filter((p) => p !== "");
+ if (normalized.length === 0) {
+ console.error("✗ --only-dir: expected a non-empty repo-relative path");
+ process.exit(1);
+ }
+ onlyDirs = normalized;
+ }
const followSubmodulesWasExplicit = command.getOptionValueSource("followSubmodules") === "cli";
if (followSubmodulesWasExplicit && typeof opts.followSubmodules === "boolean") {
buildConfigPatch.followSubmodules = opts.followSubmodules;
@@ -445,6 +471,7 @@ program
concurrency,
reuse: opts.reuse,
lsp: opts.lsp,
+ onlyDirs,
onProgress: ({ phase, index, total, file }) =>
process.stderr.write(
`\r${phase === "enrich" ? "summarizing" : "parsing"} ${index + 1}/${total}: ${file.slice(0, 50).padEnd(50)}`,
diff --git a/src/engine.ts b/src/engine.ts
index 3fa93d23..9b6511f7 100644
--- a/src/engine.ts
+++ b/src/engine.ts
@@ -45,6 +45,8 @@ export interface GraphRunOptions {
reuse?: boolean;
/** Opt-in compiler-grade LSP edge enrichment (`graft build --lsp`). */
lsp?: boolean;
+ /** Repo-relative directory prefixes to limit the build to (`--only-dir`). */
+ onlyDirs?: string[];
onProgress?: GraphBuildOptions["onProgress"];
}
@@ -90,6 +92,7 @@ export class Graft {
concurrency: opts.concurrency,
reuse: opts.reuse,
lsp: opts.lsp,
+ onlyDirs: opts.onlyDirs,
onProgress: opts.onProgress,
});
}
diff --git a/src/graph/build.ts b/src/graph/build.ts
index 059eb3a1..0ea1ca0c 100644
--- a/src/graph/build.ts
+++ b/src/graph/build.ts
@@ -32,7 +32,7 @@ import {
} from "./extract-cache.js";
import { writeFingerprint } from "./fingerprint.js";
import { seedGraph, type SeedResult } from "./seed.js";
-import { listSourceStats } from "./source-files.js";
+import { filterByOnlyDirs, listSourceStats } from "./source-files.js";
import { resolveEdges, type GoModule } from "./resolve.js";
import { enrichGraph, type EnrichStats } from "./enrich.js";
import { readGraph, writeGraph, wiringPath } from "./write.js";
@@ -89,6 +89,10 @@ export interface GraphBuildOptions {
summarizer?: CruxSummarizer;
/** Max files summarized in parallel during the Tier-2 pass. Default is set in enrich. */
concurrency?: number;
+ /** Repo-relative directory prefixes to limit the build to (`--only-dir`). When
+ * set, only files under these prefixes are indexed; the list is recorded in the
+ * fingerprint so the freshness probe enumerates the same set. */
+ onlyDirs?: string[];
onProgress?: (info: {
phase: "parse" | "enrich";
index: number;
@@ -153,9 +157,11 @@ export async function buildGraph(
// Enumerate once: source extraction, scope discovery, and Go module
// resolution must agree on the same Git-ignore-aware working-tree view —
// including the repo's persisted directory and submodule choices.
- const repoFiles = walkDir(root, readIncludeDirs(root), {
+ const walked = walkDir(root, readIncludeDirs(root), {
followSubmodules: readFollowSubmodules(root),
});
+ const onlyDirs = opts.onlyDirs && opts.onlyDirs.length > 0 ? new Set(opts.onlyDirs) : undefined;
+ const repoFiles = filterByOnlyDirs(walked, root, onlyDirs);
const files = listSourceStats(root, outDir, repoFiles);
const discoveredScopes = discoverScopes(root, repoFiles);
@@ -351,7 +357,7 @@ export async function buildGraph(
// these source bytes." Nothing about the projections below — which is why it is
// safe to write here, and why `graphOnly` builds (the query path, which stops
// right after this line) are still recorded as fresh.
- writeFingerprint(outDir, entries);
+ writeFingerprint(outDir, entries, opts.onlyDirs);
// Tier-2 passive surface: project the nodes into per-file markdown cards, and
// refresh the INDEX roster. Pure projection — no LLM, no network.
diff --git a/src/graph/check.ts b/src/graph/check.ts
index 1c21b263..d36f2bd2 100644
--- a/src/graph/check.ts
+++ b/src/graph/check.ts
@@ -25,6 +25,7 @@ import { extractGeneric, genericLangOf, warmGenericGrammars } from "./generic.js
import { containerLangOf, extractContainer, warmContainerGrammars } from "./container.js";
import { listSourceFiles } from "./build.js";
import { readGraph, wiringPath } from "./write.js";
+import { readFingerprint } from "./fingerprint.js";
import { readSourceFile } from "../util/source.js";
export interface GraphCheckResult {
@@ -80,7 +81,12 @@ export async function checkGraph(
}
// Freshly extract Tier-1 nodes from the code on disk (same file set as build).
- const sourceFiles = listSourceFiles(root, outDir);
+ // A `--only-dir` build records its whitelist in the fingerprint; read it back
+ // so `check` diffs the same limited set instead of flagging every excluded
+ // file as "added".
+ const fpOnlyDirs = readFingerprint(outDir)?.onlyDirs;
+ const onlyDirs = fpOnlyDirs && fpOnlyDirs.length > 0 ? new Set(fpOnlyDirs) : undefined;
+ const sourceFiles = listSourceFiles(root, outDir, undefined, onlyDirs);
await warmGenericGrammars(
new Set(sourceFiles.map((f) => genericLangOf(f)?.name).filter((n): n is string => !!n)),
);
diff --git a/src/graph/fingerprint.ts b/src/graph/fingerprint.ts
index 7496957e..f8fb7785 100644
--- a/src/graph/fingerprint.ts
+++ b/src/graph/fingerprint.ts
@@ -49,6 +49,11 @@ export interface Fingerprint {
* clean and queries would keep answering from nodes the old extractor built. */
extractor: string;
files: Record<string, Print>;
+ /** Repo-relative directory prefixes this build was limited to (`--only-dir`).
+ * Absent = full tree. Recorded here — not in the source repo's `.graft/config.json`
+ * — so the query-path freshness probe (which never sees a CLI flag) enumerates the
+ * identical whitelisted set and excluded files are never phantom "added" drift. */
+ onlyDirs?: string[];
}
/** What moved since the last build. Empty in all three arrays = nothing to do. */
@@ -79,11 +84,17 @@ export function readFingerprint(outDir: string): Fingerprint | null {
/** Project the extraction cache's entries into the probe sidecar. Best-effort:
* the graph is already on disk when this runs, so a failed write costs the next
* probe its fast path and nothing more. */
-export function writeFingerprint(outDir: string, entries: Record<string, ExtractEntry>): boolean {
+export function writeFingerprint(
+ outDir: string,
+ entries: Record<string, ExtractEntry>,
+ onlyDirs?: string[],
+): boolean {
const files: Record<string, Print> = {};
for (const [rel, e] of Object.entries(entries)) files[rel] = [e.size, e.mtimeMs, e.hash];
try {
- writeJsonAtomic(fingerprintPath(outDir), { version: FINGERPRINT_VERSION, extractor: stamp(), files }, true);
+ const record: Fingerprint = { version: FINGERPRINT_VERSION, extractor: stamp(), files };
+ if (onlyDirs && onlyDirs.length > 0) record.onlyDirs = onlyDirs;
+ writeJsonAtomic(fingerprintPath(outDir), record, true);
pruneSidecars(join(outDir, CACHE_DIR), FINGERPRINT_PREFIX);
return true;
} catch {
@@ -143,7 +154,8 @@ export function probeDrift(root: string, outDir: string): Drift | null {
const drift: Drift = { changed: [], added: [], removed: [] };
const seen = new Set<string>();
- for (const f of listSourceStats(root, outDir)) {
+ const onlyDirs = fp.onlyDirs && fp.onlyDirs.length > 0 ? new Set(fp.onlyDirs) : undefined;
+ for (const f of listSourceStats(root, outDir, undefined, onlyDirs)) {
seen.add(f.rel);
const print = fp.files[f.rel];
if (!print) {
diff --git a/src/graph/refresh.ts b/src/graph/refresh.ts
index 7140ce8a..a749f7ab 100644
--- a/src/graph/refresh.ts
+++ b/src/graph/refresh.ts
@@ -37,7 +37,7 @@ import { contextDirFor } from "../context/node-file.js";
import { acquireLockIn, releaseLockIn } from "../util/state.js";
import { CACHE_DIR } from "../context/node-file.js";
import { buildGraph } from "./build.js";
-import { driftCount, isClean, probeDrift, type Drift } from "./fingerprint.js";
+import { driftCount, isClean, probeDrift, readFingerprint, type Drift } from "./fingerprint.js";
import { invalidateGraphCaches } from "./load.js";
import { seedGraph, type SeedResult } from "./seed.js";
import { wiringPath } from "./write.js";
@@ -209,7 +209,11 @@ export async function ensureFreshGraph(root: string, opts: RefreshOptions = {}):
// else. The markdown projections under `graft/` stay the `Stop` hook's job —
// a query has no business rewriting the repo's `.gitignore` or churning every
// card's mtime, and skipping them is most of what keeps this cheap.
- await buildGraph(dir, { contextDir: opts.contextDir, graphOnly: true });
+ // A `--only-dir` build recorded its whitelist in the fingerprint; re-apply it
+ // here so an auto-rebuild keeps the same limited file set instead of silently
+ // widening to the whole tree.
+ const onlyDirs = readFingerprint(outDir)?.onlyDirs;
+ await buildGraph(dir, { contextDir: opts.contextDir, graphOnly: true, onlyDirs });
invalidateGraphCaches(outDir);
return { refreshed: true, drift: drift ?? undefined, note: seedNote };
} finally {
diff --git a/src/graph/source-files.ts b/src/graph/source-files.ts
index 416ca349..11fa81db 100644
--- a/src/graph/source-files.ts
+++ b/src/graph/source-files.ts
@@ -45,20 +45,41 @@ export function unsupportedExtensions(exts: string[]): string[] {
* none of which ever see a CLI flag) behaves identically to the build that
* saved those choices.
*/
+/** Keep only files whose repo-relative path is at or under one of `onlyDirs`.
+ * No-op when `onlyDirs` is empty/absent. The whitelist is carried in the graph
+ * itself (the fingerprint records it at build time), never in the source repo,
+ * so a build and the query-path freshness probe read the identical set. */
+export function filterByOnlyDirs(
+ files: string[],
+ root: string,
+ onlyDirs?: ReadonlySet<string>,
+): string[] {
+ if (!onlyDirs || onlyDirs.size === 0) return files;
+ return files.filter((abs) => {
+ const rel = relPosix(root, abs);
+ return [...onlyDirs].some((d) => rel === d || rel.startsWith(`${d}/`));
+ });
+}
+
export function listSourceFiles(
root: string,
outDir: string,
repoFiles: string[] = walkDir(root, readIncludeDirs(resolve(root)), {
followSubmodules: readFollowSubmodules(resolve(root)),
}),
+ onlyDirs?: ReadonlySet<string>,
): string[] {
// A file is a source file if a depth-tier grammar (languageOf), a breadth-tier
// grammar (genericLangOf) or a container (containerLangOf) claims its extension.
// All three must agree here or `build` and `check` would enumerate different sets.
- return repoFiles.filter(
- (f) =>
- !f.startsWith(outDir) &&
- (languageOf(f) !== null || genericLangOf(f) !== null || containerLangOf(f) !== null),
+ return filterByOnlyDirs(
+ repoFiles.filter(
+ (f) =>
+ !f.startsWith(outDir) &&
+ (languageOf(f) !== null || genericLangOf(f) !== null || containerLangOf(f) !== null),
+ ),
+ root,
+ onlyDirs,
);
}
@@ -78,9 +99,14 @@ export interface SourceStat {
* both the freshness probe and the extraction cache. Files that vanish between
* the walk and the stat are dropped (same fail-soft posture as `walkDir`).
*/
-export function listSourceStats(root: string, outDir: string, repoFiles?: string[]): SourceStat[] {
+export function listSourceStats(
+ root: string,
+ outDir: string,
+ repoFiles?: string[],
+ onlyDirs?: ReadonlySet<string>,
+): SourceStat[] {
const out: SourceStat[] = [];
- for (const abs of listSourceFiles(root, outDir, repoFiles)) {
+ for (const abs of listSourceFiles(root, outDir, repoFiles, onlyDirs)) {
let s: { size: number; mtimeMs: number };
try {
s = statSync(abs);
diff --git a/test/graph-only-dir.test.ts b/test/graph-only-dir.test.ts
new file mode 100644
index 00000000..153e804c
--- /dev/null
+++ b/test/graph-only-dir.test.ts
@@ -0,0 +1,89 @@
+/**
+ * `graft build --only-dir <path>` end-to-end through the real CLI.
+ *
+ * The whitelist is the inverse of SKIP_DIRS: when set, ONLY files under the
+ * listed repo-relative prefixes are indexed, and everything else (including
+ * top-level files) is skipped. It is recorded in the fingerprint — the graph's
+ * own freshness sidecar under `graft/` — never in the source repo's
+ * `.graft/config.json`, so a limited build leaves no trace under the repo being
+ * indexed. That also keeps the query-path freshness probe honest: the excluded
+ * files must not read as phantom "added" drift on every query.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { readGraph, wiringPath } from "../src/graph/write.js";
+import { probeDrift, isClean, readFingerprint } from "../src/graph/fingerprint.js";
+import type { GraphV1 } from "../src/graph/types.js";
+
+function repoWithDirs(): string {
+ const d = mkdtempSync(join(tmpdir(), "graft-only-dir-"));
+ mkdirSync(join(d, "src", "a"), { recursive: true });
+ mkdirSync(join(d, "src", "b"), { recursive: true });
+ writeFileSync(join(d, "src", "a", "a.ts"), "export function a(): number {\n return 1;\n}\n");
+ writeFileSync(join(d, "src", "b", "b.ts"), "export function b(): number {\n return 2;\n}\n");
+ writeFileSync(join(d, "top.ts"), "export function top(): number {\n return 3;\n}\n");
+ return d;
+}
+
+function runCli(args: string[]): void {
+ execFileSync(process.execPath, ["--import", "tsx", "src/cli.ts", ...args], { stdio: "pipe" });
+}
+
+function graphOf(d: string): GraphV1 | null {
+ return readGraph(wiringPath(join(d, "graft")));
+}
+
+test("--only-dir limits the walk, records the whitelist in the fingerprint, and the probe stays clean", () => {
+ const d = repoWithDirs();
+ try {
+ // Default: everything is indexed.
+ runCli(["build", d]);
+ const full = graphOf(d);
+ assert.ok(full, "expected a built graph");
+ assert.ok(full!.nodes.some((n) => n.path === "src/a/a.ts"), "src/a indexed by default");
+ assert.ok(full!.nodes.some((n) => n.path === "src/b/b.ts"), "src/b indexed by default");
+ assert.ok(full!.nodes.some((n) => n.path === "top.ts"), "top.ts indexed by default");
+
+ // Only src/a.
+ runCli(["build", d, "--only-dir", "src/a"]);
+ const limited = graphOf(d);
+ assert.ok(limited, "expected a rebuilt graph");
+ assert.ok(limited!.nodes.some((n) => n.path === "src/a/a.ts"), "src/a must be indexed");
+ assert.ok(!limited!.nodes.some((n) => n.path === "src/b/b.ts"), "src/b must be skipped");
+ assert.ok(!limited!.nodes.some((n) => n.path === "top.ts"), "top.ts must be skipped");
+
+ // The whitelist lives in the fingerprint, not the source repo's config.
+ const fp = readFingerprint(join(d, "graft"));
+ assert.deepEqual(fp?.onlyDirs, ["src/a"], "fingerprint must record the whitelist");
+ assert.ok(!existsSync(join(d, ".graft", "config.json")), "source repo config must be untouched");
+
+ // The fingerprint probe (the fast path `ensureFreshGraph`/hooks use, which
+ // never sees CLI flags) must enumerate the same whitelisted set — so the
+ // excluded src/b and top.ts are NOT reported as phantom "added" drift.
+ const drift = probeDrift(d, join(d, "graft"));
+ assert.ok(drift && isClean(drift), "excluded files must not read as drift");
+ } finally {
+ rmSync(d, { recursive: true, force: true });
+ }
+});
+
+test("--only-dir rejects a prefix that normalizes to empty", () => {
+ const d = repoWithDirs();
+ try {
+ let failed = false;
+ try {
+ execFileSync(process.execPath, ["--import", "tsx", "src/cli.ts", "build", d, "--only-dir", "/"], {
+ stdio: "pipe",
+ });
+ } catch {
+ failed = true;
+ }
+ assert.ok(failed, "a bare / prefix must be rejected");
+ } finally {
+ rmSync(d, { recursive: true, force: true });
+ }
+});