@knowvah/dot-engine 0.1.0

package/src/layout/twopi/twopi-test-helpers.ts

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Shared test fixtures for twopi layout tests.
+ * Kept in a separate file so lizard does not conflate helper function spans
+ * with the describe() callbacks that follow them in the test file.
+ */
+
+import { Graph } from '../../model/graph.js';
+import { Node } from '../../model/node.js';
+import { Edge } from '../../model/edge.js';
+import { makeNodeInfo } from '../../model/nodeInfo.js';
+
+let _id = 0;
+
+export function h_node(g: Graph, name: string): Node {
+  const n = new Node(_id++, name, g);
+  n.info = makeNodeInfo();
+  n.info.lw = 18; n.info.rw = 18; n.info.ht = 18;
+  g.nodes.set(name, n);
+  return n;
+}
+
+export function h_edge(g: Graph, t: Node, h: Node): void {
+  g.edges.push(new Edge(t, h, `${t.name}-${h.name}`));
+}
+
+export function makeStar(leaves: number): Graph {
+  _id = 0;
+  const g = new Graph('star', 'undirected');
+  const hub = h_node(g, 'hub');
+  for (let i = 0; i < leaves; i++) h_edge(g, hub, h_node(g, `l${i}`));
+  return g;
+}
+
+export function makeTwoTriangles(): Graph {
+  _id = 0;
+  const g = new Graph('two-tri', 'undirected');
+  const a = h_node(g, 'a'); const b = h_node(g, 'b'); const c = h_node(g, 'c');
+  h_edge(g, a, b); h_edge(g, b, c); h_edge(g, c, a);
+  const d = h_node(g, 'd'); const e = h_node(g, 'e'); const f = h_node(g, 'f');
+  h_edge(g, d, e); h_edge(g, e, f); h_edge(g, f, d);
+  return g;
+}

package/src/model/algData.ts

@@ -0,0 +1,194 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Per-engine algorithm data — discriminated union (AD-7).
+ *
+ * In C, ND_alg is a void* that each layout engine casts to its own private
+ * struct. TypeScript uses a discriminated union so the kind discriminant is
+ * statically knowable and no unsafe casts are needed. Each engine's batch
+ * adds its concrete fields; the `kind` discriminant is the only required
+ * field now. Split out of nodeInfo.ts to keep that file under the size cap.
+ *
+ * @see lib/common/types.h:Agnodeinfo_t:alg (ND_alg)
+ */
+
+import type { Graph } from './graph.js';
+import type { Node } from './node.js';
+
+/**
+ * Layout-engine algorithm data stored in ND_alg for the dot engine.
+ *
+ * @see lib/dotgen/ — dot-engine algorithm data
+ */
+export interface DotAlgData {
+  readonly kind: 'dot';
+}
+
+/**
+ * Layout-engine algorithm data stored in ND_alg for the neato engine.
+ *
+ * @see lib/neatogen/ — neato-engine algorithm data
+ */
+export interface NeatoAlgData {
+  readonly kind: 'neato';
+}
+
+/**
+ * fdp data for REAL (input-graph) nodes.
+ *
+ * C stores DNODE in ND_next and PARENT in ND_clust (dot fields reused);
+ * here both live in the alg record together with the numeric ND_pinned
+ * state (P_SET/P_FIX/P_PIN), which the boolean NodeInfo.pinned cannot
+ * represent.
+ *
+ * @see lib/fdpgen/fdp.h:DNODE / PARENT
+ */
+export interface FdpAlgData {
+  readonly kind: 'fdp';
+  /** Derived node for this real node. @see lib/fdpgen/fdp.h:DNODE */
+  dnode: Node | null;
+  /** Smallest containing cluster. @see lib/fdpgen/fdp.h:PARENT */
+  parent: Graph | null;
+  /** ND_pinned P_* state. @see lib/common/const.h:P_SET */
+  pinned: number;
+}
+
+/**
+ * fdp data for DERIVED-graph nodes (dndata in C).
+ *
+ * @see lib/fdpgen/fdp.h:dndata
+ */
+export interface FdpDndata {
+  readonly kind: 'fdp-dndata';
+  /** Degree of node. @see lib/fdpgen/fdp.h:DEG */
+  deg: number;
+  /** Weighted degree of node. @see lib/fdpgen/fdp.h:WDEG */
+  wdeg: number;
+  /** Real node if not a cluster. @see lib/fdpgen/fdp.h:ANODE */
+  dn: Node | null;
+  /** Cluster in real graph, for cluster nodes. @see lib/common/types.h:ND_clust */
+  clust: Graph | null;
+  /** Incremental displacement. @see lib/fdpgen/fdp.h:DISP */
+  disp: [number, number];
+  /** ND_pinned P_* state. @see lib/common/const.h:P_SET */
+  pinned: number;
+}
+
+/**
+ * Per-node init data for the circo engine (ndata in C).
+ * Stored in ND_alg on original-graph nodes during Pass 0.
+ * @see lib/circogen/circular.h:ndata
+ */
+export interface CircoNData {
+  readonly kind: 'circo-ndata';
+  dnode: unknown;
+}
+
+/**
+ * Rich per-node layout data for the circo engine (cdata in C).
+ * Stored in ND_alg on derived-graph nodes across Passes 1–4.
+ * @see lib/circogen/circular.h:cdata
+ */
+export interface CircoCData {
+  readonly kind: 'circo-cdata';
+  flags: number;
+  parent: unknown;
+  block: unknown;
+  bc: { val: number; lowVal: number };
+  clone: unknown;
+  tparent: unknown;
+  leafone: unknown;
+  leaftwo: unknown;
+  fdist: number;
+  sdist: number;
+  pos: number;
+  psi: number;
+  degree: number;
+  derivedNode: unknown;
+}
+
+/**
+ * Sentinel value for an unset theta (angular position).
+ * Valid theta values are in [0, 2π]; 10.0 is outside this range.
+ *
+ * @see lib/twopigen/circle.c:#define UNSET 10.00
+ */
+export const THETA_UNSET = 10.0;
+
+/**
+ * Per-node radial layout data for the twopi engine.
+ *
+ * Mirrors the `rdata` struct in lib/twopigen/circle.h. All fields are zeroed
+ * at allocation time (gv_calloc equivalent). theta is set to THETA_UNSET
+ * (10.0) by initLayout; nStepsToCenter is set to n² as the INF sentinel.
+ *
+ * @see lib/twopigen/circle.h:rdata
+ * @see lib/twopigen/circle.c:initLayout
+ */
+export interface TwopiAlgData {
+  readonly kind: 'twopi';
+  /** BFS distance to nearest leaf. @see lib/twopigen/circle.h:rdata:nStepsToLeaf (SLEAF) */
+  nStepsToLeaf: number;
+  /** Leaf count in BFS subtree. @see lib/twopigen/circle.h:rdata:subtreeSize (STSIZE) */
+  subtreeSize: number;
+  /** Number of BFS children. @see lib/twopigen/circle.h:rdata:nChildren (NCHILD) */
+  nChildren: number;
+  /**
+   * BFS distance from root (ring index). n² = INF sentinel.
+   * @see lib/twopigen/circle.h:rdata:nStepsToCenter (SCENTER)
+   */
+  nStepsToCenter: number;
+  /** BFS parent pointer; null for root. @see lib/twopigen/circle.h:rdata:parent (SPARENT) */
+  parent: Node | null;
+  /** Angular span in radians. @see lib/twopigen/circle.h:rdata:span (SPAN) */
+  span: number;
+  /**
+   * Angular midpoint in radians. THETA_UNSET (10.0) until assigned.
+   * @see lib/twopigen/circle.h:rdata:theta (THETA)
+   */
+  theta: number;
+}
+
+/**
+ * Layout-engine algorithm data stored in ND_alg for the osage engine.
+ *
+ * ND_alg(n) is repurposed as a cluster-ownership marker during layout():
+ * when a node is claimed by a cluster, alg is set to an OsageAlgData
+ * with ownerCluster pointing to that cluster. Unclaimed nodes have
+ * alg === undefined.
+ *
+ * @see lib/osage/osageinit.c:PARENT macro
+ */
+export interface OsageAlgData {
+  readonly kind: 'osage';
+  /** The cluster graph that owns this node. @see lib/osage/osageinit.c:ND_alg usage */
+  readonly ownerCluster: Graph;
+}
+
+/**
+ * Layout-engine algorithm data stored in ND_alg for the patchwork engine.
+ *
+ * @see lib/patchwork/ — patchwork-engine algorithm data
+ */
+export interface PatchworkAlgData {
+  readonly kind: 'patchwork';
+}
+
+/**
+ * Discriminated union of all per-engine algorithm data structs stored in
+ * Agnodeinfo_t.alg (ND_alg). Each layout engine stores a different struct
+ * in the C void*; here the `kind` discriminant makes the active engine
+ * statically knowable without unsafe casting.
+ *
+ * @see lib/common/types.h:Agnodeinfo_t:alg (ND_alg)
+ */
+export type NodeAlgData =
+  | DotAlgData
+  | NeatoAlgData
+  | FdpAlgData
+  | FdpDndata
+  | CircoNData
+  | CircoCData
+  | TwopiAlgData
+  | OsageAlgData
+  | PatchworkAlgData;

package/src/model/cgraph-ops.ts

@@ -0,0 +1,175 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Faithful TypeScript port of the cgraph subgraph/node operations needed by
+ * later layout passes (e.g. dot's newrank fill_ranks, which creates a
+ * `_new_rank` subgraph and adds anonymous placeholder nodes).
+ *
+ * Nodes are owned by the root graph and keyed by name in each graph's
+ * `nodes` Map; subgraph membership is presence in that subgraph's `nodes`
+ * Map. A node in a subgraph is a member of every enclosing graph up to and
+ * including root (Subgraph Ownership Semantics).
+ *
+ * @see lib/cgraph/node.c
+ * @see lib/cgraph/subg.c
+ */
+
+import type { Graph } from './graph.js';
+import { Graph as GraphClass } from './graph.js';
+import { Node } from './node.js';
+
+/**
+ * The C anonymous-name prefix LOCALNAMEPREFIX ('%'); an object with no
+ * external name has `agnameof` synthesize "%<id>".
+ * @see lib/cgraph/cghdr.h:LOCALNAMEPREFIX
+ * @see lib/cgraph/id.c:aginternalmapprint
+ */
+const LOCALNAMEPREFIX = '%';
+
+/**
+ * Allocate a fresh node id unique within `root.nodes`. Mirrors C's
+ * agnextseq/agmapnametoid id reservation: at layout time the per-parse
+ * NodeRegistry counter is unavailable, so derive (max existing root id) + 1.
+ * @see lib/cgraph/node.c:agnextseq
+ */
+function freshNodeId(root: Graph): number {
+  let max = -1;
+  for (const n of root.nodes.values()) {
+    if (n.id > max) max = n.id;
+  }
+  return max + 1;
+}
+
+/**
+ * Create-or-get a node by name on the root graph. When `name` is null/empty,
+ * mint a fresh anonymous node with a unique id and unique "%<id>" name. When
+ * `create` is false and a named node is absent, returns null.
+ *
+ * Unlike the C agnode (which keys by id), this port keys nodes by name in
+ * `Graph.nodes`; node creation always installs into the root graph.
+ *
+ * @see lib/cgraph/node.c:agnode
+ */
+export function agnode(
+  g: Graph,
+  name: string | null,
+  create: boolean,
+): Node | null {
+  const root = g.root;
+  if (name !== null && name !== '') {
+    const existing = root.nodes.get(name);
+    if (existing !== undefined) return existing;
+    if (!create) return null;
+    const node = new Node(freshNodeId(root), name, root);
+    root.nodes.set(name, node);
+    return node;
+  }
+  if (!create) return null;
+  const id = freshNodeId(root);
+  const anonName = LOCALNAMEPREFIX + String(id);
+  const node = new Node(id, anonName, root);
+  root.nodes.set(anonName, node);
+  return node;
+}
+
+/**
+ * Assign a subgraph its AGSEQ from the root-level counter, mirroring
+ * `agnextseq(par, AGRAPH)` in agopen: pre-increment `clos->seq[AGRAPH]` (stored
+ * on the root as `subgSeqCounter`) and record it on the subgraph. Call once,
+ * only when the subgraph is first created.
+ *
+ * @see lib/cgraph/graph.c:agopen (AGSEQ(g) = agnextseq(par, AGRAPH))
+ * @see lib/cgraph/graph.c:agnextseq
+ */
+export function assignSubgSeq(parent: Graph, sg: Graph): void {
+  sg.seq = ++parent.root.subgSeqCounter;
+}
+
+/**
+ * Create-or-get a named subgraph under `parent`. On create, sets the new
+ * graph's `parent`/`root`, assigns its AGSEQ, and registers it in
+ * `parent.subgraphs`. Returns null when `create` is false and the subgraph is
+ * absent.
+ *
+ * @see lib/cgraph/subg.c:agsubg
+ */
+export function agsubg(
+  parent: Graph,
+  name: string,
+  create: boolean,
+): Graph | null {
+  const existing = parent.subgraphs.get(name);
+  if (existing !== undefined) return existing;
+  if (!create) return null;
+  const subg = new GraphClass(name, parent.kind);
+  subg.parent = parent;
+  subg.root = parent.root;
+  assignSubgSeq(parent, subg);
+  parent.subgraphs.set(name, subg);
+  return subg;
+}
+
+/**
+ * Lookup or insert node `n` in subgraph `g`, recursively installing it into
+ * every enclosing graph up to and including root. Returns null if `n` does
+ * not belong to `g`'s root. Mirrors the parser's enclosing-graph membership
+ * loop (builder.ts processNodeStmt).
+ *
+ * @see lib/cgraph/node.c:agsubnode
+ */
+export function agsubnode(g: Graph, n: Node, create: boolean): Node | null {
+  if (g.root !== n.root) return null;
+  const existing = g.nodes.get(n.name);
+  if (existing !== undefined) return existing;
+  if (!create) return null;
+  const par = g.parent;
+  if (par !== null) {
+    agsubnode(par, n, create);
+  }
+  g.nodes.set(n.name, n);
+  return n;
+}
+
+/**
+ * Remove node `n` from graph `g` and every enclosing graph up to and
+ * including root (its member graphs). Mirrors agdelnode's image removal
+ * applied across the graph and its ancestors.
+ *
+ * @see lib/cgraph/node.c:agdelnode
+ */
+export function agdelnode(g: Graph, n: Node): void {
+  for (let cur: Graph | null = g; cur !== null; cur = cur.parent) {
+    cur.nodes.delete(n.name);
+  }
+}
+
+/**
+ * Remove subgraph `sg` from `parent.subgraphs`. Mirrors agdelsubg, which
+ * only deletes the entry in the parent's subgraph dict.
+ *
+ * @see lib/cgraph/subg.c:agdelsubg
+ */
+export function agdelsubg(parent: Graph, sg: Graph): void {
+  parent.subgraphs.delete(sg.name);
+}
+
+/**
+ * Faithful `agxget` for a graph attribute, mirroring C's
+ * `late_string(g, agfindgraphattr(g, name), NULL)`:
+ * - returns `g`'s explicit value if set;
+ * - else, if `name` was declared graph-wide (set on any (sub)graph at parse
+ *   time → present in `root.declaredGraphAttrs`), returns the empty-string
+ *   default `""` (cgraph's agsafeset default);
+ * - else returns `undefined` (the attribute symbol does not exist).
+ *
+ * The `undefined` vs `""` distinction is load-bearing: e.g. `ordered_edges`
+ * treats a non-NULL (incl. empty) value as "graph ordering present, do not
+ * recurse into subgraphs". A subgraph-scoped `ordering=out` therefore yields
+ * `""` at the root, so the root no-ops it exactly as C does.
+ * @see lib/cgraph/attr.c:agxget, lib/common/utils.c:late_string
+ */
+export function agGraphAttr(g: Graph, name: string): string | undefined {
+  const own = g.attrs.get(name);
+  if (own !== undefined) return own;
+  return g.root.declaredGraphAttrs.has(name) ? '' : undefined;
+}

package/src/model/edge.ts

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * TypeScript port of Agedge_t / Agedgepair_t from lib/cgraph/cgraph.h.
+ *
+ * @see lib/cgraph/cgraph.h:Agedge_s
+ * @see lib/cgraph/cgraph.h:Agedgepair_s
+ */
+
+import type { Node } from './node.js';
+import { type EdgeInfo, makeEdgeInfo, makePort } from './edgeInfo.js';
+
+/**
+ * Represents an abstract edge in the graph, corresponding to Agedgepair_t.
+ *
+ * IMPORTANT: In Agedgepair_t, the "out" half stores the HEAD node and the
+ * "in" half stores the TAIL node. This is counterintuitive but matches C:
+ *   out.node == head,  in.node == tail
+ * See lib/cgraph/cgraph.h Agedgepair_t and the AGTAIL/AGHEAD macro definitions.
+ *
+ * From cgraph.md "Edge Direction Semantics":
+ *   - tail: source node (arrow comes FROM); AGTAIL(e) = AGMKIN(e)->node = in.node
+ *   - head: destination node (arrow goes TO); AGHEAD(e) = AGMKOUT(e)->node = out.node
+ *   - out-edge: stored in tail node's out-edge set; out.node == head
+ *   - in-edge: stored in head node's in-edge set; in.node == tail
+ *
+ * The `info` field replaces the agbindrec / ED_* mechanism (AD-1).
+ *
+ * @see lib/cgraph/cgraph.h:Agedgepair_s
+ * @see lib/cgraph/cgraph.h:AGTAIL
+ * @see lib/cgraph/cgraph.h:AGHEAD
+ * @see lib/cgraph/cgraph.h:AGMKIN
+ * @see lib/cgraph/cgraph.h:AGMKOUT
+ */
+export class Edge {
+  // Code review: process-wide static seq counter, never reset between renders
+  // (C's AGSEQ lives in a per-agopen Agclos_t). Safe today — every reader only
+  // compares .seq values within one graph's own edges for relative ordering —
+  // and it evades the module-globals fitness scan (a private static field, not
+  // a module-scope `let`). Revisit if any consumer serializes an absolute .seq
+  // or relies on the counter resetting per parse/createGraph.
+  /** @see lib/cgraph/cgraph.h:AGSEQ */
+  private static _nextSeq = 0;
+
+  /**
+   * Monotone sequence number — equivalent to AGSEQ(e) in C.
+   * Used by edgeidcmpf for stable sort ordering.
+   *
+   * Mutable because C's new_virtual_edge overwrites a virtual edge's AGSEQ
+   * with AGSEQ(orig) after allocation; copyVirtualEdgeInfo mirrors that.
+   * @see lib/cgraph/cgraph.h:AGSEQ, lib/dotgen/fastgr.c:new_virtual_edge
+   */
+  seq: number;
+
+  /**
+   * Per-graph creation-order index (1-based).
+   * Set by the parser after root.edges.push(). Used as the SVG edge id,
+   * matching C's AGSEQ-based edge id assignment.
+   */
+  graphSeq: number = 0;
+
+  /**
+   * Source node (arrow origin).
+   * C: AGTAIL(e) = AGMKIN(e)->node = in.node
+   * @see lib/cgraph/cgraph.h:AGTAIL
+   */
+  readonly tail: Node;
+
+  /**
+   * Destination node (arrow target).
+   * C: AGHEAD(e) = AGMKOUT(e)->node = out.node
+   * @see lib/cgraph/cgraph.h:AGHEAD
+   */
+  readonly head: Node;
+
+  /**
+   * Edge key; empty string for anonymous edges.
+   * Corresponds to the `name` argument of agedge().
+   * @see lib/cgraph/cgraph.h:agedge
+   */
+  readonly name: string;
+
+  /**
+   * String attributes (agget/agset equivalents).
+   * @see lib/cgraph/cgraph.h:Agattr_s
+   */
+  attrs: Map<string, string>;
+
+  /**
+   * Layout-engine info; replaces ED_* macros via agbindrec (AD-1).
+   * @see lib/cgraph/cgraph.h:agbindrec
+   */
+  info: EdgeInfo;
+
+  /** @see lib/cgraph/edge.c:agedge */
+  constructor(tail: Node, head: Node, name: string) {
+    this.seq = Edge._nextSeq++;
+    this.tail = tail;
+    this.head = head;
+    this.name = name;
+    this.attrs = new Map();
+    this.info = makeEdgeInfo(makePort(), makePort());
+  }
+}