Skip to content

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

Add per-symbol code graph: tree-sitter structure, LLM meaning layer, drift check

anirudhkumar-nanonets79e5e9490538
diff --git a/.env.example b/.env.example
index 107f4386..6401b6c8 100644
--- a/.env.example
+++ b/.env.example
@@ -1,25 +1,19 @@
# Context Graph Engine — configuration
#
-# Runs fully locally by default (no keys): extraction and summaries use a local
-# Ollama model. Install Ollama (https://ollama.com) and pull a model:
-# ollama pull llama3.2
+# The engine calls OpenRouter for extraction and summaries, so an API key is
+# required for any LLM-backed step (`init`, `graph --llm`). Get one at:
+# https://openrouter.ai/keys
#
-# Set an OpenRouter key for higher-quality cloud summaries/extraction — it's
-# picked up automatically when present.
+# Tier-1 graph structure (`graph`, `check`) is deterministic tree-sitter and
+# needs no key.
-# --- Cloud (optional) ---------------------------------------------------------
+# --- OpenRouter (required for LLM steps) --------------------------------------
# OPENROUTER_API_KEY=sk-or-...
# Optional: override the model (default: openai/gpt-4o-mini)
# CONTEXT_GRAPH_OPENROUTER_MODEL=openai/gpt-4o-mini
# Optional: override the API base URL (default: https://openrouter.ai/api/v1)
# OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
-# --- Local (defaults; used when the key above is absent) ----------------------
-# Force local even when a cloud key is set.
-# CONTEXT_GRAPH_LOCAL=1
-# CONTEXT_GRAPH_OLLAMA_MODEL=llama3.2
-# CONTEXT_GRAPH_OLLAMA_URL=http://localhost:11434
-
# --- Graph location -----------------------------------------------------------
# Where the graph lives (default: <repo>/.context)
# CONTEXT_GRAPH_DIR=.context
diff --git a/package-lock.json b/package-lock.json
index 5046e710..6b7c9e0c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -12,7 +12,10 @@
"commander": "^15.0.0",
"dotenv": "^17.4.2",
"gray-matter": "^4.0.3",
- "openai": "^6.45.0"
+ "openai": "^6.45.0",
+ "tree-sitter": "^0.21.1",
+ "tree-sitter-python": "^0.21.0",
+ "tree-sitter-typescript": "^0.23.2"
},
"bin": {
"context-graph": "dist/cli.js"
@@ -642,6 +645,26 @@
"node": ">=0.10.0"
}
},
+ "node_modules/node-addon-api": {
+ "version": "8.9.0",
+ "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-8.9.0.tgz",
+ "integrity": "sha512-ekZMeaaIzSQTSpr7X2X3iJM7lTzgnx8ahAG9pJfT/7+14mlEM8ZYQ9cgCDvSSRbReFK0oHli3WrZdCiRsgAT9Q==",
+ "license": "MIT",
+ "engines": {
+ "node": "^18 || ^20 || >= 21"
+ }
+ },
+ "node_modules/node-gyp-build": {
+ "version": "4.8.4",
+ "resolved": "https://registry.npmjs.org/node-gyp-build/-/node-gyp-build-4.8.4.tgz",
+ "integrity": "sha512-LA4ZjwlnUblHVgq0oBF3Jl/6h/Nvs5fzBLwdEF4nuxnFdsfajde4WfxtJr3CaiH+F6ewcIB/q4jQ4UzPyid+CQ==",
+ "license": "MIT",
+ "bin": {
+ "node-gyp-build": "bin.js",
+ "node-gyp-build-optional": "optional.js",
+ "node-gyp-build-test": "build-test.js"
+ }
+ },
"node_modules/openai": {
"version": "6.45.0",
"resolved": "https://registry.npmjs.org/openai/-/openai-6.45.0.tgz",
@@ -694,6 +717,81 @@
"node": ">=0.10.0"
}
},
+ "node_modules/tree-sitter": {
+ "version": "0.21.1",
+ "resolved": "https://registry.npmjs.org/tree-sitter/-/tree-sitter-0.21.1.tgz",
+ "integrity": "sha512-7dxoA6kYvtgWw80265MyqJlkRl4yawIjO7S5MigytjELkX43fV2WsAXzsNfO7sBpPPCF5Gp0+XzHk0DwLCq3xQ==",
+ "hasInstallScript": true,
+ "license": "MIT",
+ "dependencies": {
+ "node-addon-api": "^8.0.0",
+ "node-gyp-build": "^4.8.0"
+ }
+ },
+ "node_modules/tree-sitter-javascript": {
+ "version": "0.23.1",
+ "resolved": "https://registry.npmjs.org/tree-sitter-javascript/-/tree-sitter-javascript-0.23.1.tgz",
+ "integrity": "sha512-/bnhbrTD9frUYHQTiYnPcxyHORIw157ERBa6dqzaKxvR/x3PC4Yzd+D1pZIMS6zNg2v3a8BZ0oK7jHqsQo9fWA==",
+ "hasInstallScript": true,
+ "license": "MIT",
+ "dependencies": {
+ "node-addon-api": "^8.2.2",
+ "node-gyp-build": "^4.8.2"
+ },
+ "peerDependencies": {
+ "tree-sitter": "^0.21.1"
+ },
+ "peerDependenciesMeta": {
+ "tree-sitter": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/tree-sitter-python": {
+ "version": "0.21.0",
+ "resolved": "https://registry.npmjs.org/tree-sitter-python/-/tree-sitter-python-0.21.0.tgz",
+ "integrity": "sha512-IUKx7JcTVbByUx1iHGFS/QsIjx7pqwTMHL9bl/NGyhyyydbfNrpruo2C7W6V4KZrbkkCOlX8QVrCoGOFW5qecg==",
+ "hasInstallScript": true,
+ "license": "MIT",
+ "dependencies": {
+ "node-addon-api": "^7.1.0",
+ "node-gyp-build": "^4.8.0"
+ },
+ "peerDependencies": {
+ "tree-sitter": "^0.21.0"
+ },
+ "peerDependenciesMeta": {
+ "tree_sitter": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/tree-sitter-python/node_modules/node-addon-api": {
+ "version": "7.1.1",
+ "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz",
+ "integrity": "sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==",
+ "license": "MIT"
+ },
+ "node_modules/tree-sitter-typescript": {
+ "version": "0.23.2",
+ "resolved": "https://registry.npmjs.org/tree-sitter-typescript/-/tree-sitter-typescript-0.23.2.tgz",
+ "integrity": "sha512-e04JUUKxTT53/x3Uq1zIL45DoYKVfHH4CZqwgZhPg5qYROl5nQjV+85ruFzFGZxu+QeFVbRTPDRnqL9UbU4VeA==",
+ "hasInstallScript": true,
+ "license": "MIT",
+ "dependencies": {
+ "node-addon-api": "^8.2.2",
+ "node-gyp-build": "^4.8.2",
+ "tree-sitter-javascript": "^0.23.1"
+ },
+ "peerDependencies": {
+ "tree-sitter": "^0.21.0"
+ },
+ "peerDependenciesMeta": {
+ "tree-sitter": {
+ "optional": true
+ }
+ }
+ },
"node_modules/tsx": {
"version": "4.22.4",
"resolved": "https://registry.npmjs.org/tsx/-/tsx-4.22.4.tgz",
diff --git a/package.json b/package.json
index 79c04c5e..0ab21d2f 100644
--- a/package.json
+++ b/package.json
@@ -44,7 +44,10 @@
"commander": "^15.0.0",
"dotenv": "^17.4.2",
"gray-matter": "^4.0.3",
- "openai": "^6.45.0"
+ "openai": "^6.45.0",
+ "tree-sitter": "^0.21.1",
+ "tree-sitter-python": "^0.21.0",
+ "tree-sitter-typescript": "^0.23.2"
},
"devDependencies": {
"@types/node": "^26.1.0",
diff --git a/src/ai/crux.ts b/src/ai/crux.ts
new file mode 100644
index 00000000..7ba70fc6
--- /dev/null
+++ b/src/ai/crux.ts
@@ -0,0 +1,127 @@
+/**
+ * Tier-2 "meaning" call for the code graph — batched one request per file.
+ *
+ * Given a source file (with 1-based line numbers) and the list of definitions in
+ * it, one call returns, for each definition:
+ * 1. `summary` — one plain-English sentence: what the symbol is *for*, at the
+ * business-logic level, not a restatement of its signature.
+ * 2. `crux_start`/`crux_end` — the smallest contiguous range of FILE line
+ * numbers (inside that symbol's own span) that a reviewer must read to see
+ * the decision or rule the code encodes. `0/0` means there is no single
+ * crux (a trivial getter, a plain data holder).
+ *
+ * Batching per file means N definitions cost one request, not N — and the model
+ * sees each symbol's neighbours, which sharpens the summaries. Line numbers are
+ * consumed once, at write time, to slice the crux text verbatim from source.
+ */
+import OpenAI from "openai";
+import type { Kind } from "../graph/types.js";
+
+/** One definition we want described, located by its line span within the file. */
+export interface NodeRef {
+ id: string;
+ kind: Kind;
+ signature: string | null;
+ startLine: number; // 1-based file line where the definition starts
+ endLine: number;
+}
+
+export interface FileCruxInput {
+ path: string;
+ source: string;
+ nodes: NodeRef[];
+}
+
+export interface NodeCrux {
+ id: string;
+ summary: string;
+ crux_start: number; // file line, within the symbol's span; 0 = no distinct crux
+ crux_end: number;
+}
+
+export interface CruxSummarizer {
+ describeFile(input: FileCruxInput): Promise<NodeCrux[]>;
+}
+
+const SYSTEM_PROMPT = `You explain code definitions for a code graph that helps engineers navigate a codebase.
+
+You are given ONE source file with 1-based line numbers, and a list of TARGET definitions in it. For every target, return its purpose and the line range of its core logic.
+
+Return STRICT JSON, exactly:
+{ "symbols": [ { "id": string, "summary": string, "crux_start": number, "crux_end": number }, ... ] }
+
+Rules:
+- Emit exactly one entry per target id given, using that id verbatim.
+- summary: ONE sentence — what the symbol is FOR at the business-logic level. Say what problem it solves or rule it enforces, not what its signature already says.
+- crux_start / crux_end: FILE line numbers (as shown), and they MUST fall inside that symbol's own line range. Pick the smallest contiguous span carrying the core branch, formula, guard, or state change — not boilerplate, logging, or plumbing.
+- If a symbol has no meaningful crux (trivial getter, data holder, one-line delegation), use "crux_start": 0 and "crux_end": 0.
+- Output ONLY the JSON object. No prose, no code fences.`;
+
+/** Cap the file text sent per request so one huge file can't blow the context. */
+const MAX_CODE_CHARS = 18_000;
+
+function numberLines(source: string): string {
+ const clipped =
+ source.length > MAX_CODE_CHARS ? `${source.slice(0, MAX_CODE_CHARS)}\n… (truncated)` : source;
+ return clipped
+ .split("\n")
+ .map((line, i) => `${i + 1}\t${line}`)
+ .join("\n");
+}
+
+function userContent(input: FileCruxInput): string {
+ const targets = input.nodes
+ .map(
+ (n) =>
+ `- id=${n.id} | ${n.kind} | lines L${n.startLine}-L${n.endLine}` +
+ (n.signature ? ` | ${n.signature}` : ""),
+ )
+ .join("\n");
+ return `FILE: ${input.path}\n\n${numberLines(input.source)}\n\nTARGETS:\n${targets}`;
+}
+
+/** Best-effort parse of a model's JSON reply into a {@link NodeCrux} list. */
+function parseResults(raw: string): NodeCrux[] {
+ const text = raw.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
+ const obj = JSON.parse(text) as { symbols?: unknown };
+ if (!Array.isArray(obj.symbols)) return [];
+ const num = (v: unknown) => (typeof v === "number" && Number.isFinite(v) ? Math.trunc(v) : 0);
+ return obj.symbols
+ .map((s) => s as Record<string, unknown>)
+ .filter((s) => typeof s.id === "string")
+ .map((s) => ({
+ id: s.id as string,
+ summary: typeof s.summary === "string" ? s.summary.trim() : "",
+ crux_start: num(s.crux_start),
+ crux_end: num(s.crux_end),
+ }));
+}
+
+/** Crux summarizer backed by OpenRouter's OpenAI-compatible chat API. */
+export class OpenRouterCruxSummarizer implements CruxSummarizer {
+ private client: OpenAI;
+ private model: string;
+
+ constructor(apiKey: string, model: string, baseUrl = "https://openrouter.ai/api/v1") {
+ this.client = new OpenAI({
+ apiKey,
+ baseURL: baseUrl,
+ defaultHeaders: { "X-Title": "Context Graph Engine" },
+ });
+ this.model = model;
+ }
+
+ async describeFile(input: FileCruxInput): Promise<NodeCrux[]> {
+ if (input.nodes.length === 0) return [];
+ const response = await this.client.chat.completions.create({
+ model: this.model,
+ temperature: 0,
+ response_format: { type: "json_object" },
+ messages: [
+ { role: "system", content: SYSTEM_PROMPT },
+ { role: "user", content: userContent(input) },
+ ],
+ });
+ return parseResults(response.choices[0]?.message?.content ?? "");
+ }
+}
diff --git a/src/ai/providers.ts b/src/ai/providers.ts
index 349bc2d3..d269cd83 100644
--- a/src/ai/providers.ts
+++ b/src/ai/providers.ts
@@ -3,8 +3,8 @@ import type { Synthesizer } from "./synthesize.js";
/**
* User-facing configuration. Anything omitted falls back to environment
- * variables and then to sensible defaults. The engine runs fully locally
- * (Ollama) unless an OpenRouter key is present.
+ * variables and then to sensible defaults. The engine calls OpenRouter, so an
+ * API key is required for any LLM-backed operation.
*/
export interface EngineConfig {
/** Where the graph lives. Env: CONTEXT_GRAPH_DIR. Default: `<repo>/.context`. */
@@ -17,17 +17,10 @@ export interface EngineConfig {
/** OpenRouter API base URL. Env: OPENROUTER_BASE_URL. Default: https://openrouter.ai/api/v1 */
openrouterBaseUrl?: string;
- /** Force local providers (Ollama) even when an OpenRouter key is set. Env: CONTEXT_GRAPH_LOCAL=1. */
- forceLocal?: boolean;
- /** Ollama model for local extraction/summarization. Env: CONTEXT_GRAPH_OLLAMA_MODEL. Default: llama3.2 */
- ollamaModel?: string;
- /** Ollama base URL. Env: CONTEXT_GRAPH_OLLAMA_URL. Default: http://localhost:11434 */
- ollamaBaseUrl?: string;
-
// --- advanced: bring your own components ---
- /** Override the synthesizer (defaults to OpenRouter, or local Ollama with no key). */
+ /** Override the synthesizer (defaults to OpenRouter). */
synthesizer?: Synthesizer;
- /** Override the code summarizer (same fallbacks as the synthesizer). */
+ /** Override the code summarizer (defaults to OpenRouter). */
summarizer?: Summarizer;
}
@@ -37,9 +30,6 @@ export interface ResolvedConfig {
openrouterApiKey?: string;
openrouterModel: string;
openrouterBaseUrl: string;
- forceLocal: boolean;
- ollamaModel: string;
- ollamaBaseUrl: string;
synthesizer?: Synthesizer;
summarizer?: Summarizer;
}
@@ -47,8 +37,6 @@ export interface ResolvedConfig {
export const DEFAULTS = {
openrouterModel: "openai/gpt-4o-mini",
openrouterBaseUrl: "https://openrouter.ai/api/v1",
- ollamaModel: "llama3.2",
- ollamaBaseUrl: "http://localhost:11434",
} as const;
/** Merge user config with environment variables and defaults. */
@@ -61,11 +49,6 @@ export function resolveConfig(config: EngineConfig = {}): ResolvedConfig {
config.openrouterModel ?? env.CONTEXT_GRAPH_OPENROUTER_MODEL ?? DEFAULTS.openrouterModel,
openrouterBaseUrl:
config.openrouterBaseUrl ?? env.OPENROUTER_BASE_URL ?? DEFAULTS.openrouterBaseUrl,
- forceLocal:
- config.forceLocal ??
- ["1", "true", "yes"].includes((env.CONTEXT_GRAPH_LOCAL ?? "").toLowerCase()),
- ollamaModel: config.ollamaModel ?? env.CONTEXT_GRAPH_OLLAMA_MODEL ?? DEFAULTS.ollamaModel,
- ollamaBaseUrl: config.ollamaBaseUrl ?? env.CONTEXT_GRAPH_OLLAMA_URL ?? DEFAULTS.ollamaBaseUrl,
synthesizer: config.synthesizer,
summarizer: config.summarizer,
};
diff --git a/src/ai/summarize.ts b/src/ai/summarize.ts
index 72e02c2e..82548af6 100644
--- a/src/ai/summarize.ts
+++ b/src/ai/summarize.ts
@@ -59,45 +59,3 @@ export class OpenRouterSummarizer implements Summarizer {
return response.choices[0]?.message?.content?.trim() ?? "";
}
}
-
-/** Summarizer backed by a locally running Ollama instance (key-free fallback). */
-export class OllamaSummarizer implements Summarizer {
- private baseUrl: string;
- private model: string;
-
- constructor(model = "llama3.2", baseUrl = "http://localhost:11434") {
- this.model = model;
- this.baseUrl = baseUrl.replace(/\/$/, "");
- }
-
- async summarize(code: string, opts: { path: string }): Promise<string> {
- let res: Response;
- try {
- res = await fetch(`${this.baseUrl}/api/chat`, {
- method: "POST",
- headers: { "content-type": "application/json" },
- body: JSON.stringify({
- model: this.model,
- stream: false,
- options: { temperature: 0 },
- messages: [
- { role: "system", content: SYSTEM_PROMPT },
- { role: "user", content: userContent(code, opts.path) },
- ],
- }),
- });
- } catch (err) {
- throw new Error(
- `Could not reach Ollama at ${this.baseUrl}. Start it (https://ollama.com) and pull a model ` +
- `(e.g. \`ollama pull ${this.model}\`), or set OPENROUTER_API_KEY to use cloud summarization. ` +
- `Underlying error: ${err instanceof Error ? err.message : String(err)}`,
- );
- }
- if (!res.ok) {
- const body = await res.text().catch(() => "");
- throw new Error(`Ollama returned ${res.status}: ${body}`);
- }
- const data = (await res.json()) as { message?: { content?: string } };
- return data.message?.content?.trim() ?? "";
- }
-}
diff --git a/src/ai/synthesize.ts b/src/ai/synthesize.ts
index 5d18befa..75d7f736 100644
--- a/src/ai/synthesize.ts
+++ b/src/ai/synthesize.ts
@@ -158,56 +158,3 @@ export class OpenRouterSynthesizer implements Synthesizer {
}
}
-/** Synthesizer backed by a locally running Ollama instance (key-free). */
-export class OllamaSynthesizer implements Synthesizer {
- private baseUrl: string;
- private model: string;
-
- constructor(model = "llama3.2", baseUrl = "http://localhost:11434") {
- this.model = model;
- this.baseUrl = baseUrl.replace(/\/$/, "");
- }
-
- async synthesize(files: FileSummary[]): Promise<SynthNode[]> {
- if (files.length === 0) return [];
- let res: Response;
- try {
- res = await fetch(`${this.baseUrl}/api/chat`, {
- method: "POST",
- headers: { "content-type": "application/json" },
- body: JSON.stringify({
- model: this.model,
- stream: false,
- format: NODES_SCHEMA,
- options: { temperature: 0 },
- messages: [
- { role: "system", content: SYSTEM_PROMPT },
- { role: "user", content: userContent(files) },
- ],
- }),
- });
- } catch (err) {
- throw new Error(
- `Could not reach Ollama at ${this.baseUrl}. Start it (https://ollama.com) and pull a model ` +
- `(e.g. \`ollama pull ${this.model}\`), or set OPENROUTER_API_KEY to use cloud synthesis. ` +
- `Underlying error: ${err instanceof Error ? err.message : String(err)}`,
- );
- }
- if (!res.ok) {
- const body = await res.text().catch(() => "");
- if (res.status === 404) {
- throw new Error(
- `Ollama has no model "${this.model}". Run \`ollama pull ${this.model}\`, or set ` +
- `CONTEXT_GRAPH_OLLAMA_MODEL to a model you have.`,
- );
- }
- throw new Error(`Ollama returned ${res.status}: ${body}`);
- }
- const data = (await res.json()) as { message?: { content?: string } };
- try {
- return clean((JSON.parse(data.message?.content ?? "{}") as { nodes?: unknown }).nodes);
- } catch {
- return [];
- }
- }
-}
diff --git a/src/cli.ts b/src/cli.ts
index bfa8e45e..ae4f10f0 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -14,18 +14,18 @@ import { Command } from "commander";
import { relative } from "node:path";
import { ContextGraphEngine } from "./engine.js";
import { formatCheckReport } from "./context/check.js";
+import { formatGraphCheckReport } from "./graph/check.js";
const program = new Command();
program
.name("context-graph")
.description("Build a repo's context graph as linked markdown, and keep it in sync with the code.")
- .option("--dir <path>", "context graph directory (default: <repo>/.context)")
- .option("--local", "force local Ollama providers even when OPENROUTER_API_KEY is set");
+ .option("--dir <path>", "context graph directory (default: <repo>/.context)");
function engineFrom(): ContextGraphEngine {
- const opts = program.opts<{ dir?: string; local?: boolean }>();
- return new ContextGraphEngine({ contextDir: opts.dir, forceLocal: opts.local });
+ const opts = program.opts<{ dir?: string }>();
+ return new ContextGraphEngine({ contextDir: opts.dir });
}
program
@@ -53,6 +53,36 @@ program
console.log(` commit it: git add ${rel} && git commit -m "update context graph"`);
});
+program
+ .command("graph")
+ .description("Build .context/graph.json — a per-symbol code graph (tree-sitter structure + optional LLM meaning)")
+ .argument("[dir]", "repository root", ".")
+ .option("--llm", "run the Tier-2 LLM pass (summary + crux); unchanged bodies are served from cache")
+ .action(async (dir: string, opts: { llm?: boolean }) => {
+ const engine = engineFrom();
+ const r = await engine.graph(dir, {
+ llm: opts.llm,
+ onProgress: ({ phase, index, total, file }) =>
+ process.stderr.write(
+ `\r${phase === "enrich" ? "summarizing" : "parsing"} ${index + 1}/${total}: ${file.slice(0, 50).padEnd(50)}`,
+ ),
+ });
+ process.stderr.write("\n");
+ const fmt = (o: Record<string, number>) =>
+ Object.entries(o)
+ .sort((a, b) => b[1] - a[1])
+ .map(([k, n]) => `${n} ${k}`)
+ .join(", ");
+ console.log(`✓ ${r.nodes} nodes (${fmt(r.byKind)}) from ${r.files} files [${r.languages.join(", ")}]`);
+ console.log(` ${r.edges} edges (${fmt(r.byRelation)})`);
+ const m = r.meaning;
+ console.log(
+ ` meaning: ${m.computed} computed, ${m.cached} cached, ${m.stale} stale, ${m.pending} pending`,
+ );
+ console.log(` → ${r.graphPath}`);
+ for (const e of r.errors) console.error(`✗ ${e}`);
+ });
+
program
.command("check")
.description("Fail if .context/ is stale relative to the code (for CI)")
@@ -62,8 +92,17 @@ program
.action((dir: string, opts: { extensions?: string[]; json?: boolean }) => {
const engine = engineFrom();
const r = engine.check(dir, { extensions: opts.extensions });
- console.log(opts.json ? JSON.stringify(r, null, 2) : formatCheckReport(r));
- if (!r.ok) process.exit(1);
+ const g = engine.checkGraph(dir); // graph.json is only judged when it exists
+
+ if (opts.json) {
+ console.log(JSON.stringify({ context: r, graph: g.missing ? null : g }, null, 2));
+ } else {
+ console.log(formatCheckReport(r));
+ if (!g.missing) console.log("\n" + formatGraphCheckReport(g));
+ }
+
+ // A missing graph.json is not a failure — the markdown graph stands alone.
+ if (!r.ok || (!g.missing && !g.ok)) process.exit(1);
});
program.parseAsync().catch((err) => {
diff --git a/src/context/build.ts b/src/context/build.ts
index 463a9f1c..840e344f 100644
--- a/src/context/build.ts
+++ b/src/context/build.ts
@@ -56,7 +56,7 @@ export interface BuildOptions {
contextDir?: string;
/** Extensions to treat as code. Default: {@link CODE_EXTENSIONS}. */
extensions?: string[];
- /** Human label for the model, recorded in the manifest (e.g. "ollama:llama3.2"). */
+ /** Human label for the model, recorded in the manifest (e.g. "openrouter:openai/gpt-4o-mini"). */
model: string;
summarizer: Summarizer;
synthesizer: Synthesizer;
diff --git a/src/context/node-file.ts b/src/context/node-file.ts
index bab14950..cf0453c9 100644
--- a/src/context/node-file.ts
+++ b/src/context/node-file.ts
@@ -60,7 +60,7 @@ export interface ContextNode {
/** The generated index written alongside the node files. */
export interface Manifest {
version: number;
- /** Human label for the model that built the graph, e.g. "ollama:llama3.2". */
+ /** Human label for the model that built the graph, e.g. "openrouter:openai/gpt-4o-mini". */
model: string;
/** sha256 over every source file's `path:hash` — the whole-graph fingerprint. */
repoDigest: string;
diff --git a/src/engine.ts b/src/engine.ts
index ee8159a2..ce80315c 100644
--- a/src/engine.ts
+++ b/src/engine.ts
@@ -7,17 +7,20 @@
* sync with the code (for CI).
*
* The graph is a folder of linked markdown files committed to the repo; git is
- * the sync. This class only wires the configured LLM providers (local Ollama by
- * default, OpenRouter when a key is present) into the build/check pipelines.
+ * the sync. This class wires the OpenRouter LLM providers into the build/check
+ * pipelines; an API key is required for any LLM-backed operation.
*/
import { resolveConfig, type EngineConfig, type ResolvedConfig } from "./ai/providers.js";
-import { OpenRouterSynthesizer, OllamaSynthesizer, type Synthesizer } from "./ai/synthesize.js";
-import { OpenRouterSummarizer, OllamaSummarizer, type Summarizer } from "./ai/summarize.js";
+import { OpenRouterSynthesizer, type Synthesizer } from "./ai/synthesize.js";
+import { OpenRouterSummarizer, type Summarizer } from "./ai/summarize.js";
+import { OpenRouterCruxSummarizer, type CruxSummarizer } from "./ai/crux.js";
import { buildContext, CODE_EXTENSIONS, type BuildProgress, type BuildResult } from "./context/build.js";
import { checkContext, type CheckResult } from "./context/check.js";
+import { buildGraph, type GraphBuildOptions, type GraphBuildResult } from "./graph/build.js";
+import { checkGraph, type GraphCheckResult } from "./graph/check.js";
export { CODE_EXTENSIONS };
-export type { BuildResult, BuildProgress, CheckResult };
+export type { BuildResult, BuildProgress, CheckResult, GraphBuildResult, GraphCheckResult };
export interface InitOptions {
/** Code extensions to include. Default: {@link CODE_EXTENSIONS}. */
@@ -30,6 +33,12 @@ export interface CheckRunOptions {
extensions?: string[];
}
+export interface GraphRunOptions {
+ /** Run the Tier-2 LLM meaning pass (summary + crux). Absent → Tier-1 only. */
+ llm?: boolean;
+ onProgress?: GraphBuildOptions["onProgress"];
+}
+
export class ContextGraphEngine {
private cfg: ResolvedConfig;
@@ -49,39 +58,58 @@ export class ContextGraphEngine {
});
}
- /** Report whether the committed graph is still in sync with the code. */
+ /** Report whether the committed `.context/` markdown graph is in sync with the code. */
check(dir: string, opts: CheckRunOptions = {}): CheckResult {
return checkContext(dir, { contextDir: this.cfg.contextDir, extensions: opts.extensions });
}
- private synthesizer(): Synthesizer {
- if (this.cfg.synthesizer) return this.cfg.synthesizer;
- if (!this.cfg.forceLocal && this.cfg.openrouterApiKey) {
- return new OpenRouterSynthesizer(
- this.cfg.openrouterApiKey,
- this.cfg.openrouterModel,
- this.cfg.openrouterBaseUrl,
+ /** Report whether the committed `graph.json` is in sync with the code (Tier-1 diff). */
+ checkGraph(dir: string): GraphCheckResult {
+ return checkGraph(dir, { contextDir: this.cfg.contextDir });
+ }
+
+ /**
+ * Build `.context/graph.json` — a per-symbol code graph from tree-sitter.
+ * Tier-1 (structure) always runs; the Tier-2 meaning layer runs only when
+ * `opts.llm` is set. Either way the prior meaning layer is preserved.
+ */
+ graph(dir: string, opts: GraphRunOptions = {}): Promise<GraphBuildResult> {
+ return buildGraph(dir, {
+ contextDir: this.cfg.contextDir,
+ summarizer: opts.llm ? this.cruxSummarizer() : undefined,
+ onProgress: opts.onProgress,
+ });
+ }
+
+ /** The OpenRouter API key, or a clear error telling the user how to set it. */
+ private requireKey(): string {
+ if (!this.cfg.openrouterApiKey) {
+ throw new Error(
+ "No OpenRouter API key. Set OPENROUTER_API_KEY (get one at https://openrouter.ai/keys) " +
+ "to build or summarize the graph.",
);
}
- return new OllamaSynthesizer(this.cfg.ollamaModel, this.cfg.ollamaBaseUrl);
+ return this.cfg.openrouterApiKey;
+ }
+
+ private synthesizer(): Synthesizer {
+ if (this.cfg.synthesizer) return this.cfg.synthesizer;
+ return new OpenRouterSynthesizer(this.requireKey(), this.cfg.openrouterModel, this.cfg.openrouterBaseUrl);
+ }
+
+ /** Per-node crux summarizer for the code graph's Tier-2 pass. */
+ private cruxSummarizer(): CruxSummarizer {
+ return new OpenRouterCruxSummarizer(this.requireKey(), this.cfg.openrouterModel, this.cfg.openrouterBaseUrl);
}
private summarizer(): Summarizer {
if (this.cfg.summarizer) return this.cfg.summarizer;
- if (!this.cfg.forceLocal && this.cfg.openrouterApiKey) {
- return new OpenRouterSummarizer(
- this.cfg.openrouterApiKey,
- this.cfg.openrouterModel,
- this.cfg.openrouterBaseUrl,
- );
- }
- return new OllamaSummarizer(this.cfg.ollamaModel, this.cfg.ollamaBaseUrl);
+ return new OpenRouterSummarizer(this.requireKey(), this.cfg.openrouterModel, this.cfg.openrouterBaseUrl);
}
/** Human label for the active model, recorded in the manifest. */
private modelLabel(): string {
if (this.cfg.synthesizer || this.cfg.summarizer) return "custom";
- if (!this.cfg.forceLocal && this.cfg.openrouterApiKey) return `openrouter:${this.cfg.openrouterModel}`;
- return `ollama:${this.cfg.ollamaModel}`;
+ return `openrouter:${this.cfg.openrouterModel}`;
}
}
diff --git a/src/graph/build.ts b/src/graph/build.ts
new file mode 100644
index 00000000..a9ee8671
--- /dev/null
+++ b/src/graph/build.ts
@@ -0,0 +1,133 @@
+/**
+ * `graph` — build `.context/graph.json` from a code repository.
+ *
+ * M1 pipeline (Tier-1 only, deterministic, no LLM):
+ * 1. Walk the repo for TS/Python source files.
+ * 2. Parse each with tree-sitter and emit one NodeV1 per definition.
+ * 3. Write a sorted graph.json.
+ * Edges (M2) and LLM summary/crux (M3) layer onto this without changing it.
+ */
+import { readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { walkDir } from "../ingest/fs.js";
+import { contextDirFor } from "../context/node-file.js";
+import { extractFile, languageOf, type Language, type RawEdge } from "./extract.js";
+import { resolveEdges } from "./resolve.js";
+import { enrichGraph, type EnrichStats } from "./enrich.js";
+import { GRAPH_FILE, readGraph, writeGraph } from "./write.js";
+import type { GraphV1, Kind, NodeV1, Relation } from "./types.js";
+import type { CruxSummarizer } from "../ai/crux.js";
+
+export interface GraphBuildOptions {
+ /** Override the output dir (default: `<root>/.context`). */
+ contextDir?: string;
+ /** Run the Tier-2 LLM meaning pass. Absent → Tier-1 only (cache is still preserved). */
+ summarizer?: CruxSummarizer;
+ onProgress?: (info: {
+ phase: "parse" | "enrich";
+ index: number;
+ total: number;
+ file: string;
+ }) => void;
+}
+
+export interface GraphBuildResult {
+ contextDir: string;
+ graphPath: string;
+ files: number;
+ nodes: number;
+ edges: number;
+ byKind: Record<Kind, number>;
+ byRelation: Record<Relation, number>;
+ languages: string[];
+ meaning: EnrichStats;
+ errors: string[];
+}
+
+/** The source files a graph build parses: supported languages, minus the output dir. */
+export function listSourceFiles(root: string, outDir: string): string[] {
+ return walkDir(root).filter((f) => !f.startsWith(outDir) && languageOf(f) !== null);
+}
+
+export async function buildGraph(
+ dir: string,
+ opts: GraphBuildOptions = {},
+): Promise<GraphBuildResult> {
+ const root = resolve(dir);
+ const outDir = contextDirFor(root, opts.contextDir);
+ const files = listSourceFiles(root, outDir);
+
+ const nodes: NodeV1[] = [];
+ const rawEdges: RawEdge[] = [];
+ const sources = new Map<string, string>();
+ const langs = new Set<Language>();
+ const errors: string[] = [];
+
+ files.forEach((file, i) => {
+ const rel = relative(root, file);
+ opts.onProgress?.({ phase: "parse", index: i, total: files.length, file: rel });
+ const lang = languageOf(file)!;
+ let source: string;
+ try {
+ source = readFileSync(file, "utf8");
+ } catch (err) {
+ errors.push(`${rel}: ${err instanceof Error ? err.message : String(err)}`);
+ return;
+ }
+ try {
+ const { nodes: fileNodes, rawEdges: fileEdges } = extractFile(rel, source, lang);
+ nodes.push(...fileNodes);
+ rawEdges.push(...fileEdges);
+ sources.set(rel, source);
+ langs.add(lang);
+ } catch (err) {
+ errors.push(`${rel}: parse failed — ${err instanceof Error ? err.message : String(err)}`);
+ }
+ });
+
+ const edges = resolveEdges(nodes, rawEdges);
+
+ // graph.json is its own Tier-2 cache: fold in the prior meaning layer so an
+ // unchanged body is never re-summarized (and a Tier-1-only run never wipes it).
+ const prior = readGraph(join(outDir, GRAPH_FILE));
+ const priorById = new Map((prior?.nodes ?? []).map((n) => [n.id, n]));
+ const meaning = await enrichGraph(nodes, priorById, sources, {
+ summarizer: opts.summarizer,
+ onProgress: ({ index, total, node }) =>
+ opts.onProgress?.({ phase: "enrich", index, total, file: node }),
+ });
+ errors.push(...meaning.errors);
+
+ const graph: GraphV1 = {
+ meta: {
+ version: 1,
+ nodeCount: nodes.length,
+ edgeCount: edges.length,
+ languages: [...langs].sort(),
+ },
+ nodes,
+ edges,
+ };
+
+ const graphPath = writeGraph(graph, outDir);
+
+ const byKind = {} as Record<Kind, number>;
+ for (const n of nodes) byKind[n.kind] = (byKind[n.kind] ?? 0) + 1;
+ const byRelation = {} as Record<Relation, number>;
+ for (const e of edges) byRelation[e.relation] = (byRelation[e.relation] ?? 0) + 1;
+
+ return {
+ contextDir: outDir,
+ graphPath,
+ files: files.length,
+ nodes: nodes.length,
+ edges: edges.length,
+ byKind,
+ byRelation,
+ languages: [...langs].sort(),
+ meaning,
+ errors,
+ };
+}
+
+export { GRAPH_FILE };
diff --git a/src/graph/check.ts b/src/graph/check.ts
new file mode 100644
index 00000000..0e6ae7aa
--- /dev/null
+++ b/src/graph/check.ts
@@ -0,0 +1,135 @@
+/**
+ * `checkGraph` — is the committed `graph.json` still in sync with the code?
+ *
+ * Deterministic and fast (tree-sitter only, no LLM, no network): it re-runs
+ * Tier-1 extraction and diffs the fresh node set against the committed graph by
+ * `id` and `body_hash`. Meant for CI — exit non-zero when a PR changed code but
+ * didn't rebuild the graph.
+ *
+ * Drift categories:
+ * added a definition exists in code but not in graph.json (run `graph`)
+ * removed a node in graph.json no longer exists in code (run `graph`)
+ * changed a node's body_hash differs from the committed one (run `graph`)
+ * stale a committed node's summary is flagged stale — its body changed
+ * since it was last summarized (run `graph --llm`)
+ *
+ * `added`/`removed`/`changed` are structural: the graph no longer describes the
+ * code. `stale` is a meaning-layer signal the last build already recorded.
+ * `pending` (never summarized) is not drift — it's a deliberate Tier-1-only build.
+ */
+import { readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { contextDirFor } from "../context/node-file.js";
+import { extractFile, languageOf } from "./extract.js";
+import { listSourceFiles } from "./build.js";
+import { GRAPH_FILE, readGraph } from "./write.js";
+
+export interface GraphCheckResult {
+ ok: boolean;
+ /** True when there is no graph.json (a graph has never been built). */
+ missing: boolean;
+ added: string[];
+ removed: string[];
+ changed: string[];
+ stale: string[];
+ /** Nodes never summarized (reported for context; not counted as drift). */
+ pending: number;
+}
+
+export interface GraphCheckOptions {
+ contextDir?: string;
+}
+
+export function checkGraph(dir: string, opts: GraphCheckOptions = {}): GraphCheckResult {
+ const root = resolve(dir);
+ const outDir = contextDirFor(root, opts.contextDir);
+
+ const result: GraphCheckResult = {
+ ok: false,
+ missing: false,
+ added: [],
+ removed: [],
+ changed: [],
+ stale: [],
+ pending: 0,
+ };
+
+ const committed = readGraph(join(outDir, GRAPH_FILE));
+ if (!committed) {
+ result.missing = true;
+ return result;
+ }
+
+ // Freshly extract Tier-1 nodes from the code on disk (same file set as build).
+ const current = new Map<string, string>(); // id → body_hash
+ for (const file of listSourceFiles(root, outDir)) {
+ const lang = languageOf(file)!;
+ let source: string;
+ try {
+ source = readFileSync(file, "utf8");
+ } catch {
+ continue; // unreadable now → its nodes show up as `removed` below
+ }
+ try {
+ const { nodes } = extractFile(relative(root, file), source, lang);
+ for (const n of nodes) current.set(n.id, n.body_hash);
+ } catch {
+ // parse failure → skip; the committed nodes for this file become `removed`.
+ }
+ }
+
+ const committedById = new Map(committed.nodes.map((n) => [n.id, n]));
+ for (const [id, node] of committedById) {
+ const now = current.get(id);
+ if (now === undefined) result.removed.push(id);
+ else if (now !== node.body_hash) result.changed.push(id);
+ if (node.summary_state === "stale") result.stale.push(id);
+ if (node.summary_state === "pending") result.pending++;
+ }
+ for (const id of current.keys()) {
+ if (!committedById.has(id)) result.added.push(id);
+ }
+
+ for (const arr of [result.added, result.removed, result.changed, result.stale]) arr.sort();
+
+ result.ok =
+ result.added.length === 0 &&
+ result.removed.length === 0 &&
+ result.changed.length === 0 &&
+ result.stale.length === 0;
+ return result;
+}
+
+/** Render a graph-check result as a human-readable report. */
+export function formatGraphCheckReport(r: GraphCheckResult): string {
+ if (r.missing) {
+ return "graph check: NO GRAPH\n\nNo .context/graph.json found. Run `context-graph graph` first.";
+ }
+ if (r.ok) {
+ const note = r.pending ? ` (${r.pending} node(s) not yet summarized — run \`graph --llm\`)` : "";
+ return `graph check: OK — graph.json is in sync with the code.${note}`;
+ }
+
+ const lines: string[] = ["graph check: STALE", ""];
+ const structural = r.added.length + r.removed.length + r.changed.length;
+ if (r.changed.length) {
+ lines.push(`changed (${r.changed.length}):`);
+ for (const id of r.changed) lines.push(` ~ ${id}`);
+ }
+ if (r.added.length) {
+ lines.push(`added (${r.added.length}):`);
+ for (const id of r.added) lines.push(` + ${id}`);
+ }
+ if (r.removed.length) {
+ lines.push(`removed (${r.removed.length}):`);
+ for (const id of r.removed) lines.push(` - ${id}`);
+ }
+ if (r.stale.length) {
+ lines.push(`stale summaries (${r.stale.length}):`);
+ for (const id of r.stale) lines.push(` ! ${id}`);
+ }
+ lines.push("");
+ if (structural) lines.push("Run `context-graph graph` to rebuild the structure, then commit .context/.");
+ if (r.stale.length) lines.push("Run `context-graph graph --llm` to refresh stale summaries.");
+ return lines.join("\n");
+}
diff --git a/src/graph/enrich.ts b/src/graph/enrich.ts
new file mode 100644
index 00000000..7acd892f
--- /dev/null
+++ b/src/graph/enrich.ts
@@ -0,0 +1,152 @@
+/**
+ * Tier-2 pass: attach the LLM meaning layer (`summary` + `crux`) to nodes.
+ *
+ * graph.json is its own cache — the committed file already holds every node's
+ * summary/crux from a prior run. So this pass is diff-driven:
+ *
+ * - cache hit — a prior node with the same id, same `body_hash`, and
+ * `summary_state:"ready"` → carry its summary/crux over, no LLM call.
+ * - stale — a prior ready summary whose body has since changed → keep the
+ * old text as a hint but mark it "stale". Recomputed only if an LLM is given.
+ * - pending — new or never-summarized node → one LLM call when an LLM is
+ * given, otherwise left "pending".
+ *
+ * Passing no summarizer runs the cache/stale bookkeeping alone (no calls, no
+ * cost) — which is what a plain `graph` build does, so it never wipes the
+ * meaning layer a previous `--llm` run produced.
+ *
+ * The LLM returns line numbers into the slice it was shown; we consume them here,
+ * once, to cut `crux.code` verbatim from the source. `crux.span` is a pointer
+ * only and is never used to re-slice.
+ */
+import type { CruxSummarizer, NodeCrux, NodeRef } from "../ai/crux.js";
+import type { Crux, NodeV1 } from "./types.js";
+
+export interface EnrichOptions {
+ /** When present, (re)compute meaning for stale/pending nodes. Absent → cache only. */
+ summarizer?: CruxSummarizer;
+ /** Progress is reported per file (one LLM call each), not per node. */
+ onProgress?: (info: { index: number; total: number; node: string }) => void;
+}
+
+export interface EnrichStats {
+ cached: number; // carried over from a prior identical body
+ computed: number; // freshly summarized by the LLM this run
+ stale: number; // body changed, left with an outdated summary (no LLM this run)
+ pending: number; // never summarized and not computed this run
+ errors: string[];
+}
+
+export async function enrichGraph(
+ nodes: NodeV1[],
+ prior: Map<string, NodeV1>,
+ sources: Map<string, string>,
+ opts: EnrichOptions = {},
+): Promise<EnrichStats> {
+ const stats: EnrichStats = { cached: 0, computed: 0, stale: 0, pending: 0, errors: [] };
+
+ // Which nodes actually need an LLM call this run (after cache carry-over).
+ const dirty: NodeV1[] = [];
+
+ for (const node of nodes) {
+ const was = prior.get(node.id);
+ if (was?.summary_state === "ready" && was.body_hash === node.body_hash) {
+ node.summary = was.summary;
+ node.crux = was.crux;
+ node.summary_state = "ready";
+ stats.cached++;
+ continue;
+ }
+ // needs computing; seed with the old summary as a stale hint when one exists.
+ if (was && was.summary) {
+ node.summary = was.summary;
+ node.crux = was.crux;
+ node.summary_state = "stale";
+ }
+ dirty.push(node);
+ }
+
+ if (!opts.summarizer) {
+ for (const node of dirty) {
+ if (node.summary_state === "stale") stats.stale++;
+ else stats.pending++;
+ }
+ return stats;
+ }
+
+ // One LLM call per file: group the dirty nodes by the file they live in.
+ const byFile = new Map<string, NodeV1[]>();
+ for (const node of dirty) {
+ if (!sources.has(node.path)) continue;
+ const arr = byFile.get(node.path);
+ if (arr) arr.push(node);
+ else byFile.set(node.path, [node]);
+ }
+
+ const files = [...byFile.keys()];
+ for (let i = 0; i < files.length; i++) {
+ const path = files[i];
+ const fileNodes = byFile.get(path)!;
+ const source = sources.get(path)!;
+ const lineCount = source.split("\n").length;
+ opts.onProgress?.({ index: i, total: files.length, node: path });
+
+ const refs: NodeRef[] = fileNodes.map((n) => {
+ const [startLine, endLine] = spanLines(n.span, lineCount);
+ return { id: n.id, kind: n.kind, signature: n.signature, startLine, endLine };
+ });
+
+ let results: Map<string, NodeCrux>;
+ try {
+ const list = await opts.summarizer.describeFile({ path, source, nodes: refs });
+ results = new Map(list.map((r) => [r.id, r]));
+ } catch (err) {
+ // whole-file call failed: leave every node as-is (stale hint or pending).
+ for (const node of fileNodes) {
+ if (node.summary_state === "stale") stats.stale++;
+ else stats.pending++;
+ }
+ stats.errors.push(`${path}: ${err instanceof Error ? err.message : String(err)}`);
+ continue;
+ }
+
+ for (const node of fileNodes) {
+ const r = results.get(node.id);
+ if (!r) {
+ // model skipped this symbol; keep whatever it had.
+ if (node.summary_state === "stale") stats.stale++;
+ else stats.pending++;
+ continue;
+ }
+ node.summary = r.summary || null;
+ node.crux = buildCrux(r, node, source, lineCount);
+ node.summary_state = "ready";
+ stats.computed++;
+ }
+ }
+ return stats;
+}
+
+/**
+ * Cut the crux text verbatim from the file using the model's file-absolute line
+ * range, clamped to the node's own span. Returns null when the model reported no
+ * distinct crux (0/0) or gave an unusable range.
+ */
+function buildCrux(r: NodeCrux, node: NodeV1, source: string, lineCount: number): Crux | null {
+ if (r.crux_start < 1 || r.crux_end < r.crux_start) return null;
+ const [nodeStart, nodeEnd] = spanLines(node.span, lineCount);
+ const start = Math.max(nodeStart, Math.min(r.crux_start, nodeEnd));
+ const end = Math.max(start, Math.min(r.crux_end, nodeEnd));
+ const code = source.split("\n").slice(start - 1, end).join("\n");
+ if (!code.trim()) return null;
+ return { code, span: `L${start}-L${end}` };
+}
+
+/** Parse a `"L12-L30"` span into a clamped [start, end] line pair (1-based). */
+function spanLines(span: string, fileLines: number): [number, number] {
+ const m = /^L(\d+)-L(\d+)$/.exec(span);
+ if (!m) return [1, fileLines];
+ const start = Math.max(1, Math.min(Number(m[1]), fileLines));
+ const end = Math.max(start, Math.min(Number(m[2]), fileLines));
+ return [start, end];
+}
diff --git a/src/graph/extract.ts b/src/graph/extract.ts
new file mode 100644
index 00000000..029f06ed
--- /dev/null
+++ b/src/graph/extract.ts
@@ -0,0 +1,297 @@
+/**
+ * Tier-1 extraction: source file → {@link NodeV1}[] + raw edges, via tree-sitter.
+ *
+ * Deterministic and dependency-only (no LLM, no network). Emits one node per
+ * definition (file, class, function, method, interface, type, enum, and TS
+ * arrow-function consts) plus unresolved edge intents. Edge *targets* are
+ * resolved against the whole-repo node index later, in build.ts.
+ */
+import Parser from "tree-sitter";
+import TypeScript from "tree-sitter-typescript";
+import Python from "tree-sitter-python";
+import { basename } from "node:path";
+import { contentHash } from "../util/id.js";
+import type { Kind, NodeV1, Relation } from "./types.js";
+
+export type Language = "typescript" | "tsx" | "python";
+
+/** Map a file path to a supported language, or null if unsupported. */
+export function languageOf(path: string): Language | null {
+ const p = path.toLowerCase();
+ if (p.endsWith(".tsx") || p.endsWith(".jsx")) return "tsx";
+ if (/\.(ts|mts|cts|js|mjs|cjs)$/.test(p)) return "typescript";
+ if (p.endsWith(".py") || p.endsWith(".pyi")) return "python";
+ return null;
+}
+
+/**
+ * An edge whose target isn't resolved yet. build.ts turns these into EdgeV1 by
+ * matching `name`/`specifier` against the repo-wide node index.
+ */
+export interface RawEdge {
+ source: string; // resolved node id
+ relation: Relation;
+ file: string; // the file this edge originates in (scopes name resolution)
+ targetId?: string; // already-resolved target (contains)
+ specifier?: string; // module path to resolve (imports)
+ name?: string; // symbol name to resolve (extends/implements/calls)
+ viaMember?: boolean; // calls: was it `obj.foo()` (→ prefer method targets)?
+}
+
+export interface ExtractResult {
+ nodes: NodeV1[];
+ rawEdges: RawEdge[];
+}
+
+const TS_KINDS: Record<string, Kind> = {
+ class_declaration: "class",
+ abstract_class_declaration: "class",
+ function_declaration: "function",
+ generator_function_declaration: "function",
+ method_definition: "method",
+ interface_declaration: "interface",
+ type_alias_declaration: "type",
+ enum_declaration: "enum",
+};
+
+const PY_KINDS: Record<string, Kind> = {
+ class_definition: "class",
+ function_definition: "function", // → "method" inside a class (resolved in the walk)
+};
+
+const FUNCTION_VALUE_TYPES = new Set([
+ "arrow_function",
+ "function",
+ "function_expression",
+ "generator_function",
+]);
+
+const parser = new Parser();
+const GRAMMARS: Record<Language, unknown> = {
+ typescript: TypeScript.typescript,
+ tsx: TypeScript.tsx,
+ python: Python,
+};
+
+interface WalkCtx {
+ rel: string;
+ source: string;
+ lang: Language;
+ kinds: Record<string, Kind>;
+ scope: string[]; // enclosing definition names, for id scoping
+ enclosingKind: Kind | null; // kind of the nearest enclosing definition
+ parentId: string; // nearest enclosing definition id, or the file id
+}
+
+/** A definition we're about to emit, normalized across the two shapes we handle. */
+interface DefDescriptor {
+ name: string;
+ kind: Kind;
+ headerEnd: number; // char index where the signature ends (body starts)
+ hashNode: Parser.SyntaxNode; // node whose text forms body_hash / span
+}
+
+export function extractFile(rel: string, source: string, lang: Language): ExtractResult {
+ parser.setLanguage(GRAMMARS[lang] as never);
+ const root = parser.parse(source).rootNode;
+
+ const nodes: NodeV1[] = [
+ {
+ id: rel,
+ name: basename(rel),
+ kind: "file",
+ path: rel,
+ span: `L1-L${root.endPosition.row + 1}`,
+ signature: null,
+ exported: true,
+ origin: "ast",
+ body_hash: contentHash(source),
+ summary_state: "pending",
+ summary: null,
+ crux: null,
+ },
+ ];
+ const rawEdges: RawEdge[] = [];
+
+ const ctx: WalkCtx = {
+ rel,
+ source,
+ lang,
+ kinds: lang === "python" ? PY_KINDS : TS_KINDS,
+ scope: [],
+ enclosingKind: null,
+ parentId: rel,
+ };
+ for (const child of root.namedChildren) walk(child, ctx, nodes, rawEdges);
+ return { nodes, rawEdges };
+}
+
+function walk(node: Parser.SyntaxNode, ctx: WalkCtx, out: NodeV1[], edges: RawEdge[]): void {
+ const desc = describe(node, ctx);
+ if (desc) {
+ const id = `${ctx.rel}#${[...ctx.scope, desc.name].join(".")}`;
+ out.push({
+ id,
+ name: desc.name,
+ kind: desc.kind,
+ path: ctx.rel,
+ span: `L${desc.hashNode.startPosition.row + 1}-L${desc.hashNode.endPosition.row + 1}`,
+ signature: clean(ctx.source.slice(desc.hashNode.startIndex, desc.headerEnd)),
+ exported: ctx.lang === "python" ? !desc.name.startsWith("_") : tsExported(node),
+ origin: "ast",
+ body_hash: contentHash(desc.hashNode.text),
+ summary_state: "pending",
+ summary: null,
+ crux: null,
+ });
+ // structural containment
+ edges.push({ source: ctx.parentId, relation: "contains", targetId: id, file: ctx.rel });
+ // class heritage
+ if (desc.kind === "class") edges.push(...heritageEdges(node, id, ctx));
+
+ const childCtx: WalkCtx = {
+ ...ctx,
+ scope: [...ctx.scope, desc.name],
+ enclosingKind: desc.kind,
+ parentId: id,
+ };
+ for (const child of node.namedChildren) walk(child, childCtx, out, edges);
+ return;
+ }
+
+ // not a definition — capture calls/imports, then descend with the same context
+ const callType = ctx.lang === "python" ? "call" : "call_expression";
+ if (node.type === callType) {
+ const callee = calleeName(node, ctx.lang);
+ if (callee) {
+ edges.push({
+ source: ctx.parentId,
+ relation: "calls",
+ name: callee.name,
+ viaMember: callee.viaMember,
+ file: ctx.rel,
+ });
+ }
+ } else if (isImport(node)) {
+ const spec = importSpecifier(node, ctx.lang);
+ if (spec) edges.push({ source: ctx.rel, relation: "imports", specifier: spec, file: ctx.rel });
+ }
+
+ for (const child of node.namedChildren) walk(child, ctx, out, edges);
+}
+
+/** Recognize the two definition shapes: mapped node types, and TS arrow-consts. */
+function describe(node: Parser.SyntaxNode, ctx: WalkCtx): DefDescriptor | null {
+ const mapped = ctx.kinds[node.type];
+ if (mapped) {
+ const name = node.childForFieldName("name")?.text;
+ if (!name) return null;
+ let kind = mapped;
+ if (ctx.lang === "python" && mapped === "function" && ctx.enclosingKind === "class") {
+ kind = "method";
+ }
+ const body = node.childForFieldName("body");
+ return { name, kind, headerEnd: body ? body.startIndex : node.endIndex, hashNode: node };
+ }
+
+ // TS: `const foo = (…) => …` / `const foo = function () {}`
+ if (ctx.lang !== "python" && node.type === "variable_declarator") {
+ const value = node.childForFieldName("value");
+ if (value && FUNCTION_VALUE_TYPES.has(value.type)) {
+ const name = node.childForFieldName("name")?.text;
+ if (!name) return null;
+ const vbody = value.childForFieldName("body");
+ return {
+ name,
+ kind: "function",
+ headerEnd: vbody ? vbody.startIndex : node.endIndex,
+ hashNode: node,
+ };
+ }
+ }
+ return null;
+}
+
+function heritageEdges(node: Parser.SyntaxNode, classId: string, ctx: WalkCtx): RawEdge[] {
+ const edges: RawEdge[] = [];
+ if (ctx.lang === "python") {
+ const supers = node.childForFieldName("superclasses"); // argument_list
+ for (const c of supers?.namedChildren ?? []) {
+ if (c.type === "identifier") {
+ edges.push({ source: classId, relation: "extends", name: c.text, file: ctx.rel });
+ }
+ }
+ return edges;
+ }
+ const heritage = node.namedChildren.find((c) => c.type === "class_heritage");
+ for (const clause of heritage?.namedChildren ?? []) {
+ const relation: Relation | null =
+ clause.type === "implements_clause"
+ ? "implements"
+ : clause.type === "extends_clause"
+ ? "extends"
+ : null;
+ if (!relation) continue;
+ for (const t of clause.namedChildren) {
+ if (t.type === "identifier" || t.type === "type_identifier") {
+ edges.push({ source: classId, relation, name: t.text, file: ctx.rel });
+ }
+ }
+ }
+ return edges;
+}
+
+function calleeName(
+ node: Parser.SyntaxNode,
+ lang: Language,
+): { name: string; viaMember: boolean } | null {
+ const fn = node.childForFieldName("function");
+ if (!fn) return null;
+ if (fn.type === "identifier") return { name: fn.text, viaMember: false };
+ if (lang === "python" && fn.type === "attribute") {
+ const a = fn.childForFieldName("attribute") ?? fn.namedChildren.at(-1);
+ return a ? { name: a.text, viaMember: true } : null;
+ }
+ if (lang !== "python" && fn.type === "member_expression") {
+ const p = fn.childForFieldName("property") ?? fn.namedChildren.at(-1);
+ return p ? { name: p.text, viaMember: true } : null;
+ }
+ return null;
+}
+
+function isImport(node: Parser.SyntaxNode): boolean {
+ return node.type === "import_statement" || node.type === "import_from_statement";
+}
+
+function importSpecifier(node: Parser.SyntaxNode, lang: Language): string | null {
+ if (lang === "python") {
+ const m =
+ node.childForFieldName("module_name") ??
+ node.namedChildren.find((c) => c.type === "dotted_name" || c.type === "relative_import");
+ return m?.text ?? null;
+ }
+ const str = node.namedChildren.find((c) => c.type === "string");
+ if (!str) return null;
+ const frag = str.namedChildren.find((c) => c.type === "string_fragment");
+ return frag?.text ?? str.text.replace(/^['"]|['"]$/g, "");
+}
+
+/** Signature = the definition header, whitespace-collapsed, trailing punctuation stripped. */
+function clean(raw: string): string | null {
+ const sig = raw
+ .replace(/\s+/g, " ")
+ .trim()
+ .replace(/(=>|[{:=])\s*$/, "")
+ .trim();
+ return sig || null;
+}
+
+/** TS: a definition is exported if any ancestor is an `export` statement. */
+function tsExported(node: Parser.SyntaxNode): boolean {
+ let p = node.parent;
+ while (p) {
+ if (p.type === "export_statement") return true;
+ p = p.parent;
+ }
+ return false;
+}
diff --git a/src/graph/resolve.ts b/src/graph/resolve.ts
new file mode 100644
index 00000000..398a796e
Binary files /dev/null and b/src/graph/resolve.ts differ
diff --git a/src/graph/types.ts b/src/graph/types.ts
new file mode 100644
index 00000000..39cc33db
--- /dev/null
+++ b/src/graph/types.ts
@@ -0,0 +1,81 @@
+/**
+ * `graph.json` — the code graph schema (v1).
+ *
+ * One node per definition (file, class, function, method, interface, type, enum),
+ * wired by edges (contains, imports, calls, ...). Field names follow the LSP /
+ * SCIP vocabulary (`name`, `kind`, ...) rather than any one tool's conventions.
+ *
+ * Two tiers of data live on a node:
+ * - Tier-1 (deterministic, $0): everything from the AST. Rebuilt on every run.
+ * - Tier-2 (one LLM call, cached on `body_hash`): `summary` + `crux`.
+ * M1 populates Tier-1 only; Tier-2 fields ship as `pending`/null.
+ */
+
+/** What a node represents. LSP SymbolKind, narrowed to what TS + Python produce. */
+export type Kind =
+ | "file"
+ | "class"
+ | "function"
+ | "method"
+ | "interface" // TS only
+ | "type" // TS only (type alias)
+ | "enum"; // TS only
+
+/** How confident we are an edge is true. */
+export type Confidence = "extracted" | "inferred";
+
+/** Whether the LLM meaning-layer has been computed for a node. */
+export type SummaryState = "pending" | "ready" | "stale";
+
+/** The LLM-chosen business-logic excerpt. `code` is the source of truth; `span`
+ * is a best-effort pointer that may drift and is never used to re-slice. */
+export interface Crux {
+ code: string;
+ span: string; // e.g. "L189-L196"
+}
+
+export interface NodeV1 {
+ // identity
+ id: string; // path-scoped: "src/cache.ts#Cache.get"
+ name: string; // the symbol's own name: "get"
+ kind: Kind;
+
+ // location (Tier-1, deterministic)
+ path: string; // repo-relative: "src/cache.ts"
+ span: string; // whole definition: "L165-L222"
+ signature: string | null; // "get(k: string): number" — null for kind:"file"
+ exported: boolean;
+ origin: "ast";
+ body_hash: string; // sha256 of the definition text; the Tier-2 re-run trigger
+
+ // meaning (Tier-2, one LLM call)
+ summary_state: SummaryState;
+ summary: string | null;
+ crux: Crux | null;
+}
+
+export type Relation =
+ | "contains" // file → symbol, class → method (structural)
+ | "calls" // function → function it invokes
+ | "imports" // file → module
+ | "references" // symbol → symbol it names but doesn't call
+ | "implements" // TS: class → interface
+ | "extends"; // class → base class
+
+export interface EdgeV1 {
+ source: string; // node id
+ target: string; // node id, or an unresolved module string for imports
+ relation: Relation;
+ confidence: Confidence;
+}
+
+export interface GraphV1 {
+ meta: {
+ version: 1;
+ nodeCount: number;
+ edgeCount: number;
+ languages: string[];
+ };
+ nodes: NodeV1[];
+ edges: EdgeV1[];
+}
diff --git a/src/graph/write.ts b/src/graph/write.ts
new file mode 100644
index 00000000..0aa0dfc3
--- /dev/null
+++ b/src/graph/write.ts
@@ -0,0 +1,44 @@
+/**
+ * Serialize a {@link GraphV1} to `<contextDir>/graph.json`.
+ *
+ * Output is sorted (nodes by id, edges by source/relation/target) and carries no
+ * timestamps, so rebuilding an unchanged repo produces a byte-identical file and
+ * git diffs stay minimal.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { EdgeV1, GraphV1 } from "./types.js";
+
+export const GRAPH_FILE = "graph.json";
+
+/**
+ * Read an existing graph.json for use as the Tier-2 cache. Returns null when the
+ * file is absent or unparseable (a fresh build, or a corrupt file we'll replace).
+ */
+export function readGraph(path: string): GraphV1 | null {
+ try {
+ return JSON.parse(readFileSync(path, "utf8")) as GraphV1;
+ } catch {
+ return null;
+ }
+}
+
+export function writeGraph(graph: GraphV1, outDir: string): string {
+ const sorted: GraphV1 = {
+ ...graph,
+ nodes: [...graph.nodes].sort((a, b) => a.id.localeCompare(b.id)),
+ edges: [...graph.edges].sort(edgeOrder),
+ };
+ mkdirSync(outDir, { recursive: true });
+ const path = join(outDir, GRAPH_FILE);
+ writeFileSync(path, JSON.stringify(sorted, null, 2) + "\n");
+ return path;
+}
+
+function edgeOrder(a: EdgeV1, b: EdgeV1): number {
+ return (
+ a.source.localeCompare(b.source) ||
+ a.relation.localeCompare(b.relation) ||
+ a.target.localeCompare(b.target)
+ );
+}
diff --git a/src/index.ts b/src/index.ts
index ecd5beb8..f3303c58 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -22,13 +22,15 @@ export { buildContext } from "./context/build.js";
export type { BuildOptions } from "./context/build.js";
export { checkContext, formatCheckReport } from "./context/check.js";
export type { CheckOptions } from "./context/check.js";
+export { checkGraph, formatGraphCheckReport } from "./graph/check.js";
+export type { GraphCheckResult, GraphCheckOptions } from "./graph/check.js";
export type { ContextNode, NodeLink, SourceRef, Manifest } from "./context/node-file.js";
export type { EngineConfig, ResolvedConfig } from "./ai/providers.js";
export { resolveConfig, DEFAULTS } from "./ai/providers.js";
// Providers, for advanced/custom setups.
-export { OpenRouterSynthesizer, OllamaSynthesizer } from "./ai/synthesize.js";
+export { OpenRouterSynthesizer } from "./ai/synthesize.js";
export type { Synthesizer, SynthNode, SynthLink, FileSummary } from "./ai/synthesize.js";
-export { OpenRouterSummarizer, OllamaSummarizer } from "./ai/summarize.js";
+export { OpenRouterSummarizer } from "./ai/summarize.js";
export type { Summarizer } from "./ai/summarize.js";