Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
/**
* Woher die Galaxie ihre Punkte bekommt.
*
* `/api/layout` ist die einzige Route, die ein fertiges 3D-Layout liefert: die
* Koordinaten, die Groessen und die Farben rechnet der C-Server (layout3d.c),
* nicht der Browser. Es gibt hier also keine Kraeftesimulation und keinen
* zweiten Layout-Begriff, und das ist der Grund, warum die uebernommene Szene
* ueberhaupt so klein sein kann.
*
* Das Vorbild (graph-ui/src/hooks/useGraphData.ts) liest den Rumpf stueckweise
* mit, um einen Fortschritt anzuzeigen. Das ist hier weggelassen: der Deckel
* liegt bei 5000 Knoten, das sind wenige hundert Kilobyte, und ein
* Fortschrittsbalken, der immer sofort voll ist, ist eine Anzeige, die nichts
* anzeigt.
*
* Was NICHT weggelassen ist: der Fehlerfall. Eine Galaxie, die bei einem 500er
* einfach leer bleibt, behauptet, das Projekt habe keine Knoten. Also traegt
* jeder Fehlweg hier seinen Text, und das Panel zeigt ihn.
*/
import { layoutUrl, LAYOUT_NODE_BUDGET, LAYOUT_ROUTE } from './galaxy-model';
import { nodeFilePath } from './node-names';
import type { GraphData, GraphEdge, GraphNode, MissedGraph, NodeStatus } from './types';
export interface LayoutSourceOptions {
/** Ursprung des Servers, ohne Schraegstrich am Ende. Leer heisst same-origin. */
base?: string;
/** Ersetzbares fetch, damit Tests ohne Netz laufen. */
fetch?: typeof globalThis.fetch;
/** Knotendeckel der Anfrage. */
maxNodes?: number;
/** Abbruchsignal. */
signal?: AbortSignal;
}
/** Ein Fehler der Layout-Route, mit dem Status, den sie geliefert hat. */
export class LayoutError extends Error {
constructor(readonly status: number, message: string) {
super(message);
this.name = 'LayoutError';
}
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value);
}
function num(value: unknown): number | undefined {
if (typeof value === 'number' && Number.isFinite(value)) {
return value;
}
if (typeof value === 'string' && value.trim().length > 0) {
const parsed = Number(value);
return Number.isFinite(parsed) ? parsed : undefined;
}
return undefined;
}
function text(value: unknown): string | undefined {
return typeof value === 'string' && value.length > 0 ? value : undefined;
}
/**
* Die Antwort der Route als Szenendaten.
*
* Streng gegenueber dem, was die Szene zum Zeichnen braucht (Identitaet, Ort,
* Groesse, Farbe): fehlt eines davon, faellt der Knoten weg, denn ein Knoten
* ohne Ort waere ein Punkt im Ursprung, den niemand dort erwartet. Nachsichtig
* gegenueber allem anderen: eine fehlende Datei, ein fehlender qualifizierter
* Name und eine fehlende Zeile bleiben leer statt erfunden.
*
* Kanten auf Knoten, die nicht in der Antwort stehen, bleiben drin: die Szene
* laesst sie beim Zeichnen selbst fallen (EdgeLines), und sie hier zu filtern
* waere dieselbe Regel an zwei Stellen.
*/
export function readGraphData(value: unknown): GraphData {
const raw = isRecord(value) ? value : {};
const nodes: GraphNode[] = [];
for (const entry of Array.isArray(raw['nodes']) ? raw['nodes'] : []) {
if (!isRecord(entry)) {
continue;
}
const id = num(entry['id']);
const x = num(entry['x']);
const y = num(entry['y']);
const z = num(entry['z']);
const size = num(entry['size']);
const color = text(entry['color']);
const name = text(entry['name']);
if (id === undefined || x === undefined || y === undefined || z === undefined) {
continue;
}
const label = text(entry['label']) ?? '';
const qualifiedName = text(entry['qualified_name']);
nodes.push({
id,
x,
y,
z,
label,
name: name ?? String(id),
// Der Branch-Knoten traegt im Layout die Datei "{}"; das ist keine Datei (Runde 4, N1).
file_path: nodeFilePath({ name: name ?? String(id), label, qualified_name: qualifiedName, file_path: text(entry['file_path']) }),
qualified_name: qualifiedName,
start_line: num(entry['start_line']),
end_line: num(entry['end_line']),
size: size !== undefined && size > 0 ? size : 1,
color: color ?? '#8899aa',
status: text(entry['status']) as NodeStatus | undefined,
in_calls: num(entry['in_calls']),
out_calls: num(entry['out_calls']),
});
}
const edges: GraphEdge[] = [];
for (const entry of Array.isArray(raw['edges']) ? raw['edges'] : []) {
if (!isRecord(entry)) {
continue;
}
const source = num(entry['source']);
const target = num(entry['target']);
if (source === undefined || target === undefined) {
continue;
}
edges.push({ source, target, type: text(entry['type']) ?? '' });
}
let missedGraph: MissedGraph | undefined;
const missed = raw['missed_graph'];
if (isRecord(missed) && isRecord(missed['offset'])) {
const x = num(missed['offset']['x']);
const y = num(missed['offset']['y']);
const z = num(missed['offset']['z']);
if (x !== undefined && y !== undefined && z !== undefined) {
// Pass only these arrays, so a nested missed_graph cannot recurse.
const skeleton = readGraphData({ nodes: missed['nodes'], edges: missed['edges'] });
missedGraph = { nodes: skeleton.nodes, edges: skeleton.edges, offset: { x, y, z } };
}
}
return { nodes, edges, total_nodes: num(raw['total_nodes']) ?? nodes.length, ...(missedGraph ? { missed_graph: missedGraph } : {}) };
}
/**
* Das Layout eines Projekts holen.
*
* Wirft einen `LayoutError` mit Status 0, wenn niemand geantwortet hat, und
* mit dem HTTP-Status, wenn der Server nein gesagt hat. Beide Texte nennen die
* Route, weil ein Fehler ohne Adresse den Leser raten laesst, welche der zwei
* Flaechen dieses Servers gerade schweigt.
*/
export async function loadLayout(
project: string,
options: LayoutSourceOptions = {},
): Promise<GraphData> {
const route = layoutUrl(project, options.maxNodes ?? LAYOUT_NODE_BUDGET);
const url = `${options.base ?? ''}${route}`;
const doFetch = options.fetch ?? globalThis.fetch;
let response: Response;
try {
response = await doFetch(url, {
headers: { Accept: 'application/json' },
...(options.signal !== undefined ? { signal: options.signal } : {}),
});
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
throw new LayoutError(0, `${LAYOUT_ROUTE} war nicht erreichbar: ${message}`);
}
const body = await response.text();
if (!response.ok) {
throw new LayoutError(
response.status,
`${LAYOUT_ROUTE} antwortete mit HTTP ${response.status}: ${body.slice(0, 200)}`,
);
}
let parsed: unknown;
try {
parsed = JSON.parse(body) as unknown;
} catch {
throw new LayoutError(response.status, `${LAYOUT_ROUTE} lieferte kein JSON: ${body.slice(0, 200)}`);
}
return readGraphData(parsed);
}