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 per-symbol code graph: tree-sitter structure, LLM meaning layer, drift check
anirudhkumar-nanonets79e5e9490538
diff --git a/.env.example b/.env.exampleindex 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=.contextdiff --git a/package-lock.json b/package-lock.jsonindex 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.jsonindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 @@ programconsole.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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 00000000..398a796eBinary files /dev/null and b/src/graph/resolve.ts differdiff --git a/src/graph/types.ts b/src/graph/types.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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";