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
feat: add --only-dir whitelist to graft build (#149)
贾旭卿e6dd2905badf
diff --git a/node_modules b/node_modulesdeleted file mode 120000index 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 filediff --git a/src/cli.ts b/src/cli.tsindex b05617ac..9c58253a 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -38,6 +38,7 @@ import { formatNonInteractiveHelp, formatPlan, runPicker } from "./cli-picker.jsimport { 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 @@ programlsp?: 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 @@ programconcurrency,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.tsindex 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.tsindex 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.tsindex 1c21b263..d36f2bd2 100644--- a/src/graph/check.ts+++ b/src/graph/check.ts@@ -25,6 +25,7 @@ import { extractGeneric, genericLangOf, warmGenericGrammars } from "./generic.jsimport { 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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 });+ }+});