@knowvah/dot-engine 1.9.0 → 2.0.1

package/src/errors.ts

@@ -27,6 +27,9 @@ export type GvErrorCode =
   | 'EDGE_OP_UNDIRECTED_IN_DIRECTED' // '--' used in a digraph
   | 'HTML_PARSE_ERROR' // HTML-like label parse failure
   | 'RENDER_ERROR' // known layout/render-stage failure
+  | 'INTERNAL_ERROR' // dot-engine bug (assert / invariant / foreign throw)
+  | 'UNKNOWN_LAYOUT' // graph layout="..." names no registered engine
+  | 'UNSUPPORTED_FEATURE' // graph uses a Graphviz feature not yet ported
   | 'GENERIC_ERROR'; // catch-all fallback
 
 /** Structured error contract shared by every error source. */
@@ -66,6 +69,11 @@ export const FRIENDLY_MESSAGES: Record<GvErrorCode, string> = {
     "An undirected edge '--' was used in a directed graph; use '->' instead.",
   HTML_PARSE_ERROR: 'An HTML-like label could not be parsed.',
   RENDER_ERROR: 'The graph could not be laid out or rendered.',
+  INTERNAL_ERROR:
+    'dot-engine hit an internal bug while processing the graph. Please report it with the DOT source that triggered it.',
+  UNKNOWN_LAYOUT: 'The graph names a layout engine that is not available.',
+  UNSUPPORTED_FEATURE:
+    'The graph uses a Graphviz feature that dot-engine does not support yet.',
   GENERIC_ERROR: 'An unexpected error occurred while rendering the graph.',
 };
 
@@ -77,19 +85,194 @@ export function friendlyMessageFor(code: GvErrorCode): string {
   return FRIENDLY_MESSAGES[code];
 }
 
+/** Codes a {@link RenderError} types as `semantic` rather than `render`. */
+const SEMANTIC_RENDER_CODES: ReadonlySet<GvErrorCode> = new Set<GvErrorCode>([
+  'UNKNOWN_LAYOUT',
+  'UNSUPPORTED_FEATURE',
+]);
+
 /**
- * Error thrown for known layout/render-stage failures. Only `RENDER_ERROR`
- * and `GENERIC_ERROR` are valid render-stage codes.
+ * Abstract base of every library-originated error: `instanceof
+ * DotEngineError` means dot-engine failed on this input (bad input, a fatal
+ * error Graphviz itself would report, or a dot-engine bug). Each subclass
+ * sets a hard-coded `name`.
  */
-export class RenderError extends Error implements GvError {
+export abstract class DotEngineError extends Error implements GvError {
+  abstract readonly type: GvErrorType;
+  abstract readonly code: GvErrorCode;
+  abstract readonly friendlyMessage: string;
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+  }
+}
+
+/** A dot-engine bug: failed assertion, broken invariant or foreign throw. */
+export class InternalError extends DotEngineError {
   readonly type = 'render';
+  readonly code = 'INTERNAL_ERROR';
+  readonly friendlyMessage = friendlyMessageFor('INTERNAL_ERROR');
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'InternalError';
+  }
+}
+
+/**
+ * Error thrown for known layout/render-stage failures. `type` is `semantic`
+ * for `UNKNOWN_LAYOUT` / `UNSUPPORTED_FEATURE`, otherwise `render`.
+ */
+export class RenderError extends DotEngineError {
+  readonly type: GvErrorType;
   readonly code: GvErrorCode;
   readonly friendlyMessage: string;
 
-  constructor(message: string, code: GvErrorCode = 'RENDER_ERROR') {
-    super(message);
+  constructor(
+    message: string,
+    code: GvErrorCode = 'RENDER_ERROR',
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
     this.name = 'RenderError';
     this.code = code;
+    this.type = SEMANTIC_RENDER_CODES.has(code) ? 'semantic' : 'render';
     this.friendlyMessage = friendlyMessageFor(code);
   }
 }
+
+/** Guard shared by every boundary: structural check, works across bundles. */
+export function isGvError(e: unknown): e is GvError {
+  if (typeof e !== 'object' || e === null) return false;
+  const c = e as { type?: unknown; code?: unknown };
+  return typeof c.type === 'string' && typeof c.code === 'string';
+}
+
+// ── Usage errors (caller mistakes; not DotEngineError, not GvError) ─────────
+
+/** Node-style codes carried by caller-mistake errors. */
+export type UsageErrorCode =
+  | 'ERR_INVALID_ARG_TYPE'
+  | 'ERR_INVALID_ARG_VALUE'
+  | 'ERR_OUT_OF_RANGE'
+  | 'ERR_INVALID_STATE';
+
+/** TypeError carrying a usage code; `name` stays `TypeError`. */
+export class UsageTypeError extends TypeError {
+  readonly code: UsageErrorCode;
+
+  constructor(message: string, code: UsageErrorCode) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/** RangeError carrying a usage code; `name` stays `RangeError`. */
+export class UsageRangeError extends RangeError {
+  readonly code: UsageErrorCode;
+
+  constructor(message: string, code: UsageErrorCode) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/** Error carrying a usage code; `name` stays `Error`. */
+export class UsageStateError extends Error {
+  readonly code: UsageErrorCode;
+
+  constructor(message: string, code: UsageErrorCode) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/** Short description of a received value for usage-error messages. */
+function describeReceived(v: unknown): string {
+  if (v === null || v === undefined) return String(v);
+  switch (typeof v) {
+    case 'string':
+      return `string ${JSON.stringify(v)}`;
+    case 'number':
+    case 'boolean':
+    case 'bigint':
+      return `${typeof v} ${String(v)}`;
+    case 'function':
+      return 'a function';
+    case 'symbol':
+      return 'a symbol';
+    default: {
+      const ctor = (v as { constructor?: { name?: unknown } }).constructor;
+      return typeof ctor?.name === 'string' && ctor.name !== ''
+        ? `an instance of ${ctor.name}`
+        : 'an object';
+    }
+  }
+}
+
+/** Wrong type, `null` or a missing required argument. */
+export function invalidArgType(
+  param: string,
+  expected: string,
+  actual: unknown,
+): TypeError {
+  return new UsageTypeError(
+    `The "${param}" argument must be of type ${expected}. Received ${describeReceived(actual)}`,
+    'ERR_INVALID_ARG_TYPE',
+  );
+}
+
+/** Unknown engine/format name (or other enum-like value) as an argument. */
+export function invalidArgValue(
+  param: string,
+  value: unknown,
+  allowed: readonly string[],
+): TypeError {
+  return new UsageTypeError(
+    `The argument "${param}" is invalid. Received ${JSON.stringify(value)}; allowed: ${allowed.join(', ')}`,
+    'ERR_INVALID_ARG_VALUE',
+  );
+}
+
+/** Numeric argument outside its range. */
+export function outOfRange(
+  param: string,
+  range: string,
+  value: number,
+): RangeError {
+  return new UsageRangeError(
+    `The value of "${param}" is out of range. It must be ${range}. Received ${String(value)}`,
+    'ERR_OUT_OF_RANGE',
+  );
+}
+
+/** Call made in the wrong state (e.g. `getLayout` before layout). */
+export function invalidState(message: string): Error {
+  return new UsageStateError(message, 'ERR_INVALID_STATE');
+}
+
+/** True for errors built by the usage-error factories. */
+export function isUsageError(e: unknown): boolean {
+  return (
+    e instanceof UsageTypeError ||
+    e instanceof UsageRangeError ||
+    e instanceof UsageStateError
+  );
+}
+
+// ── Public-boundary catch (shared by every entry point; not re-exported) ────
+
+/** Message of any thrown value. */
+export function messageOf(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Boundary `catch` (ADR-5): usage errors and {@link GvError}s re-surface
+ * unchanged; anything else is a dot-engine bug and becomes an
+ * {@link InternalError} keeping the original as `cause`.
+ */
+export function rethrowAtBoundary(err: unknown): never {
+  if (isUsageError(err) || isGvError(err)) throw err;
+  throw new InternalError(messageOf(err), { cause: err });
+}

package/src/gvc/context.ts

@@ -23,7 +23,10 @@ import type { Point, Box } from '../model/geom.js';
 import type { TextSpan } from '../common/emit-types.js';
 import type { TextMeasurer } from '../common/textmeasure.js';
 import type { DebugOptions } from '../debug.js';
+import type { ImageSizer } from '../common/htmltable-types.js';
+import type { ImageResolver } from './image-resolver.js';
 import type { RenderJob } from './job.js';  // scaffold in T25; full class in T26
+import { RenderError, invalidArgType, invalidArgValue } from '../errors.js';
 
 // ---------------------------------------------------------------------------
 // Enums — match C definitions in lib/gvc/gvcjob.h exactly
@@ -165,6 +168,24 @@ class PluginRegistry {
   }
 }
 
+/** Argument check for a TextMeasurer parameter (ADR-3). */
+function checkMeasurer(m: unknown): void {
+  if (typeof m !== 'object' || m === null
+      || typeof (m as { measure?: unknown }).measure !== 'function') {
+    throw invalidArgType('measurer', 'TextMeasurer', m);
+  }
+}
+
+/** Argument check for `register` (ADR-3): shape of a plugin, not its behaviour. */
+function checkPlugin(p: unknown): void {
+  const o = p as { type?: unknown; quality?: unknown; layout?: unknown; cleanup?: unknown };
+  const ok = typeof p === 'object' && p !== null && typeof o.type === 'string'
+    && ('quality' in o
+      ? typeof o.quality === 'number'
+      : typeof o.layout === 'function' && typeof o.cleanup === 'function');
+  if (!ok) throw invalidArgType('p', 'RendererPlugin or LayoutEngine', p);
+}
+
 /**
  * Root Graphviz context.  Owns the plugin registry, text measurer, and
  * the layout-engine dispatch.
@@ -180,15 +201,40 @@ export class GvcContext {
   textMeasurer: TextMeasurer;
   readonly debug: DebugOptions | undefined;
 
+  /**
+   * Per-context HTML `<IMG>` sizer; takes precedence over the global
+   * `setImageSizer`. Undefined by default. @see ADR-2 (async-api)
+   */
+  imageSizer?: ImageSizer;
+  /**
+   * Per-context image resolver for `inlineImages`; takes precedence over the
+   * global `setImageResolver`. Undefined by default. @see ADR-2 (async-api)
+   */
+  imageResolver?: ImageResolver;
+
+  /**
+   * @throws TypeError `ERR_INVALID_ARG_TYPE` if `measurer` has no `measure`
+   *   function or `options` is neither undefined nor an object
+   */
   constructor(measurer: TextMeasurer, options?: { debug?: DebugOptions }) {
+    checkMeasurer(measurer);
+    if (options !== undefined && (typeof options !== 'object' || options === null)) {
+      throw invalidArgType('options', 'object or undefined', options);
+    }
     this.textMeasurer = measurer;
     this.debug = options?.debug;
   }
 
-  /** Register a renderer or layout engine; overload discriminated by `quality`. */
+  /**
+   * Register a renderer or layout engine; overload discriminated by `quality`.
+   * @throws TypeError `ERR_INVALID_ARG_TYPE` if `p` is not a renderer plugin
+   *   (string `type`, numeric `quality`) or a layout engine (string `type`,
+   *   `layout` and `cleanup` functions)
+   */
   register(p: RendererPlugin): void;
   register(p: LayoutEngine): void;
   register(p: RendererPlugin | LayoutEngine): void {
+    checkPlugin(p);
     if ('quality' in p) {
       const idx = PluginRegistry.insertionIdx(this.renderers, p);
       this.renderers.splice(idx, 0, p);
@@ -202,14 +248,35 @@ export class GvcContext {
    * Because renderers are sorted quality-descending within a prefix, the first
    * match is always the highest-quality one (last-registered wins on tie).
    *
-   * @throws Error if no renderer is registered for format
+   * @throws TypeError (ERR_INVALID_ARG_TYPE) if format is not a string
+   * @throws TypeError (ERR_INVALID_ARG_VALUE) if no renderer is registered
+   *   for format
    * @see lib/gvc/gvplugin.c:gvplugin_find
    */
   bestRenderer(format: string): RendererPlugin {
+    if (typeof format !== 'string') {
+      throw invalidArgType('format', 'string', format);
+    }
     for (const r of this.renderers) {
       if (r.type.split(':')[0] === format) return r;
     }
-    throw new Error(`no renderer registered for format: ${format}`);
+    const prefixes = new Set(this.renderers.map((r) => r.type.split(':')[0]!));
+    throw invalidArgValue('format', format, [...prefixes]);
+  }
+
+  /** Validate the `(g, engineName)` arguments shared by layout/freeLayout. */
+  private checkLayoutArgs(g: Graph, engineName: EngineName): LayoutEngine {
+    if (typeof g !== 'object' || g === null) {
+      throw invalidArgType('g', 'object', g);
+    }
+    if (typeof engineName !== 'string') {
+      throw invalidArgType('engine', 'string', engineName);
+    }
+    const engine = this.layouts.get(engineName);
+    if (engine === undefined) {
+      throw invalidArgValue('engine', engineName, [...this.layouts.keys()]);
+    }
+    return engine;
   }
 
   /**
@@ -218,27 +285,37 @@ export class GvcContext {
    * rendering happens in between and must see the layout state
    * (e.g. cluster arrays).
    *
-   * @throws Error if the engine is not registered
+   * @throws TypeError (ERR_INVALID_ARG_TYPE / ERR_INVALID_ARG_VALUE) for a
+   *   bad `g`, or an engine argument that is not registered
+   * @throws RenderError (UNKNOWN_LAYOUT) if the `layout` attribute names no
+   *   registered engine
+   * @throws RenderError (RENDER_ERROR / UNSUPPORTED_FEATURE) or InternalError
+   *   from the engine itself, unwrapped; a foreign throw from an engine bug
+   *   also propagates unwrapped (only the public render functions wrap it)
    * @see lib/gvc/gvlayout.c:gvLayoutJobs
    */
   layout(g: Graph, engineName: EngineName): void {
+    const selected = this.checkLayoutArgs(g, engineName);
     // C gvLayoutJobs: the graph's `layout` ATTRIBUTE unconditionally
     // overrides the selected engine (-K / API choice); an unrecognized
     // value is an error, not a fallback. @see lib/gvc/gvlayout.c:66-73
     const attr = g.attrs?.get('layout'); // test doubles may lack attrs
-    let name = engineName;
+    let engine = selected;
     if (attr !== undefined && attr !== '') {
-      if (!this.layouts.has(attr as EngineName)) {
-        throw new Error(`Layout type: "${attr}" not recognized`);
+      const override = this.layouts.get(attr);
+      if (override === undefined) {
+        throw new RenderError(
+          `Layout type: "${attr}" not recognized`,
+          'UNKNOWN_LAYOUT',
+        );
       }
-      name = attr as EngineName;
-    }
-    const engine = this.layouts.get(name);
-    if (engine === undefined) {
-      throw new Error(`no layout engine registered: ${name}`);
+      engine = override;
     }
     if (g.info) g.info.gvc = this;
     engine.layout(g);
+    // C: GD_cleanup(g) = gvle->cleanup — freeLayout must use the engine that
+    // actually ran, not its argument. @see lib/gvc/gvlayout.c:88
+    if (g.info) g.info.cleanup = (x: Graph): void => engine.cleanup(x);
     // Mark the graph laid-out so the public getLayout can reject a graph that
     // still carries calloc-zero geometry defaults.
     if (g.info) g.info.laidOut = true;
@@ -247,14 +324,16 @@ export class GvcContext {
   /**
    * Release engine layout state after rendering.
    *
-   * @throws Error if the engine is not registered
+   * @throws TypeError (ERR_INVALID_ARG_TYPE / ERR_INVALID_ARG_VALUE) for a
+   *   bad `g`, or an engine argument that is not registered
    * @see lib/gvc/gvlayout.c:gvFreeLayout
    */
   freeLayout(g: Graph, engineName: EngineName): void {
-    const engine = this.layouts.get(engineName);
-    if (engine === undefined) {
-      throw new Error(`no layout engine registered: ${engineName}`);
+    this.checkLayoutArgs(g, engineName); // argument validation only
+    const cleanup = g.info?.cleanup;
+    if (cleanup) {
+      cleanup(g);
+      g.info.cleanup = undefined;
     }
-    engine.cleanup(g);
   }
 }

package/src/gvc/device.ts

@@ -18,8 +18,9 @@ import { parseDrawingSize, initJobViewportZoom, parseLandscape, parseGraphPad, p
 import type { Graph } from '../model/graph.js';
 import type { Node } from '../model/node.js';
 import type { Edge } from '../model/edge.js';
-import type { RendererPlugin, GvcContext } from './context.js';
-import { PenType } from './context.js';
+import type { RendererPlugin } from './context.js';
+import { GvcContext, PenType } from './context.js';
+import { invalidArgType } from '../errors.js';
 import { gvrenderTextspan, withLabelEmitState } from './textspan-emit.js';
 import { resolveEdgeAnchor, resolveObjAnchor, beginAnchorIf } from './anchor.js';
 import type { ShapeDesc, TextlabelT } from '../common/types.js';
@@ -57,9 +58,8 @@ import { svgNodeId, svgEdgeId, svgClusterId, svgGraphId } from '../render/svg-id
 // ---------------------------------------------------------------------------
 // AD-1 (image-api): `inlineImages` on RenderJob via module augmentation
 //
-// Declared here (not as an edit to job.ts) so the field lives with the one
-// caller that sets it (render(), below) and the one caller that reads it
-// (svg.ts usershape()). Purely additive: an unset field reads `undefined`,
+// Declared here (not in job.ts), beside render() which sets it; svg.ts
+// usershape() reads it. Purely additive: an unset field reads `undefined`,
 // which is falsy, so any RenderJob built without going through this render()
 // (tests, other call sites) keeps today's raw-src passthrough unchanged.
 // @see src/render/public.ts:RenderOptions.inlineImages
@@ -536,13 +536,18 @@ function renderPage(g: Graph, renderer: RendererPlugin, job: RenderJob, info: La
  *   (`setImageResolver`) and inlines a `data:` URI on a hit instead of the
  *   raw src passthrough. Unset/false reproduces byte-identical pre-AD-1
  *   output. @see src/render/public.ts:RenderOptions.inlineImages
- * @throws Error if no renderer is registered for format
+ * @throws TypeError `ERR_INVALID_ARG_TYPE` if `ctx` is not a GvcContext, `g`
+ *   is not an object, or `format` is not a string
+ * @throws TypeError `ERR_INVALID_ARG_VALUE` if no renderer is registered for format
  * @see lib/gvc/gvrender.c:gvrender_select
  */
 export function render(ctx: GvcContext, g: Graph, format: string, inlineImages = false): string {
+  if (!(ctx instanceof GvcContext)) throw invalidArgType('ctx', 'GvcContext', ctx);
+  if (typeof g !== 'object' || g === null) throw invalidArgType('g', 'object', g);
   const renderer = ctx.bestRenderer(format);
   const job = new RenderJob(format, ctx.textMeasurer);
   job.inlineImages = inlineImages;
+  if (ctx.imageResolver !== undefined) job.imageResolver = ctx.imageResolver;
   // gvc->bb = GD_bb(g) verbatim -- no recompute fallback. Every layout engine
   // sets g.info.bb itself before render() runs (set_aspect for dot,
   // compute_bb-equivalent computeSubgraphBB calls in neato/circo/sfdp/fdp/

package/src/gvc/image-resolver.ts

@@ -16,6 +16,8 @@
  * @see lib/gvc/gvusershape.c (ImageDict, gvusershape_find/size)
  */
 
+import { invalidArgType } from '../errors.js';
+
 // ---------------------------------------------------------------------------
 // Resolver registry
 // ---------------------------------------------------------------------------
@@ -29,14 +31,30 @@ export type ImageResolver = (
   src: string,
 ) => { bytes: Uint8Array; mime?: string } | Uint8Array | null;
 
+/**
+ * Per-render resolver on the render job (async-api ADR-2): device.ts render()
+ * copies `GvcContext.imageResolver` here; svg.ts usershape() passes it to
+ * findImageBytes, which then skips the global resolver.
+ */
+declare module './job.js' {
+  interface RenderJob {
+    imageResolver?: ImageResolver;
+  }
+}
+
 let activeResolver: ImageResolver | null = null;
 
 /**
  * Register (or clear, with null) the global image resolver consulted when
  * `RenderOptions.inlineImages` is set. Mirrors gvusershape's process-global
  * dictionary and `setImageSizer`'s registration shape.
+ * @throws TypeError `ERR_INVALID_ARG_TYPE` if `fn` is neither a function nor
+ *   null
  */
 export function setImageResolver(fn: ImageResolver | null): void {
+  if (fn !== null && typeof fn !== 'function') {
+    throw invalidArgType('resolver', 'function or null', fn);
+  }
   activeResolver = fn;
 }
 
@@ -73,12 +91,17 @@ function inferMimeFromSrc(src: string): string {
  * when the resolver omits it). Returns `null` when no resolver is set or the
  * resolver itself returns `null` — the graceful-miss path that keeps the raw
  * `src` passthrough in `usershape()`.
+ *
+ * @param resolver - per-context resolver (ADR-2); when given it is consulted
+ *   instead of the global one, with the same normalization.
  */
 export function findImageBytes(
   src: string,
+  resolver?: ImageResolver,
 ): { bytes: Uint8Array; mime: string } | null {
-  if (activeResolver === null) return null;
-  const result = activeResolver(src);
+  const active = resolver ?? activeResolver;
+  if (active === null) return null;
+  const result = active(src);
   if (result === null) return null;
   if (result instanceof Uint8Array) {
     return { bytes: result, mime: inferMimeFromSrc(src) };

package/src/gvc/job.ts

@@ -10,6 +10,7 @@
  * @see lib/gvc/gvdevice.c:gvprintdouble
  */
 
+import { InternalError } from '../errors.js';
 import type { Graph } from '../model/graph.js';
 import { FontnameKind } from '../model/layoutParams.js';
 import type { Node } from '../model/node.js';
@@ -361,11 +362,12 @@ export class RenderJob {
 
   /**
    * Pop the top object state from the stack.
+   * @see lib/common/emit.c:pop_obj_state (assert(obj) at emit.c:135)
    * @throws Error if the stack is empty.
    */
   popObj(): void {
     if (this.objStack.length === 0) {
-      throw new Error('RenderJob.popObj: stack is empty');
+      throw new InternalError('RenderJob.popObj: stack is empty');
     }
     this.objStack.pop();
   }

package/src/gvc/usershape.ts

@@ -13,6 +13,7 @@
  * @see lib/gvc/gvusershape.c (ImageDict, gvusershape_find/size)
  */
 
+import { invalidArgType } from '../errors.js';
 import type { ImageSizer } from '../common/htmltable-types.js';
 
 export type { ImageSizer } from '../common/htmltable-types.js';
@@ -22,8 +23,13 @@ let activeSizer: ImageSizer | null = null;
 /**
  * Register (or clear, with null) the global image sizer consulted by
  * HTML <IMG> sizing. Mirrors gvusershape's process-global dictionary.
+ * @throws TypeError `ERR_INVALID_ARG_TYPE` if `sizer` is neither a function
+ *   nor null
  */
 export function setImageSizer(sizer: ImageSizer | null): void {
+  if (sizer !== null && typeof sizer !== 'function') {
+    throw invalidArgType('sizer', 'function or null', sizer);
+  }
   activeSizer = sizer;
 }