@knowvah/dot-engine 2.11.0 → 2.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@knowvah/dot-engine",
3
- "version": "2.11.0",
3
+ "version": "2.12.0",
4
4
  "description": "Faithful TypeScript port of Graphviz (dot, neato, fdp, sfdp, circo, twopi, osage, patchwork) — no C: no native binary, no WASM. Oracle-verified against the C implementation, runs in the browser.",
5
5
  "keywords": [
6
6
  "graphviz",
@@ -13,6 +13,10 @@
13
13
  * joined line printed on the held line's channel. A held line is flushed on
14
14
  * its own by {@link agerrLineOn}/{@link agerrFinished} and by render-state
15
15
  * reset.
16
+ *
17
+ * A caller-set {@link agseterrf} function replaces the console as C's
18
+ * `usererrf` replaces `default_usererrf`: it receives the raw pieces `out`
19
+ * writes, and no line is held.
16
20
  */
17
21
 
18
22
  import { registerRenderState } from './render-state.js';
@@ -45,6 +49,31 @@ let lastLevel: 'error' | 'warning' = 'warning';
45
49
  */
46
50
  const pending: { line: string | null; channel: AgerrChannel } = { line: null, channel: 'warn' };
47
51
 
52
+ /**
53
+ * C's `agusererrf`: called with each piece of a message as `out` writes it.
54
+ * The return value is ignored, as C ignores it.
55
+ * @see lib/cgraph/cgraph.h:agusererrf
56
+ */
57
+ export type AgUserErrF = (message: string) => number | void;
58
+
59
+ /**
60
+ * The user-set error function, or null for the console. Process-wide and not
61
+ * reset per render, as C's `usererrf` static is not.
62
+ * @see lib/cgraph/agerror.c:usererrf
63
+ */
64
+ let usererrf: AgUserErrF | null = null;
65
+
66
+ /**
67
+ * Set the function that receives engine messages in place of the console;
68
+ * null restores the console. Returns the previous function.
69
+ * @see lib/cgraph/agerror.c:agseterrf
70
+ */
71
+ export function agseterrf(newf: AgUserErrF | null): AgUserErrF | null {
72
+ const oldf = usererrf;
73
+ usererrf = newf;
74
+ return oldf;
75
+ }
76
+
48
77
  registerRenderState(() => {
49
78
  flushPending();
50
79
  lastLevel = 'warning';
@@ -84,7 +113,8 @@ function flushPending(): void {
84
113
  }
85
114
 
86
115
  function writeLine(channel: AgerrChannel, line: string): void {
87
- if (channel === 'warn') console.warn(escapeControl(line));
116
+ if (usererrf !== null) usererrf(`${line}\n`);
117
+ else if (channel === 'warn') console.warn(escapeControl(line));
88
118
  else console.error(escapeControl(line));
89
119
  }
90
120
 
@@ -95,6 +125,19 @@ function assemble(level: AgerrLevel, msg: string): string {
95
125
  return `${prefix}${PREFIX_SEP}${msg}`;
96
126
  }
97
127
 
128
+ /**
129
+ * `out` with a user function: the prefix and `": "` (none for AGPREV), then
130
+ * the message, each as its own call.
131
+ * @see lib/cgraph/agerror.c:out
132
+ */
133
+ function outToUser(errf: AgUserErrF, level: AgerrLevel, msg: string): void {
134
+ if (level !== 'prev') {
135
+ errf(level === 'error' ? PREFIX_ERROR : PREFIX_WARNING);
136
+ errf(PREFIX_SEP);
137
+ }
138
+ errf(msg);
139
+ }
140
+
98
141
  /** Console channel of a message; AGPREV continues the previous level's. */
99
142
  function channelOf(level: AgerrLevel): AgerrChannel {
100
143
  const eff = level === 'prev' ? lastLevel : level;
@@ -108,6 +151,11 @@ function channelOf(level: AgerrLevel): AgerrChannel {
108
151
  function emit(level: AgerrLevel, msg: string, channel: AgerrChannel | undefined, hold: boolean): void {
109
152
  const target = channel ?? channelOf(level);
110
153
  if (level !== 'prev') lastLevel = level;
154
+ if (usererrf !== null) {
155
+ flushPending();
156
+ outToUser(usererrf, level, hold ? msg : `${msg}\n`);
157
+ return;
158
+ }
111
159
  const text = assemble(level, msg);
112
160
  if (pending.line === null) {
113
161
  pending.channel = target;
package/src/index.ts CHANGED
@@ -143,6 +143,10 @@ export type {
143
143
  GvExpectation,
144
144
  RenderResult,
145
145
  } from './errors.js';
146
+ // Engine messages (graphviz's stderr): a caller-set function receives them
147
+ // in place of the console, as cgraph's agseterrf. @see lib/cgraph/agerror.c
148
+ export { agseterrf } from './common/agerr.js';
149
+ export type { AgUserErrF } from './common/agerr.js';
146
150
  export { setImageSizer } from './gvc/usershape.js';
147
151
  export type { ImageSizer } from './common/htmltable-types.js';
148
152
  export { setImageResolver } from './gvc/image-resolver.js';
@@ -13,7 +13,7 @@
13
13
 
14
14
  import type { Graph } from '../../model/graph.js';
15
15
  import type { Edge as GraphEdge } from '../../model/edge.js';
16
- import type { Point, Box } from '../../model/geom.js';
16
+ import type { Point, Box, Port } from '../../model/geom.js';
17
17
  import type { Node } from '../../model/node.js';
18
18
  import { VIRTUAL, NORMAL } from './fastgr.js';
19
19
  import type { NodeBox } from './edge-route-geom.js';
@@ -229,6 +229,77 @@ function routeChainSegmented(
229
229
  return finishChain(w, endEdge, segs[ei], segFirst, segs) ? w.pts : null;
230
230
  }
231
231
 
232
+ // ---------------------------------------------------------------------------
233
+ // Hackflag views for an edge routed on another edge's chain
234
+ // @see lib/dotgen/dotsplines.c:make_regular_edge (abs(rank diff) > 1)
235
+ // ---------------------------------------------------------------------------
236
+
237
+ /** A port copied by value, as C's struct assignment copies `port`. */
238
+ function copyPort(p: Port): Port {
239
+ return { ...p, p: { ...p.p } };
240
+ }
241
+
242
+ /**
243
+ * C's `fwdedgea`: a copy of `e` from its rank-low end to the first vnode of the
244
+ * chain, head port undefined at (0,0), VIRTUAL with `to_orig = e`. beginpath's
245
+ * side-port clip reset therefore lands on `e` itself.
246
+ */
247
+ function hackflagBeginView(e: GraphEdge, back: boolean, firstVnode: Node): GraphEdge {
248
+ const tailPort = back ? e.info.head_port : e.info.tail_port;
249
+ return {
250
+ ...e,
251
+ tail: back ? e.head : e.tail,
252
+ head: firstVnode,
253
+ info: {
254
+ ...e.info,
255
+ tail_port: copyPort(tailPort),
256
+ head_port: { ...copyPort(e.info.head_port), defined: false, p: { x: 0, y: 0 } },
257
+ edge_type: VIRTUAL,
258
+ to_orig: e,
259
+ },
260
+ } as GraphEdge;
261
+ }
262
+
263
+ /**
264
+ * C's `fwdedgeb`: for a back edge, `makefwdedge(e)` (VIRTUAL, `to_orig = e`);
265
+ * otherwise a plain struct copy of `e` that stays NORMAL, so endpath's
266
+ * side-port clip reset lands on the copy and `e` keeps its head clip.
267
+ */
268
+ function hackflagEndView(e: GraphEdge, back: boolean): GraphEdge {
269
+ if (back) return makeFwdEdge(e);
270
+ return {
271
+ ...e,
272
+ info: { ...e.info, tail_port: copyPort(e.info.tail_port), head_port: copyPort(e.info.head_port) },
273
+ } as GraphEdge;
274
+ }
275
+
276
+ /**
277
+ * The edges that drive the chain's first beginpath and last endpath. A chain
278
+ * owned by `e` itself is C's ordinary walk from the first to the last fast
279
+ * edge. A chain owned by another edge means class2 merged `e` into it
280
+ * (`merge_chain`), so `e` sits in ND_other and C's group loop hands the real
281
+ * edge to make_regular_edge, which takes the hackflag branch: beginpath on
282
+ * `fwdedgea`, endpath on `fwdedgeb`. Driving those calls with the owner's
283
+ * segments reset the owner's clip flags instead of `e`'s (plantuml-ts 41).
284
+ * @see lib/dotgen/dotsplines.c:make_regular_edge (hackflag)
285
+ * @see lib/dotgen/class2.c:class2 (merge_chain, other_edge)
286
+ */
287
+ function chainEnds(e: GraphEdge, segs: GraphEdge[]): [GraphEdge, GraphEdge] {
288
+ const first = segs[0];
289
+ const last = segs[segs.length - 1];
290
+ const orig = resolveOrigEdge(e);
291
+ if (resolveOrigEdge(first) === orig) return [first, last];
292
+ const back = (orig.head.info.rank ?? 0) < (orig.tail.info.rank ?? 0);
293
+ return [hackflagBeginView(orig, back, first.head), hackflagEndView(orig, back)];
294
+ }
295
+
296
+ /** True when `e` runs forward across two or more ranks of a ranked graph. */
297
+ function spansRanksForward(g: Graph, e: GraphEdge): boolean {
298
+ const r = e.tail.info.rank;
299
+ const rh = e.head.info.rank;
300
+ return g.info.rank !== undefined && r !== undefined && rh !== undefined && rh > r + 1;
301
+ }
302
+
232
303
  /**
233
304
  * Route a forward edge spanning ≥2 ranks via its virtual-node chain through the
234
305
  * faithful pipeline (REGULAREDGE side boxes steer the port, routeSplines over
@@ -240,9 +311,7 @@ function routeChainSegmented(
240
311
  * @see lib/dotgen/dotsplines.c:make_regular_edge (hackflag forward path)
241
312
  */
242
313
  export function routeMultiRankEdgeFaithful(g: Graph, e: GraphEdge): Point[] | null | 'lost' {
243
- const r = e.tail.info.rank;
244
- const rh = e.head.info.rank;
245
- if (g.info.rank === undefined || r === undefined || rh === undefined || rh <= r + 1) return null;
314
+ if (!spansRanksForward(g, e)) return null;
246
315
  const et = edgeType(g);
247
316
  // EDGETYPE_LINE: C tries makeLineEdge first (direct tail→head segment),
248
317
  // falling back to the box corridor only when it declines (delr==1, or delr==2
@@ -261,8 +330,10 @@ export function routeMultiRankEdgeFaithful(g: Graph, e: GraphEdge): Point[] | nu
261
330
  // endpath with the LAST (each carries the orig's copied port, so a dyna
262
331
  // record port resolves toward the adjacent-rank vnode, not the far real
263
332
  // endpoint). @see lib/dotgen/dotsplines.c:make_regular_edge (tn/hn walk),
264
- // lib/dotgen/fastgr.c:new_virtual_edge (port copies)
265
- return routeChainSegmented(g, segs[0], segs[segs.length - 1], segs) ?? 'lost';
333
+ // lib/dotgen/fastgr.c:new_virtual_edge (port copies). An edge merged into
334
+ // another's chain takes the hackflag views instead (chainEnds).
335
+ const [beginEdge, endEdge] = chainEnds(e, segs);
336
+ return routeChainSegmented(g, beginEdge, endEdge, segs) ?? 'lost';
266
337
  }
267
338
 
268
339
  /**
@@ -415,7 +486,8 @@ export function routeBackEdge(e: GraphEdge, _tailBox: NodeBox, _headBox: NodeBox
415
486
  // (fastgr new_virtual_edge copy rules); fwdEdge remains the clip target so
416
487
  // bezier_clip keeps the load-bearing forward direction (1644).
417
488
  // @see lib/dotgen/dotsplines.c:make_regular_edge (segfirst/tn/hn walk)
418
- const fwd = routeChainSegmented(g, segs[0], segs[segs.length - 1], segs);
489
+ const [beginEdge, endEdge] = chainEnds(e, segs);
490
+ const fwd = routeChainSegmented(g, beginEdge, endEdge, segs);
419
491
  // Chain routing failed: C's make_regular_edge returns with no spline and
420
492
  // dot_splines_ never revisits the edge — mark it consumed so the backstop
421
493
  // sweep does not re-route (and re-report) it.
@@ -26,7 +26,7 @@ import { dispatchOrthoEdges } from './ortho-adapter.js';
26
26
  import { routeEdgeGroups } from './splines-groups.js';
27
27
  import { placePortLabels, placeRegularEdgeLabels, setEdgeLabelPos } from './splines-label.js';
28
28
  import { nodesInSeq } from './decomp.js';
29
- import { agerrLineOn } from '../../common/agerr.js';
29
+ import { agwarningf } from '../../common/agerr.js';
30
30
  import { setState, GVSPLINES } from '../../common/layout-state.js';
31
31
 
32
32
  // ---------------------------------------------------------------------------
@@ -476,7 +476,7 @@ function orthoDispatch(g: Graph): number {
476
476
  function curvedTop(g: Graph): void {
477
477
  resetRW(g);
478
478
  if (((g.root.info.has_labels ?? 0) & EDGE_LABEL) !== 0) {
479
- agerrLineOn('warn', 'edge labels with splines=curved not supported in dot - use xlabels\n');
479
+ agwarningf('edge labels with splines=curved not supported in dot - use xlabels');
480
480
  }
481
481
  }
482
482
 
@@ -27,7 +27,7 @@ import { fdpLayout, mkClusters } from './layout.js';
27
27
  import { gdata } from './fdp-model.js';
28
28
  import { graphInit } from '../../common/graph-init.js';
29
29
  import { csrand } from '../../common/crand.js';
30
- import { agerrLineOn } from '../../common/agerr.js';
30
+ import { agwarningf } from '../../common/agerr.js';
31
31
 
32
32
  export { fdpLayout, mkClusters, evalPositions, setBB } from './layout.js';
33
33
  export { fdpTLayout } from './tlayout.js';
@@ -94,7 +94,7 @@ function fdpSplines(g: Graph): void {
94
94
  );
95
95
  }
96
96
  if (g.info.n_cluster_edges) { // HAS_CLUST_EDGE(g)
97
- agerrLineOn('warn', CLUSTER_EDGE_WARNING);
97
+ agwarningf(CLUSTER_EDGE_WARNING);
98
98
  et = EDGETYPE_LINE;
99
99
  } else {
100
100
  splineEdges1(g, et);
@@ -18,7 +18,7 @@ import { drand48 } from '../../common/random.js';
18
18
  import { lateDouble } from '../../common/nodeinit.js';
19
19
  import { checkStart, parseStart, INIT_RANDOM, INIT_REGULAR } from './start.js';
20
20
  import { jitter3d, ndimOf } from './init-dim.js';
21
- import { agerrLineOn } from '../../common/agerr.js';
21
+ import { agwarningf } from '../../common/agerr.js';
22
22
 
23
23
  // ---------------------------------------------------------------------------
24
24
  // Model constants — @see lib/neatogen/defs.h
@@ -415,17 +415,11 @@ export function buildUnfixed(g: Graph, n: number): boolean[] {
415
415
  */
416
416
  export function resolveModel(model: number): number {
417
417
  if (model === MODEL_CIRCUIT) {
418
- agerrLineOn(
419
- 'warn',
420
- 'circuit model not yet supported in Gmode=sgd, reverting to shortpath model',
421
- );
418
+ agwarningf('circuit model not yet supported in Gmode=sgd, reverting to shortpath model');
422
419
  return MODEL_SHORTPATH;
423
420
  }
424
421
  if (model === MODEL_MDS) {
425
- agerrLineOn(
426
- 'warn',
427
- 'mds model not yet supported in Gmode=sgd, reverting to shortpath model',
428
- );
422
+ agwarningf('mds model not yet supported in Gmode=sgd, reverting to shortpath model');
429
423
  return MODEL_SHORTPATH;
430
424
  }
431
425
  return model;