@knowvah/dot-engine 2.6.6 → 2.6.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowvah/dot-engine",
-  "version": "2.6.6",
+  "version": "2.6.8",
   "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.",
   "keywords": [
     "graphviz",

package/src/common/htmltable-attr-warn.ts

@@ -11,7 +11,7 @@
  * @see lib/common/htmllex.c:doAttrs
  */
 
-/** An attribute as written: name in source case, value verbatim. */
+/** An attribute as startElement gets it: name in source case, value decoded by expat. */
 export type AttrEntry = readonly [name: string, value: string];
 
 export interface CheckedAttrs {
@@ -247,9 +247,9 @@ export function checkAttrs(tag: string, pairs: readonly AttrEntry[]): CheckedAtt
 // ---------------------------------------------------------------------------
 
 /**
- * C's stderr as lines: text is appended, each completed line goes to
- * `writeLine`, and a message without a trailing newline stays pending so the
- * next write continues it. `flush` emits a pending partial line.
+ * C's stderr as messages: a write ending in a newline goes to `writeLine`
+ * (newline dropped, embedded newlines kept), while a message without one stays
+ * pending so the next write continues it. `flush` emits a pending message.
  */
 export class StderrLines {
   private pending = '';
@@ -257,9 +257,11 @@ export class StderrLines {
   constructor(private readonly writeLine: (line: string) => void) {}
 
   write(text: string): void {
-    const parts = (this.pending + text).split('\n');
-    this.pending = parts.pop() ?? '';
-    for (const line of parts) this.writeLine(line);
+    this.pending += text;
+    if (!this.pending.endsWith('\n')) return;
+    const line = this.pending.slice(0, -1);
+    this.pending = '';
+    this.writeLine(line);
   }
 
   flush(): void {
@@ -268,3 +270,18 @@ export class StderrLines {
     this.pending = '';
   }
 }
+
+/** A finished stderr line on the console channel the port uses for it. */
+export const consoleLine = (line: string): void => {
+  if (line.startsWith('Warning')) console.warn(line);
+  else console.error(line);
+};
+
+/** One label's stderr: what make_html_label and make_label print, in order. */
+export const labelStderr = (): StderrLines => new StderrLines(consoleLine);
+
+/** agerr of one newline-terminated message: to `out`, or the console when there is none. */
+export const agerrLine = (out: StderrLines | undefined, msg: string): void => {
+  if (out === undefined) consoleLine(msg);
+  else out.write(`${msg}\n`);
+};

package/src/common/htmltable-label.ts

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * make_html_label: parse, size and position an HTML-like label, writing what
+ * C writes to stderr along the way through one {@link StderrLines}, so a
+ * message without a trailing newline (htmllex.c's doInt) runs into the next
+ * write: a later warning, the parse error, or make_label's `in label of ...`.
+ *
+ * @see lib/common/htmltable.c:make_html_label
+ */
+
+import type { TextlabelT } from './types.js';
+import type { TextMeasurer } from './textmeasure.js';
+import type { HtmlLabel, ImageSizer } from './htmltable-types.js';
+import { sizeHtmlLabel, parseHtmlLabelRv, inheritTablePenColor } from './htmltable.js';
+import { makeLabel } from './make-label.js';
+import { HtmlLexError } from './htmltable-lex.js';
+import { labelStderr, type StderrLines } from './htmltable-attr-warn.js';
+import { posHtmlLabel, type HtmlFontInfo, type PlacedHtml } from './htmltable-pos.js';
+
+/** parseHTML's rv for a label that failed to parse (`ctx->error`). */
+const HTML_PARSE_FATAL = 3;
+
+/** A built HTML label plus make_html_label's "problem" return value. */
+export interface HtmlLabelResult {
+  label: TextlabelT;
+  rv: number;
+}
+
+/** The label's font, the object's pen color, and the `<IMG>` sizer. */
+export type HtmlLabelInfo = HtmlFontInfo & { imageSizer?: ImageSizer; pencolor?: string };
+
+/**
+ * make_html_label: parse, size and position an HTML-like label. Returns C's
+ * rv too (nonzero: the caller appends `in label of ...`, labels.c:make_label).
+ * Everything C prints goes to `stderr`, which the caller owns and flushes once
+ * its own continuation is written. The optional `imageSizer` resolves
+ * `<IMG SRC>`; absent means C's missing image.
+ * @see lib/common/htmltable.c:make_html_label
+ */
+export function makeHtmlLabelTo(
+  content: string,
+  finfo: HtmlLabelInfo,
+  measurer: TextMeasurer,
+  stderr: StderrLines,
+): HtmlLabelResult {
+  const { fontname, fontsize, fontcolor, imageSizer, pencolor } = finfo;
+  let lbl: HtmlLabel, lexWarn: boolean; // lexWarn: htmllex.c's ctx->warn, rv bit 1
+  try {
+    ({ label: lbl, warn: lexWarn } = parseHtmlLabelRv(content, stderr));
+  } catch (e) {
+    // C aborts the HTML parse on a syntax error (YYABORT): parseHTML returns
+    // rv 3 (ctx->error) with no label, and make_html_label returns it with
+    // lp->html cleared and no spans, so the label renders empty.
+    // @see lib/common/htmltable.c:1880 (rv == 3), htmlparse.y (YYABORT)
+    if (e instanceof HtmlLexError) for (const line of e.diagnostics) stderr.write(`${line}\n`);
+    return { label: makeLabel('', fontname, fontsize, fontcolor, measurer), rv: HTML_PARSE_FATAL };
+  }
+  // A top-level table with no explicit COLOR inherits the object's pen color,
+  // which then flows table->cell->nested-table.
+  // @see lib/common/htmltable.c:1911 (getPenColor), :1406/:1556 (inheritance)
+  if (lbl.kind === 'table') inheritTablePenColor(lbl.table, pencolor);
+  const rv = Number(lexWarn) | sizeHtmlLabel(lbl, measurer, {
+    fontsize, fontname, imageSizer, stderr,
+  });
+  const placed = posHtmlLabel(lbl, { fontname, fontsize, fontcolor }, measurer);
+  const dim = lbl.dimen ?? { w: 0, h: 0 };
+  // C replaces table-label text: "this may be used for the title and
+  // alt fields in image maps" — anchors inherit it as default tooltip.
+  // @see lib/common/htmltable.c:make_html_label (line 1935)
+  const text = lbl.kind === 'table' ? '<TABLE>' : content;
+  return { label: htmlTextLabel(text, { fontname, fontsize, fontcolor }, placed, dim), rv };
+}
+
+/** {@link makeHtmlLabelTo} on a stderr of its own, flushed before it returns. */
+export function makeHtmlLabelRv(content: string, finfo: HtmlLabelInfo, measurer: TextMeasurer): HtmlLabelResult {
+  const stderr = labelStderr();
+  try {
+    return makeHtmlLabelTo(content, finfo, measurer, stderr);
+  } finally {
+    stderr.flush();
+  }
+}
+
+/** {@link makeHtmlLabelRv} without the problem flag. */
+export function makeHtmlLabel(content: string, finfo: HtmlLabelInfo, measurer: TextMeasurer): TextlabelT {
+  return makeHtmlLabelRv(content, finfo, measurer).label;
+}
+
+/** Build the TextlabelT wrapper around a positioned HTML label. */
+function htmlTextLabel(
+  text: string,
+  finfo: HtmlFontInfo,
+  placed: PlacedHtml,
+  dim: { w: number; h: number },
+): TextlabelT {
+  return {
+    text,
+    fontname: finfo.fontname, fontcolor: finfo.fontcolor, charset: 0,
+    fontsize: finfo.fontsize,
+    dimen: { x: dim.w, y: dim.h },
+    space: { x: dim.w, y: dim.h },
+    pos: { x: 0, y: 0 },
+    u: { kind: 'html', html: placed },
+    valign: 'c'.charCodeAt(0),
+    set: false,
+    html: true,
+  };
+}

package/src/common/htmltable-lex-attvalue.ts

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * expat's handling of an attribute value, which `doAttrs` only ever sees
+ * decoded: scanAtts tokenizes the quoted value (a `<`, or an `&` that does not
+ * start a well-formed reference, is an invalid token), storeAtts then
+ * normalizes it (references decoded, white space to spaces) and reports an
+ * undefined entity or a reference to a character XML does not allow.
+ *
+ * Not vendored with graphviz; read from libexpat R_2_6_4.
+ * @see expat lib/xmltok_impl.c:PREFIX(scanAtts)
+ * @see expat lib/xmltok_impl.c:PREFIX(scanRef)
+ * @see expat lib/xmlparse.c:storeAtts
+ * @see expat lib/xmlparse.c:appendAttributeValue
+ */
+
+/** expat `XML_ErrorString(XML_ERROR_UNDEFINED_ENTITY)`. */
+export const XML_ERROR_UNDEFINED_ENTITY = 'undefined entity';
+/** expat `XML_ErrorString(XML_ERROR_BAD_CHAR_REF)`. */
+export const XML_ERROR_BAD_CHAR_REF = 'reference to invalid character number';
+
+/** How scanAtts ends a quoted value: at its closing quote, short of data, or on an invalid token. */
+export type AttValueScan = { close: number } | { partial: true } | { invalid: number };
+
+/** A storeAtts error: its message and where expat's event pointer is (undefined: the tag's start). */
+export interface AttValueError {
+  message: string;
+  offset?: number;
+}
+
+const NAME_START = /[A-Za-z_:\u0080-￿]/;
+const NAME_CHAR = /[\w.:\u0080-￿-]/;
+const DEC_DIGIT = /[0-9]/;
+const HEX_DIGIT = /[0-9A-Fa-f]/;
+/** Bytes expat's tokenizer rejects anywhere (BT_NONXML): controls other than tab, LF and CR. */
+const NON_XML = /[\x00-\x08\x0b\x0c\x0e-\x1f]/;
+
+/** A reference's digits from `i` up to `;`: the index after it, or where scanning stops. */
+function scanDigits(text: string, i: number, digit: RegExp): number | AttValueScan {
+  if (i >= text.length) return { partial: true };
+  if (!digit.test(text[i]!)) return { invalid: i };
+  for (let k = i + 1; k < text.length; k++) {
+    if (text[k] === ';') return k + 1;
+    if (!digit.test(text[k]!)) return { invalid: k };
+  }
+  return { partial: true };
+}
+
+/**
+ * The reference after the `&` at `i - 1`: the index after its `;`, or where
+ * scanning stops.
+ * @see expat lib/xmltok_impl.c:PREFIX(scanRef)
+ * @see expat lib/xmltok_impl.c:PREFIX(scanCharRef)
+ */
+function scanRef(text: string, i: number): number | AttValueScan {
+  const c = text[i];
+  if (c === undefined) return { partial: true };
+  if (c === '#') return text[i + 1] === 'x' ? scanDigits(text, i + 2, HEX_DIGIT) : scanDigits(text, i + 1, DEC_DIGIT);
+  if (!NAME_START.test(c)) return { invalid: i };
+  for (let k = i + 1; k < text.length; k++) {
+    if (text[k] === ';') return k + 1;
+    if (!NAME_CHAR.test(text[k]!)) return { invalid: k };
+  }
+  return { partial: true };
+}
+
+/**
+ * scanAtts over the value whose opening quote is at `j`.
+ * @see expat lib/xmltok_impl.c:PREFIX(scanAtts) ("in attribute value")
+ */
+export function scanAttValue(text: string, j: number): AttValueScan {
+  const q = text[j];
+  let k = j + 1;
+  for (;;) {
+    const c = text[k];
+    if (c === undefined) return { partial: true };
+    if (c === q) return { close: k };
+    if (c === '<' || NON_XML.test(c)) return { invalid: k };
+    if (c !== '&') {
+      k++;
+      continue;
+    }
+    const r = scanRef(text, k + 1);
+    if (typeof r !== 'number') return r;
+    k = r;
+  }
+}
+
+/**
+ * XmlCharRefNumber: the code point of `&#...;`, or -1 for one XML does not
+ * allow (controls other than tab, LF and CR; surrogates; U+FFFE and U+FFFF;
+ * beyond U+10FFFF).
+ * @see expat lib/xmltok_impl.c:PREFIX(charRefNumber)
+ * @see expat lib/xmltok.c:checkCharRefNumber
+ */
+export function charRefNumber(ref: string): number {
+  const hex = ref.startsWith('&#x');
+  const n = parseInt(ref.slice(hex ? 3 : 2, -1), hex ? 16 : 10);
+  if (n >= 0x110000) return -1;
+  if (n >= 0xd800 && n <= 0xdfff) return -1;
+  if (n < 0x20 && NON_XML.test(String.fromCharCode(n))) return -1;
+  return n === 0xfffe || n === 0xffff ? -1 : n;
+}
+
+const PREDEFINED: Readonly<Record<string, string>> = { lt: '<', gt: '>', amp: '&', quot: '"', apos: "'" };
+
+/** The references of a well-formed value, and its CR LF pairs. */
+const VALUE_PIECE = /&#x?[0-9A-Fa-f]+;|&[^;]+;|\r\n|[\t\n\r]/g;
+
+/**
+ * storeAtts' check of a well-formed value (`raw`, between the quotes, at
+ * `base`): the first undefined entity or disallowed character reference. No
+ * DTD, so only the five predefined entities exist.
+ * @see expat lib/xmlparse.c:appendAttributeValue
+ */
+export function attValueError(raw: string, base: number): AttValueError | undefined {
+  for (const m of raw.matchAll(VALUE_PIECE)) {
+    const ref = m[0];
+    if (!ref.startsWith('&')) continue;
+    if (ref.startsWith('&#')) {
+      if (charRefNumber(ref) < 0) return { message: XML_ERROR_BAD_CHAR_REF, offset: base + m.index };
+    } else if (!Object.hasOwn(PREDEFINED, ref.slice(1, -1))) {
+      return { message: XML_ERROR_UNDEFINED_ENTITY };
+    }
+  }
+  return undefined;
+}
+
+/**
+ * appendAttributeValue for a CDATA attribute (no DTD declares one otherwise)
+ * on a value storeAtts accepted: references become their characters, which
+ * stay as they are (a `&#9;` is a tab); a tab, LF, CR or CR LF in the source
+ * becomes one space.
+ * @see expat lib/xmlparse.c:appendAttributeValue
+ */
+export function decodeAttValue(raw: string): string {
+  return raw.replace(VALUE_PIECE, (m) => {
+    if (!m.startsWith('&')) return ' ';
+    if (m.startsWith('&#')) return String.fromCodePoint(charRefNumber(m));
+    return PREDEFINED[m.slice(1, -1)]!;
+  });
+}

package/src/common/htmltable-lex-chardata.ts

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * The htmllex state characterData reads: `ctx->inCell`, which the element
+ * handlers set, and `ctx->xb`, the buffer it appends to. Every handler assigns
+ * `ctx->tok`, so when one `XML_Parse` call fires several events only the last
+ * token reaches the parser, but characters an earlier event appended stay in
+ * xb: they lead the next string the parser reduces, or count in the table
+ * rule's nonSpace check.
+ *
+ * @see lib/common/htmllex.c:startElement
+ * @see lib/common/htmllex.c:endElement
+ * @see lib/common/htmllex.c:characterData
+ */
+
+import { htmlEntityUTF8 } from './html-entities.js';
+import type { TagChunk } from './htmltable-lex-expat.js';
+import type { Token } from './htmltable-types.js';
+
+/** `ctx->inCell`, and the text in `ctx->xb` that no token carried to the parser. */
+export interface CharDataState {
+  inCell: boolean;
+  xb: string;
+}
+
+/** initHTMLlexer: text is kept until the first TABLE or TR. @see lib/common/htmllex.c:initHTMLlexer */
+export const initialCharData = (): CharDataState => ({ inCell: true, xb: '' });
+
+/** startElement's assignment to inCell for element `name` (upper case). */
+function startInCell(name: string, inCell: boolean): boolean {
+  if (name === 'TABLE' || name === 'TR' || name === 'TH') return false;
+  return name === 'TD' ? true : inCell;
+}
+
+/** endElement's assignment to inCell for element `name` (upper case). */
+function endInCell(name: string, inCell: boolean): boolean {
+  if (name === 'TABLE') return true;
+  return name === 'TD' ? false : inCell;
+}
+
+/** Run a tag's element handlers on inCell; `<X/>` runs startElement, then endElement. */
+export function tagInCell(st: CharDataState, tag: TagChunk): void {
+  const name = tag.name.toUpperCase();
+  if (tag.close) {
+    st.inCell = endInCell(name, st.inCell);
+    return;
+  }
+  st.inCell = startInCell(name, st.inCell);
+  if (tag.selfClose) st.inCell = endInCell(name, st.inCell);
+}
+
+/** Keep the text of tokens a later event in the same call overwrote. */
+export function keepLostText(st: CharDataState, lost: readonly Token[]): void {
+  for (const t of lost) if (t.type === 'text') st.xb += t.value;
+}
+
+/**
+ * Hand xb's kept text to the token the parser is about to get: a string
+ * starts with it, and a TABLE carries it for the table rule's nonSpace check.
+ * Any other token leaves it in xb for the next of those.
+ * @see lib/common/htmlparse.y:table
+ */
+export function releaseXb(st: CharDataState, first: Token): void {
+  if (st.xb === '') return;
+  if (first.type === 'text') first.value = st.xb + first.value;
+  else if (first.type === 'open' && first.tag === 'TABLE') first.heldText = st.xb;
+  else return;
+  st.xb = '';
+}
+
+/**
+ * characterData keeps each byte `>= ' '` of the text expat decoded: anything
+ * below 0x20 goes (tab, LF and CR too, from the source or a character
+ * reference); DEL and non-ASCII stay.
+ * @see lib/common/htmllex.c:characterData
+ */
+function cleanText(decoded: string) {
+  return decoded.replace(/[\x00-\x1f]/g, '');
+}
+
+/** The text token of a text run, if anything is left after cleaning. */
+export function textTokens(raw: string): Token[] {
+  // Decode XML/HTML entities in the text run. C's HTML lexer resolves entities
+  // via expat during tokenization (htmllex.c), so both sizing and emit see the
+  // decoded UTF-8 text. Skipping this measured the raw "&#91;el..." (9-10 chars)
+  // instead of "[el..." (6 chars), inflating edge-label vnodes and shifting
+  // layout (corpus 1949: +18.7px). Plain-string labels already decode via the
+  // make_label path, so only HTML-delimited labels diverged.
+  return charDataTokens(htmlEntityUTF8(raw));
+}
+
+/** characterData on what expat decoded: a T_string when any character survives. */
+export function charDataTokens(decoded: string): Token[] {
+  const clean = cleanText(decoded);
+  return clean.length > 0 ? [{ type: 'text', value: clean }] : [];
+}