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
/**
* Recursive clip-and-scale draw of the containment tree. Browser code.
*
* Each node resolves to a screen rect from its absolute world rect and the
* camera. We draw the node's card (fading out as `t` grows), then clip to its
* rect and recurse into the top-N children (fading in), so a card *visibly
* opens into its parts* as you zoom. Off-screen subtrees, sub-pixel nodes and
* fully-faded subtrees are skipped, and a density cap bounds how many children
* are drawn at any depth, keeping the live node count bounded on huge trees.
*/
import { type Camera, type Rect, type Viewport, worldRectToScreen } from "./camera";
import {
ALPHA_EPSILON,
ARROW_MIN_BOX_PX,
EDGE_FOCUS_ALPHA,
EDGE_MAX_PER_PARENT,
EDGE_MIN_BOX_PX,
GRID_MAJOR_EVERY,
GRID_SPACING_PX,
MAX_CHILDREN_DRAWN,
MIN_DRAW_PX,
} from "./constants";
import { isOnScreen, selectChildren } from "./cull";
import { type EdgeInput, routeEdges } from "./edges";
import { drawCard, drawEdge } from "./nodes";
import type { PaperTexture } from "./paper";
import { childNodes, type ZoomScene } from "./scene";
import type { ZoomPalette } from "./theme";
import type { ZoomNode } from "./types";
import {
expandThresholds,
fadeAlphas,
leafCapScale,
transitionT,
} from "./zoom-transition";
export interface DrawOptions {
selectedId: string | null;
hoveredId: string | null;
lowDetail: boolean;
/** Shared ruled-paper card texture; null until the asset loads (or on SSR). */
paper?: PaperTexture | null;
/**
* Draw only relations whose verb (`ZoomRelation.label`) is in this set, or
* every relation when null. Null rather than "the set of all verbs" so the
* unfiltered case costs no lookup and needs no knowledge of the vocabulary.
*
* This was a single verb while the map was fed file-level edges only, where
* the arrows carried three verbs, 80.5% of them `imports`, and 89% of boxes
* had one verb across every relation — a multi-select would have been inert.
* Projecting the call graph onto file pairs changed that: the vocabulary runs
* to seven verbs on Ocelot, and the share of boxes carrying more than one
* goes 48% -> 67% there and 8% -> 32% on jhipster-sample-app.
*/
relationVerbs?: ReadonlySet<string> | null;
}
/**
* A faint graph-paper line grid under the cards, anchored to the camera so it
* parallaxes on pan (fixed screen spacing) and reads as a designed surface. Every
* `GRID_MAJOR_EVERY`-th line, counted from the world origin so majors stay put on
* pan, is drawn a touch firmer. Cheap: two batched stroke passes.
*/
function drawGrid(
ctx: CanvasRenderingContext2D,
cam: Camera,
vp: Viewport,
palette: ZoomPalette,
): void {
const sp = GRID_SPACING_PX;
const maj = GRID_MAJOR_EVERY;
const baseX = vp.w / 2 - cam.cx * cam.scale; // screen x of world x = 0
const baseY = vp.h / 2 - cam.cy * cam.scale;
const ox = ((baseX % sp) + sp) % sp;
const oy = ((baseY % sp) + sp) % sp;
const startKx = Math.round((ox - baseX) / sp); // world-line index of the first line
const startKy = Math.round((oy - baseY) / sp);
const isMajor = (k: number): boolean => (((k % maj) + maj) % maj) === 0;
const pass = (major: boolean): void => {
ctx.beginPath();
let kx = startKx;
for (let x = ox; x < vp.w; x += sp, kx++) {
if (isMajor(kx) !== major) continue;
const xx = Math.round(x) + 0.5; // crisp 1px line
ctx.moveTo(xx, 0);
ctx.lineTo(xx, vp.h);
}
let ky = startKy;
for (let y = oy; y < vp.h; y += sp, ky++) {
if (isMajor(ky) !== major) continue;
const yy = Math.round(y) + 0.5;
ctx.moveTo(0, yy);
ctx.lineTo(vp.w, yy);
}
ctx.strokeStyle = major ? palette.gridStrong : palette.grid;
ctx.lineWidth = 1;
ctx.stroke();
};
pass(false); // minor lines
pass(true); // major lines on top
}
export interface PickEntry {
id: string;
rect: Rect;
depth: number;
}
export interface DrawStats {
drawn: number;
culled: number;
maxDepthDrawn: number;
/** Drawn cards, deepest last, for hit-testing the most recent frame. */
pick: PickEntry[];
}
/** Shrink a rect about its centre by `scale` (used for the leaf cap). */
function shrinkAboutCentre(rect: Rect, scale: number): Rect {
if (scale >= 1) return rect;
const w = rect.w * scale;
const h = rect.h * scale;
return { x: rect.x + (rect.w - w) / 2, y: rect.y + (rect.h - h) / 2, w, h };
}
export function drawScene(
ctx: CanvasRenderingContext2D,
scene: ZoomScene,
cam: Camera,
vp: Viewport,
palette: ZoomPalette,
opts: DrawOptions,
): DrawStats {
const thresholds = expandThresholds(vp.w);
const stats: DrawStats = { drawn: 0, culled: 0, maxDepthDrawn: 0, pick: [] };
// Resolve the paper pattern once per frame (lazily built against this ctx).
const paper = opts.paper?.get(ctx) ?? null;
ctx.fillStyle = palette.bg;
ctx.fillRect(0, 0, vp.w, vp.h);
drawGrid(ctx, cam, vp, palette);
const root = scene.nodes.get(scene.rootId);
if (!root) return stats;
// The node under the cursor (or selected) lifts its incident relations out of
// the quiet baseline. Hover wins for immediate feedback.
const focusId = opts.hoveredId ?? opts.selectedId;
const drawNode = (node: ZoomNode, inheritedAlpha: number, depth: number): void => {
const worldRect = scene.worldRects.get(node.id);
if (!worldRect) return;
const screen = worldRectToScreen(cam, vp, worldRect);
if (!isOnScreen(screen, vp)) {
stats.culled++;
return;
}
if (screen.w < MIN_DRAW_PX || screen.h < MIN_DRAW_PX) {
stats.culled++;
return;
}
const kids = childNodes(scene, node);
const hasChildren = kids.length > 0;
const t = transitionT(screen.w, thresholds, hasChildren);
const { body, child } = fadeAlphas(inheritedAlpha, t);
// Leaf cap: a file stops growing once it fills enough of the screen.
const cap = leafCapScale(screen.w, thresholds, hasChildren);
const drawnRect = cap < 1 ? shrinkAboutCentre(screen, cap) : screen;
if (body > ALPHA_EPSILON) {
drawCard(ctx, drawnRect, node, palette, body, {
selected: node.id === opts.selectedId,
hovered: node.id === opts.hoveredId,
lowDetail: opts.lowDetail,
}, t, paper);
}
stats.drawn++;
stats.maxDepthDrawn = Math.max(stats.maxDepthDrawn, depth);
stats.pick.push({ id: node.id, rect: drawnRect, depth });
if (!hasChildren || child <= ALPHA_EPSILON) return;
ctx.save();
ctx.beginPath();
ctx.rect(screen.x, screen.y, screen.w, screen.h);
ctx.clip();
// Draw every child (uniform cells fade and grow in together); the cap is a
// safety net for a pathologically flat folder, dropping the least-important
// tail so the frame stays cheap. Each child still self-culls below.
const visible =
kids.length > MAX_CHILDREN_DRAWN ? selectChildren(kids, MAX_CHILDREN_DRAWN) : kids;
// Screen rects of the children big enough to anchor an arrow to. Edges are
// drawn (behind the cards) only between boxes that are actually on screen,
// so an arrow can never point at a culled or density-capped sibling.
const childRects = new Map<string, Rect>();
for (const kid of visible) {
const wr = scene.worldRects.get(kid.id);
if (!wr) continue;
const r = worldRectToScreen(cam, vp, wr);
if (isOnScreen(r, vp) && r.w >= EDGE_MIN_BOX_PX) childRects.set(kid.id, r);
}
drawEdges(
ctx,
scene,
node,
childRects,
palette,
child,
opts.lowDetail,
focusId,
opts.relationVerbs ?? null,
);
for (const kid of visible) drawNode(kid, child, depth + 1);
ctx.restore();
};
drawNode(root, 1, 0);
return stats;
}
/**
* Draw the relations among the children of a parent we are zoomed into, as
* routed directed connectors (see `edges.ts`). Only edges whose BOTH endpoints
* are in `childRects` (currently drawn) are considered; the rest are dropped.
* The set is capped to the strongest `EDGE_MAX_PER_PARENT` by edge count so a
* dense level never sprays the canvas, then routed so edges that share a box
* side fan out and curve around the boxes between their endpoints.
*/
function drawEdges(
ctx: CanvasRenderingContext2D,
scene: ZoomScene,
parent: ZoomNode,
childRects: Map<string, Rect>,
palette: ZoomPalette,
alpha: number,
lowDetail: boolean,
focusId: string | null,
relationVerbs: ReadonlySet<string> | null,
): void {
// Relations are revealed only for the box the user is pointing at / has
// selected, so the canvas is not a thicket of arrows. No focus -> no edges.
if (lowDetail || childRects.size < 2 || focusId === null) return;
const rels = scene.relationsByParent.get(parent.id);
if (!rels) return;
const drawable = rels.filter(
(r) =>
r.source_id !== r.target_id &&
(r.source_id === focusId || r.target_id === focusId) &&
(relationVerbs === null || relationVerbs.has(r.label)) &&
childRects.has(r.source_id) &&
childRects.has(r.target_id),
);
if (drawable.length === 0) return;
drawable.sort((a, b) => b.edge_count - a.edge_count);
const top = drawable.length > EDGE_MAX_PER_PARENT ? drawable.slice(0, EDGE_MAX_PER_PARENT) : drawable;
const inputs: EdgeInput[] = top.map((r) => ({
id: `${r.source_id} ${r.target_id}`,
sourceId: r.source_id,
targetId: r.target_id,
coupling: r.coupling,
edgeCount: r.edge_count,
}));
for (const routed of routeEdges(inputs, childRects)) {
const to = childRects.get(routed.targetId)!;
const withArrow = to.w >= ARROW_MIN_BOX_PX && to.h >= ARROW_MIN_BOX_PX;
drawEdge(ctx, routed.route, routed.coupling, palette, alpha * EDGE_FOCUS_ALPHA, withArrow);
}
}
/** Deepest drawn card containing the screen point, or null. Pure. */
export function pickNode(stats: DrawStats, sx: number, sy: number): string | null {
let best: PickEntry | null = null;
for (const entry of stats.pick) {
const r = entry.rect;
if (sx < r.x || sx > r.x + r.w || sy < r.y || sy > r.y + r.h) continue;
if (!best || entry.depth >= best.depth) best = entry;
}
return best ? best.id : null;
}