Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
/**
* A drawn levels view plus its positions, as React Flow nodes and edges.
* Joins what each card shows (service record, repo health, role, lens marks,
* group health and source) onto the drawn ids. Cards with no position yet
* (new to the view while its layout runs) are left out, with their children
* and lines, so nothing flashes at the origin. Pure, no React rendering.
*/
import { MarkerType, type Edge, type Node } from "@xyflow/react";
import type { NodeArchitectureRole, SystemEdge, SystemNode } from "@repowise-dev/types";
import type { C4LayoutPosition } from "../../c4/layout/elk-c4-layout";
import { bandSentence, groupSourceLabel, healthCounts, kindMixText, type HealthCounts } from "./aggregate-facts";
import { roleStyle } from "./architecture";
import { edgeLabel } from "./edge-kinds";
import { focusColumnLabels, type ColumnLabelData } from "./focus-labels";
import type {
DrawnBand,
DrawnGroupNode,
DrawnMoreNode,
DrawnNode,
DrawnServiceNode,
DrawnSingleEdge,
DrawnTrayNode,
} from "./level-types";
import type { LevelView } from "./levels";
import {
resolveEdgeOverlay,
resolveNodeOverlay,
type NodeOverlayState,
type RepoHealth,
type SystemMapEdgeData,
type SystemMapNodeData,
type SystemMapOverlay,
} from "./types";
export interface GroupNodeData {
group: DrawnGroupNode;
sourceLabel: string | null;
health: HealthCounts;
/** Lens marks folded up from the members: highlighted when any is, dimmed when all are. */
overlay: NodeOverlayState | null;
[key: string]: unknown;
}
export interface TrayNodeData {
tray: DrawnTrayNode;
/** Names of the first services, for the closed card. */
names: string[];
[key: string]: unknown;
}
export interface MoreNodeData {
more: DrawnMoreNode;
/** In a focus column: connectors join its sides. */
horizontal?: boolean;
[key: string]: unknown;
}
export interface BandEdgeData {
band: DrawnBand;
sentence: string;
overlay: { highlighted: boolean; dimmed: boolean } | null;
[key: string]: unknown;
}
export interface FlowInputs {
view: LevelView;
positions: ReadonlyMap<string, C4LayoutPosition> | null;
nodesById: ReadonlyMap<string, SystemNode>;
edgesById: ReadonlyMap<string, SystemEdge>;
healthByRepo?: ReadonlyMap<string, RepoHealth> | undefined;
overlay?: SystemMapOverlay | undefined;
roleByNodeId?: ReadonlyMap<string, NodeArchitectureRole> | undefined;
/** Drawn id to mark selected. */
selectedId?: string | null | undefined;
}
export interface FlowElements {
nodes: Node[];
edges: Edge[];
}
/** Names on the tray's closed card before "+N more". */
const TRAY_NAMES = 3;
const ARROW = { type: MarkerType.ArrowClosed, width: 14, height: 14, color: "var(--color-diagram-edge)" } as const;
/** Bands are wide; an arrow in user units keeps one head size whatever the band's width. */
const BAND_ARROW = { ...ARROW, width: 16, height: 16, markerUnits: "userSpaceOnUse" } as const;
/** Members' lens marks on their group card, so a lens still reads at the estate. */
function groupOverlay(overlay: SystemMapOverlay | undefined, ids: readonly string[]): NodeOverlayState | null {
if (!overlay) return null;
const marks = ids.map((id) => resolveNodeOverlay(overlay, id));
const highlighted = marks.some((m) => m?.highlighted);
const dimmed = marks.length > 0 && marks.every((m) => m?.dimmed);
return highlighted || dimmed ? { highlighted, dimmed } : null;
}
function bandOverlay(overlay: SystemMapOverlay | undefined, edgeIds: readonly string[]): BandEdgeData["overlay"] {
if (!overlay) return null;
const marks = edgeIds.map((id) => resolveEdgeOverlay(overlay, id));
const highlighted = marks.some((m) => m?.highlighted);
const dimmed = marks.length > 0 && marks.every((m) => m?.dimmed);
return highlighted || dimmed ? { highlighted, dimmed } : null;
}
/** A drawn id's display name: a service's name, a group's label, or the aggregate's own words. */
export function drawnLabel(n: DrawnNode | undefined, nodesById: ReadonlyMap<string, SystemNode>): string {
if (!n) return "";
if (n.type === "service") return nodesById.get(n.serviceId)?.name ?? n.serviceId;
if (n.type === "group") return n.label;
if (n.type === "tray") return "Not linked at runtime";
return `${n.serviceIds.length} more`;
}
type Shaped = { type: string; data: Record<string, unknown> } | null;
/** A focus-column card's links to its neighbour column: "8 · HTTP 2, Event 6", plus "both ways". */
function focusLinksText(n: DrawnServiceNode): string | null {
if (!n.links) return null;
const mix = kindMixText(n.links.kinds);
const head = mix ? `${n.links.links.toLocaleString()} · ${mix}` : n.links.links.toLocaleString();
return n.bothWays ? `${head} · both ways` : head;
}
function serviceData(n: DrawnServiceNode, { view, nodesById, healthByRepo, overlay, roleByNodeId }: FlowInputs): Shaped {
const node = nodesById.get(n.serviceId);
if (!node) return null;
const role = roleByNodeId?.get(n.serviceId);
const pair = view.between;
const data: SystemMapNodeData = {
node,
health: healthByRepo?.get(node.repo) ?? null,
overlay: resolveNodeOverlay(overlay, n.serviceId),
role: role ? roleStyle(role.role).label : null,
// Focus columns read left to right, so their connectors join card sides.
horizontal: view.level === "focus",
focusLinks: focusLinksText(n),
endpoint: pair !== null && (n.serviceId === pair.a || n.serviceId === pair.b),
};
return { type: "systemService", data };
}
/** A service's repo health on the canonical 0-10 scale (repo health arrives 0-100); null when unscored. */
function score10(id: string, { nodesById, healthByRepo }: FlowInputs): number | null {
const repo = nodesById.get(id)?.repo;
const h = repo ? healthByRepo?.get(repo) : undefined;
return h ? h.score / 10 : null;
}
function groupData(n: DrawnGroupNode, inputs: FlowInputs): Shaped {
const data: GroupNodeData = {
group: n,
sourceLabel: groupSourceLabel(n.groupId, n.source, n.serviceIds.length),
health: healthCounts(n.serviceIds.map((id) => score10(id, inputs))),
overlay: groupOverlay(inputs.overlay, n.serviceIds),
};
return { type: "systemGroup", data };
}
function trayData(n: DrawnTrayNode, { nodesById }: FlowInputs): Shaped {
const names = n.serviceIds.slice(0, TRAY_NAMES).map((id) => nodesById.get(id)?.name ?? id);
const data: TrayNodeData = { tray: n, names };
return { type: "systemTray", data };
}
function moreData(n: DrawnMoreNode, { view }: FlowInputs): Shaped {
const data: MoreNodeData = { more: n, horizontal: view.level === "focus" };
return { type: "systemMore", data };
}
function nodeData(n: DrawnNode, inputs: FlowInputs): Shaped {
switch (n.type) {
case "service":
return serviceData(n, inputs);
case "group":
return groupData(n, inputs);
case "tray":
return trayData(n, inputs);
default:
return moreData(n, inputs);
}
}
function parentOf(n: DrawnNode): string | null {
return n.type === "service" || n.type === "more" ? n.parentId : null;
}
function isOpenContainer(n: DrawnNode): boolean {
return (n.type === "group" || n.type === "tray") && n.open;
}
/** One React Flow node, or null when it has no position yet or its container is not drawn. */
function flowNode(n: DrawnNode, inputs: FlowInputs, placed: ReadonlySet<string>): Node | null {
const pos = inputs.positions?.get(n.id);
const parentId = parentOf(n);
if (!pos || (parentId && !placed.has(parentId))) return null;
const shaped = nodeData(n, inputs);
if (!shaped) return null;
return {
id: n.id,
type: shaped.type,
position: { x: pos.x, y: pos.y },
data: shaped.data,
...(parentId ? { parentId } : {}),
// An open container sits under its cards and lines.
...(isOpenContainer(n) ? { width: pos.width, height: pos.height, zIndex: -1 } : {}),
...(inputs.selectedId === n.id ? { selected: true } : {}),
ariaLabel: drawnLabel(n, inputs.nodesById),
};
}
function singleEdge(e: DrawnSingleEdge, inputs: FlowInputs, name: (id: string) => string): Edge | null {
const edge = inputs.edgesById.get(e.edgeId);
if (!edge) return null;
const data: SystemMapEdgeData = { edge, overlay: resolveEdgeOverlay(inputs.overlay, edge.id) };
return {
id: e.id,
source: e.source,
target: e.target,
type: "systemEdge",
markerEnd: ARROW,
data,
ariaLabel: `${name(e.source)} to ${name(e.target)}, ${edgeLabel(edge)}`,
};
}
function bandEdge(e: DrawnBand, inputs: FlowInputs, name: (id: string) => string): Edge {
const sentence = bandSentence(name(e.source), name(e.target), e.summary);
const data: BandEdgeData = { band: e, sentence, overlay: bandOverlay(inputs.overlay, e.summary.edgeIds) };
return { id: e.id, source: e.source, target: e.target, type: "systemBand", markerEnd: BAND_ARROW, data, ariaLabel: sentence };
}
export function toFlowElements(inputs: FlowInputs): FlowElements {
const { view, positions, nodesById, selectedId } = inputs;
if (!positions) return { nodes: [], edges: [] };
const placed = new Set<string>();
const nodes: Node[] = [];
for (const n of view.nodes) {
const flow = flowNode(n, inputs, placed);
if (!flow) continue;
placed.add(n.id);
nodes.push(flow);
}
const drawnById = new Map(view.nodes.map((n) => [n.id, n]));
const name = (id: string) => drawnLabel(drawnById.get(id), nodesById);
const edges: Edge[] = [];
for (const e of view.edges) {
if (!placed.has(e.source) || !placed.has(e.target)) continue;
const flow = e.type === "edge" ? singleEdge(e, inputs, name) : bandEdge(e, inputs, name);
if (flow) edges.push(selectedId === e.id ? { ...flow, selected: true } : flow);
}
if (view.focus) nodes.push(...columnLabelNodes(view, positions));
return { nodes, edges };
}
/** The focus level's column headings, as inert nodes above each column. */
function columnLabelNodes(view: LevelView, positions: ReadonlyMap<string, C4LayoutPosition>): Node[] {
return focusColumnLabels(view.focus!, positions).map((l): Node => {
const data: ColumnLabelData = { label: l.label };
return {
id: l.id,
type: "systemColumnLabel",
position: { x: l.x, y: l.y },
data,
selectable: false,
focusable: false,
draggable: false,
};
});
}