@rokkit/graph 1.6.0 → 1.8.0

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>[];

package/dist/layout/squarify.js

@@ -0,0 +1,114 @@
+/* Squarified treemap — Bruls, Huizing & van Wijk (2000).
+ *
+ * Fills a rectangle with child rectangles whose areas are proportional to their values, laid
+ * out in rows chosen to keep each rectangle as square as possible.
+ *
+ * The naive alternative (slice-and-dice: split the rect by value along one axis, alternating
+ * per level) is far simpler and unusable here — it produces 1px-wide slivers at any real
+ * value spread, and a sliver holds no label. A box you cannot read is a box you cannot
+ * decide to click, which is the whole of drill-down navigation.
+ *
+ * Hand-written rather than taken from `d3-hierarchy`: the algorithm is small and naturally
+ * deterministic, and `@rokkit/graph` has no third-party runtime dependency — a property
+ * `dependencies.spec.js` asserts, so acquiring the first one should buy more than 80 lines.
+ */
+/**
+ * Worst aspect ratio in a row of areas laid along `side`. Lower is squarer.
+ *
+ * No zero guard: a side or total of 0 divides to Infinity in JS, which is exactly the answer —
+ * a row with no room is infinitely bad and the caller closes it. A guard here would be a
+ * statement no input can reach.
+ */
+function worst(areas, side, total) {
+    const max = Math.max(...areas);
+    const min = Math.min(...areas);
+    const s2 = side * side;
+    const t2 = total * total;
+    return Math.max((s2 * max) / t2, t2 / (s2 * min));
+}
+/** Lay one finished row along the short side of `rect`, and return what remains. */
+function placeRow(row, rect, out) {
+    const total = row.reduce((sum, r) => sum + r.area, 0);
+    const vertical = rect.w >= rect.h;
+    // Thickness of the band this row occupies, derived from its total area so the row exactly
+    // consumes the share of the rectangle its values earned.
+    const thickness = total / (vertical ? rect.h : rect.w);
+    let offset = vertical ? rect.y : rect.x;
+    for (const entry of row) {
+        const length = entry.area / thickness;
+        out.push({
+            item: entry.item,
+            rect: vertical
+                ? { x: rect.x, y: offset, w: thickness, h: length }
+                : { x: offset, y: rect.y, w: length, h: thickness }
+        });
+        offset += length;
+    }
+    return vertical
+        ? { x: rect.x + thickness, y: rect.y, w: rect.w - thickness, h: rect.h }
+        : { x: rect.x, y: rect.y + thickness, w: rect.w, h: rect.h - thickness };
+}
+/**
+ * Place `items` inside `rect`, area proportional to `value`.
+ *
+ * Largest first: the greedy row-closing rule only produces near-square boxes if the big ones
+ * are placed while there is room to choose. Ties break on the caller's order, which is already
+ * sorted, so the result is deterministic.
+ *
+ * A zero or negative value gets the same floor as a tiny one — "unknown" is a normal state in
+ * a partially-indexed graph, and a zero-area box is indistinguishable from a missing one.
+ */
+/**
+ * Does adding `area` make this row's worst aspect ratio worse?
+ *
+ * That comparison IS the algorithm — it trades row length against squareness, and closing the
+ * row at the moment the answer turns yes is what keeps boxes near-square instead of slivers.
+ */
+function shouldClose(areas, area, side) {
+    if (areas.length === 0)
+        return false;
+    const total = areas.reduce((sum, a) => sum + a, 0);
+    return worst([...areas, area], side, total + area) > worst(areas, side, total);
+}
+export function squarify(items, rect, minimum = 0) {
+    if (items.length === 0 || rect.w <= 0 || rect.h <= 0)
+        return [];
+    const ordered = [...items].sort((a, b) => b.value - a.value);
+    const floor = Math.max(minimum, 0);
+    const values = ordered.map((item) => Math.max(item.value, floor));
+    const total = values.reduce((sum, v) => sum + v, 0);
+    if (total <= 0)
+        return evenly(ordered, rect);
+    // Values are scaled into pixels ONCE, so every row shares one area currency.
+    const scale = (rect.w * rect.h) / total;
+    const out = [];
+    let remaining = rect;
+    let row = [];
+    ordered.forEach((item, i) => {
+        const area = values[i] * scale;
+        if (shouldClose(row.map((r) => r.area), area, Math.min(remaining.w, remaining.h))) {
+            remaining = placeRow(row, remaining, out);
+            row = [];
+        }
+        row.push({ item, area });
+    });
+    // `row` always holds at least the final item, so no guard: the loop pushes before it ends.
+    placeRow(row, remaining, out);
+    return out;
+}
+/** Equal shares, for when every value is zero and proportion means nothing. */
+function evenly(items, rect) {
+    const columns = Math.ceil(Math.sqrt(items.length));
+    const rows = Math.ceil(items.length / columns);
+    const w = rect.w / columns;
+    const h = rect.h / rows;
+    return items.map((item, i) => ({
+        item,
+        rect: {
+            x: rect.x + (i % columns) * w,
+            y: rect.y + Math.floor(i / columns) * h,
+            w,
+            h
+        }
+    }));
+}

package/dist/layout/structure.d.ts

@@ -0,0 +1,9 @@
+import type { LayoutFn } from './types.js';
+/**
+ * A codebase as a radial dendrogram, with its calls bundled through the structure.
+ *
+ * `levels` caps how many ancestor bands are drawn; `focusPath` scopes the whole canvas to a
+ * subtree, which is drilling. Both mean exactly what they mean in `world` and `sunburst`, so
+ * switching between the three views keeps your place.
+ */
+export declare const structure: LayoutFn;