@knowvah/dot-engine 0.1.0

package/src/model/edgeInfo.ts

@@ -0,0 +1,431 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * TypeScript port of Agedgeinfo_t from lib/common/types.h.
+ *
+ * All ED_* accessor macros in the C source expand to typed reads/writes into
+ * this struct. In TypeScript the macro indirection is unnecessary — consumers
+ * access fields directly on the EdgeInfo object attached to each Edge.
+ *
+ * @see lib/common/types.h:Agedgeinfo_t
+ * @see lib/common/types.h:ED_* macros
+ */
+
+import type { Port, Spline } from './geom.js';
+import type { Edge } from './edge.js';
+import type { TextlabelT } from '../common/types.js';
+import type { ArrowDrawOp } from '../common/arrows-types.js';
+
+/**
+ * Edge layout and rendering info record; replaces the ED_* macro family.
+ *
+ * Required fields are always initialized when an edge is created (matching C
+ * zero-init of the port struct in common_init_edge). All other fields are
+ * optional; they are populated by specific phases of the layout pipeline.
+ *
+ * @see lib/common/types.h:Agedgeinfo_t
+ * @see lib/common/utils.c:common_init_edge
+ */
+export interface EdgeInfo {
+  /**
+   * Tail-end port specification. Always initialized on edge creation.
+   * @see lib/common/types.h:Agedgeinfo_t.tail_port
+   * @see lib/common/types.h:ED_tail_port
+   */
+  tail_port: Port;
+
+  /**
+   * Head-end port specification. Always initialized on edge creation.
+   * @see lib/common/types.h:Agedgeinfo_t.head_port
+   * @see lib/common/types.h:ED_head_port
+   */
+  head_port: Port;
+
+  /**
+   * Rendered spline geometry. Undefined before the spline routing phase.
+   * Set by clip_and_install() in lib/common/splines.c. Do not read before
+   * the layout engine's spline pass has completed.
+   *
+   * @see lib/common/types.h:Agedgeinfo_t.spl
+   * @see lib/common/types.h:ED_spl
+   * @see lib/common/splines.c:clip_and_install
+   */
+  spl?: Spline;
+
+  // -------------------------------------------------------------------------
+  // Labels — AD6: typed as TextlabelT (was unknown until TextLabel was ported).
+  // -------------------------------------------------------------------------
+
+  /**
+   * Center edge label.
+   * @see lib/common/types.h:Agedgeinfo_t.label
+   * @see lib/common/types.h:ED_label
+   */
+  label?: TextlabelT;
+
+  /**
+   * Head-end label (arrowhead side).
+   * @see lib/common/types.h:Agedgeinfo_t.head_label
+   * @see lib/common/types.h:ED_head_label
+   */
+  head_label?: TextlabelT;
+
+  /**
+   * Tail-end label (arrowtail side).
+   * @see lib/common/types.h:Agedgeinfo_t.tail_label
+   * @see lib/common/types.h:ED_tail_label
+   */
+  tail_label?: TextlabelT;
+
+  /**
+   * External label (placed outside the edge spline).
+   * @see lib/common/types.h:Agedgeinfo_t.xlabel
+   * @see lib/common/types.h:ED_xlabel
+   */
+  xlabel?: TextlabelT;
+
+  // -------------------------------------------------------------------------
+  // Arrowhead draw-ops (ADR-1). The C port regenerates arrowheads at render
+  // time from the rotated spline endpoint; this TS port precomputes the typed
+  // primitive list during routing (per arrowhead/arrowtail type) and rotates
+  // it in postproc. Replaces the loose `_arrowPts`/`_tailArrowPts` Point[].
+  // -------------------------------------------------------------------------
+
+  /** Head-end arrow primitives (arrowhead). @see lib/common/arrows.c:arrow_gen */
+  headArrowOps?: ArrowDrawOp[];
+
+  /** Tail-end arrow primitives (arrowtail). @see lib/common/arrows.c:arrow_gen */
+  tailArrowOps?: ArrowDrawOp[];
+
+  // -------------------------------------------------------------------------
+  // Edge metadata
+  // -------------------------------------------------------------------------
+
+  /**
+   * Whether this edge participates in rank constraints.
+   * Corresponds to the `constraint` edge attribute (default: true).
+   * When false, the edge does not constrain rank assignment.
+   * @see lib/dotgen/class1.c:nonconstraint_edge
+   */
+  constraint?: boolean;
+
+  /**
+   * Edge type code: REGULAREDGE / FLATEDGE / SELFEDGE.
+   * Stored as char in C; mapped to number here.
+   * @see lib/common/types.h:Agedgeinfo_t.edge_type
+   * @see lib/common/types.h:ED_edge_type
+   */
+  edge_type?: number;
+
+  /**
+   * True for compound edges (cross-cluster).
+   * Stored as char in C.
+   * @see lib/common/types.h:Agedgeinfo_t.compound
+   * @see lib/common/types.h:ED_compound
+   */
+  compound?: number;
+
+  /**
+   * True for flat edges whose tail and head are adjacent in rank.
+   * Stored as char in C.
+   * @see lib/common/types.h:Agedgeinfo_t.adjacent
+   * @see lib/common/types.h:ED_adjacent
+   */
+  adjacent?: number;
+
+  /**
+   * Whether the edge label is placed above (on top of) the spline.
+   * Stored as char in C.
+   * @see lib/common/types.h:Agedgeinfo_t.label_ontop
+   * @see lib/common/types.h:ED_label_ontop
+   */
+  label_ontop?: number;
+
+  /**
+   * GUI state flags (bitwise OR of GUI_STATE_* constants).
+   * Stored as unsigned char in C.
+   * @see lib/common/types.h:Agedgeinfo_t.gui_state
+   * @see lib/common/types.h:ED_gui_state
+   * @see lib/common/types.h:GUI_STATE_ACTIVE / GUI_STATE_SELECTED / GUI_STATE_VISITED / GUI_STATE_DELETED
+   */
+  gui_state?: number;
+
+  // -------------------------------------------------------------------------
+  // Virtual edge back-pointers (dot layout)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Back-pointer to the original (non-virtual) edge; set on virtual edges
+   * created during dot layout for long-range connections.
+   * @see lib/common/types.h:Agedgeinfo_t.to_orig
+   * @see lib/common/types.h:ED_to_orig
+   * @see lib/common/shapes.c
+   */
+  to_orig?: Edge;
+
+  /**
+   * Back-pointer to the virtual edge that represents this edge in the
+   * rank-spanning chain; set on real edges when a virtual chain exists.
+   * @see lib/common/types.h:Agedgeinfo_t.to_virt
+   * @see lib/common/types.h:ED_to_virt
+   */
+  to_virt?: Edge;
+
+  /**
+   * Routing attempted and routesplines failed: the edge is LOST exactly as in
+   * C (no spline installed, map_edge warns, emit skips). Port-only bookkeeping
+   * so the routeDotEdges backstop does not re-attempt an edge C routes once.
+   * @see lib/common/routespl.c:routesplines (NULL), lib/common/postproc.c:map_edge
+   */
+  lost?: boolean;
+
+  // -------------------------------------------------------------------------
+  // Engine scratch
+  // -------------------------------------------------------------------------
+
+  /**
+   * Layout-engine algorithm scratch pointer. Engine-specific; not typed here.
+   * @see lib/common/types.h:Agedgeinfo_t.alg
+   * @see lib/common/types.h:ED_alg
+   */
+  alg?: unknown;
+
+  // -------------------------------------------------------------------------
+  // dot-specific fields (#ifndef NEATO_ONLY in C)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Edge weight for network simplex. Higher weight means the edge length is
+   * penalized more, biasing ranks toward short edges.
+   * int in C.
+   * @see lib/common/types.h:Agedgeinfo_t.weight
+   * @see lib/common/types.h:ED_weight
+   */
+  weight?: number;
+
+  /**
+   * Minimum rank separation required between tail and head nodes.
+   * int in C.
+   * @see lib/common/types.h:Agedgeinfo_t.minlen
+   * @see lib/common/types.h:ED_minlen
+   */
+  minlen?: number;
+
+  /**
+   * Network-simplex cut value; used during feasible-tree construction.
+   * @see lib/common/types.h:Agedgeinfo_t.cutvalue
+   * @see lib/common/types.h:ED_cutvalue
+   */
+  cutvalue?: number;
+
+  /**
+   * Index into the network-simplex spanning tree edge list.
+   * @see lib/common/types.h:Agedgeinfo_t.tree_index
+   * @see lib/common/types.h:ED_tree_index
+   */
+  tree_index?: number;
+
+  /**
+   * Crossing penalty multiplier for this edge.
+   * short in C.
+   * @see lib/common/types.h:Agedgeinfo_t.xpenalty
+   * @see lib/common/types.h:ED_xpenalty
+   */
+  xpenalty?: number;
+
+  /**
+   * Multiplicity count — number of parallel edges merged into this one
+   * during concentration.
+   * short in C.
+   * @see lib/common/types.h:Agedgeinfo_t.count
+   * @see lib/common/types.h:ED_count
+   */
+  count?: number;
+
+  /**
+   * Concentrated-opposite flag; set when merging parallel edges from
+   * opposing directions.
+   * @see lib/common/types.h:Agedgeinfo_t.conc_opp_flag
+   * @see lib/common/types.h:ED_conc_opp_flag
+   */
+  conc_opp_flag?: boolean;
+
+  /**
+   * Debug: render intermediate routing boxes.
+   * unsigned char in C.
+   * @see lib/common/types.h:Agedgeinfo_t.showboxes
+   * @see lib/common/types.h:ED_showboxes
+   */
+  showboxes?: number;
+
+  /**
+   * True for edges created inside the flat-adjacent auxiliary clone graph
+   * (make_flat_adj_edges). Models C's setState window: cloneGraph re-declares
+   * the aux attribute dictionary via agnxtattr (NAME-sorted), so aux ids are
+   * alphabetical ranks while the global symbols E_arrowsz/E_penwidth — which
+   * setState does NOT remap — keep main-graph declaration-order ids. Inside
+   * the aux, arrow_length's agxget(e, E_arrowsz) therefore mis-indexes into
+   * an unrelated attribute (e.g. #1949: id 1 = `color` → "black"/"blue"),
+   * strtod fails, and late_double falls back to 1.0 for both arrowsize and
+   * penwidth. The arrow POLYGON is unaffected (C regenerates it at emit time
+   * from the original edge). Load-bearing C quirk; consumed by the arrow
+   * clip-length computation only.
+   * @see lib/dotgen/dotsplines.c:setState (E_arrowsz/E_penwidth not remapped)
+   * @see lib/common/arrows.c:arrow_length (late_double(e, E_arrowsz, 1.0, 0.0))
+   */
+  stale_arrow_attrs?: boolean;
+
+  // -------------------------------------------------------------------------
+  // neato/fdp-specific fields (#ifndef DOT_ONLY in C)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Spring factor (ideal edge length multiplier) for spring-model layout.
+   * double in C.
+   * @see lib/common/types.h:Agedgeinfo_t.factor
+   * @see lib/common/types.h:ED_factor
+   */
+  factor?: number;
+
+  /**
+   * Ideal edge length for neato/fdp stress-model layout.
+   * double in C.
+   * @see lib/common/types.h:Agedgeinfo_t.dist
+   * @see lib/common/types.h:ED_dist
+   */
+  dist?: number;
+
+  /**
+   * Path used during spline routing (Ppolyline_t in C).
+   * Typed in Batch 4 when pathplan types are ported.
+   * @see lib/common/types.h:Agedgeinfo_t.path
+   * @see lib/common/types.h:ED_path
+   */
+  path?: unknown; // ED_path — Ppolyline_t in C
+
+
+  // -------------------------------------------------------------------------
+  // samehead / sametail — group id for port merging (sameport.c)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Group id for samehead port merging. Edges sharing this value at the same
+   * head node will be merged onto a single port by dot_sameports().
+   * Corresponds to agxget(e, E_samehead) in the C source.
+   * @see lib/dotgen/sameport.c:dot_sameports
+   */
+  samehead?: string;
+
+  /**
+   * Group id for sametail port merging. Edges sharing this value at the same
+   * tail node will be merged onto a single port by dot_sameports().
+   * Corresponds to agxget(e, E_sametail) in the C source.
+   * @see lib/dotgen/sameport.c:dot_sameports
+   */
+  sametail?: string;
+
+  // -------------------------------------------------------------------------
+  // Compound edge cluster clipping (dot layout)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Name of the cluster subgraph to clip the head of this edge against.
+   * When set, the spline endpoint at the head is clipped to the cluster's
+   * bounding box by dot_compoundEdges(). Corresponds to agget(e, "lhead").
+   * @see lib/dotgen/compound.c:makeCompoundEdge
+   */
+  lhead?: string;
+
+  /**
+   * Name of the cluster subgraph to clip the tail of this edge against.
+   * When set, the spline start at the tail is clipped to the cluster's
+   * bounding box by dot_compoundEdges(). Corresponds to agget(e, "ltail").
+   * @see lib/dotgen/compound.c:makeCompoundEdge
+   */
+  ltail?: string;
+
+  // -------------------------------------------------------------------------
+  // dot layout tracking (TypeScript-only, no C equivalent field)
+  // -------------------------------------------------------------------------
+
+  /**
+   * True if this edge was reversed by acyclic() during cycle-breaking.
+   * Set by reverseEdge() in src/layout/dot/fastgr.ts. Used by dot_splines
+   * to swap bezier control-point order back to tail→head orientation.
+   *
+   * There is no corresponding C field; C detects reversal via rank comparison
+   * in swap_ends_p() (lib/dotgen/dotsplines.c). The TypeScript port adds this
+   * field for explicit tracking.
+   *
+   * @see lib/dotgen/dotsplines.c:swap_ends_p
+   */
+  reversed?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Factory functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a zero-initialized Port matching C's zero-init of the port struct
+ * in common_init_edge.
+ *
+ * @see lib/common/types.h:struct port
+ * @see lib/common/utils.c:common_init_edge
+ */
+export function makePort(): Port {
+  return {
+    p: { x: 0, y: 0 },
+    theta: 0,
+    bp: null,
+    defined: false,
+    constrained: false,
+    // C's default Center port has clip = true; edges clip to the node
+    // boundary unless head/tailclip disables it.
+    // @see lib/common/shapes.c:Center
+    clip: true,
+    dyna: false,
+    order: 0,
+    side: 0,
+    name: null,
+  };
+}
+
+/**
+ * Constructs a minimal EdgeInfo with required port fields initialized.
+ *
+ * Both ports are required — tail_port and head_port are always initialized
+ * when an edge is created (never null in the C model).
+ *
+ * @see lib/common/types.h:Agedgeinfo_t
+ * @see lib/common/utils.c:common_init_edge
+ */
+export function makeEdgeInfo(tailPort: Port, headPort: Port): EdgeInfo {
+  // C agbindrec calloc-zeroes the WHOLE Agedgeinfo_t struct, so every ED_*
+  // field exists from creation at a fixed offset. Mirror that (same treatment
+  // as makeNodeInfo): pre-declare EVERY optional field as value-preserving
+  // `undefined` to pin a single V8 hidden class for all EdgeInfo objects.
+  // Without this, fields added lazily during layout (weight/minlen/cutvalue/
+  // tree_index/edge_type/to_virt/...) drove EdgeInfo into dictionary (slow)
+  // mode — the dominant per-op cost of the network-simplex enter-edge scan
+  // (dfsEnterInedge ~52% of 2371's profile), which reads tree_index, cutvalue
+  // and minlen per candidate edge. No code reads edge.info via `in`/
+  // Object.keys/for-in; the `{...e.info}` spreads copy identical key sets, so
+  // adding the keys is behavior-free. Keep in sync with EdgeInfo.
+  return {
+    tail_port: tailPort,
+    head_port: headPort,
+    // --- lazily-assigned fields, pre-declared to lock the hidden class ---
+    spl: undefined, label: undefined, head_label: undefined, tail_label: undefined,
+    xlabel: undefined, headArrowOps: undefined, tailArrowOps: undefined,
+    constraint: undefined, edge_type: undefined, compound: undefined,
+    adjacent: undefined, label_ontop: undefined, gui_state: undefined,
+    to_orig: undefined, to_virt: undefined, lost: undefined, alg: undefined,
+    weight: undefined, minlen: undefined, cutvalue: undefined, tree_index: undefined,
+    xpenalty: undefined, count: undefined, conc_opp_flag: undefined,
+    showboxes: undefined, stale_arrow_attrs: undefined,
+    factor: undefined, dist: undefined, path: undefined,
+    samehead: undefined, sametail: undefined, lhead: undefined, ltail: undefined,
+    reversed: undefined,
+  };
+}

package/src/model/geom.ts

@@ -0,0 +1,204 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Geometric primitive types ported from lib/common/geom.h and lib/common/types.h.
+ *
+ * @see lib/common/geom.h
+ * @see lib/common/types.h
+ * @see lib/common/const.h
+ */
+
+// ---------------------------------------------------------------------------
+// Points
+// ---------------------------------------------------------------------------
+
+/**
+ * Floating-point 2-D point.
+ *
+ * @see lib/common/geom.h: struct pointf_s { double x, y; }
+ */
+export type Point = { x: number; y: number };
+
+// ---------------------------------------------------------------------------
+// Boxes
+// ---------------------------------------------------------------------------
+
+/**
+ * Floating-point axis-aligned bounding box, defined by lower-left and
+ * upper-right corners.
+ *
+ * C uses uppercase `LL`/`UR`; TypeScript uses `ll`/`ur` per camelCase
+ * convention documented in the port mapping table.
+ *
+ * @see lib/common/geom.h: typedef struct { pointf LL, UR; } boxf
+ */
+export type Box = { ll: Point; ur: Point };
+
+// ---------------------------------------------------------------------------
+// Bezier curves and splines
+// ---------------------------------------------------------------------------
+
+/**
+ * A single Bezier curve segment used in edge spline rendering.
+ *
+ * @see lib/common/types.h: typedef struct bezier
+ */
+export type Bezier = {
+  /** @see lib/common/types.h: pointf *list */
+  list: Point[];
+  /** @see lib/common/types.h: size_t size */
+  size: number;
+  /** @see lib/common/types.h: uint32_t sflag */
+  sflag: number;
+  /** @see lib/common/types.h: uint32_t eflag */
+  eflag: number;
+  /** @see lib/common/types.h: pointf sp */
+  sp: Point;
+  /** @see lib/common/types.h: pointf ep */
+  ep: Point;
+};
+
+/**
+ * A collection of Bezier curves that form an edge spline, together with
+ * its bounding box.
+ *
+ * @see lib/common/types.h: typedef struct splines
+ */
+export type Spline = {
+  /** @see lib/common/types.h: bezier *list */
+  list: Bezier[];
+  /** @see lib/common/types.h: size_t size */
+  size: number;
+  /** @see lib/common/types.h: boxf bb */
+  bb: Box;
+};
+
+// ---------------------------------------------------------------------------
+// Port
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal edge endpoint specification.
+ *
+ * @see lib/common/types.h: typedef struct port
+ */
+export type Port = {
+  /** Aiming point relative to node center. @see lib/common/types.h: pointf p */
+  p: Point;
+  /** Slope in radians. @see lib/common/types.h: double theta */
+  theta: number;
+  /**
+   * When non-null, points to the bounding box of the rectangular port target.
+   * @see lib/common/types.h: boxf *bp
+   */
+  bp: Box | null;
+  /** If true, edge has port info at this end. @see lib/common/types.h: bool defined */
+  defined: boolean;
+  /** If true, constraints such as theta are set. @see lib/common/types.h: bool constrained */
+  constrained: boolean;
+  /** If true, clip end to node/port shape. @see lib/common/types.h: bool clip */
+  clip: boolean;
+  /** If true, assign compass point dynamically. @see lib/common/types.h: bool dyna */
+  dyna: boolean;
+  /** For mincross. @see lib/common/types.h: unsigned char order */
+  order: number;
+  /**
+   * If port is on perimeter of node, contains the bitwise OR of the sides
+   * (TOP, BOTTOM, etc.) it is on.
+   * @see lib/common/types.h: unsigned char side
+   */
+  side: number;
+  /**
+   * Port name if explicitly given, otherwise null.
+   * @see lib/common/types.h: char *name
+   */
+  name: string | null;
+};
+
+// ---------------------------------------------------------------------------
+// Utility functions
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Rotation helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Counter-clockwise rotate point p by ccwrot degrees (0, 90, 180, or 270).
+ *
+ * Matches the four-case switch in lib/common/geom.c:ccwrotatepf exactly:
+ *   0   → identity
+ *   90  → perp(p)  = { x: -p.y, y: p.x }
+ *   180 → { x: p.x, y: -p.y }    (note: keep x, negate y — matches geom.c:180 case)
+ *   270 → exch_xyf(p) = { x: p.y, y: p.x }
+ *
+ * @see lib/common/geom.c:ccwrotatepf
+ */
+export function ccwrotatepf(p: Point, ccwrot: number): Point {
+  switch (ccwrot) {
+    case 0:   return p;
+    case 90:  return { x: -p.y, y: p.x };
+    case 180: return { x: p.x, y: -p.y };
+    case 270: return { x: p.y, y: p.x };
+    default:  return p;
+  }
+}
+
+/**
+ * Returns true if box `b0` completely contains box `b1`.
+ *
+ * Matches the C `CONTAINS` macro exactly:
+ * ```c
+ * #define CONTAINS(b0,b1) \
+ *   (((b0).UR.x >= (b1).UR.x) && ((b0).UR.y >= (b1).UR.y) && \
+ *    ((b0).LL.x <= (b1).LL.x) && ((b0).LL.y <= (b1).LL.y))
+ * ```
+ *
+ * @see lib/common/geom.h: CONTAINS macro
+ */
+export function boxContains(b0: Box, b1: Box): boolean {
+  return (
+    b0.ur.x >= b1.ur.x &&
+    b0.ur.y >= b1.ur.y &&
+    b0.ll.x <= b1.ll.x &&
+    b0.ll.y <= b1.ll.y
+  );
+}
+
+/**
+ * Returns true if boxes `b0` and `b1` intersect (touching edges count).
+ *
+ * Matches the C `OVERLAP` macro exactly:
+ * ```c
+ * #define OVERLAP(b0,b1) (((b0).UR.x >= (b1).LL.x) && ((b1).UR.x >= (b0).LL.x) \
+ *                       && ((b0).UR.y >= (b1).LL.y) && ((b1).UR.y >= (b0).LL.y))
+ * ```
+ *
+ * @see lib/common/geom.h: OVERLAP macro
+ */
+export function boxOverlap(b0: Box, b1: Box): boolean {
+  return (
+    b0.ur.x >= b1.ll.x &&
+    b1.ur.x >= b0.ll.x &&
+    b0.ur.y >= b1.ll.y &&
+    b1.ur.y >= b0.ll.y
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Points per inch — used throughout Graphviz for unit conversion.
+ *
+ * @see lib/common/geom.h: #define POINTS_PER_INCH 72
+ */
+export const POINTS_PER_INCH = 72;
+
+/**
+ * Default line spacing multiplier for multi-line labels.
+ *
+ * @see lib/common/const.h: #define LINESPACING 1.20
+ */
+export const LINESPACING = 1.20;