@knowvah/dot-engine 0.1.0

package/src/label/node.ts

@@ -0,0 +1,278 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * R-tree node types and node-level operations.
+ * @see label/node.h
+ * @see label/node.c
+ * @see label/index.h
+ */
+
+import { type Rect, initRect, combineRect, rectArea, nullRect } from './rectangle.js';
+
+// C node.c uses uint64_t for bestIncr, bestArea, increase — subtraction wraps.
+const _U64_MOD = 2n ** 64n;
+/** Simulate C uint64_t subtraction (wraps mod 2^64). */
+function u64sub(a: number, b: number): bigint {
+  const r = BigInt(a) - BigInt(b);
+  return r < 0n ? r + _U64_MOD : r;
+}
+
+/** @see label/index.h:NODECARD */
+export const NODECARD = 64;
+
+/**
+ * METHODS constant — number of partition methods.
+ * Only method 0 (quadratic) is used.
+ * @see label/split.q.h:METHODS
+ */
+const METHODS = 1;
+
+/**
+ * A single branch in an R-tree node: a bounding rectangle and a child pointer.
+ * @see label/node.h:Branch_t
+ */
+export interface Branch {
+  rect: Rect;
+  /** null means this slot is empty; pointer to child Node otherwise */
+  child: Node | null;
+}
+
+/**
+ * An R-tree node: up to NODECARD branches.
+ * level 0 = leaf, positive = internal.
+ * @see label/node.h:Node_t
+ */
+export interface Node {
+  count: number;
+  /** 0 is leaf, others positive */
+  level: number;
+  branch: Branch[];   // length == NODECARD
+}
+
+/**
+ * Per-split partition bookkeeping.
+ * @see label/split.q.h:PartitionVars
+ */
+export interface PartitionVars {
+  partition: number[];   // length NODECARD+1
+  taken: boolean[];      // length NODECARD+1
+  count: [number, number];
+  cover: [Rect, Rect];
+  area: [number, number];
+}
+
+/**
+ * Quadratic-split scratchpad stored in the RTree.
+ * @see label/split.q.h:SplitQ_t / split_q_s
+ */
+export interface SplitQ {
+  branchBuf: Branch[];         // length NODECARD+1
+  coverSplit: Rect;
+  coverSplitArea: number;
+  partitions: PartitionVars[]; // length METHODS
+}
+
+/**
+ * Minimal RTree fields touched by node.c and split.q.c.
+ * T3 (index.c) will flesh out the full RTree type; this structural
+ * base keeps T2 self-contained.
+ * @see label/index.h:struct RTree
+ */
+export interface RTreeBase {
+  root: Node | null;
+  split: SplitQ;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers to build fresh structs
+// ---------------------------------------------------------------------------
+
+/** Build an empty PartitionVars. */
+function makePartitionVars(): PartitionVars {
+  return {
+    partition: new Array<number>(NODECARD + 1).fill(-1),
+    taken:     new Array<boolean>(NODECARD + 1).fill(false),
+    count:     [0, 0],
+    cover:     [nullRect(), nullRect()],
+    area:      [0, 0],
+  };
+}
+
+/** Build an empty branch. */
+function makeBranch(): Branch {
+  return { rect: { boundary: [0, 0, 0, 0] }, child: null };
+}
+
+/** Build an empty SplitQ. */
+export function makeSplitQ(): SplitQ {
+  return {
+    branchBuf: Array.from({ length: NODECARD + 1 }, makeBranch),
+    coverSplit: { boundary: [0, 0, 0, 0] },
+    coverSplitArea: 0,
+    partitions: Array.from({ length: METHODS }, makePartitionVars),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// node.c functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Initialize one branch cell: zeroed rect, null child.
+ * @see label/node.c:InitBranch
+ */
+export function initBranch(b: Branch): void {
+  initRect(b.rect);
+  b.child = null;
+}
+
+/**
+ * Initialize a Node structure: count=0, level=-1, all branches empty.
+ * @see label/node.c:InitNode
+ */
+export function initNode(n: Node): void {
+  n.count = 0;
+  n.level = -1;
+  for (let i = 0; i < NODECARD; i++) {
+    initBranch(n.branch[i]);
+  }
+}
+
+/**
+ * Allocate and initialize a new Node.
+ * @see label/node.c:RTreeNewNode
+ */
+export function rTreeNewNode(): Node {
+  const branches: Branch[] = Array.from({ length: NODECARD }, makeBranch);
+  const n: Node = { count: 0, level: -1, branch: branches };
+  initNode(n);
+  return n;
+}
+
+// ---------------------------------------------------------------------------
+// pickBranch helpers — placed before nodeCover so lizard measures nodeCover
+// length correctly (it uses the next function start as the end marker).
+// ---------------------------------------------------------------------------
+
+/** State carrier for pickBranch's running best. */
+interface PickBest {
+  idx: number;
+  area: number;
+  incr: bigint;  // uint64_t in C — uses wrapping subtraction
+  set: boolean;
+}
+
+/**
+ * Update running-best for one candidate branch.
+ * Extracted to keep pickBranch CCN within limit.
+ * incr uses uint64 semantics (C: uint64_t increase = RectArea(combined) - area).
+ */
+function updatePickBest(best: PickBest, i: number, area: number, increase: bigint): void {
+  if (!best.set || increase < best.incr) {
+    best.idx = i; best.area = area; best.incr = increase; best.set = true;
+  } else if (increase === best.incr && area < best.area) {
+    best.idx = i; best.area = area; best.incr = increase;
+  }
+}
+
+/** Smallest rect enclosing all occupied branch rects. @see label/node.c:NodeCover */
+export function nodeCover(n: Node): Rect {
+  let r: Rect = { boundary: [0, 0, 0, 0] };
+  initRect(r);
+  let flag = true;
+  for (let i = 0; i < NODECARD; i++) {
+    if (n.branch[i].child !== null) {
+      if (flag) { r = n.branch[i].rect; flag = false; }
+      else { r = combineRect(r, n.branch[i].rect); }
+    }
+  }
+  return r;
+}
+
+/**
+ * Pick the branch that will need the smallest area increase to
+ * accommodate rect r. Ties broken by smaller current area.
+ * @see label/node.c:PickBranch
+ */
+export function pickBranch(r: Rect, n: Node): number {
+  const best: PickBest = { idx: 0, area: 0, incr: 0n, set: false };
+  for (let i = 0; i < NODECARD; i++) {
+    if (n.branch[i].child !== null) {
+      const rr = n.branch[i].rect;
+      const area = rectArea(rr);
+      updatePickBest(best, i, area, u64sub(rectArea(combineRect(r, rr)), area));
+    }
+  }
+  return best.idx;
+}
+
+/**
+ * Add a branch to a node. Splits the node if necessary.
+ * Returns 0 if no split; old node updated.
+ * Returns 1 if split; newNodeOut.value set to the new node.
+ *
+ * Cycle note: addBranch → splitNode (split-q.ts) → loadNodes → addBranch.
+ * Resolved via late-binding shim below; both modules fully initialised
+ * before any function executes at runtime.
+ * @see label/node.c:AddBranch
+ */
+export function addBranch(
+  rtp: RTreeBase,
+  b: Branch,
+  n: Node,
+  newNodeOut: { value: Node | null },
+): number {
+  if (n.count < NODECARD) {
+    for (let i = 0; i < NODECARD; i++) {
+      if (n.branch[i].child === null) {
+        n.branch[i] = {
+          rect: { boundary: [b.rect.boundary[0], b.rect.boundary[1], b.rect.boundary[2], b.rect.boundary[3]] },
+          child: b.child,
+        };
+        n.count++;
+        break;
+      }
+    }
+    return 0;
+  } else {
+    splitNode(rtp, n, b, newNodeOut);
+    return 1;
+  }
+}
+
+/**
+ * Disconnect a dependent node (clears branch slot, decrements count).
+ * @see label/node.c:DisconBranch
+ */
+export function disconnectBranch(n: Node, i: number): void {
+  initBranch(n.branch[i]);
+  n.count--;
+}
+
+// ---------------------------------------------------------------------------
+// Late-binding shim for splitNode — breaks the ESM circular-import at module
+// evaluation time while preserving C call semantics at runtime.
+// split-q.ts calls registerSplitNode() at module load time.
+// ---------------------------------------------------------------------------
+
+let _splitNodeImpl: (
+  rtp: RTreeBase,
+  n: Node,
+  b: Branch,
+  newNodeOut: { value: Node | null },
+) => void = () => {
+  throw new Error('splitNode not yet registered — import split-q.ts first');
+};
+
+/** Register the splitNode implementation. Called by split-q.ts at load time. */
+export function registerSplitNode(
+  impl: (rtp: RTreeBase, n: Node, b: Branch, newNodeOut: { value: Node | null }) => void,
+): void {
+  _splitNodeImpl = impl;
+}
+
+function splitNode(
+  rtp: RTreeBase, n: Node, b: Branch, newNodeOut: { value: Node | null },
+): void {
+  _splitNodeImpl(rtp, n, b, newNodeOut);
+}

package/src/label/rectangle.ts

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * R-tree rectangle primitives.
+ * @see label/rectangle.h
+ * @see label/rectangle.c
+ * @see label/index.h
+ */
+
+/** @see label/index.h:NUMDIMS */
+export const NUMDIMS = 2;
+
+/** @see label/index.h:NUMSIDES (2*NUMDIMS) */
+export const NUMSIDES = 2 * NUMDIMS;
+
+/**
+ * Flat boundary array: [lowX, lowY, highX, highY].
+ * Indexed via CX/CY/NX/NY helpers matching the C macros.
+ * @see label/rectangle.h:Rect_t
+ */
+export interface Rect {
+  boundary: [number, number, number, number];
+}
+
+/** @see label/index.h:CX(i) — low side, x-axis offset i */
+export function CX(i: number): number { return i; }
+
+/** @see label/index.h:NX(i) — high side, x-axis offset i */
+export function NX(i: number): number { return i + NUMDIMS; }
+
+/** @see label/index.h:CY(i) — low side, y-axis offset i */
+export function CY(i: number): number { return i + 1; }
+
+/** @see label/index.h:NY(i) — high side, y-axis offset i */
+export function NY(i: number): number { return i + 1 + NUMDIMS; }
+
+/**
+ * Returns true when the rect is undefined (NullRect convention).
+ * C: boundary[0] > boundary[NUMDIMS]
+ * @see label/rectangle.c:Undefined
+ */
+function isUndefined(r: Rect): boolean {
+  return r.boundary[0] > r.boundary[NUMDIMS];
+}
+
+/**
+ * Initialize a rectangle to have all 0 coordinates.
+ * @see label/rectangle.c:InitRect
+ */
+export function initRect(r: Rect): void {
+  for (let i = 0; i < NUMSIDES; i++) {
+    r.boundary[i] = 0;
+  }
+}
+
+/**
+ * Return a rect whose first low side is higher than its opposite side —
+ * interpreted as an undefined rect.
+ * C: boundary[0]=1, boundary[NUMDIMS]=-1, rest 0.
+ * @see label/rectangle.c:NullRect
+ */
+export function nullRect(): Rect {
+  const r: Rect = { boundary: [0, 0, 0, 0] };
+  r.boundary[0] = 1;
+  r.boundary[NUMDIMS] = -1;
+  return r;
+}
+
+/**
+ * Calculate the n-dimensional area of a rectangle.
+ * Returns 0 for undefined rects or zero-width dimensions.
+ * Throws if area overflows Number.MAX_SAFE_INTEGER (browser-safe substitute
+ * for C's graphviz_exit on UINT64_MAX overflow).
+ * @see label/rectangle.c:RectArea
+ */
+export function rectArea(r: Rect): number {
+  if (isUndefined(r)) return 0;
+
+  let area = 1;
+  for (let i = 0; i < NUMDIMS; i++) {
+    const dim = r.boundary[i + NUMDIMS] - r.boundary[i];
+    if (dim === 0) return 0;
+    if (Number.MAX_SAFE_INTEGER / dim < area) {
+      throw new Error('label: area too large for rtree');
+    }
+    area *= dim;
+  }
+  return area;
+}
+
+/**
+ * Combine two rectangles, making one that includes both.
+ * Uses fmin for both low and high sides — faithful to C source.
+ * @see label/rectangle.c:CombineRect
+ */
+export function combineRect(r: Rect, rr: Rect): Rect {
+  if (isUndefined(r)) return rr;
+  if (isUndefined(rr)) return r;
+
+  const result: Rect = { boundary: [0, 0, 0, 0] };
+  for (let i = 0; i < NUMDIMS; i++) {
+    result.boundary[i] = Math.min(r.boundary[i], rr.boundary[i]);
+    const j = i + NUMDIMS;
+    result.boundary[j] = Math.min(r.boundary[j], rr.boundary[j]);
+  }
+  return result;
+}
+
+/**
+ * Decide whether two rectangles overlap.
+ * C: for each dim i, false if r.lo[i] > s.hi[i] OR s.lo[i] > r.hi[i].
+ * Touching edges (equal) are considered overlapping (strict > only).
+ * @see label/rectangle.c:Overlap
+ */
+export function overlap(r: Rect, s: Rect): boolean {
+  for (let i = 0; i < NUMDIMS; i++) {
+    const j = i + NUMDIMS;
+    if (r.boundary[i] > s.boundary[j] || s.boundary[i] > r.boundary[j]) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/label/split-q.ts

@@ -0,0 +1,237 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * R-tree quadratic node splitter.
+ * @see label/split.q.h
+ * @see label/split.q.c
+ */
+
+import { type Rect, combineRect, rectArea, nullRect } from './rectangle.js';
+import {
+  NODECARD,
+  type Branch,
+  type Node,
+  type PartitionVars,
+  type RTreeBase,
+  addBranch,
+  initNode,
+  rTreeNewNode,
+  registerSplitNode,
+} from './node.js';
+
+// ---------------------------------------------------------------------------
+// Unsigned 64-bit arithmetic helpers
+//
+// C split.q.c declares waste/growth/diff/area as uint64_t.  Subtraction wraps
+// mod 2^64.  JavaScript uses IEEE-754 doubles, so we use BigInt for these
+// comparisons to faithfully reproduce the C unsigned-overflow behaviour.
+// ---------------------------------------------------------------------------
+
+const UINT64_MOD = 2n ** 64n;
+
+/** Simulate C uint64_t subtraction: wraps mod 2^64. */
+function u64sub(a: number, b: number): bigint {
+  const r = BigInt(a) - BigInt(b);
+  return r < 0n ? r + UINT64_MOD : r;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers — mirror static functions in split.q.c
+// ---------------------------------------------------------------------------
+
+/** @see label/split.q.c:InitPVars */
+function initPVars(rtp: RTreeBase): void {
+  const p = rtp.split.partitions[0];
+  p.count[0] = p.count[1] = 0;
+  p.cover[0] = nullRect();
+  p.cover[1] = nullRect();
+  p.area[0] = p.area[1] = 0;
+  for (let i = 0; i < NODECARD + 1; i++) {
+    p.taken[i] = false;
+    p.partition[i] = -1;
+  }
+}
+
+/** @see label/split.q.c:Classify */
+function classify(rtp: RTreeBase, i: number, group: number): void {
+  const p: PartitionVars = rtp.split.partitions[0];
+  p.partition[i] = group;
+  p.taken[i] = true;
+  if (p.count[group] === 0) {
+    p.cover[group] = rtp.split.branchBuf[i].rect;
+  } else {
+    p.cover[group] = combineRect(rtp.split.branchBuf[i].rect, p.cover[group]);
+  }
+  p.area[group] = rectArea(p.cover[group]);
+  p.count[group]++;
+}
+
+/** @see label/split.q.c:PickSeeds */
+function pickSeeds(rtp: RTreeBase): void {
+  const area: number[] = new Array<number>(NODECARD + 1);
+  for (let i = 0; i < NODECARD + 1; i++) {
+    area[i] = rectArea(rtp.split.branchBuf[i].rect);
+  }
+  let worst = 0n;
+  let seed0 = 0;
+  let seed1 = 0;
+  for (let i = 0; i < NODECARD; i++) {
+    for (let j = i + 1; j < NODECARD + 1; j++) {
+      const rect: Rect = combineRect(
+        rtp.split.branchBuf[i].rect,
+        rtp.split.branchBuf[j].rect,
+      );
+      // C: uint64_t waste = RectArea(rect) - area[i] - area[j]  (wraps on underflow)
+      const combArea = rectArea(rect);
+      const waste = u64sub(combArea, area[i] + area[j]);
+      if (waste > worst) {
+        worst = waste;
+        seed0 = i;
+        seed1 = j;
+      }
+    }
+  }
+  classify(rtp, seed0, 0);
+  classify(rtp, seed1, 1);
+}
+
+/** Deep-copy a Rect boundary so the copy is independent of the source. */
+function copyRect(r: Rect): Rect {
+  return { boundary: [r.boundary[0], r.boundary[1], r.boundary[2], r.boundary[3]] };
+}
+
+/** @see label/split.q.c:GetBranches */
+function getBranches(rtp: RTreeBase, n: Node, b: Branch): void {
+  for (let i = 0; i < NODECARD; i++) {
+    rtp.split.branchBuf[i] = { rect: copyRect(n.branch[i].rect), child: n.branch[i].child };
+  }
+  rtp.split.branchBuf[NODECARD] = { rect: copyRect(b.rect), child: b.child };
+  rtp.split.coverSplit = rtp.split.branchBuf[0].rect;
+  for (let i = 1; i < NODECARD + 1; i++) {
+    rtp.split.coverSplit = combineRect(
+      rtp.split.coverSplit,
+      rtp.split.branchBuf[i].rect,
+    );
+  }
+  rtp.split.coverSplitArea = rectArea(rtp.split.coverSplit);
+  initNode(n);
+}
+
+/** @see label/split.q.c:LoadNodes */
+function loadNodes(rtp: RTreeBase, n: Node, q: Node): void {
+  for (let i = 0; i < NODECARD + 1; i++) {
+    const part = rtp.split.partitions[0].partition[i];
+    if (part === 0) {
+      addBranch(rtp, rtp.split.branchBuf[i], n, { value: null });
+    } else if (part === 1) {
+      addBranch(rtp, rtp.split.branchBuf[i], q, { value: null });
+    }
+  }
+}
+
+/** @see label/split.q.c:MethodZero */
+function methodZero(rtp: RTreeBase): void {
+  initPVars(rtp);
+  pickSeeds(rtp);
+  const p = rtp.split.partitions[0];
+  while (
+    p.count[0] + p.count[1] < NODECARD + 1 &&
+    p.count[0] < NODECARD + 1 &&
+    p.count[1] < NODECARD + 1
+  ) {
+    pickAndClassifyBest(rtp);
+  }
+  flushRemaining(rtp);
+}
+
+/** Running best state for pickAndClassifyBest. */
+interface DiffBest { set: boolean; diff: bigint; chosen: number; group: number; }
+
+/** Compute preferred group and diff for one untaken branch (uint64 semantics). */
+function branchDiff(
+  growth0: bigint, growth1: bigint,
+): { diff: bigint; group: number } {
+  if (growth1 >= growth0) return { diff: growth1 - growth0, group: 0 };
+  return { diff: growth0 - growth1, group: 1 };
+}
+
+/** Update DiffBest with candidate i if it is a new best. */
+function updateDiffBest(
+  best: DiffBest, i: number, diff: bigint, group: number,
+  p: PartitionVars,
+): void {
+  if (!best.set || diff > best.diff) {
+    best.diff = diff; best.set = true; best.chosen = i; best.group = group;
+  } else if (diff === best.diff && p.count[group] < p.count[best.group]) {
+    best.chosen = i; best.group = group;
+  }
+}
+
+/**
+ * One iteration of MethodZero's inner loop: pick the unassigned branch
+ * with the greatest inter-group difference and classify it.
+ */
+function pickAndClassifyBest(rtp: RTreeBase): void {
+  const p = rtp.split.partitions[0];
+  const best: DiffBest = { set: false, diff: 0n, chosen: 0, group: 0 };
+  for (let i = 0; i < NODECARD + 1; i++) {
+    if (!p.taken[i]) {
+      const r: Rect = rtp.split.branchBuf[i].rect;
+      // C: uint64_t growth0 = RectArea(combine) - area[0]  (uint64 subtraction)
+      const growth0 = u64sub(rectArea(combineRect(r, p.cover[0])), p.area[0]);
+      const growth1 = u64sub(rectArea(combineRect(r, p.cover[1])), p.area[1]);
+      const { diff, group } = branchDiff(growth0, growth1);
+      updateDiffBest(best, i, diff, group, p);
+    }
+  }
+  classify(rtp, best.chosen, best.group);
+}
+
+/**
+ * After MethodZero's main loop, assign any remaining unclassified branches
+ * to the group that still has room.
+ */
+function flushRemaining(rtp: RTreeBase): void {
+  const p = rtp.split.partitions[0];
+  if (p.count[0] + p.count[1] >= NODECARD + 1) return;
+  let group = 0;
+  if (p.count[0] >= NODECARD + 1) group = 1;
+  for (let i = 0; i < NODECARD + 1; i++) {
+    if (!p.taken[i]) classify(rtp, i, group);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Split a node. Divides the node's branches and the extra one between two
+ * nodes. Old node is one of the two; a new node is created and returned via
+ * nn.value.
+ * @see label/split.q.c:SplitNode
+ */
+export function splitNode(
+  rtp: RTreeBase,
+  n: Node,
+  b: Branch,
+  nn: { value: Node | null },
+): void {
+  const level = n.level;
+  getBranches(rtp, n, b);
+  methodZero(rtp);
+  nn.value = rTreeNewNode();
+  (nn.value as Node).level = n.level = level;
+  loadNodes(rtp, n, nn.value as Node);
+}
+
+// Register with node.ts so addBranch can call splitNode without a
+// module-evaluation-time circular import.
+registerSplitNode(splitNode);
+
+// METHODS constant — number of partition methods (only 0 is used).
+// @see label/split.q.h:METHODS
+const METHODS = 1;
+
+// Re-export METHODS count for consumers that need it (mirrors index.h exposure).
+export { METHODS };