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
Add covers: backlinks on concept nodes from the wiring graph
anirudhkumar-nanonets3183a6f29d4a
diff --git a/.gitignore b/.gitignoreindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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 });+ }+});