Skip to content

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

fix(check): don't treat root-level file cards as missing concept nodes (#213) (#215)

Frankie-Xu05321263d9b0
diff --git a/src/context/node-file.ts b/src/context/node-file.ts
index dfd9f2d3..bb8ccb22 100644
--- a/src/context/node-file.ts
+++ b/src/context/node-file.ts
@@ -253,15 +253,39 @@ export interface ParsedNode {
links: NodeLink[];
}
-/** Read and parse every `.md` node file in a context dir (skips the manifest). */
+/**
+ * Stems of per-file wiring cards that sit at the graft/ top level — i.e. cards
+ * for source files in the repo root. Those cards share a directory with concept
+ * nodes (`graft/<stem>.md`) but are recorded in `manifest.files`, not
+ * `manifest.nodes`. Nested file cards live in subdirs and are never scanned here.
+ */
+function rootFileCardStems(dir: string): Set<string> {
+ const manifest = readManifest(dir);
+ if (!manifest) return new Set();
+ const stems = new Set<string>();
+ for (const f of manifest.files) {
+ if (f.path.includes("/")) continue;
+ stems.add(f.path.replace(/\.[^./]+$/, ""));
+ }
+ return stems;
+}
+
+/** Read and parse every concept-node `.md` in a context dir (skips INDEX.md
+ * and root-level per-file cards already recorded in `manifest.files`). */
export function readNodes(dir: string): ParsedNode[] {
if (!existsSync(dir)) return [];
+ const fileCardStems = rootFileCardStems(dir);
const out: ParsedNode[] = [];
for (const entry of readdirSync(dir)) {
if (!entry.endsWith(".md") || entry === "INDEX.md") continue;
const fm = matter(readFileSync(join(dir, entry), "utf8")).data as Record<string, unknown>;
+ const fallbackSlug = entry.replace(/\.md$/, "");
+ // A root-level file card has no concept `slug` and its stem matches a
+ // recorded source file. Skipping it here (instead of all slug-less `.md`)
+ // keeps a hand-dropped notes.md visible to check's indexDrift detector.
+ if (fileCardStems.has(fallbackSlug) && fm.slug == null) continue;
out.push({
- slug: String(fm.slug ?? entry.replace(/\.md$/, "")),
+ slug: String(fm.slug ?? fallbackSlug),
name: String(fm.name ?? ""),
type: String(fm.type ?? ""),
sources: Array.isArray(fm.sources) ? (fm.sources as SourceRef[]) : [],
diff --git a/test/context.test.ts b/test/context.test.ts
index fd0cf02c..7b07afe2 100644
--- a/test/context.test.ts
+++ b/test/context.test.ts
@@ -11,6 +11,7 @@ import { execFileSync } from "node:child_process";
import { buildContext } from "../src/context/build.js";
import { checkContext, indexFreshness, staleBanner } from "../src/context/check.js";
import { contextDirFor, ensureGitignored, ensureSearchable } from "../src/context/node-file.js";
+import { buildGraph } from "../src/graph/build.js";
import { writeBuildConfig } from "../src/util/state.js";
import { fakeProviders, PassthroughSummarizer } from "./helpers.js";
import type { Synthesizer } from "../src/index.js";
@@ -91,6 +92,47 @@ test("check passes immediately after init", async () => {
}
});
+// #213 — per-file cards for root-level sources land in graft/<stem>.md, the same
+// directory readNodes() scans for concept nodes. Nested cards (graft/src/…) are
+// not scanned. After a deep context build + wiring cards, check must not treat
+// the root file card as a missing concept node.
+test("check: root-level file card is not indexDrift after build (#213)", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "ctxgraph-root-card-"));
+ try {
+ writeFileSync(
+ join(dir, "main.ts"),
+ `export function rootFn(a: number): number { return a * 2; }\n`,
+ );
+ mkdirSync(join(dir, "src"));
+ writeFileSync(
+ join(dir, "src", "foo.ts"),
+ `export function nestedFn(a: number): number { return a + 1; }\n`,
+ );
+
+ await buildContext(dir, buildOpts());
+ await buildGraph(dir);
+
+ assert.ok(existsSync(join(dir, "graft", "main.md")), "root source gets a top-level file card");
+ assert.ok(existsSync(join(dir, "graft", "src", "foo.md")), "nested source card stays in a subdir");
+
+ const r = checkContext(dir);
+ assert.equal(r.ok, true, `expected clean check, got ${JSON.stringify(r)}`);
+ assert.deepEqual(r.indexDrift, []);
+
+ // A hand-dropped .md in graft/ is still an orphaned node — the detector
+ // must not go silent for anything that is not a recorded per-file card.
+ writeFileSync(join(dir, "graft", "notes.md"), "# stray notes\n");
+ const stray = checkContext(dir);
+ assert.equal(stray.ok, false);
+ assert.ok(
+ stray.indexDrift.some((s) => s.startsWith("notes:")),
+ `expected stray notes.md to be indexDrift, got ${JSON.stringify(stray.indexDrift)}`,
+ );
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
test("check reports NO GRAPH when init never ran", () => {
const dir = mkdtempSync(join(tmpdir(), "ctxgraph-"));
try {