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
/**
* Data layer: fetches both graphs from the graft viz server and carries the
* edge semantics (verb → family → form) defined in the design spec.
*/
export interface VizNode {
id: string;
name: string;
type: string;
summary: string;
sources: string[];
evidence?: Evidence[];
owners?: NodeOwner[];
}
/** A contributor on a node — see `NodeOwner` in src/viz/assemble.ts. */
export interface NodeOwner {
name: string;
handle?: string;
commits: number;
/** `YYYY-MM-DD`; the viewer turns it into "9d ago" when it renders. */
last: string;
}
export interface VizEdge {
source: string;
target: string;
relation: string;
description?: string;
confidence?: "extracted" | "inferred";
}
export interface EvidenceLine {
n: number | null;
sign: "+" | "-" | " ";
text: string;
}
/** A code snippet shown under a node — see `Evidence` in src/viz/assemble.ts. */
export interface Evidence {
label: string;
note?: string;
lines: EvidenceLine[];
more?: number;
}
export interface VizGraph {
meta: {
repoName?: string; subtitle?: string;
/** Set by `graft viz --export`: the tab whose graph actually has content. */
defaultTab?: "context" | "code";
/** Tabs this page offers. A blast export ships Context alone. */
tabs?: Array<"context" | "code" | "outline">;
nodeCount: number; edgeCount: number; skippedFiles?: number; droppedEdges?: number;
/** Why the graph is empty, when it is — set by `blast --export-viz`. */
emptyNote?: string;
};
nodes: VizNode[];
edges: VizEdge[];
}
/** Every relation verb belongs to one family; form follows family. */
export type Family = "structure" | "dependency" | "contract" | "association";
const FAMILY: Record<string, Family> = {
part_of: "structure", contains: "structure",
uses: "dependency", depends_on: "dependency", calls: "dependency", imports: "dependency",
produces: "dependency", configures: "dependency", validates: "dependency",
extends: "contract", implements: "contract",
references: "association",
};
export function famOf(rel: string): Family {
return FAMILY[rel] ?? "association";
}
/** Force-spring rest length per family: hierarchy pulls tight. */
export const REST: Record<Family, number> = { structure: 85, dependency: 145, contract: 150, association: 185 };
/** Chip grouping: "part of" and "uses" are clear as groups; other verbs stand alone. */
export function chipKey(rel: string): string {
if (famOf(rel) === "structure") return "part of";
if (rel === "calls" || rel === "uses" || rel === "depends_on" || rel === "imports") return "uses";
return rel.replace(/_/g, " ");
}
/** Hover hint: the question the verb answers for someone building or reviewing code. */
export const CHIP_HINT: Record<string, string> = {
"part of": "where does this live? (contains, part of)",
"uses": "what breaks if the target changes? (calls, uses, depends on, imports)",
"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)",
"extends": "what contract must this honor? (inheritance)",
"implements": "what contract must this honor? (interface)",
"references": "mentioned but never called — possible dead coupling",
};
/** Node-type → CSS custom property, per tab. */
// `changed` / `affected` come from `graft blast --export-viz`, where the graph is a
// PR's blast radius rather than the concept map: amber for what the diff touched,
// blue for what depends on it. The legend labels itself from these type names.
const CONTEXT_COLORS: Record<string, string> = {
system: "--sys", concept: "--con", file: "--fil", api: "--api",
changed: "--fil", affected: "--sys",
};
const CODE_COLORS: Record<string, string> = {
file: "--k-file", class: "--k-class", function: "--k-fn", method: "--k-method",
interface: "--k-iface", type: "--k-type", enum: "--k-enum",
};
export function colorToken(tab: "context" | "code", type: string): string {
const m = tab === "code" ? CODE_COLORS : CONTEXT_COLORS;
return m[type] ?? "--edge";
}
export function cvar(name: string): string {
return getComputedStyle(document.documentElement).getPropertyValue(name).trim();
}
/**
* Graphs inlined by `graft viz --export`, when the page was exported rather than
* served. The static file has no server behind it, so a fetch would 404 — but the
* viewer must not care which way it was opened, so this is the only place that
* knows the difference.
*/
interface InlinedData {
contextGraph?: VizGraph;
codeGraph?: unknown;
}
const inlined = (globalThis as { __GRAFT_DATA__?: InlinedData }).__GRAFT_DATA__;
export async function loadContextGraph(): Promise<VizGraph> {
if (inlined?.contextGraph) return inlined.contextGraph;
const res = await fetch("/api/context-graph");
return (await res.json()) as VizGraph;
}
interface CodeGraphV1 {
meta: { version: number; nodeCount: number; edgeCount: number };
nodes: Array<{
id: string; name: string; kind: string; path: string; span: string;
signature: string | null; summary: string | null; crux: { code: string; span: string } | null;
}>;
edges: Array<{ source: string; target: string; relation: string; confidence: "extracted" | "inferred" }>;
}
/** Fetch graph.json and reshape it into the viewer's graph form (null if absent). */
export async function loadCodeGraph(): Promise<VizGraph | null> {
let raw: CodeGraphV1;
if (inlined) {
if (!inlined.codeGraph) return null;
raw = inlined.codeGraph as CodeGraphV1;
} else {
const res = await fetch("/api/code-graph");
if (!res.ok) return null;
raw = (await res.json()) as CodeGraphV1;
}
const nodes: VizNode[] = raw.nodes.map((n) => ({
id: n.id,
name: n.name,
type: n.kind,
summary: n.summary ?? n.signature ?? "",
sources: [`${n.path} · ${n.span}`],
}));
const known = new Set(nodes.map((n) => n.id));
// imports edges may point at unresolved module strings — drop those for rendering
const edges: VizEdge[] = raw.edges
.filter((e) => known.has(e.source) && known.has(e.target))
.map((e) => ({ source: e.source, target: e.target, relation: e.relation, confidence: e.confidence }));
return { meta: { nodeCount: nodes.length, edgeCount: edges.length }, nodes, edges };
}
/** Subscribe to the server's live-reload channel, when there is a server at all. */
export function onServerChange(handler: () => void): void {
// An exported page has no /events endpoint, and EventSource retries a failed
// connection forever — a console error every few seconds on a static file.
if (inlined) return;
const source = new EventSource("/events");
source.onmessage = (ev) => {
if (ev.data === "change") handler();
};
}