Skip to content

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

Add covers: backlinks on concept nodes from the wiring graph

anirudhkumar-nanonets3183a6f29d4a
diff --git a/.gitignore b/.gitignore
index 670e1d83..9f10fe96 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,9 +2,10 @@ node_modules/
dist/
*.log
-# The context graph's local LLM-call cache — regenerated, never committed.
-# The graph itself (.context/*.md + manifest.json) IS committed.
-.context/.cache/
+# The graph's local LLM-call cache — regenerated, never committed. Everything
+# else in graft/ (concept nodes, wiring cards, .graph/wiring.json, manifest.json)
+# IS committed — it's the lockfile teammates and their agents read.
+graft/.cache/
# Benchmark run artifacts (regenerated per run)
bench/results/
diff --git a/src/graph/build.ts b/src/graph/build.ts
index a9ecde93..1e388dc8 100644
--- a/src/graph/build.ts
+++ b/src/graph/build.ts
@@ -15,7 +15,7 @@ import { extractFile, languageOf, type Language, type RawEdge } from "./extract.
import { resolveEdges } from "./resolve.js";
import { enrichGraph, type EnrichStats } from "./enrich.js";
import { readGraph, writeGraph, wiringPath } from "./write.js";
-import { writeCards, writeIndex } from "./cards.js";
+import { writeCards, writeIndex, writeCovers } from "./cards.js";
import type { GraphV1, Kind, NodeV1, Relation } from "./types.js";
import type { CruxSummarizer } from "../ai/crux.js";
@@ -118,6 +118,9 @@ export async function buildGraph(
// refresh the INDEX roster. Pure projection — no LLM, no network.
const cardStats = writeCards(graph, outDir);
writeIndex(outDir, cardStats.files);
+ // Backfill concept nodes with their `covers:` symbol/file:line list (the
+ // OKF↔Wiring link). No-op when there are no concept nodes (a $0 build).
+ writeCovers(graph, outDir);
const byKind = {} as Record<Kind, number>;
for (const n of nodes) byKind[n.kind] = (byKind[n.kind] ?? 0) + 1;
diff --git a/src/graph/cards.ts b/src/graph/cards.ts
index 8fa0c1cb..6905f038 100644
--- a/src/graph/cards.ts
+++ b/src/graph/cards.ts
@@ -14,8 +14,9 @@
* `summary` when present (after `graft build --deep`), else its deterministic
* `signature`, so cards are useful even in a $0 structure-only build.
*/
-import { mkdirSync, writeFileSync, existsSync, readdirSync, rmSync } from "node:fs";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, rmSync } from "node:fs";
import { dirname, join, relative } from "node:path";
+import matter from "gray-matter";
import type { GraphV1, NodeV1 } from "./types.js";
import { CACHE_DIR, readNodes } from "../context/node-file.js";
import { GRAPH_DIR } from "./write.js";
@@ -221,3 +222,62 @@ export function writeIndex(outDir: string, files: CardFileInfo[]): void {
writeFileSync(join(outDir, INDEX_FILE), lines.join("\n"));
}
+
+/** One symbol a concept node covers: its name, kind, and `path:span` pointer. */
+export interface CoverRef {
+ symbol: string;
+ kind: string;
+ /** `src/ai/providers.ts:L28-L35` — same vocabulary `graft ask` returns. */
+ at: string;
+}
+
+/**
+ * Backfill each concept node's frontmatter with a `covers:` list — the symbols
+ * (and their exact `file:line`) it spans, read from the wiring graph. This is the
+ * explicit OKF↔Wiring link: it doubles as grep bait (a `grep <symbol>` lands on
+ * the prose node, not just its card) and lets an agent read the span straight
+ * from the node without ever opening `wiring.json`.
+ *
+ * A surgical frontmatter patch: the generated body and every other key are
+ * preserved verbatim; only `covers` is added/replaced. Concept nodes are the
+ * top-level `.md` files (cards live in subdirs; INDEX.md is skipped). On a $0
+ * structure-only build there are no concept nodes, so this is a no-op. Returns
+ * the number of nodes enriched.
+ */
+export function writeCovers(graph: GraphV1, outDir: string): number {
+ if (!existsSync(outDir)) return 0;
+
+ const symbolsByPath = new Map<string, NodeV1[]>();
+ for (const n of graph.nodes) {
+ if (n.kind === "file") continue;
+ const list = symbolsByPath.get(n.path) ?? [];
+ list.push(n);
+ symbolsByPath.set(n.path, list);
+ }
+ for (const list of symbolsByPath.values()) {
+ list.sort((a, b) => spanStart(a.span) - spanStart(b.span) || a.name.localeCompare(b.name));
+ }
+
+ let enriched = 0;
+ for (const entry of readdirSync(outDir)) {
+ if (!entry.endsWith(".md") || entry === INDEX_FILE) continue;
+ const full = join(outDir, entry);
+ const parsed = matter(readFileSync(full, "utf8"));
+ const sources = Array.isArray(parsed.data.sources)
+ ? (parsed.data.sources as Array<{ path?: string }>)
+ : [];
+
+ const covers: CoverRef[] = [];
+ for (const path of [...new Set(sources.map((s) => s.path ?? ""))].sort()) {
+ for (const n of symbolsByPath.get(path) ?? []) {
+ covers.push({ symbol: n.name, kind: n.kind, at: `${n.path}:${n.span}` });
+ }
+ }
+
+ // Re-stringify with covers appended last, so re-runs produce a stable diff.
+ const { covers: _prev, ...rest } = parsed.data as Record<string, unknown>;
+ writeFileSync(full, matter.stringify(parsed.content, { ...rest, covers }));
+ enriched++;
+ }
+ return enriched;
+}
diff --git a/test/covers.test.ts b/test/covers.test.ts
new file mode 100644
index 00000000..6a9139fa
--- /dev/null
+++ b/test/covers.test.ts
@@ -0,0 +1,76 @@
+/**
+ * Tests for `covers:` — the backlink written onto concept nodes from the wiring
+ * graph. After a wiring build, each concept node's frontmatter should list the
+ * symbols (with `path:span`) in the files it cites, and re-runs stay stable.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import matter from "gray-matter";
+import { buildContext } from "../src/context/build.js";
+import { buildGraph } from "../src/graph/build.js";
+import { fakeProviders } from "./helpers.js";
+
+function makeFixture(): string {
+ const dir = mkdtempSync(join(tmpdir(), "graft-covers-"));
+ writeFileSync(
+ join(dir, "auth.ts"),
+ `// [[Auth Service]] ==depends_on==> [[Token Store]]\n` +
+ `export function login(user: string): boolean {\n return user.length > 0;\n}\n`,
+ );
+ return dir;
+}
+
+test("wiring build backfills covers: onto concept nodes", async () => {
+ const dir = makeFixture();
+ try {
+ await buildContext(dir, { model: "fake", ...fakeProviders() });
+ await buildGraph(dir); // $0, no LLM — still writes cards + covers
+
+ const fm = matter(readFileSync(join(dir, "graft", "auth-service.md"), "utf8")).data;
+ assert.ok(Array.isArray(fm.covers), "covers should be an array");
+ const login = fm.covers.find((c: { symbol: string }) => c.symbol === "login");
+ assert.ok(login, "covers should include the login function");
+ assert.equal(login.kind, "function");
+ assert.match(login.at, /^auth\.ts:L\d+-L\d+$/);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("patching covers preserves the node's body and other frontmatter", async () => {
+ const dir = makeFixture();
+ try {
+ await buildContext(dir, { model: "fake", ...fakeProviders() });
+ const path = join(dir, "graft", "auth-service.md");
+ const before = matter(readFileSync(path, "utf8"));
+ await buildGraph(dir);
+ const after = matter(readFileSync(path, "utf8"));
+
+ // Body (Summary + Related + human notes) is untouched.
+ assert.equal(after.content, before.content);
+ // Existing frontmatter survives; only covers is added.
+ assert.equal(after.data.slug, before.data.slug);
+ assert.deepEqual(after.data.sources, before.data.sources);
+ assert.deepEqual(after.data.links, before.data.links);
+ assert.ok("covers" in after.data && !("covers" in before.data));
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("re-running the wiring build leaves covers byte-stable", async () => {
+ const dir = makeFixture();
+ try {
+ await buildContext(dir, { model: "fake", ...fakeProviders() });
+ await buildGraph(dir);
+ const first = readFileSync(join(dir, "graft", "auth-service.md"), "utf8");
+ await buildGraph(dir);
+ const second = readFileSync(join(dir, "graft", "auth-service.md"), "utf8");
+ assert.equal(second, first);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});