@knowvah/dot-engine 2.12.4 → 2.13.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.12.4",
3
+ "version": "2.13.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",
package/src/errors.ts CHANGED
@@ -45,6 +45,8 @@ export interface GvError {
45
45
  location?: { line: number; column: number; offset?: number };
46
46
  /** Peggy's discriminated union, passed through unmapped; SYNTAX_* only. */
47
47
  expected?: GvExpectation[];
48
+ /** Named values the message refers to (e.g. `{ node }`); string-valued. */
49
+ context?: Record<string, string>;
48
50
  }
49
51
 
50
52
  /** Result of a result-style render: `svg` XOR `errors` for v1. */
@@ -91,6 +93,11 @@ const SEMANTIC_RENDER_CODES: ReadonlySet<GvErrorCode> = new Set<GvErrorCode>([
91
93
  'UNSUPPORTED_FEATURE',
92
94
  ]);
93
95
 
96
+ /** `ErrorOptions` plus the optional structured {@link GvError.context}. */
97
+ export interface DotEngineErrorOptions extends ErrorOptions {
98
+ context?: Record<string, string>;
99
+ }
100
+
94
101
  /**
95
102
  * Abstract base of every library-originated error: `instanceof
96
103
  * DotEngineError` means dot-engine failed on this input (bad input, a fatal
@@ -101,9 +108,12 @@ export abstract class DotEngineError extends Error implements GvError {
101
108
  abstract readonly type: GvErrorType;
102
109
  abstract readonly code: GvErrorCode;
103
110
  abstract readonly friendlyMessage: string;
111
+ /** `declare`: no own property unless the caller supplied a context. */
112
+ declare context?: Record<string, string>;
104
113
 
105
- constructor(message: string, options?: ErrorOptions) {
114
+ constructor(message: string, options?: DotEngineErrorOptions) {
106
115
  super(message, options);
116
+ if (options?.context !== undefined) this.context = options.context;
107
117
  }
108
118
  }
109
119
 
@@ -113,7 +123,7 @@ export class InternalError extends DotEngineError {
113
123
  readonly code = 'INTERNAL_ERROR';
114
124
  readonly friendlyMessage = friendlyMessageFor('INTERNAL_ERROR');
115
125
 
116
- constructor(message: string, options?: ErrorOptions) {
126
+ constructor(message: string, options?: DotEngineErrorOptions) {
117
127
  super(message, options);
118
128
  this.name = 'InternalError';
119
129
  }
@@ -131,7 +141,7 @@ export class RenderError extends DotEngineError {
131
141
  constructor(
132
142
  message: string,
133
143
  code: GvErrorCode = 'RENDER_ERROR',
134
- options?: ErrorOptions,
144
+ options?: DotEngineErrorOptions,
135
145
  ) {
136
146
  super(message, options);
137
147
  this.name = 'RenderError';
@@ -27,6 +27,7 @@ import type { ImageSizer } from '../common/htmltable-types.js';
27
27
  import type { ImageResolver } from './image-resolver.js';
28
28
  import type { RenderJob } from './job.js'; // scaffold in T25; full class in T26
29
29
  import { resetRenderState } from '../common/render-state.js';
30
+ import { agerrorf } from '../common/agerr.js';
30
31
  import { RenderError, invalidArgType, invalidArgValue } from '../errors.js';
31
32
  import { bindDotRoot, resetFreedLayouts, undoRenderedClusterEdges } from './layout-reset.js';
32
33
  import { initXdot } from './init-xdot.js';
@@ -326,12 +327,7 @@ export class GvcContext {
326
327
  let engine = selected;
327
328
  if (attr !== undefined && attr !== '') {
328
329
  const override = this.layouts.get(attr);
329
- if (override === undefined) {
330
- throw new RenderError(
331
- `Layout type: "${attr}" not recognized`,
332
- 'UNKNOWN_LAYOUT',
333
- );
334
- }
330
+ if (override === undefined) throw this.unknownLayout(attr);
335
331
  engine = override;
336
332
  }
337
333
  undoRenderedClusterEdges(g);
@@ -352,6 +348,25 @@ export class GvcContext {
352
348
  if (g.info) g.info.laidOut = true;
353
349
  }
354
350
 
351
+ /**
352
+ * C's `agerrorf("Layout type: \"%s\" not recognized. Use one of:%s\n", ...)`
353
+ * (`gvplugin_list` writes each type as a leading space + name), then the
354
+ * structured error. The thrown wording may differ from the agerr text.
355
+ * @see lib/gvc/gvlayout.c:gvLayoutJobs
356
+ */
357
+ private unknownLayout(attr: string): RenderError {
358
+ const list = [...this.layouts.keys()]
359
+ .sort()
360
+ .map((name: string) => ` ${name}`)
361
+ .join('');
362
+ agerrorf(`Layout type: "${attr}" not recognized. Use one of:${list}`);
363
+ return new RenderError(
364
+ `Layout type: "${attr}" not recognized. Use one of:${list}.`,
365
+ 'UNKNOWN_LAYOUT',
366
+ { context: { layout: attr } },
367
+ );
368
+ }
369
+
355
370
  /**
356
371
  * Release engine layout state after rendering. The records themselves stay,
357
372
  * for getLayout, until the next layout replaces them (part-9 AD-11, see
package/src/index.ts CHANGED
@@ -52,6 +52,7 @@ function classifyError(err: unknown): GvError {
52
52
  };
53
53
  if (gv.location !== undefined) out.location = gv.location;
54
54
  if (gv.expected !== undefined) out.expected = gv.expected;
55
+ if (gv.context !== undefined) out.context = { ...gv.context };
55
56
  return out;
56
57
  }
57
58
 
@@ -17,6 +17,8 @@ import type { Graph } from '../../model/graph.js';
17
17
  import type { Node } from '../../model/node.js';
18
18
  import { buildOutEdgeIndex } from '../../model/node.js';
19
19
  import type { Edge } from '../../model/edge.js';
20
+ import { agerrorf } from '../../common/agerr.js';
21
+ import { RenderError } from '../../errors.js';
20
22
  import {
21
23
  VIRTUAL,
22
24
  virtualNode, virtualEdge, fastNode, flatEdge,
@@ -68,6 +70,7 @@ export function nonconstraintEdge(e: Edge): boolean {
68
70
  const WNODE_ORDINARY = 0;
69
71
  const WNODE_SINGLETON = 1;
70
72
  const WNODE_VIRTUAL = 2;
73
+ const INT_MAX = 2147483647;
71
74
  const CLASSIFY_WEIGHT_TABLE = [[1, 1, 1], [1, 2, 2], [1, 2, 4]];
72
75
 
73
76
  function epClass(n: Node): number {
@@ -79,7 +82,26 @@ function epClass(n: Node): number {
79
82
  /** @see lib/dotgen/mincross.c:virtual_weight (inlined to avoid cycle) */
80
83
  function applyVirtualWeight(e: Edge): void {
81
84
  const t = CLASSIFY_WEIGHT_TABLE[epClass(e.tail)][epClass(e.head)];
82
- e.info.weight = (e.info.weight ?? 1) * t;
85
+ const w = e.info.weight ?? 1;
86
+ // C: INT_MAX / t < ED_weight(e), int division, before the multiply.
87
+ if (Math.trunc(INT_MAX / t) < w) throw virtualWeightOverflow(e, t);
88
+ e.info.weight = w * t;
89
+ }
90
+
91
+ /**
92
+ * C `agerrorf` + `graphviz_exit(EXIT_FAILURE)`: the stderr line verbatim,
93
+ * then the structured throw naming the original edge.
94
+ * @see lib/dotgen/mincross.c:virtual_weight
95
+ */
96
+ function virtualWeightOverflow(e: Edge, t: number): RenderError {
97
+ agerrorf('overflow when calculating virtual weight of edge');
98
+ const o = e.info.to_orig ?? e;
99
+ const name = `${o.tail.name}->${o.head.name}`;
100
+ return new RenderError(
101
+ `Edge "${name}" has a weight too large for the layout (weight x ${t} exceeds the 32-bit integer limit); lower its weight attribute.`,
102
+ 'RENDER_ERROR',
103
+ { context: { edge: name } },
104
+ );
83
105
  }
84
106
 
85
107
  // ---------------------------------------------------------------------------
@@ -3,6 +3,8 @@
3
3
  import type { Node } from '../../model/node.js';
4
4
  import type { Edge } from '../../model/edge.js';
5
5
  import type { EdgeList } from '../../model/nodeInfo.js';
6
+ import { agerrorf } from '../../common/agerr.js';
7
+ import { RenderError } from '../../errors.js';
6
8
  import { seq, isTreeEdge } from './ns-core.js';
7
9
  import type { NsCtx } from './ns-core.js';
8
10
 
@@ -77,15 +79,49 @@ export function xVal(e: Edge, v: Node, dir: number): number {
77
79
  return d < 0 ? -rv : rv;
78
80
  }
79
81
 
82
+ const INT_MAX = 2147483647;
83
+ const INT_MIN = -2147483648;
84
+
85
+ /**
86
+ * `sadd_overflow` as x_cutval uses it: add in int32 range, report overflow.
87
+ * @see lib/common/ns.c:x_cutval
88
+ */
89
+ function sumOverflows(sum: number, add: number): boolean {
90
+ const s = sum + add;
91
+ return s > INT_MAX || s < INT_MIN;
92
+ }
93
+
94
+ /**
95
+ * C `agerrorf` + `graphviz_exit(EXIT_FAILURE)`: the stderr line verbatim,
96
+ * then the structured throw.
97
+ * @see lib/common/ns.c:x_cutval
98
+ */
99
+ function cutvalOverflow(v: Node): RenderError {
100
+ agerrorf('overflow when computing edge weight sum');
101
+ return new RenderError(
102
+ `Edge weights at node "${v.name}" sum past the 32-bit integer limit; lower the weight attribute values.`,
103
+ 'RENDER_ERROR',
104
+ { context: { node: v.name } },
105
+ );
106
+ }
107
+
108
+ /** Add one edge list's x_val terms to `sum`, in C order. @see x_cutval */
109
+ function sumXVals(list: EdgeList | undefined, v: Node, dir: number, sum: number): number {
110
+ if (!list) return sum;
111
+ for (let i = 0; i < list.size; i++) {
112
+ const add = xVal(list.list[i], v, dir);
113
+ if (sumOverflows(sum, add)) throw cutvalOverflow(v);
114
+ sum += add;
115
+ }
116
+ return sum;
117
+ }
118
+
80
119
  /** @see lib/common/ns.c:x_cutval */
81
120
  export function xCutval(f: Edge): void {
82
121
  const v = f.tail.info.par === f ? f.tail : f.head;
83
122
  const dir = f.tail.info.par === f ? 1 : -1;
84
- let sum = 0;
85
- const out = v.info.out;
86
- if (out) for (let i = 0; i < out.size; i++) sum += xVal(out.list[i], v, dir);
87
- const inp = v.info.in;
88
- if (inp) for (let i = 0; i < inp.size; i++) sum += xVal(inp.list[i], v, dir);
123
+ let sum = sumXVals(v.info.out, v, dir, 0);
124
+ sum = sumXVals(v.info.in, v, dir, sum);
89
125
  f.info.cutvalue = sum;
90
126
  }
91
127