Skip to content

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

fix: make submodule indexing opt-in

yescine36acfc233ff1
diff --git a/README.md b/README.md
index 60f4fa1e..5410f0a4 100644
--- a/README.md
+++ b/README.md
@@ -336,6 +336,8 @@ graft build [dir] # build graft/ from the code at [dir]: wiri
graft build --deep # add the LLM layer: concept nodes + per-symbol summary/crux (cached)
graft build --extensions .ts .py # only include these code extensions
graft build --no-reuse # re-parse every file instead of replaying unchanged ones from cache
+graft build --follow-submodules # include initialized submodules; persist the choice for builds + MCP refresh
+graft build --no-follow-submodules # exclude submodules again and persist that choice (the default)
graft ask "<task>" [dir] # query the graph — ranked nodes + exact file:line (no LLM, no key)
graft ask "<task>" --json # machine-readable result
@@ -421,7 +423,7 @@ hotspots: contextDirFor · function · src/context/node-file.ts:L100-L103 · 21
## Monorepos, submodules & multi-repo folders
-Graft handles these layouts without any config:
+Graft supports these layouts:
- **A monorepo with one `.git`** (a `pnpm-workspace.yaml`/`package.json`
`workspaces`, or per-package `go.mod`/`pyproject.toml`/`Cargo.toml`) —
@@ -429,11 +431,15 @@ Graft handles these layouts without any config:
rank every scope on its own terms and fuse the results, so the biggest
sub-project can't drown a small one; hits carry `[scope/]` labels, and
`graft map` groups its directory clusters by scope first.
-- **A Git superproject with initialized submodules** — `graft build` follows
- initialized gitlinks into one graph, prefixing child paths (for example,
+- **A Git superproject with initialized submodules** — submodules stay excluded
+ by default. Run `graft build --follow-submodules` to fold initialized gitlinks
+ into one graph, prefixing child paths (for example,
`deps/parser/src/index.ts`) while honoring each submodule's own Git ignore
rules. Visible untracked files are included too; uninitialized submodules
- remain absent until `git submodule update --init` checks them out.
+ remain absent until `git submodule update --init` checks them out. The choice
+ is saved in `.graft/config.json`, so later no-flag builds and MCP automatic
+ refreshes behave the same way. Run `graft build --no-follow-submodules` to
+ restore and persist the default boundary.
- **A folder of separate git repos** (no `.git` at the top) — `graft build`
auto-splits: each child gets its own (git-ignored) `graft/`, and the parent
gets a `graft/workspace.json` index. Queries from the parent federate across
diff --git a/src/cli.ts b/src/cli.ts
index da5ad539..b7a2ef21 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -33,7 +33,7 @@ import { planInit, selectedWrites } from "./hosts/plan.js";
import { formatNonInteractiveHelp, formatPlan, runPicker } from "./cli-picker.js";
import { homedir } from "node:os";
import { formatUpgradeReport, formatVersionReport, getNpmViewVersion, readCurrentVersion, runUpgrade } from "./cli-meta.js";
-import { writeBuildConfig } from "./util/state.js";
+import { patchBuildConfig, type BuildConfig } from "./util/state.js";
const program = new Command();
const currentVersion = readCurrentVersion(import.meta.url);
@@ -120,6 +120,14 @@ program
.option("-e, --extensions <exts...>", 'code extensions to include (e.g. ".ts" ".py")')
.option("-j, --concurrency <n>", "files summarized in parallel during --deep (default 5)")
.option("--no-reuse", "re-parse every file instead of replaying unchanged ones from the extraction cache")
+ .option(
+ "--follow-submodules",
+ "include initialized Git submodules recursively; persisted for later builds and automatic refreshes",
+ )
+ .option(
+ "--no-follow-submodules",
+ "exclude Git submodules; persisted for later builds and automatic refreshes (default)",
+ )
.option(
"--include-dir <name>",
"override SKIP_DIRS for this repo's walks — repeatable (e.g. --include-dir build --include-dir tools); " +
@@ -127,7 +135,18 @@ program
(val: string, prev: string[]) => [...prev, val],
[] as string[],
)
- .action(async (dir: string, opts: { deep?: boolean; extensions?: string[]; concurrency?: string; reuse?: boolean; includeDir?: string[] }) => {
+ .action(async (
+ dir: string,
+ opts: {
+ deep?: boolean;
+ extensions?: string[];
+ concurrency?: string;
+ reuse?: boolean;
+ includeDir?: string[];
+ followSubmodules?: boolean;
+ },
+ command: Command,
+ ) => {
const concurrency = opts.concurrency ? Math.max(1, Number(opts.concurrency)) : undefined;
if (opts.concurrency && !Number.isFinite(concurrency)) {
console.error(`✗ --concurrency must be a number, got "${opts.concurrency}"`);
@@ -136,6 +155,7 @@ program
// Persisted BEFORE the build itself runs, so this invocation's walks (and
// every later no-flag build / hooks refresh) see it identically — the
// walkDir call sites read it from state, not from a threaded option.
+ const buildConfigPatch: BuildConfig = {};
if (opts.includeDir && opts.includeDir.length > 0) {
// --include-dir takes bare SKIP_DIRS-style directory NAMES (shouldSkipDir
// compares a single path segment), never paths, and dot-dirs are never
@@ -152,7 +172,14 @@ program
process.exit(1);
}
}
- writeBuildConfig(resolve(dir), { includeDirs: opts.includeDir });
+ buildConfigPatch.includeDirs = opts.includeDir;
+ }
+ const followSubmodulesWasExplicit = command.getOptionValueSource("followSubmodules") === "cli";
+ if (followSubmodulesWasExplicit && typeof opts.followSubmodules === "boolean") {
+ buildConfigPatch.followSubmodules = opts.followSubmodules;
+ }
+ if (Object.keys(buildConfigPatch).length > 0) {
+ patchBuildConfig(resolve(dir), buildConfigPatch);
}
const engine = engineFrom();
const fmt = (o: Record<string, number>) =>
@@ -189,6 +216,7 @@ program
childConfig: cliConfig(),
override: buildGlobalDir,
includeDirs: opts.includeDir,
+ followSubmodules: followSubmodulesWasExplicit ? opts.followSubmodules : undefined,
});
return;
}
diff --git a/src/context/build.ts b/src/context/build.ts
index 537a56d9..45936ea3 100644
--- a/src/context/build.ts
+++ b/src/context/build.ts
@@ -17,7 +17,7 @@ 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 { readIncludeDirs } from "../util/state.js";
+import { readFollowSubmodules, readIncludeDirs } from "../util/state.js";
import type { Summarizer } from "../ai/summarize.js";
import type { FileSummary, SynthNode, Synthesizer } from "../ai/synthesize.js";
import {
@@ -103,10 +103,11 @@ export async function buildContext(dir: string, opts: BuildOptions): Promise<Bui
const root = resolve(dir);
const outDir = contextDirFor(root, opts.contextDir);
const exts = opts.extensions ?? CODE_EXTENSIONS;
- // Read root's persisted `--include-dir` override (same lookup source-files.ts
- // does for the Tier-1 wiring graph) so an included dir like `build/` isn't
- // invisible to the Tier-2 concept pipeline while the wiring graph sees it.
- const files = walkDir(root, readIncludeDirs(root))
+ // 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),
+ })
.filter((f) => exts.some((e) => f.toLowerCase().endsWith(e)))
.filter((f) => !f.startsWith(outDir));
diff --git a/src/context/check.ts b/src/context/check.ts
index f95dfcd2..d446f8d9 100644
--- a/src/context/check.ts
+++ b/src/context/check.ts
@@ -18,7 +18,7 @@ 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 { readIncludeDirs } from "../util/state.js";
+import { readFollowSubmodules, readIncludeDirs } from "../util/state.js";
import { CODE_EXTENSIONS } from "./build.js";
import { contextDirFor, readManifest, readNodes } from "./node-file.js";
@@ -57,12 +57,13 @@ export function checkContext(dir: string, opts: CheckOptions = {}): CheckResult
return result;
}
- // Current code files on disk (same rules `init` used) — including root's
- // persisted `--include-dir` override, so this freshness check never
- // disagrees with buildContext about what "current" means (an included
- // build/ must not silently vanish from one side and not the other).
+ // Current code files on disk (same persisted directory/submodule choices
+ // `init` used), 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))) {
+ for (const file of walkDir(root, readIncludeDirs(root), {
+ followSubmodules: readFollowSubmodules(root),
+ })) {
if (file.startsWith(outDir)) continue;
if (!exts.some((e) => file.toLowerCase().endsWith(e))) continue;
try {
diff --git a/src/graph/build.ts b/src/graph/build.ts
index 3d5fbd5a..0f3fcf95 100644
--- a/src/graph/build.ts
+++ b/src/graph/build.ts
@@ -21,7 +21,7 @@ import { extractFile, languageLabelOf, languageOf, type RawEdge } from "./extrac
import { contentHash } from "../util/id.js";
import { relPosix } from "../util/paths.js";
import { readSourceFile } from "../util/source.js";
-import { readIncludeDirs } from "../util/state.js";
+import { readFollowSubmodules, readIncludeDirs } from "../util/state.js";
import {
emptyExtractCache,
readExtractCache,
@@ -145,8 +145,10 @@ export async function buildGraph(
const outDir = contextDirFor(root, opts.contextDir);
// 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 `--include-dir` override.
- const repoFiles = walkDir(root, readIncludeDirs(root));
+ // including the repo's persisted directory and submodule choices.
+ const repoFiles = walkDir(root, readIncludeDirs(root), {
+ followSubmodules: readFollowSubmodules(root),
+ });
const files = listSourceStats(root, outDir, repoFiles);
const discoveredScopes = discoverScopes(root, repoFiles);
diff --git a/src/graph/scopes.ts b/src/graph/scopes.ts
index 407b6c30..f9bb5eb7 100644
--- a/src/graph/scopes.ts
+++ b/src/graph/scopes.ts
@@ -25,7 +25,7 @@ import { existsSync, readdirSync, readFileSync, type Dirent } from "node:fs";
import { join, resolve } from "node:path";
import { shouldSkipDir, walkDir } from "../ingest/fs.js";
import { relPosix } from "../util/paths.js";
-import { readIncludeDirs } from "../util/state.js";
+import { readFollowSubmodules, readIncludeDirs } from "../util/state.js";
import type { GraphV1, ScopeV1 } from "./types.js";
/** Project-marker files, checked in this order (also the order `markers` is built in). */
@@ -128,11 +128,13 @@ interface Candidate {
isWorkspace: boolean;
}
-/** Walk the tree (reusing `walkDir`'s skip rules, including the repo's persisted
- * `--include-dir` override) and find project-marker dirs. */
+/** Walk the tree (reusing `walkDir`'s persisted directory and submodule
+ * choices) and find project-marker dirs. */
export function discoverScopes(
root: string,
- repoFiles: string[] = walkDir(root, readIncludeDirs(resolve(root))),
+ repoFiles: string[] = walkDir(root, readIncludeDirs(resolve(root)), {
+ followSubmodules: readFollowSubmodules(resolve(root)),
+ }),
): ScopeV1[] {
const absRoot = resolve(root);
const dirs = collectDirs(absRoot, repoFiles);
diff --git a/src/graph/source-files.ts b/src/graph/source-files.ts
index 1dcb903b..b6cd5cee 100644
--- a/src/graph/source-files.ts
+++ b/src/graph/source-files.ts
@@ -10,21 +10,23 @@ import { statSync } from "node:fs";
import { resolve } from "node:path";
import { walkDir } from "../ingest/fs.js";
import { relPosix } from "../util/paths.js";
-import { readIncludeDirs } from "../util/state.js";
+import { readFollowSubmodules, readIncludeDirs } from "../util/state.js";
import { languageOf } from "./extract.js";
/**
* The source files a graph build parses: supported languages, minus the
* output dir. When no pre-enumerated `repoFiles` is passed, the walk reads
- * `root`'s persisted `--include-dir` override (if any) directly from state —
- * so every caller that enumerates through here (the fingerprint probe, the
- * hooks/refresh path, none of which ever see a CLI flag) behaves identically
- * to the `graft build --include-dir` invocation that set it.
+ * `root`'s persisted file-walk choices directly from state, so every caller
+ * that enumerates through here (the fingerprint probe and hooks/refresh path,
+ * none of which ever see a CLI flag) behaves identically to the build that
+ * saved those choices.
*/
export function listSourceFiles(
root: string,
outDir: string,
- repoFiles: string[] = walkDir(root, readIncludeDirs(resolve(root))),
+ repoFiles: string[] = walkDir(root, readIncludeDirs(resolve(root)), {
+ followSubmodules: readFollowSubmodules(resolve(root)),
+ }),
): string[] {
return repoFiles.filter((f) => !f.startsWith(outDir) && languageOf(f) !== null);
}
diff --git a/src/graph/workspace-cli.ts b/src/graph/workspace-cli.ts
index 0c68a9b5..9035e104 100644
--- a/src/graph/workspace-cli.ts
+++ b/src/graph/workspace-cli.ts
@@ -7,7 +7,7 @@
*/
import { Graft } from "../engine.js";
import { contextDirFor, ensureGitignored } from "../context/node-file.js";
-import { writeBuildConfig } from "../util/state.js";
+import { patchBuildConfig, type BuildConfig } from "../util/state.js";
import type { EngineConfig } from "../ai/providers.js";
import { formatAsk } from "../ask/ask.js";
import type { Direction } from "./traverse.js";
@@ -36,6 +36,8 @@ export interface WorkspaceBuildOptions {
* independent repos with their own local settings and can later be rebuilt
* directly without seeing the parent invocation's flags. */
includeDirs?: string[];
+ /** An explicit CLI submodule choice to persist into every child repo. */
+ followSubmodules?: boolean;
}
/** Build every git child into its own committable `graft/`, then replace the
@@ -44,10 +46,16 @@ export interface WorkspaceBuildOptions {
export async function runWorkspaceBuild(root: string, opts: WorkspaceBuildOptions): Promise<void> {
const buildChild = async (childDir: string, childName: string): Promise<void> => {
// Persisted BEFORE the child build itself runs, same as the single-repo
- // `graft build --include-dir` path in cli.ts — so this child's walks (and
- // every later no-flag build of it) see the override identically.
+ // path in cli.ts, so this build and every later no-flag child build agree.
+ const childConfigPatch: BuildConfig = {};
if (opts.includeDirs && opts.includeDirs.length > 0) {
- writeBuildConfig(childDir, { includeDirs: opts.includeDirs });
+ childConfigPatch.includeDirs = opts.includeDirs;
+ }
+ if (opts.followSubmodules !== undefined) {
+ childConfigPatch.followSubmodules = opts.followSubmodules;
+ }
+ if (Object.keys(childConfigPatch).length > 0) {
+ patchBuildConfig(childDir, childConfigPatch);
}
const engine = new Graft({ ...opts.childConfig, contextDir: undefined });
if (opts.deep) await engine.init(childDir, { extensions: opts.extensions });
diff --git a/src/ingest/fs.ts b/src/ingest/fs.ts
index 040b1f83..ecc10c05 100644
--- a/src/ingest/fs.ts
+++ b/src/ingest/fs.ts
@@ -54,15 +54,24 @@ export function shouldSkipDir(name: string, includes?: ReadonlySet<string>): boo
* In a Git worktree, tracked files plus untracked, non-ignored files come from
* `git ls-files`; this gives indexing exactly Git's nested `.gitignore`,
* negation, and global-exclude semantics. Initialized submodules are enumerated
- * recursively as repositories of their own, so their tracked and visible
- * untracked files share one graph while keeping each child's ignore rules.
- * Uninitialized submodules remain absent. Non-Git directories retain the plain
+ * recursively only when `followSubmodules` is true; the default preserves the
+ * historical superproject boundary. Each child keeps its own ignore rules, and
+ * uninitialized submodules remain absent. Non-Git directories retain the plain
* filesystem walk. `includes` lifts only the built-in skip list — it never
* overrides Git's ignore rules (un-ignore or `git add -f` a directory to
* index it, the same contract as tracked-but-ignored files).
*/
-export function walkDir(dir: string, includes?: ReadonlySet<string>): string[] {
- return gitVisibleFiles(dir, includes) ?? walkFilesystem(dir, includes);
+export interface WalkOptions {
+ /** Include initialized Git submodules recursively. Default false. */
+ followSubmodules?: boolean;
+}
+
+export function walkDir(
+ dir: string,
+ includes?: ReadonlySet<string>,
+ opts: WalkOptions = {},
+): string[] {
+ return gitVisibleFiles(dir, includes, opts.followSubmodules === true) ?? walkFilesystem(dir, includes);
}
/** Git's canonical working-tree file set, relative to `dir`. Tracked files are
@@ -71,17 +80,19 @@ export function walkDir(dir: string, includes?: ReadonlySet<string>): string[] {
function gitVisibleFiles(
dir: string,
includes?: ReadonlySet<string>,
+ followSubmodules = false,
traversal?: { topRoot: string; activeRoots: Set<string> },
): string[] | null {
const root = resolve(dir);
+ if (!followSubmodules) return gitVisibleFilesShallow(root, includes);
+
const state = traversal ?? { topRoot: root, activeRoots: new Set<string>() };
const rootKey = process.platform === "win32" ? root.toLowerCase() : root;
if (state.activeRoots.has(rootKey)) return [];
state.activeRoots.add(rootKey);
- // `-t --stage` makes the cached/other output unambiguous in one process:
- // tracked entries are `H <mode> <oid> <stage>\t<path>`, while untracked
- // entries are `? <path>`. `-z` keeps either form safe for unusual paths.
+ // Following uses `-t --stage` so one process can distinguish gitlinks from
+ // tracked and untracked files. `-z` keeps either form safe for unusual paths.
const result = spawnSync(
"git",
["ls-files", "-t", "--stage", "--cached", "--others", "--exclude-standard", "-z", "--"],
@@ -101,7 +112,8 @@ function gitVisibleFiles(
// records and remember if any of them identifies the path as a gitlink.
const entries = new Map<string, { gitlink: boolean }>();
for (const record of result.stdout.split("\0")) {
- if (!record || record.length < 2 || record[1] !== " ") continue;
+ if (!record) continue;
+ if (record.length < 2 || record[1] !== " ") continue;
const tag = record[0];
const body = record.slice(2);
@@ -133,7 +145,7 @@ function gitVisibleFiles(
// runs inside it. Requiring the child's own .git prevents duplicate,
// mis-prefixed parent files and recursive loops.
if (!existsSync(join(abs, ".git"))) continue;
- let childFiles = gitVisibleFiles(abs, includes, state);
+ let childFiles = gitVisibleFiles(abs, includes, true, state);
if (childFiles === null) {
// Do not let one broken child recreate a "healthy but incomplete"
// graph. Match the top-level fail-soft contract locally: fall back to
@@ -164,6 +176,39 @@ function gitVisibleFiles(
return [...out].sort();
}
+/** The historical, non-recursive Git path. Kept separate so the default does
+ * exactly the same command, filtering, ordering, and duplicate handling as it
+ * did before submodule support existed. */
+function gitVisibleFilesShallow(root: string, includes?: ReadonlySet<string>): string[] | null {
+ const result = spawnSync(
+ "git",
+ ["ls-files", "--cached", "--others", "--exclude-standard", "-z", "--"],
+ {
+ cwd: root,
+ encoding: "utf8",
+ stdio: ["ignore", "pipe", "ignore"],
+ maxBuffer: 64 * 1024 * 1024,
+ },
+ );
+ if (result.status !== 0 || result.error || typeof result.stdout !== "string") return null;
+
+ const out: string[] = [];
+ for (const rel of result.stdout.split("\0")) {
+ if (!rel || skippedPath(rel, includes)) continue;
+ const abs = resolve(root, rel);
+ try {
+ const stat = lstatSync(abs);
+ if (!stat.isFile() || stat.size > MAX_FILE_BYTES) continue;
+ } catch {
+ // A tracked file deleted from the working tree is still printed by
+ // `--cached`; absence means it is not part of the current source set.
+ continue;
+ }
+ out.push(abs);
+ }
+ return out;
+}
+
/** A path (git-relative, either separator) is skipped when any of its
* segments is a skippable directory name — the final segment doubles as the
* dot-FILE check (`.eslintrc.js` and friends are not source either). */
diff --git a/src/util/state.ts b/src/util/state.ts
index fa2aa361..8011a946 100644
--- a/src/util/state.ts
+++ b/src/util/state.ts
@@ -64,16 +64,18 @@ export function readStats(d: string): Stats | null { return readJson<Stats>(stat
export function writeStats(d: string, s: Stats): void { writeJsonAtomic(statsPath(d), s); }
/**
- * Persisted per-repo build configuration — currently just `graft build
- * --include-dir`'s override. An explicit input like the graph itself: absent
- * or empty `includeDirs` means today's default (every `SKIP_DIRS` name stays
- * skipped), so a repo that never used the flag is entirely unaffected.
+ * Persisted per-repo build configuration. Explicit CLI choices live here so
+ * later no-flag builds and automatic refreshes enumerate the same file set.
+ * Missing fields always retain backwards-compatible defaults.
*/
export interface BuildConfig {
/** SKIP_DIRS names to include in this repo's walks, persisted so a LATER
* no-flag build — and the fingerprint/refresh path, which never sees CLI
* flags at all — behave identically to the invocation that set it. */
includeDirs?: string[];
+ /** Whether initialized Git submodules are folded into this repo's graph.
+ * Absent/false keeps the historical boundary at the superproject. */
+ followSubmodules?: boolean;
}
/** Local, Git-ignored repository configuration. Kept outside generated
@@ -105,6 +107,12 @@ export function writeBuildConfig(d: string, c: BuildConfig): void {
writeJsonAtomic(buildConfigPath(d), c);
}
+/** Merge explicit CLI choices into the existing local config, so updating one
+ * persisted build option cannot erase another. */
+export function patchBuildConfig(d: string, patch: BuildConfig): void {
+ writeBuildConfig(d, { ...(readBuildConfig(d) ?? {}), ...patch });
+}
+
/** The persisted `--include-dir` override for repo `d`, as a Set — `undefined`
* when nothing was ever persisted (or the persisted list is empty), which every
* `shouldSkipDir`/`walkDir` caller treats as "today's default behavior". Shared
@@ -114,6 +122,11 @@ export function readIncludeDirs(d: string): Set<string> | undefined {
const dirs = readBuildConfig(d)?.includeDirs;
return dirs && dirs.length ? new Set(dirs) : undefined;
}
+
+/** Missing and explicit false both retain the backwards-compatible default. */
+export function readFollowSubmodules(d: string): boolean {
+ return readBuildConfig(d)?.followSubmodules === true;
+}
// Best-effort read-modify-write; not atomic across concurrent processes, but acceptable
// for episodic hook writes (worst case is a lost update, not corruption).
export function patchStats(d: string, patch: Partial<Stats>): Stats {
diff --git a/test/graph-follow-submodules.test.ts b/test/graph-follow-submodules.test.ts
new file mode 100644
index 00000000..adfc75ac
--- /dev/null
+++ b/test/graph-follow-submodules.test.ts
@@ -0,0 +1,138 @@
+import { execFileSync } from "node:child_process";
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { isClean, probeDrift } from "../src/graph/fingerprint.js";
+import { readGraph, wiringPath } from "../src/graph/write.js";
+import { callTool } from "../src/mcp/tools.js";
+import { readBuildConfig } from "../src/util/state.js";
+import type { GraphV1 } from "../src/graph/types.js";
+import { runCli, tmpRepo } from "./helpers.js";
+
+function gitRun(root: string, args: string[]): void {
+ execFileSync("git", args, { cwd: root, stdio: "ignore" });
+}
+
+function commitAll(root: string, message: string): void {
+ gitRun(root, ["add", "-A"]);
+ gitRun(root, [
+ "-c", "user.name=Graft Tests",
+ "commit", "-qm", message,
+ ]);
+}
+
+function graphOf(root: string): GraphV1 {
+ const graph = readGraph(wiringPath(join(root, "graft")));
+ assert.ok(graph, `expected a graph for ${root}`);
+ return graph;
+}
+
+function expectCliOk(args: string[]): void {
+ const result = runCli(args);
+ assert.equal(result.status, 0, result.describe());
+}
+
+test("follow-submodules is opt-in, persisted for MCP refresh, and explicitly reversible (#74)", async () => {
+ const parent = tmpRepo("follow-submodules-parent");
+ const child = tmpRepo("follow-submodules-child");
+ try {
+ gitRun(child, ["init", "-q"]);
+ mkdirSync(join(child, "src"), { recursive: true });
+ writeFileSync(
+ join(child, "src", "sub.ts"),
+ "export function subValue(): number { return 1; }\n",
+ );
+ commitAll(child, "child fixture");
+
+ gitRun(parent, ["init", "-q"]);
+ mkdirSync(join(parent, "src"), { recursive: true });
+ mkdirSync(join(parent, "build"), { recursive: true });
+ writeFileSync(join(parent, "src", "root.ts"), "export const rootValue = 1;\n");
+ writeFileSync(
+ join(parent, "build", "local.ts"),
+ "export function localBuildValue(): number { return 1; }\n",
+ );
+ commitAll(parent, "parent fixture");
+ gitRun(parent, [
+ "-c", "protocol.file.allow=always",
+ "submodule", "add", "-q", child.replace(/\\/g, "/"), "modules/child",
+ ]);
+ commitAll(parent, "add child submodule");
+
+ expectCliOk(["build", parent]);
+ const defaultGraph = graphOf(parent);
+ assert.ok(defaultGraph.nodes.some((node) => node.path === "src/root.ts"));
+ assert.ok(!defaultGraph.nodes.some((node) => node.path.startsWith("modules/child/")));
+ assert.ok(!defaultGraph.nodes.some((node) => node.path.startsWith("build/")));
+ assert.equal(
+ existsSync(join(parent, ".graft", "config.json")),
+ false,
+ "an implicit default must not create local config",
+ );
+
+ expectCliOk(["build", parent, "--follow-submodules", "--include-dir", "build"]);
+ const enabled = graphOf(parent);
+ assert.ok(enabled.nodes.some((node) => node.id === "modules/child/src/sub.ts#subValue"));
+ assert.ok(enabled.nodes.some((node) => node.id === "build/local.ts#localBuildValue"));
+ assert.deepEqual(readBuildConfig(parent), {
+ includeDirs: ["build"],
+ followSubmodules: true,
+ });
+ assert.ok(isClean(probeDrift(parent, join(parent, "graft"))!));
+
+ expectCliOk(["build", parent]);
+ assert.ok(
+ graphOf(parent).nodes.some((node) => node.id === "modules/child/src/sub.ts#subValue"),
+ "a no-flag build must retain the persisted opt-in",
+ );
+
+ const childCheckout = join(parent, "modules", "child", "src", "sub.ts");
+ writeFileSync(
+ childCheckout,
+ "export function changedSubValue(): number { return 2; }\n",
+ );
+ const mcp = await callTool(parent, "graft_file_api", {
+ file: "modules/child/src/sub.ts",
+ });
+ assert.equal(mcp.isError, false, mcp.text);
+ assert.match(mcp.text, /^\[graft\] refreshed the graph/);
+ assert.match(mcp.text, /changedSubValue/);
+ assert.ok(isClean(probeDrift(parent, join(parent, "graft"))!));
+
+ expectCliOk(["build", parent, "--no-follow-submodules"]);
+ const disabled = graphOf(parent);
+ assert.ok(!disabled.nodes.some((node) => node.path.startsWith("modules/child/")));
+ assert.ok(
+ disabled.nodes.some((node) => node.id === "build/local.ts#localBuildValue"),
+ "updating the submodule choice must preserve includeDirs",
+ );
+ assert.deepEqual(readBuildConfig(parent), {
+ includeDirs: ["build"],
+ followSubmodules: false,
+ });
+ assert.ok(isClean(probeDrift(parent, join(parent, "graft"))!));
+
+ writeFileSync(
+ childCheckout,
+ "export function ignoredAfterDisable(): number { return 3; }\n",
+ );
+ assert.ok(
+ isClean(probeDrift(parent, join(parent, "graft"))!),
+ "disabled child edits must not trigger automatic refresh",
+ );
+
+ expectCliOk(["build", parent]);
+ const persistedDisabled = graphOf(parent);
+ assert.ok(!persistedDisabled.nodes.some((node) => node.path.startsWith("modules/child/")));
+ assert.ok(persistedDisabled.nodes.some((node) => node.id === "build/local.ts#localBuildValue"));
+ assert.deepEqual(readBuildConfig(parent), {
+ includeDirs: ["build"],
+ followSubmodules: false,
+ });
+ } finally {
+ rmSync(parent, { recursive: true, force: true });
+ rmSync(child, { recursive: true, force: true });
+ }
+});
diff --git a/test/graph-incremental.test.ts b/test/graph-incremental.test.ts
index b00a4269..57e5fc22 100644
--- a/test/graph-incremental.test.ts
+++ b/test/graph-incremental.test.ts
@@ -17,6 +17,7 @@ import { readAskIndex } from "../src/ask/index-file.js";
import { readGraph, wiringPath } from "../src/graph/write.js";
import type { GraphV1 } from "../src/graph/types.js";
import { chmodDenialUnavailable } from "./helpers.js";
+import { writeBuildConfig } from "../src/util/state.js";
const MATH = [
"export function add(a: number, b: number): number {",
@@ -215,6 +216,12 @@ test("initialized submodule files share the graph and freshness fingerprint (#74
writeFileSync(join(checkout, "visible.ts"), "export const visible = 1;\n");
writeFileSync(join(checkout, "ignored.generated.ts"), "export const ignored = 1;\n");
+ const defaultBuild = await buildGraph(parent);
+ assert.equal(defaultBuild.files, 2, "submodules stay outside the graph by default");
+ const defaultGraph = readGraph(wiringPath(outOf(parent))) as GraphV1;
+ assert.ok(!defaultGraph.nodes.some((n) => n.path.startsWith("modules/child/")));
+
+ writeBuildConfig(parent, { followSubmodules: true });
const first = await buildGraph(parent);
assert.equal(first.files, 4);
const graph = readGraph(wiringPath(outOf(parent))) as GraphV1;
diff --git a/test/graph-workspace-include-dir.test.ts b/test/graph-workspace-include-dir.test.ts
index fe37cbe6..3b587800 100644
--- a/test/graph-workspace-include-dir.test.ts
+++ b/test/graph-workspace-include-dir.test.ts
@@ -17,7 +17,7 @@ import { join } from "node:path";
import { runWorkspaceBuild } from "../src/graph/workspace-cli.js";
import { buildGraph } from "../src/graph/build.js";
import { readGraph, wiringPath } from "../src/graph/write.js";
-import { writeBuildConfig } from "../src/util/state.js";
+import { readBuildConfig, writeBuildConfig } from "../src/util/state.js";
import type { GraphV1 } from "../src/graph/types.js";
function workspaceWithBuildDirs(): string {
@@ -38,7 +38,12 @@ function graphOf(childDir: string): GraphV1 | null {
test("A5: --include-dir on a workspace build reaches every child, which persists it for a later no-flag rebuild", async () => {
const parent = workspaceWithBuildDirs();
try {
- await runWorkspaceBuild(parent, { deep: false, childConfig: {}, includeDirs: ["build"] });
+ await runWorkspaceBuild(parent, {
+ deep: false,
+ childConfig: {},
+ includeDirs: ["build"],
+ followSubmodules: true,
+ });
for (const child of ["repoA", "repoB"]) {
const g = graphOf(join(parent, child));
@@ -47,6 +52,10 @@ test("A5: --include-dir on a workspace build reaches every child, which persists
g!.nodes.some((n) => n.id === "build/util.ts#fromBuild"),
`${child}'s build/ file must be indexed with --include-dir`,
);
+ assert.deepEqual(readBuildConfig(join(parent, child)), {
+ includeDirs: ["build"],
+ followSubmodules: true,
+ });
}
// A later no-flag rebuild of a single child (never sees the parent's CLI
@@ -59,6 +68,18 @@ test("A5: --include-dir on a workspace build reaches every child, which persists
rebuilt!.nodes.some((n) => n.id === "build/util.ts#fromBuild"),
"child's own persisted include-dir state must survive a no-flag rebuild",
);
+
+ await runWorkspaceBuild(parent, {
+ deep: false,
+ childConfig: {},
+ followSubmodules: false,
+ });
+ for (const child of ["repoA", "repoB"]) {
+ assert.deepEqual(readBuildConfig(join(parent, child)), {
+ includeDirs: ["build"],
+ followSubmodules: false,
+ });
+ }
} finally {
rmSync(parent, { recursive: true, force: true });
}
diff --git a/test/ingest-fs.test.ts b/test/ingest-fs.test.ts
index f3514cf6..c2cd324c 100644
--- a/test/ingest-fs.test.ts
+++ b/test/ingest-fs.test.ts
@@ -39,8 +39,12 @@ function addLocalSubmodule(parent: string, source: string, path: string): void {
]);
}
-function walked(root: string, includes?: ReadonlySet<string>): string[] {
- return walkDir(root, includes)
+function walked(
+ root: string,
+ includes?: ReadonlySet<string>,
+ followSubmodules = false,
+): string[] {
+ return walkDir(root, includes, { followSubmodules })
.map((path) => relative(root, path).replace(/\\/g, "/"))
.sort();
}
@@ -82,7 +86,7 @@ test("walkDir keeps tracked files that match an ignore rule and untracked visibl
}
});
-test("walkDir recursively includes initialized submodules with their own Git visibility (#74)", () => {
+test("walkDir follows initialized submodules only when enabled, with their own Git visibility (#74)", () => {
const parent = fixture("submodule-parent");
const child = fixture("submodule-child");
const nested = fixture("submodule-nested");
@@ -117,7 +121,13 @@ test("walkDir recursively includes initialized submodules with their own Git vis
write(nestedCheckout, "src/nested-untracked.ts");
write(nestedCheckout, "src/nested-untracked.generated.ts");
- assert.deepEqual(walked(parent), [
+ assert.deepEqual(
+ walked(parent),
+ ["src/root.ts"],
+ "the backwards-compatible default stops at superproject gitlinks",
+ );
+
+ assert.deepEqual(walked(parent, undefined, true), [
"deps/child module/components/nested module/src/nested-untracked.ts",
"deps/child module/components/nested module/src/nested.ts",
"deps/child module/src/forced.generated.ts",
@@ -126,12 +136,12 @@ test("walkDir recursively includes initialized submodules with their own Git vis
"src/root.ts",
]);
- const withVendor = walked(parent, new Set(["vendor"]));
+ const withVendor = walked(parent, new Set(["vendor"]), true);
assert.ok(withVendor.includes("vendor/skipped child/src/tracked.ts"), "an initialized gitlink is included when its mount's built-in skip is lifted");
assert.ok(!withVendor.includes("vendor/skipped child/build/handwritten.ts"), "the child's own build/ directory remains skipped");
assert.ok(!withVendor.some((path) => path.endsWith("untracked.generated.ts")), "--include-dir never overrides a child's Git ignore rules");
- const withVendorAndBuild = walked(parent, new Set(["vendor", "build"]));
+ const withVendorAndBuild = walked(parent, new Set(["vendor", "build"]), true);
assert.ok(withVendorAndBuild.includes("vendor/skipped child/build/handwritten.ts"));
const childGitFile = join(childCheckout, ".git");
@@ -139,14 +149,18 @@ test("walkDir recursively includes initialized submodules with their own Git vis
renameSync(childGitFile, childGitBackup);
writeFileSync(childGitFile, "gitdir: missing-gitdir\n");
assert.ok(
- walked(parent).includes("deps/child module/src/tracked.ts"),
+ walked(parent, undefined, true).includes("deps/child module/src/tracked.ts"),
"a child Git failure falls back locally instead of producing a healthy but incomplete graph",
);
rmSync(childGitFile, { force: true });
renameSync(childGitBackup, childGitFile);
runGit(parent, ["submodule", "deinit", "-f", "--all"]);
- assert.deepEqual(walked(parent), ["src/root.ts"], "deinitialized gitlinks must not resolve upward and duplicate the parent");
+ assert.deepEqual(
+ walked(parent, undefined, true),
+ ["src/root.ts"],
+ "deinitialized gitlinks must not resolve upward and duplicate the parent",
+ );
} finally {
rmSync(parent, { recursive: true, force: true });
rmSync(child, { recursive: true, force: true });
diff --git a/test/util-state.test.ts b/test/util-state.test.ts
index 6f3a2c7c..818010c1 100644
--- a/test/util-state.test.ts
+++ b/test/util-state.test.ts
@@ -1,19 +1,23 @@
/**
- * A5 — persisted --include-dir override.
+ * Persisted local build configuration.
*
- * `graft build --include-dir <name>` needs a per-repo, persisted record of
- * which SKIP_DIRS names to include, so a LATER no-flag build (or the hooks/
- * refresh path, which never sees CLI flags at all) behaves identically to the
- * invocation that set it. These tests pin the round-trip contract directly,
- * independent of the CLI wiring (covered end-to-end in
- * test/graph-include-dir.test.ts).
+ * Explicit directory and submodule choices must survive later no-flag builds
+ * and the hooks/refresh path, which never sees CLI flags. These tests pin the
+ * round-trip and merge contracts independently of the CLI wiring.
*/
import { test } from "node:test";
import assert from "node:assert/strict";
import { existsSync, mkdtempSync, readFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
-import { buildConfigPath, readBuildConfig, writeBuildConfig, readIncludeDirs } from "../src/util/state.js";
+import {
+ buildConfigPath,
+ patchBuildConfig,
+ readBuildConfig,
+ readFollowSubmodules,
+ readIncludeDirs,
+ writeBuildConfig,
+} from "../src/util/state.js";
function fresh(): string {
return mkdtempSync(join(tmpdir(), "graft-buildconfig-"));
@@ -23,6 +27,7 @@ test("readBuildConfig returns null when nothing was ever persisted", () => {
const d = fresh();
assert.equal(readBuildConfig(d), null);
assert.equal(readIncludeDirs(d), undefined, "no persisted config -> today's default (no includes)");
+ assert.equal(readFollowSubmodules(d), false, "no persisted config -> historical submodule boundary");
});
test("writeBuildConfig + readBuildConfig round-trip includeDirs", () => {
@@ -42,3 +47,35 @@ test("readIncludeDirs turns a persisted list into a Set; an empty persisted list
writeBuildConfig(d, { includeDirs: [] });
assert.equal(readIncludeDirs(d), undefined, "an empty list must read exactly like no list at all");
});
+
+test("followSubmodules round-trips true and explicit false", () => {
+ const d = fresh();
+ writeBuildConfig(d, { followSubmodules: true });
+ assert.equal(readFollowSubmodules(d), true);
+
+ writeBuildConfig(d, { followSubmodules: false });
+ assert.deepEqual(readBuildConfig(d), { followSubmodules: false });
+ assert.equal(readFollowSubmodules(d), false);
+});
+
+test("patchBuildConfig preserves unrelated persisted build choices", () => {
+ const d = fresh();
+ writeBuildConfig(d, { includeDirs: ["build"] });
+ patchBuildConfig(d, { followSubmodules: true });
+ assert.deepEqual(readBuildConfig(d), {
+ includeDirs: ["build"],
+ followSubmodules: true,
+ });
+
+ patchBuildConfig(d, { includeDirs: ["vendor"] });
+ assert.deepEqual(readBuildConfig(d), {
+ includeDirs: ["vendor"],
+ followSubmodules: true,
+ });
+
+ patchBuildConfig(d, { followSubmodules: false });
+ assert.deepEqual(readBuildConfig(d), {
+ includeDirs: ["vendor"],
+ followSubmodules: false,
+ });
+});