@knowvah/dot-engine 0.1.0

package/src/api/index.ts

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * `graphviz-ts/api` — the build + inspect + geometry entry point (ADR-2).
+ *
+ * Pure re-export barrel for the api layer: programmatic graph construction
+ * (the builder), the safe edge helper, and the computed-geometry snapshot.
+ *
+ * Typical flow: call {@link createGraph} to build nodes/edges/subgraphs
+ * without hand-writing DOT text, hand the builder's `.graph` (or a
+ * `parse()` result) to `render()` from `graphviz-ts/render` (or the root
+ * package) to lay out and emit an output format, then optionally call
+ * {@link getLayout} here to read back computed node/edge/cluster geometry
+ * from the laid-out graph.
+ *
+ * The internal mutable `Graph`/`Node`/`Edge` classes are NOT re-exported as
+ * values (ADR-1); only the opaque `Graph` *type* is surfaced so consumers can
+ * annotate variables holding a builder's `.graph` or a `parse()` result.
+ */
+
+// --- Programmatic construction (T4) ---------------------------------------
+export { createGraph } from './builder.js';
+export type {
+  GvGraphBuilder,
+  GvNode,
+  GvEdge,
+  CreateGraphOptions,
+} from './builder.js';
+
+// --- Computed-geometry snapshot (T3) --------------------------------------
+export { getLayout } from './geometry.js';
+export type {
+  LayoutSnapshot,
+  NodeGeometry,
+  EdgeGeometry,
+  BoundsGeometry,
+  ClusterGeometry,
+  YAxis,
+  GeometryOptions,
+} from './geometry.js';
+
+// --- Safe edge construction (T2) ------------------------------------------
+export { addEdge } from './edge-ops.js';
+
+// --- Opaque graph handle type (ADR-1: type only, no class internals) ------
+export type { Graph } from '../model/graph.js';

package/src/cdt/bag.ts

@@ -0,0 +1,196 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * DtBag — ordered multiset (Dtobag) backed by a splay tree.
+ *
+ * Unlike DtSplay (DT_OSET), DtBag allows duplicate keys.  On insert of a
+ * duplicate, the new node is inserted immediately to the LEFT of the
+ * matching node (mirrors C dttree.c DT_OBAG insert: new node placed in
+ * link.left, i.e. the right partition, becoming the successor of the
+ * matching group — faithfully ported from dttree.c lines 226-230).
+ *
+ * Iteration (first/next) produces ascending comparator order.  Among
+ * equal-key nodes the sub-order is the deterministic order CDT's Dtobag
+ * produces (via bagInsert's integrated splay+insert) — load-bearing for the
+ * xlabel R-tree, which drains this bag to seed its Hilbert insertion order.
+ *
+ * AD4 extension: required by xlabels.ts which uses dtopen(&Hdisc, Dtobag).
+ *
+ * @see lib/cdt/dttree.c (DT_OBAG)
+ */
+
+import type { Comparator, KeyOf } from "./types.js";
+import {
+  splay,
+  splayMin,
+  splayMax,
+  bagInsert,
+} from "./splay-core.js";
+import type { SplayNode } from "./splay-core.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk left-spine from `start` to find a node whose `.obj === target`.
+ * All nodes on the spine share the same key.
+ * Returns [node, parent] or [null, null] when not found.
+ */
+function findByIdentity<T, K>(
+  start: SplayNode<T>,
+  target: T,
+  key: K,
+  keyOf: KeyOf<T, K>,
+  compare: Comparator<K>,
+): [SplayNode<T> | null, SplayNode<T> | null] {
+  let cur: SplayNode<T> | null = start;
+  let parent: SplayNode<T> | null = null;
+  while (cur !== null) {
+    if (cur.obj === target) return [cur, parent];
+    if (compare(key, keyOf(cur.obj)) !== 0) return [null, null];
+    parent = cur;
+    cur = cur.left;
+  }
+  return [null, null];
+}
+
+/**
+ * Unlink `cur` from the tree.  `parent` is its direct parent (null → root).
+ * Returns the new root.
+ */
+function unlinkNode<T>(
+  root: SplayNode<T>,
+  cur: SplayNode<T>,
+  parent: SplayNode<T> | null,
+): SplayNode<T> | null {
+  const left  = cur.left;
+  const right = cur.right;
+  let replacement: SplayNode<T> | null;
+  if (left === null) {
+    replacement = right;
+  } else {
+    const maxLeft = splayMax(left);
+    maxLeft.right = right;
+    replacement = maxLeft;
+  }
+  if (parent === null) return replacement;
+  parent.left = replacement;
+  return root;
+}
+
+// ---------------------------------------------------------------------------
+// DtBag class
+// ---------------------------------------------------------------------------
+
+export class DtBag<T, K = T> {
+  private _root: SplayNode<T> | null = null;
+  private _size = 0;
+  private readonly _keyOf: KeyOf<T, K>;
+  private readonly _compare: Comparator<K>;
+
+  constructor(keyOf: KeyOf<T, K>, compare: Comparator<K>) {
+    this._keyOf = keyOf;
+    this._compare = compare;
+  }
+
+  /** @see lib/cdt/dtsize.c:dtsize */
+  size(): number { return this._size; }
+
+  /**
+   * Insert obj.  Duplicates ARE inserted (DT_OBAG semantics).
+   * @see lib/cdt/dttree.c:dttree DT_INSERT (DT_OBAG branch)
+   */
+  insert(obj: T): T {
+    const node: SplayNode<T> = { left: null, right: null, obj };
+    if (this._root === null) {
+      this._root = node;
+      this._size++;
+      return obj;
+    }
+    // Integrated CDT top-down splay + insert: the equal-key sub-order is
+    // load-bearing (see bagInsert), so we must NOT splay-reassemble first.
+    this._root = bagInsert(this._root, node, this._keyOf, this._compare);
+    this._size++;
+    return obj;
+  }
+
+  /**
+   * Delete one occurrence of obj by object identity.
+   * @see lib/cdt/dttree.c:dttree DT_OBAG DT_DELETE
+   */
+  delete(obj: T): boolean {
+    if (this._root === null) return false;
+    const key = this._keyOf(obj);
+    this._root = splay(this._root, key, this._keyOf, this._compare);
+    if (this._compare(key, this._keyOf(this._root.obj)) !== 0) return false;
+    const [cur, parent] = findByIdentity(
+      this._root, obj, key, this._keyOf, this._compare,
+    );
+    if (cur === null) return false;
+    const newRoot = unlinkNode(this._root, cur, parent);
+    this._root = newRoot;
+    this._size--;
+    return true;
+  }
+
+  /**
+   * Return the minimum element (splays to root).
+   * @see lib/cdt/dttree.c:dttree DT_FIRST
+   */
+  first(): T | undefined {
+    if (this._root === null) return undefined;
+    this._root = splayMin(this._root);
+    return this._root.obj;
+  }
+
+  /**
+   * Return the in-order successor of obj.
+   * @see lib/cdt/dttree.c:dttree DT_NEXT
+   */
+  next(obj: T): T | undefined {
+    if (this._root === null) return undefined;
+    const key = this._keyOf(obj);
+    this._root = splay(this._root, key, this._keyOf, this._compare);
+    const cmp = this._compare(key, this._keyOf(this._root.obj));
+    if (cmp < 0) return this._root.obj;
+    const right = this._root.right;
+    if (right === null) return undefined;
+    const minNode = splayMin(right);
+    this._root.right = null;
+    minNode.left = this._root;
+    this._root = minNode;
+    return minNode.obj;
+  }
+
+  /**
+   * Return the maximum element (splays to root).
+   * @see lib/cdt/dttree.c:dttree DT_LAST
+   */
+  last(): T | undefined {
+    if (this._root === null) return undefined;
+    this._root = splayMax(this._root);
+    return this._root.obj;
+  }
+
+  /** Remove all elements. */
+  clear(): void {
+    this._root = null;
+    this._size = 0;
+  }
+
+  /** Iterate in ascending comparator order via first() / next(). */
+  [Symbol.iterator](): Iterator<T> {
+    let current: T | undefined = this.first();
+    const self = this;
+    return {
+      next(): IteratorResult<T> {
+        if (current === undefined) {
+          return { value: undefined as unknown as T, done: true };
+        }
+        const value = current;
+        current = self.next(value);
+        return { value, done: false };
+      },
+    };
+  }
+}

package/src/cdt/hash-core.ts

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * Internal types and resize helpers for DtHash.
+ *
+ * Ported from lib/cdt/dthash.c (Kiem-Phong Vo, 05/25/96) and
+ * lib/cdt/dthdr.h macros: HSLOT, HRESIZE, HLOAD, HINDEX.
+ *
+ * @see lib/cdt/dthash.c:dthtab
+ * @see lib/cdt/dthdr.h
+ */
+
+/** Initial number of hash slots — HSLOT from dthdr.h */
+export const HSLOT = 256;
+
+/** Load threshold: resize when size > HLOAD(ntab) = 2*ntab @see dthdr.h:HLOAD */
+export function hload(n: number): number { return n << 1; }
+
+/** Map hash to slot index: HINDEX(n,h) = h & (n-1) @see dthdr.h:HINDEX */
+export function hindex(n: number, h: number): number { return h & (n - 1); }
+
+/** Internal chain node — analogous to Dtlink_t used in DT_SET mode. */
+export interface HashNode<T> {
+  right: HashNode<T> | null; // next in chain (Dtlink_t.right)
+  hash:  number;             // hl._hash
+  obj:   T;
+}
+
+/**
+ * Migrate one slot's chain into newSlots of size n.
+ * Nodes that map to a different slot are moved; those that stay are left
+ * in oldSlots[si] and copied to newSlots[si] at the end.
+ * @see lib/cdt/dthash.c:dthtab (inner rehash loop)
+ */
+export function migrateChain<T>(
+  oldSlots: Array<HashNode<T> | null>,
+  newSlots: Array<HashNode<T> | null>,
+  si: number,
+  n: number,
+): void {
+  let prev: HashNode<T> | null = null;
+  let t = oldSlots[si];
+  while (t !== null) {
+    const next = t.right;
+    const dest = hindex(n, t.hash);
+    if (dest === si) {
+      prev = t;
+    } else {
+      if (prev !== null) prev.right = next;
+      else oldSlots[si] = next;
+      t.right = newSlots[dest];
+      newSlots[dest] = t;
+    }
+    t = next;
+  }
+  if (oldSlots[si] !== null) newSlots[si] = oldSlots[si];
+}
+
+/**
+ * Compute the smallest power-of-two slot count that keeps size under load.
+ * @see lib/cdt/dthash.c:dthtab (size computation block)
+ */
+export function targetSlotCount(current: number, size: number): number {
+  let n = current === 0 ? HSLOT : current;
+  while (size > hload(n)) n = n << 1; // HRESIZE
+  return n;
+}
+
+/**
+ * Resize and rehash the table; returns the new slot array.
+ * No-op (returns oldSlots unchanged) when no resize is needed.
+ * @see lib/cdt/dthash.c:dthtab
+ */
+export function rehash<T>(
+  oldSlots: Array<HashNode<T> | null>,
+  size: number,
+): Array<HashNode<T> | null> {
+  const n = targetSlotCount(oldSlots.length, size);
+  if (n === oldSlots.length) return oldSlots;
+  const newSlots: Array<HashNode<T> | null> = new Array(n).fill(null);
+  for (let si = 0; si < oldSlots.length; si++) {
+    migrateChain(oldSlots, newSlots, si, n);
+  }
+  return newSlots;
+}

package/src/cdt/hash.ts

@@ -0,0 +1,207 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * DtHash — unordered set (DT_SET) backed by a separate-chaining hash table.
+ *
+ * Ported faithfully from lib/cdt/dthash.c (Kiem-Phong Vo, 05/25/96).
+ *
+ * Behavioral contracts preserved from C:
+ *  - Initial slot count: 256 (HSLOT)
+ *  - Resize when size > 2*ntab, suppressed while loop > 0
+ *  - loop counter: first() increments; next() returning undefined decrements
+ *  - Move-to-front on search when loop === 0; suppressed during walk
+ *
+ * @see lib/cdt/dthash.c
+ * @see lib/cdt/dthdr.h
+ */
+
+import type { Comparator, KeyOf } from "./types.js";
+import {
+  hindex,
+  hload,
+  HashNode,
+  HSLOT,
+  rehash,
+} from "./hash-core.js";
+
+/**
+ * DtHash — unordered set backed by a separate-chaining hash table.
+ * @see lib/cdt/dthash.c:dthash
+ */
+export class DtHash<T, K = T> {
+  private _slots: Array<HashNode<T> | null> = [];
+  private _size  = 0;
+  /** Nesting depth of active walks — suppresses resize when > 0. */
+  private _loop  = 0;
+  /** Finger: last accessed node — analogous to dt->data.here */
+  private _here: HashNode<T> | null = null;
+  private readonly _keyOf:   KeyOf<T, K>;
+  private readonly _hash:    (key: K) => number;
+  private readonly _compare: Comparator<K>;
+
+  constructor(
+    keyOf:   KeyOf<T, K>,
+    hash:    (key: K) => number,
+    compare: Comparator<K>,
+  ) {
+    this._keyOf   = keyOf;
+    this._hash    = hash;
+    this._compare = compare;
+  }
+
+  /** @see lib/cdt/dtsize.c:dtsize */
+  size(): number { return this._size; }
+
+  // ─── Private helpers ──────────────────────────────────────────────────────
+
+  /** Allocate the slot array on first use. */
+  private _ensureSlots(): void {
+    if (this._slots.length === 0) {
+      this._slots = new Array<HashNode<T> | null>(HSLOT).fill(null);
+    }
+  }
+
+  /**
+   * Find a node by key.
+   * Returns [node, predecessor, slotIndex]; node is null when not found.
+   */
+  private _find(key: K, h: number): [HashNode<T> | null, HashNode<T> | null, number] {
+    if (this._slots.length === 0) return [null, null, -1];
+    const si = hindex(this._slots.length, h);
+    let prev: HashNode<T> | null = null;
+    let t = this._slots[si];
+    while (t !== null) {
+      if (t.hash === h && this._compare(key, this._keyOf(t.obj)) === 0) {
+        return [t, prev, si];
+      }
+      prev = t;
+      t = t.right;
+    }
+    return [null, null, si];
+  }
+
+  /** Resize if over load and no active walk. */
+  private _maybeResize(): void {
+    if (this._loop > 0) return;
+    if (this._size > hload(this._slots.length)) {
+      this._slots = rehash(this._slots, this._size);
+    }
+  }
+
+  /** End an active walk: decrement loop, possibly trigger deferred resize. */
+  private _endWalk(): undefined {
+    if (this._loop > 0) this._loop--;
+    if (this._size > hload(this._slots.length) && this._loop <= 0) {
+      this._slots = rehash(this._slots, this._size);
+    }
+    return undefined;
+  }
+
+  // ─── Public API ───────────────────────────────────────────────────────────
+
+  /**
+   * Insert obj.  If key already exists returns the existing object (DT_SET).
+   * @see lib/cdt/dthash.c:dthash DT_INSERT
+   */
+  insert(obj: T): T {
+    const key = this._keyOf(obj);
+    const h   = this._hash(key) >>> 0;
+
+    this._ensureSlots();
+    this._maybeResize();
+
+    const [existing, , ] = this._find(key, h);
+    if (existing !== null) {
+      this._here = existing;
+      return existing.obj;
+    }
+
+    const node: HashNode<T> = { right: null, hash: h, obj };
+    const idx = hindex(this._slots.length, h);
+    node.right = this._slots[idx];
+    this._slots[idx] = node;
+    this._size++;
+    this._here = node;
+    this._maybeResize();
+    return obj;
+  }
+
+  /**
+   * Delete obj by key.  Returns true if found and removed.
+   * @see lib/cdt/dthash.c:dthash DT_DELETE
+   */
+  delete(obj: T): boolean {
+    if (this._size === 0) return false;
+    const key = this._keyOf(obj);
+    const h   = this._hash(key) >>> 0;
+    const [t, prev, si] = this._find(key, h);
+    if (t === null) return false;
+
+    if (prev !== null) prev.right = t.right;
+    else this._slots[si] = t.right;
+    this._size--;
+    this._here = prev ?? this._slots[si];
+    return true;
+  }
+
+  /**
+   * Search by key.  Applies move-to-front when loop === 0.
+   * @see lib/cdt/dthash.c:dthash DT_SEARCH
+   */
+  search(key: K): T | undefined {
+    if (this._size === 0) return undefined;
+    const h = this._hash(key) >>> 0;
+    const [t, prev, si] = this._find(key, h);
+    if (t === null) return undefined;
+
+    if (prev !== null && this._loop <= 0) {
+      prev.right      = t.right;
+      t.right         = this._slots[si];
+      this._slots[si] = t;
+    }
+    this._here = t;
+    return t.obj;
+  }
+
+  /**
+   * Return the first element; increments the walk loop counter.
+   * Scans slots from index 0 upward.
+   * @see lib/cdt/dthash.c:dthash DT_FIRST
+   */
+  first(): T | undefined {
+    if (this._size <= 0) return undefined;
+    let t: HashNode<T> | null = null;
+    for (let i = 0; i < this._slots.length; i++) {
+      if (this._slots[i] !== null) { t = this._slots[i]; break; }
+    }
+    this._loop++;
+    this._here = t;
+    return t !== null ? t.obj : undefined;
+  }
+
+  /**
+   * Return the next element; advance within chain then across slots.
+   * Decrements loop counter and triggers deferred resize when exhausted.
+   * @see lib/cdt/dthash.c:dthash DT_NEXT
+   */
+  next(_obj: T): T | undefined {
+    if (this._here === null) return this._endWalk();
+    const si = hindex(this._slots.length, this._here.hash);
+    let p: HashNode<T> | null = this._here.right;
+    if (p === null) {
+      for (let i = si + 1; i < this._slots.length; i++) {
+        if (this._slots[i] !== null) { p = this._slots[i]; break; }
+      }
+    }
+    if (p === null) return this._endWalk();
+    this._here = p;
+    return p.obj;
+  }
+
+  /** Remove all elements. @see lib/cdt/dthash.c:dthash DT_CLEAR */
+  clear(): void {
+    this._slots.fill(null);
+    this._size = 0;
+    this._loop = 0;
+    this._here = null;
+  }
+}

package/src/cdt/index.ts

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * lib/cdt — Container Data Types public API.
+ *
+ * Exports DtSplay (DT_OSET), DtHash (DT_SET), and dtStrHash.
+ *
+ * @see lib/cdt/cdt.h
+ * @see lib/cdt/dttree.c
+ * @see lib/cdt/dthash.c
+ * @see lib/cdt/dtstrhash.c
+ */
+
+export type { Comparator, KeyOf } from "./types.js";
+export { DtSplay } from "./splay.js";
+export { DtBag }   from "./bag.js";
+export { DtHash }  from "./hash.js";
+export { dtStrHash } from "./strhash.js";