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
/**
* Naming the clusters a diff reaches — the rung of the ladder between a concept
* node and the symbol backstop (see {@link LabelSource}).
*
* The point is scope. Getting labels from `build --deep` means summarising every
* file in the repo — 356 calls and thirteen minutes on graft's own repo — to put
* names on the six clusters a PR actually touches, and it still misses: only 40% of
* this repo's files are claimed by a concept, so the rest fall back to a path. Here
* the unit of work is the cluster, not the file: one request names all of them from
* data the graph already holds (paths and symbol names — no file reads), and the
* answer is cached by content hash so the next PR pays nothing for a cluster whose
* files did not change.
*
* Two rules keep it honest:
* - a cluster spanning unrelated features must come back "mixed", and then keeps
* its symbol backstop rather than a flattering name;
* - a failure of any kind — no key, spent quota, refused call, malformed answer —
* leaves every label exactly as it was and never fails the caller.
*/
import { createHash } from "node:crypto";
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { CACHE_DIR } from "../context/node-file.js";
import type { ChatModel } from "../ai/llm/types.js";
import type { GraphV1 } from "../graph/types.js";
import type { BlastReport, ChangedArea, ImpactedModule } from "./blast.js";
import { shortLabel } from "./modules.js";
/** One cluster to name: its identity, its files and the symbols inside it. */
export interface Cluster {
key: string;
files: string[];
symbols: string[];
}
/** Anything that can turn clusters into names. A model in production, a stub in tests. */
export interface Namer {
/** Names by cluster key. A key the namer chose not to name is simply absent. */
name(clusters: Cluster[]): Promise<Map<string, string>>;
}
export interface NameStats {
/** Labels taken from the cache, and labels that cost a call. */
cached: number;
named: number;
/** Clusters the namer declined ("mixed") or could not answer for. */
declined: number;
/** Set when naming was attempted and failed outright; the reason, for one line
* in the report. Never thrown: a comment without names still beats no comment. */
error?: string;
}
const SYSTEM_PROMPT = `You name parts of a codebase for a pull-request reviewer.
You are given clusters of files that a change can affect. For each cluster, answer with the FEATURE or SUBSYSTEM those files implement, as a developer on the team would refer to it in conversation.
Rules:
- 2 to 4 words, Title Case. No trailing "Module", "System", "Layer", "Manager" or "Handler" unless the team would genuinely say it.
- Name the RESPONSIBILITY, not the mechanics: "Query Freshness Gate", "Workspace Federation", "Asset Bundling". Never restate a path or a directory name, and never name it after the language or the file type.
- If the files in a cluster serve two or more unrelated responsibilities, answer exactly "mixed" for that cluster. A wrong name is worse than no name, because a reviewer will trust it.
- Answer for every cluster key you are given, and invent no other keys.`;
const NAMES_SCHEMA = {
type: "object",
properties: {
names: {
type: "array",
items: {
type: "object",
properties: {
key: { type: "string", description: "the cluster key, copied verbatim" },
name: { type: "string", description: '2-4 word Title Case name, or "mixed"' },
},
required: ["key", "name"],
additionalProperties: false,
},
},
},
required: ["names"],
additionalProperties: false,
} as const;
/** Symbols shown per cluster. Enough to characterise it; not a file listing. */
const SYMBOLS_PER_CLUSTER = 8;
/**
* Clusters per request. A PR's diagram needs six, so one batch covers it — the cap
* is for the cache-priming job, which deliberately walks a wide diff and can hand
* over fifty clusters at once. Past a dozen the prompt stops being a list and the
* model starts dropping keys.
*/
const CLUSTERS_PER_CALL = 12;
function clusterPrompt(clusters: Cluster[]): string {
return clusters
.map((c) => {
const files = c.files.slice(0, 10).join(", ");
const symbols = c.symbols.slice(0, SYMBOLS_PER_CLUSTER).join(", ");
return `key: ${c.key}\n files: ${files}\n symbols: ${symbols || "(none extracted)"}`;
})
.join("\n\n");
}
/** The production namer: one forced-tool call for every cluster at once. */
export class ChatNamer implements Namer {
constructor(private readonly model: ChatModel) {}
async name(clusters: Cluster[]): Promise<Map<string, string>> {
const res = await this.model.create({
messages: [
{ role: "system", content: SYSTEM_PROMPT },
{ role: "user", content: clusterPrompt(clusters) },
],
tools: [{ name: "record_names", description: "Record one name per cluster.", parameters: NAMES_SCHEMA as unknown as Record<string, unknown> }],
responseFormat: { kind: "tool", name: "record_names" },
temperature: 0,
maxTokens: 1024,
});
const out = new Map<string, string>();
const call = res.toolCalls[0]?.args as { names?: { key?: string; name?: string }[] } | undefined;
for (const row of call?.names ?? []) {
if (!row?.key || !row?.name) continue;
const clean = sanitize(row.name);
// "mixed" is an answer, not a name: the cluster keeps its backstop.
if (!clean || /^mixed$/i.test(clean)) continue;
out.set(row.key, clean);
}
return out;
}
}
/**
* A model-written string on its way into a Mermaid label and a markdown table.
*
* Symbol names from a fork's diff reach the prompt, so the answer is untrusted
* input: anything that could close a label, open a tag or start a table cell is
* stripped here rather than at each render site.
*/
export function sanitize(raw: string): string {
const flat = raw.replace(/[\r\n]+/g, " ").replace(/[<>"'`|(){}[\]#]/g, "").replace(/\s+/g, " ").trim();
return shortLabel(flat);
}
/**
* The cache key for a cluster: what it contains, not what it is called.
*
* Member paths pin the shape and each member's `body_hash` pins the content, so a
* cluster is renamed only when the code in it actually changes. Without this the
* same area gets a slightly different name on every PR and two comments stop being
* comparable — the failure the cache exists to prevent.
*/
export function clusterHash(files: string[], hashes: Map<string, string>): string {
const parts = [...files].sort().map((f) => `${f}:${hashes.get(f) ?? "?"}`);
return createHash("sha256").update(parts.join("\n")).digest("hex").slice(0, 16);
}
function cachePath(contextDir: string): string {
return join(contextDir, CACHE_DIR, "areas.json");
}
export function loadNameCache(contextDir: string): Record<string, string> {
try {
const raw = JSON.parse(readFileSync(cachePath(contextDir), "utf8")) as unknown;
return raw && typeof raw === "object" ? (raw as Record<string, string>) : {};
} catch {
// A missing or corrupt cache is a cache miss, never an error: the names are
// derivable again, and refusing to run because a cache file is bad is worse.
return {};
}
}
export function saveNameCache(contextDir: string, names: Record<string, string>): void {
const path = cachePath(contextDir);
try {
mkdirSync(dirname(path), { recursive: true });
writeFileSync(path, `${JSON.stringify(names, null, 2)}\n`);
} catch {
// Best-effort: an unwritable cache costs a call next time, nothing more.
}
}
/** File-node content hashes, which is what a cluster's identity is built from. */
function fileHashes(graph: GraphV1): Map<string, string> {
const out = new Map<string, string>();
for (const n of graph.nodes) if (n.kind === "file") out.set(n.path, n.body_hash ?? "");
return out;
}
type Labelled = ImpactedModule | ChangedArea;
function symbolsOf(c: Labelled): string[] {
return "symbols" in c ? c.symbols.map((s) => s.name) : c.seedNames;
}
/**
* Fill in labels for every cluster still sitting on its symbol backstop.
*
* Clusters already named by a concept node are left alone: a concept was written
* from whole file bodies, which is strictly more than the paths and symbol names
* this pass can see.
*/
export async function applyNames(
graph: GraphV1,
report: BlastReport,
opts: { namer?: Namer; contextDir: string },
): Promise<NameStats> {
const stats: NameStats = { cached: 0, named: 0, declined: 0 };
// `testModules` are deliberately absent: the comment shows them as a file count in
// one collapsed line and nowhere else, so naming them buys nothing and can push a
// normal PR over CLUSTERS_PER_CALL into a second request.
const targets: Labelled[] = [...report.modules, ...report.areas]
.filter((c) => c.labelSource === "symbol");
if (targets.length === 0) return stats;
const hashes = fileHashes(graph);
const cache = loadNameCache(opts.contextDir);
const pending: { cluster: Cluster; targets: Labelled[] }[] = [];
/** Clusters sharing a hash share a name — and one call, not several. */
const byHash = new Map<string, Labelled[]>();
for (const t of targets) {
const hash = clusterHash(t.files, hashes);
byHash.set(hash, [...(byHash.get(hash) ?? []), t]);
}
for (const [hash, group] of byHash) {
const hit = cache[hash];
if (hit) {
for (const t of group) { t.label = hit; t.labelSource = "named"; }
stats.cached++;
continue;
}
pending.push({
cluster: { key: hash, files: group[0].files, symbols: symbolsOf(group[0]) },
targets: group,
});
}
if (pending.length === 0 || !opts.namer) return stats;
const named = new Map<string, string>();
for (let i = 0; i < pending.length; i += CLUSTERS_PER_CALL) {
const batch = pending.slice(i, i + CLUSTERS_PER_CALL);
try {
for (const [k, v] of await opts.namer.name(batch.map((p) => p.cluster))) named.set(k, v);
} catch (err) {
// Every label already holds its backstop, so there is nothing to undo — and a
// later batch failing must not discard the names an earlier one returned.
stats.error = err instanceof Error ? err.message : String(err);
break;
}
}
for (const p of pending) {
const name = named.get(p.cluster.key);
if (!name) { stats.declined++; continue; }
for (const t of p.targets) { t.label = name; t.labelSource = "named"; }
cache[p.cluster.key] = name;
stats.named++;
}
if (stats.named > 0) saveNameCache(opts.contextDir, cache);
return stats;
}
/**
* Name the clusters left on their symbol backstop, and say what it cost.
*
* Everything here is best-effort by construction: no key, a spent quota or a
* refused call leaves the backstop labels in place, because neither a PR check
* nor a review comment should fail over a cosmetic layer. The note comes back
* rather than going to a stream, so `graft blast --name` can prefix it and the
* App can log it against the pull request it belongs to.
*/
export async function nameReport(
graph: GraphV1,
report: BlastReport,
contextDir: string,
): Promise<{ stats: NameStats; note: string | null }> {
const { resolveConfig } = await import("../ai/providers.js");
const cfg = resolveConfig({ contextDir });
let namer: Namer | undefined;
if (cfg.chatModel) {
namer = new ChatNamer(cfg.chatModel);
} else if (cfg.apiKey) {
const { createChatModel } = await import("../ai/llm/factory.js");
namer = new ChatNamer(createChatModel({
provider: cfg.provider, apiKey: cfg.apiKey, model: cfg.model,
baseUrl: cfg.baseUrl, headers: cfg.headers,
}));
}
const stats = await applyNames(graph, report, { namer, contextDir });
if (!namer) return { stats, note: "no API key (GRAFT_API_KEY), so areas keep their symbol names" };
if (stats.error) return { stats, note: `naming failed (${stats.error}) — areas keep their symbol names` };
if (stats.named + stats.cached + stats.declined > 0) {
const bits = [`${stats.named} named`, `${stats.cached} cached`];
if (stats.declined > 0) bits.push(`${stats.declined} left as symbols (mixed)`);
return { stats, note: bits.join(", ") };
}
return { stats, note: null };
}