@rokkit/graph 1.6.0 → 1.7.0

package/dist/layout/radial.d.ts

@@ -0,0 +1,16 @@
+import type { LayoutFn } from './types.js';
+/**
+ * A map read with a floor.
+ *
+ * Every pass below keys on the same node set, so a miss should not happen — but a node
+ * rendered at NaN coordinates disappears silently, and one rendered at the centre is at least
+ * visible and clickable. One helper rather than a `??` at each of three use sites.
+ */
+export declare function read<T>(map: Map<string, T>, id: string, fallback: T): T;
+/**
+ * A call graph around a circle.
+ *
+ * No clusters: the rings already carry structure, and a group box drawn over a radial
+ * arrangement cuts across every one of them.
+ */
+export declare const radial: LayoutFn;

package/dist/layout/radial.js

@@ -0,0 +1,214 @@
+/* The radial layout: a call graph as a tidy tree, or a dendrogram, around a circle.
+ *
+ * `points` shelf-packs a call graph into group boxes, and at seven services it already reads
+ * as a stack — tiny rects with each label colliding with the row beneath. Packing answers
+ * "how much is there"; a call graph's question is "who calls whom, and how deep does it go",
+ * and that is a SHAPE. Angle separates the subtrees, radius carries the depth.
+ *
+ * Two modes, because they answer different questions:
+ *   - `tree` (default) puts radius = depth, so the rings ARE the call depth.
+ *   - `dendrogram` puts every leaf on the rim, so leaves are compared against each other and
+ *     the internal structure stretches to reach them.
+ *
+ * A call graph is not a tree — see `hierarchy.ts`. The spanning tree decides position; the
+ * edges it could not use are still drawn, marked `back`, because "b also calls this" is
+ * exactly what a reader is looking for.
+ */
+import { childrenIn, hierarchy } from './hierarchy.js';
+import { nodeSizes } from './sizing.js';
+import { warnUnknownOptions } from './options.js';
+/** Gap between rings. Wide enough that a node plus its label clears the ring inside it. */
+const RING = 130;
+/** Arc length reserved per leaf. The outer ring's circumference is derived from this. */
+const LEAF_ARC = 92;
+/**
+ * Margin outside the widest ring.
+ *
+ * Just over half the largest node (sqrt(MAX_AREA * ASPECT) / 2 is ~33px), so a node on the rim
+ * clears the canvas edge with a little air for its label — and no more. Every pixel here is
+ * dead space that the fit-to-container scale then divides the whole diagram by.
+ */
+const PAD = 48;
+/**
+ * A map read with a floor.
+ *
+ * Every pass below keys on the same node set, so a miss should not happen — but a node
+ * rendered at NaN coordinates disappears silently, and one rendered at the centre is at least
+ * visible and clickable. One helper rather than a `??` at each of three use sites.
+ */
+export function read(map, id, fallback) {
+    return map.get(id) ?? fallback;
+}
+/**
+ * One angular slot per leaf, then every parent centred on its children.
+ *
+ * Centring is the "tidy" part: without it a parent sits at a fixed slot and its links cross
+ * the neighbouring subtrees to reach their own children. Computed bottom-up, so a parent sees
+ * children that are already placed.
+ */
+function angles(h, step) {
+    const angle = new Map();
+    h.leaves.forEach((id, i) => angle.set(id, i * step));
+    const place = (id) => {
+        const cached = angle.get(id);
+        if (cached !== undefined)
+            return cached;
+        const kids = childrenIn(h, id);
+        const mean = kids.reduce((sum, kid) => sum + place(kid), 0) / kids.length;
+        angle.set(id, mean);
+        return mean;
+    };
+    for (const root of h.roots)
+        place(root);
+    return angle;
+}
+/**
+ * How far out each node sits.
+ *
+ * `tree` reads radius as depth. `dendrogram` pins leaves to the outermost ring and lifts an
+ * internal node to just inside its deepest descendant, which is what makes leaves comparable.
+ */
+function radii(h, mode, maxDepth) {
+    const radius = new Map();
+    if (mode === 'tree') {
+        for (const [id, depth] of h.depthOf)
+            radius.set(id, depth * RING);
+        return radius;
+    }
+    // Deepest descendant, bottom-up: a leaf is its own, and a parent sits one ring inside its
+    // deepest child so the tree still reads outward.
+    const deepest = (id) => {
+        const kids = childrenIn(h, id);
+        if (kids.length === 0)
+            return maxDepth;
+        return Math.min(...kids.map((kid) => deepest(kid))) - 1;
+    };
+    for (const id of h.depthOf.keys())
+        radius.set(id, Math.max(0, deepest(id)) * RING);
+    return radius;
+}
+/**
+ * The circle the tree has to fit in.
+ *
+ * The rim's circumference has to hold every leaf plus its label, so it follows from the LEAF
+ * COUNT rather than dividing a fixed circle into ever-thinner slices — which is how a radial
+ * layout turns into the same unreadable stack it was meant to replace.
+ */
+function geometry(h) {
+    const leafCount = Math.max(1, h.leaves.length);
+    const maxDepth = Math.max(0, ...h.depthOf.values());
+    const outer = Math.max(RING, (LEAF_ARC * leafCount) / (Math.PI * 2));
+    return {
+        step: (Math.PI * 2) / leafCount,
+        maxDepth,
+        outer,
+        // Rings spaced to reach the rim the leaf count demands, so a wide tree spreads rather
+        // than piling every level on top of the last.
+        spacing: maxDepth > 0 ? outer / maxDepth : 0,
+        extent: outer + PAD
+    };
+}
+/** Centre-out placement, converted to top-left card coordinates. */
+function place(h, sizeOf, mode, model) {
+    const { step, maxDepth, spacing, extent } = geometry(h);
+    const angle = angles(h, step);
+    const radius = radii(h, mode, maxDepth);
+    const cards = {};
+    for (const node of model.nodes) {
+        // Only what the hierarchy materialised. A pruned node has no angle and no radius, and
+        // placing it anyway would stack every dropped node on the centre point.
+        if (!h.depthOf.has(node.id))
+            continue;
+        const size = read(sizeOf, node.id, { w: 1, h: 1 });
+        const r = (read(radius, node.id, 0) / RING) * spacing;
+        const a = read(angle, node.id, 0);
+        cards[node.id] = {
+            node,
+            vis: [],
+            more: node.rows.length,
+            w: size.w,
+            h: size.h,
+            x: extent + Math.cos(a) * r - size.w / 2,
+            y: extent + Math.sin(a) * r - size.h / 2,
+            groupIndex: 0
+        };
+    }
+    return { cards, size: { w: extent * 2, h: extent * 2 } };
+}
+/** Identity half of a routed edge — everything that is not geometry. */
+function identity(edge, i) {
+    return {
+        i,
+        id: edge.id,
+        fromKey: edge.source,
+        toKey: edge.target,
+        kind: edge.kind,
+        relation: edge.relation
+    };
+}
+/**
+ * Centre-to-centre links.
+ *
+ * `s1`/`s2` are derived from which way the link actually points rather than fixed: on a circle
+ * "the right side" is meaningless, and a curve control point pushed the wrong way loops back
+ * through the node it came from.
+ */
+function route(edge, i, cards, extra) {
+    const a = cards[edge.source];
+    const b = cards[edge.target];
+    if (!a || !b)
+        return null;
+    const [ax, ay] = [a.x + a.w / 2, a.y + a.h / 2];
+    const [bx, by] = [b.x + b.w / 2, b.y + b.h / 2];
+    if (a === b) {
+        return {
+            ...identity(edge, i),
+            self: true,
+            x1: a.x + a.w,
+            y1: ay,
+            x2: a.x + a.w,
+            y2: ay + 14,
+            s1: 1,
+            s2: 1
+        };
+    }
+    return {
+        ...identity(edge, i),
+        // Not a broken cycle here but the same idea: a relationship the tree could not express,
+        // still drawn. A theme distinguishes it rather than the reader wondering why one link
+        // ignores the rings.
+        back: extra.has(edge.id) || undefined,
+        self: false,
+        x1: ax,
+        y1: ay,
+        x2: bx,
+        y2: by,
+        s1: bx >= ax ? 1 : -1,
+        s2: bx >= ax ? -1 : 1
+    };
+}
+function routeAll(model, cards, extra) {
+    const routed = [];
+    model.edges.forEach((edge, i) => {
+        const e = route(edge, i, cards, extra);
+        if (e)
+            routed.push(e);
+    });
+    return routed;
+}
+/**
+ * A call graph around a circle.
+ *
+ * No clusters: the rings already carry structure, and a group box drawn over a radial
+ * arrangement cuts across every one of them.
+ */
+export const radial = (model, options) => {
+    warnUnknownOptions(options, 'radial');
+    if (model.nodes.length === 0) {
+        return { clusters: [], cards: {}, edges: [], size: { w: 0, h: 0 } };
+    }
+    const h = hierarchy(model, { focus: options.root, levels: options.levels });
+    const sizeOf = nodeSizes(model, options.sizeBy ?? 'degree', options.sizeScale ?? 'linear');
+    const { cards, size } = place(h, sizeOf, options.radialMode ?? 'tree', model);
+    return { clusters: [], cards, edges: routeAll(model, cards, h.extra), size };
+};

package/dist/layout/rank.d.ts

@@ -0,0 +1,15 @@
+import type { GraphModel } from '../types.js';
+export type Ranking = {
+    /** Node id → column index, 0-based. Every node in the model is present. */
+    ranks: Map<string, number>;
+    /** Ids of the edges reversed to make the graph acyclic. */
+    back: Set<string>;
+};
+/**
+ * Columns for every node, and the edges broken to get them.
+ *
+ * A node constrained by nothing — disconnected, or reached only by a broken edge — ranks 0 and
+ * still gets a box. Dropping it would hide a table from the diagram because of how it happens
+ * to be referenced.
+ */
+export declare function rank(model: GraphModel): Ranking;

package/dist/layout/rank.js

@@ -0,0 +1,105 @@
+/* Which column a node belongs in, and which edges had to be broken to answer that.
+ *
+ * Pure graph work, no geometry — see docs/design/25-flow-layout.md. The rule the whole `flow`
+ * layout rests on: an edge leaves its source's RIGHT and enters its target's LEFT, so a target
+ * must sit in a later column than its source. Rank is that constraint solved.
+ */
+/**
+ * Whether an edge can constrain a column.
+ *
+ * A self-loop spans no columns. An unplaced end is not a node — 59.6% of Sensei's 4.08M edges
+ * have a null target — and treating the raw string as one would invent a column for something
+ * that has no box.
+ */
+function spans(edge, byId) {
+    if (edge.source === edge.target)
+        return false;
+    return byId.has(edge.source) && byId.has(edge.target);
+}
+/**
+ * Edge ids that must be reversed to make the graph acyclic, by DFS.
+ *
+ * An edge back to a node still on the recursion stack closes a cycle, so it is the one to
+ * break. Real schemas have mutual foreign keys; refusing to rank a cyclic graph would take the
+ * whole diagram down for a pair of tables that reference each other.
+ *
+ * Iteration follows `model.nodes` order, which normalisation fixes, so WHICH edge of a cycle
+ * gets broken is stable across runs — determinism `LayoutFn` promises.
+ */
+function findBackEdges(nodes, out) {
+    const back = new Set();
+    const state = new Map();
+    const visit = (id) => {
+        state.set(id, 'open');
+        for (const edge of out.get(id) ?? []) {
+            const next = edge.target;
+            const seen = state.get(next);
+            if (seen === 'open')
+                back.add(edge.id);
+            else if (seen === undefined)
+                visit(next);
+        }
+        state.set(id, 'done');
+    };
+    for (const id of nodes) {
+        if (!state.has(id))
+            visit(id);
+    }
+    return back;
+}
+/**
+ * Longest-path ranking over the acyclic remainder.
+ *
+ * Longest, not shortest: with `a→b→c` and `a→c`, ranking `c` at 1 satisfies `a→c` and leaves
+ * `b→c` pointing leftward. Taking the longest path to each node satisfies every kept edge at
+ * once.
+ *
+ * Memoised depth-first rather than a topological sweep — the graph is already known acyclic
+ * here, so recursion terminates, and the memo makes it linear in edges.
+ */
+function longestPaths(nodes, into) {
+    const ranks = new Map();
+    const depth = (id) => {
+        const cached = ranks.get(id);
+        if (cached !== undefined)
+            return cached;
+        // Set before recursing: the graph is acyclic by construction, and this also stops a
+        // pathological input from recursing forever rather than producing a wrong number.
+        ranks.set(id, 0);
+        let best = 0;
+        for (const edge of into.get(id) ?? []) {
+            best = Math.max(best, depth(edge.source) + 1);
+        }
+        ranks.set(id, best);
+        return best;
+    };
+    for (const id of nodes)
+        depth(id);
+    return ranks;
+}
+/** Group edges by one endpoint, keeping input order. */
+function index(edges, key) {
+    const out = new Map();
+    for (const edge of edges) {
+        const list = out.get(key(edge));
+        if (list)
+            list.push(edge);
+        else
+            out.set(key(edge), [edge]);
+    }
+    return out;
+}
+/**
+ * Columns for every node, and the edges broken to get them.
+ *
+ * A node constrained by nothing — disconnected, or reached only by a broken edge — ranks 0 and
+ * still gets a box. Dropping it would hide a table from the diagram because of how it happens
+ * to be referenced.
+ */
+export function rank(model) {
+    const ids = model.nodes.map((n) => n.id);
+    const usable = model.edges.filter((e) => spans(e, model.byId));
+    const back = findBackEdges(ids, index(usable, (e) => e.source));
+    const forward = usable.filter((e) => !back.has(e.id));
+    return { ranks: longestPaths(ids, index(forward, (e) => e.target)), back };
+}

package/dist/layout/rings.d.ts

@@ -0,0 +1,20 @@
+import type { GraphModel } from '../types.js';
+/** Which side of the focus a ring sits on. */
+export type Side = 'in' | 'out';
+export type Ring = {
+    depth: number;
+    side: Side;
+    ids: string[];
+};
+/**
+ * Rings outward from `focus`, to `depth` hops, on both sides.
+ *
+ * `claimed` is seeded with the focus and grows as rings are built, which is what enforces
+ * nearest-depth-wins across BOTH sides — a node reached leftward at depth 1 is not re-reached
+ * rightward at depth 2.
+ *
+ * `seedSide` lets the caller decide ring 1 by its own rule (the dominant-direction split in
+ * `neighborhood`), and every ring beyond it inherits its ancestor's side: a caller's caller is
+ * further left, a callee's callee further right. That is what makes the columns read outward.
+ */
+export declare function rings(model: GraphModel, focusId: string, depth: number, seedSide: (id: string) => Side): Ring[];

package/dist/layout/rings.js

@@ -0,0 +1,92 @@
+/* Breadth-first rings around a focus node — the shape a depth-N neighbourhood needs.
+ *
+ * Separate from `neighborhood.ts` because it is pure graph traversal with no geometry, and
+ * because the rule that makes it correct is worth stating once: a node is claimed at its
+ * NEAREST depth and never re-placed. Without that, a node reachable both directly and via a
+ * detour gets two cards for one identity, or gets drawn further away than it actually is.
+ */
+/**
+ * The far end of an edge from `id` in one direction, or nothing.
+ *
+ * An unplaced end is not a node and has no card; a self-loop leads back where it started.
+ * Neither can seed a ring.
+ */
+function across(edge, id, side) {
+    if (edge.unplaced || edge.source === edge.target)
+        return undefined;
+    if (side === 'out')
+        return edge.source === id ? edge.target : undefined;
+    return edge.target === id ? edge.source : undefined;
+}
+/** Every node one step from `id` in one direction. */
+function step(edges, id, side) {
+    const out = [];
+    for (const edge of edges) {
+        const far = across(edge, id, side);
+        if (far !== undefined)
+            out.push(far);
+    }
+    return out;
+}
+const toRings = (bucket, depth) => ['in', 'out'].map((side) => ({ depth, side, ids: bucket.get(side) }));
+/**
+ * Rings outward from `focus`, to `depth` hops, on both sides.
+ *
+ * `claimed` is seeded with the focus and grows as rings are built, which is what enforces
+ * nearest-depth-wins across BOTH sides — a node reached leftward at depth 1 is not re-reached
+ * rightward at depth 2.
+ *
+ * `seedSide` lets the caller decide ring 1 by its own rule (the dominant-direction split in
+ * `neighborhood`), and every ring beyond it inherits its ancestor's side: a caller's caller is
+ * further left, a callee's callee further right. That is what makes the columns read outward.
+ */
+export function rings(model, focusId, depth, seedSide) {
+    const claimed = new Set([focusId]);
+    const out = [];
+    let previous = seedRing(model, focusId, claimed, seedSide);
+    out.push(...toRings(previous, 1));
+    for (let d = 2; d <= depth; d++) {
+        previous = nextRing(model, previous, claimed);
+        out.push(...toRings(previous, d));
+    }
+    return out;
+}
+/** An empty bucket per side. */
+function sides() {
+    return new Map([
+        ['in', []],
+        ['out', []]
+    ]);
+}
+/**
+ * Ring 1, sided by the CALLER's rule rather than by a direction walk — that is what lets a
+ * mutual neighbour land on the side its dominant direction earns it (#160).
+ */
+function seedRing(model, focusId, claimed, seedSide) {
+    const first = sides();
+    const reachable = new Set([
+        ...step(model.edges, focusId, 'in'),
+        ...step(model.edges, focusId, 'out')
+    ]);
+    // No `claimed` check: `reachable` is a Set, and `step` drops self-loops, so the
+    // pre-claimed focus cannot appear in it. Ring 1 is claimed here for the rings that follow.
+    for (const id of reachable) {
+        claimed.add(id);
+        first.get(seedSide(id)).push(id);
+    }
+    return first;
+}
+/** One ring further out, each side continuing in its own direction. */
+function nextRing(model, previous, claimed) {
+    const next = sides();
+    for (const side of ['in', 'out']) {
+        const reached = previous.get(side).flatMap((from) => step(model.edges, from, side));
+        for (const id of reached) {
+            if (claimed.has(id))
+                continue;
+            claimed.add(id);
+            next.get(side).push(id);
+        }
+    }
+    return next;
+}

package/dist/layout/sizing.d.ts

@@ -0,0 +1,37 @@
+import type { GraphModel, GraphNode } from '../types.js';
+export type Sized = {
+    w: number;
+    h: number;
+};
+export type Scale = 'linear' | 'log';
+/** Edges touching each node. A self-loop counts once — it is one edge, not two. */
+export declare function degreeOf(model: GraphModel): Map<string, number>;
+/**
+ * Position of `value` in `[min, max]`, 0..1.
+ *
+ * `log` is for a measure spanning orders of magnitude — declaration counts across a real repo
+ * span three or four, and a linear map puts everything below the top few on the floor. `+1`
+ * shifts the domain off zero, which has no logarithm.
+ *
+ * A flat measure — every node equal, so `max === min` — is 0, not a division by zero.
+ */
+export declare function normalise(value: number, min: number, max: number, scale: Scale): number;
+/** Area is LINEAR in the measure, so width grows as its square root — ten reads as ten. */
+export declare function sizeFor(t: number): Sized;
+/**
+ * The number each node is sized by.
+ *
+ * A node with no weight under `sizeBy: 'weight'` floors rather than vanishing or exploding —
+ * "unknown" is a normal state in a partially-indexed graph, and the alternative is a NaN
+ * width that renders as nothing at all.
+ */
+export declare function measureOf(node: GraphNode, degree: Map<string, number>, sizeBy: string): number;
+/**
+ * One size per node, from whichever measure the caller named.
+ *
+ * The domain is anchored at 0 rather than at the smallest value present, matching `points`:
+ * that is what makes a node the same size in both views, which is the point of sharing this
+ * at all. Against the present minimum, the smallest node in every graph would be identical
+ * whether it had one edge or four hundred.
+ */
+export declare function nodeSizes(model: GraphModel, sizeBy: string, scale: Scale): Map<string, Sized>;

package/dist/layout/sizing.js

@@ -0,0 +1,79 @@
+/* How big a node is drawn when the layout has no room for a card.
+ *
+ * Shared by `points` and `radial`: both replace the card with a small rect whose AREA — not
+ * width — tracks a measure, so ten edges reads as ten rather than as a hundred. Extracted from
+ * `points` rather than copied, because two copies of a size curve drift and the drift shows up
+ * as "the same node is bigger in one view than the other".
+ */
+/**
+ * Area bounds, carried over from `points`' disc version (pi*5^2 to pi*26^2) so the ink weight
+ * of a diagram is unchanged by the switch to rects.
+ */
+const MIN_AREA = Math.PI * 5 * 5;
+const MAX_AREA = Math.PI * 26 * 26;
+/** Width:height. 2:1 reads as a "chip"; a square wastes shelf height. */
+const ASPECT = 2;
+/** Edges touching each node. A self-loop counts once — it is one edge, not two. */
+export function degreeOf(model) {
+    const degree = new Map();
+    for (const node of model.nodes)
+        degree.set(node.id, 0);
+    for (const edge of model.edges) {
+        degree.set(edge.source, (degree.get(edge.source) ?? 0) + 1);
+        if (edge.source !== edge.target) {
+            degree.set(edge.target, (degree.get(edge.target) ?? 0) + 1);
+        }
+    }
+    return degree;
+}
+/**
+ * Position of `value` in `[min, max]`, 0..1.
+ *
+ * `log` is for a measure spanning orders of magnitude — declaration counts across a real repo
+ * span three or four, and a linear map puts everything below the top few on the floor. `+1`
+ * shifts the domain off zero, which has no logarithm.
+ *
+ * A flat measure — every node equal, so `max === min` — is 0, not a division by zero.
+ */
+export function normalise(value, min, max, scale) {
+    if (max <= min)
+        return 0;
+    if (scale === 'log') {
+        return Math.log(value - min + 1) / Math.log(max - min + 1);
+    }
+    return (value - min) / (max - min);
+}
+/** Area is LINEAR in the measure, so width grows as its square root — ten reads as ten. */
+export function sizeFor(t) {
+    const area = MIN_AREA + (MAX_AREA - MIN_AREA) * t;
+    return { w: Math.sqrt(area * ASPECT), h: Math.sqrt(area / ASPECT) };
+}
+/**
+ * The number each node is sized by.
+ *
+ * A node with no weight under `sizeBy: 'weight'` floors rather than vanishing or exploding —
+ * "unknown" is a normal state in a partially-indexed graph, and the alternative is a NaN
+ * width that renders as nothing at all.
+ */
+export function measureOf(node, degree, sizeBy) {
+    if (sizeBy === 'degree')
+        return degree.get(node.id) ?? 0;
+    if (sizeBy === 'weight')
+        return node.weight ?? 0;
+    return node.measures?.[sizeBy] ?? 0;
+}
+/**
+ * One size per node, from whichever measure the caller named.
+ *
+ * The domain is anchored at 0 rather than at the smallest value present, matching `points`:
+ * that is what makes a node the same size in both views, which is the point of sharing this
+ * at all. Against the present minimum, the smallest node in every graph would be identical
+ * whether it had one edge or four hundred.
+ */
+export function nodeSizes(model, sizeBy, scale) {
+    const degree = degreeOf(model);
+    const measures = model.nodes.map((n) => measureOf(n, degree, sizeBy));
+    const min = Math.min(0, ...measures);
+    const max = Math.max(0, ...measures);
+    return new Map(model.nodes.map((node, i) => [node.id, sizeFor(normalise(measures[i], min, max, scale))]));
+}

package/dist/layout/squarify.d.ts

@@ -0,0 +1,14 @@
+export type Rect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export type Sized = {
+    value: number;
+};
+export type Placed<T> = {
+    item: T;
+    rect: Rect;
+};
+export declare function squarify<T extends Sized>(items: T[], rect: Rect, minimum?: number): Placed<T>[];