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
/**
* The synthesis step: turn per-file prose summaries into a CURATED set of graph
* nodes. This is where granularity is decided — the model groups related files
* into subsystem nodes, keeps a notable file as its own node when it deserves
* one, and adds cross-cutting concept nodes, instead of emitting one entity per
* incidental identifier. Each node is attributed to the source files it is
* grounded in, so provenance (and staleness) stays exact.
*/
import type { ChatModel } from "./llm/types.js";
import { recoverToolArgsFromContent, warnToolChoiceIgnored } from "./llm/recover-tool.js";
/** A directed edge to another node, by node name (resolved to a slug later). */
export interface SynthLink {
to: string;
relation: string;
description?: string;
}
/** A node as proposed by the synthesizer, before it is written to disk. */
export interface SynthNode {
name: string;
/** system | api | file | concept */
type: string;
summary: string;
/** Source file paths (from the provided set) this node is grounded in. */
sources: string[];
links: SynthLink[];
}
/** One labeled file summary fed into synthesis. */
export interface FileSummary {
path: string;
summary: string;
}
export interface Synthesizer {
synthesize(files: FileSummary[]): Promise<SynthNode[]>;
}
const SYSTEM_PROMPT = `You build an ARCHITECTURE graph of a codebase from per-file summaries. The reader is an AI agent that will read this graph before working on the code, so it must describe the system at the level a senior engineer would explain it — not file by file.
Produce a CURATED set of nodes of mixed granularity:
- "system" nodes: GROUP files that collaborate as one component (usually a directory or a cohesive set) into a SINGLE node. This should be the most common node type. Prefer one system node over several file nodes.
- "file" nodes: only for a substantial, standalone module that genuinely deserves its own node apart from its system.
- "concept" nodes: cross-cutting ideas, design decisions, or invariants that span multiple files (e.g. "local-first provider fallback", "staleness checking", "content-hash provenance"). Include several — they are the most valuable nodes for an agent.
Rules:
- Every summary must earn its tokens with NON-OBVIOUS information: invariants, ordering constraints, conventions, failure modes, "X must never happen after Y" facts, and the WHY behind a design. Never restate what a README says or what a directory listing already makes obvious ("src/api contains the API code" is worthless); an agent reading the node already sees the file paths. If all you can say about a group of files is what their names say, fold them into a larger node instead.
- Strongly prefer FEWER, larger, meaningful nodes. For a repo of N files, aim for well under N nodes. Do NOT emit one node per file, and never a node per incidental identifier (a local interface, helper, or third-party symbol).
- Merge duplicates and surface-form variants into one node.
- For each node give: a canonical human-readable name; a type ("system" | "file" | "concept"); a 1-3 sentence summary of its ROLE in the system; "sources" = the exact file paths (from the input) it is grounded in (a system lists all its files; a concept lists the files that motivate it); and "links" to other nodes you define, each with a relation and a short description of what concretely happens in the code.
- The relation MUST be one of exactly these verbs (each answers a question a code reviewer asks): "part_of" (where does this live?), "uses" (what breaks if the target changes?), "depends_on" (same, for non-call dependencies), "produces" (where does this output come from?), "configures" (what changes its behavior without a code change?), "validates" (what checks or judges this? tests, drift checks, scoring), "implements" (what contract must this honor?). Never invent vague relations like "influences", "supports", or "relates_to" — if none of the verbs fit, drop the link.
- Only link to nodes you actually define in this response.
Respond only via the record_graph tool / JSON schema.`;
const NODES_SCHEMA = {
type: "object",
properties: {
nodes: {
type: "array",
items: {
type: "object",
properties: {
name: { type: "string" },
type: { type: "string" },
summary: { type: "string" },
sources: { type: "array", items: { type: "string" } },
links: {
type: "array",
items: {
type: "object",
properties: {
to: { type: "string" },
relation: {
type: "string",
enum: ["part_of", "uses", "depends_on", "produces", "configures", "validates", "implements"],
},
description: { type: "string" },
},
required: ["to", "relation"],
},
},
},
required: ["name", "type", "summary", "sources"],
},
},
},
required: ["nodes"],
} as const;
/** Cap the total summary text sent in one call so it never blows the context. */
const MAX_INPUT_CHARS = 60_000;
function userContent(files: FileSummary[]): string {
const body = files.map((f) => `## ${f.path}\n\n${f.summary}`).join("\n\n");
return body.length > MAX_INPUT_CHARS
? `${body.slice(0, MAX_INPUT_CHARS)}\n… (truncated)`
: body;
}
/** Normalize a raw model response into clean {@link SynthNode}s. */
function clean(nodes: unknown): SynthNode[] {
if (!Array.isArray(nodes)) return [];
const out: SynthNode[] = [];
for (const n of nodes as Array<Record<string, unknown>>) {
if (!n || typeof n.name !== "string" || typeof n.type !== "string") continue;
out.push({
name: n.name,
type: n.type,
summary: typeof n.summary === "string" ? n.summary : "",
sources: Array.isArray(n.sources) ? (n.sources as unknown[]).filter((s): s is string => typeof s === "string") : [],
links: Array.isArray(n.links)
? (n.links as Array<Record<string, unknown>>)
.filter((l) => l && typeof l.to === "string" && typeof l.relation === "string")
.map((l) => ({
to: l.to as string,
relation: l.relation as string,
description: typeof l.description === "string" ? l.description : undefined,
}))
: [],
});
}
return out;
}
/**
* A forced `record_graph` call can still deliver `nodes` as a JSON *string*
* (double-encoded args). `clean` would then return [] and the CLI ticked
* `✓ concepts: 0 nodes` (#383). Parse, then salvage balanced `{"name":…}`
* objects if a stray brace breaks the string. Do not reuse recover-tool —
* that path only runs when there is no tool-call args object.
*/
function coerceRecordGraphNodes(nodes: unknown, toolCalls: number): unknown[] {
if (Array.isArray(nodes)) return nodes;
if (typeof nodes !== "string") return [];
let parsed: unknown;
let salvaged = 0;
try {
parsed = JSON.parse(nodes);
} catch {
const objs = salvageNamedObjects(nodes);
parsed = objs;
salvaged = objs.length;
}
const values = Array.isArray(parsed) ? parsed : [];
const salvageBit = salvaged > 0 ? ` — salvaged ${salvaged} node(s) from malformed JSON` : "";
console.error(
`⚠ synthesize: tool call returned "nodes" as a ${nodes.length}-char string, not an array; ${toolCalls} tool call(s)${salvageBit}`,
);
return values;
}
/** Pull complete `{"name":…}` objects out of a near-JSON string. */
function salvageNamedObjects(raw: string): Record<string, unknown>[] {
const out: Record<string, unknown>[] = [];
for (let i = 0; i < raw.length; ) {
const start = raw.indexOf("{", i);
if (start === -1) break;
const end = balancedClose(raw, start);
if (end === -1) {
i = start + 1;
continue;
}
try {
const obj = JSON.parse(raw.slice(start, end + 1)) as unknown;
if (obj && typeof obj === "object" && !Array.isArray(obj) && typeof (obj as { name?: unknown }).name === "string") {
out.push(obj as Record<string, unknown>);
}
} catch {
/* slice was not a complete object */
}
i = end + 1;
}
return out;
}
function balancedClose(raw: string, start: number): number {
let depth = 0;
let inStr = false;
let escape = false;
for (let i = start; i < raw.length; i++) {
const c = raw[i]!;
if (inStr) {
if (escape) {
escape = false;
continue;
}
if (c === "\\") {
escape = true;
continue;
}
if (c === '"') inStr = false;
continue;
}
if (c === '"') {
inStr = true;
continue;
}
if (c === "{") depth++;
else if (c === "}") {
depth--;
if (depth === 0) return i;
}
}
return -1;
}
function shapeOfNodes(nodes: unknown): string {
if (typeof nodes === "string") return `"nodes" is string, ${nodes.length} chars`;
if (Array.isArray(nodes)) return `"nodes" is array, ${nodes.length} entries`;
if (nodes === undefined) return `"nodes" is undefined`;
return `"nodes" is ${typeof nodes}`;
}
const RECORD_TOOL = "record_graph";
/** Synthesizer backed by any {@link ChatModel} via forced tool calling. */
export class ChatSynthesizer implements Synthesizer {
constructor(private model: ChatModel) {}
async synthesize(files: FileSummary[]): Promise<SynthNode[]> {
if (files.length === 0) return [];
const res = await this.model.create({
temperature: 0,
maxTokens: 8192,
tools: [
{
name: RECORD_TOOL,
description: "Record the curated architecture-graph nodes and their links.",
parameters: NODES_SCHEMA as unknown as Record<string, unknown>,
},
],
responseFormat: { kind: "tool", name: RECORD_TOOL },
messages: [
{ role: "system", content: SYSTEM_PROMPT },
{ role: "user", content: userContent(files) },
],
});
const raw = nodesFromResponse(res)?.nodes;
const out = clean(coerceRecordGraphNodes(raw, res.toolCalls.length));
if (out.length === 0) {
console.error(`⚠ synthesize: empty batch (${shapeOfNodes(raw)}; ${res.toolCalls.length} tool call(s))`);
}
return out;
}
}
/**
* Prefer a real tool call; if the gateway ignored `tool_choice` (#129), recover
* the same payload from `content`. Recovered args still go through {@link clean}.
*/
function nodesFromResponse(res: { text: string; toolCalls: { name: string; args: unknown }[] }): {
nodes?: unknown;
} | undefined {
const call = res.toolCalls.find((c) => c.name === RECORD_TOOL) ?? res.toolCalls[0];
if (call?.args && typeof call.args === "object" && !Array.isArray(call.args)) {
return call.args as { nodes?: unknown };
}
const recovered = recoverToolArgsFromContent(res.text, {
toolNames: [RECORD_TOOL, "emit_json"],
payloadKey: "nodes",
});
if (!recovered) warnToolChoiceIgnored("synthesize", res.text?.trim() ? "unparsed" : "empty");
return recovered as { nodes?: unknown } | undefined;
}