@knowvah/dot-engine 2.6.2 → 2.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowvah/dot-engine",
-  "version": "2.6.2",
+  "version": "2.6.3",
   "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-lex.ts

@@ -13,7 +13,7 @@
 
 import { HtmlParseError } from './htmltable-types.js';
 import type { Token } from './htmltable-types.js';
-import { htmlEntityUTF8 } from './html-entities.js';
+import { HTML_ENTITIES, htmlEntityUTF8 } from './html-entities.js';
 
 export type { Token } from './htmltable-types.js';
 
@@ -140,12 +140,272 @@ function parseOpenToken(inner: string) {
   return { type: 'open' as const, tag: normalizeTag(tag), attrs: parseAttrs(inner.slice(sp + 1)) };
 }
 
-/** @see lib/common/htmllex.c:findNext */
-export function tokenize(src: string) {
+/**
+ * expat `XML_ErrorString` texts for the two errors the port detects. Taken
+ * from native dot's stderr (graphviz 16.1.0): expat's xmlparse.c is not
+ * vendored with the graphviz sources.
+ * @see lib/common/htmllex.c:htmllex (XML_ErrorString at the XML_Parse failure)
+ */
+const XML_ERROR_UNDEFINED_ENTITY = 'undefined entity';
+const XML_ERROR_TAG_MISMATCH = 'mismatched tag';
+const XML_ERROR_INVALID_TOKEN = 'not well-formed (invalid token)';
+const XML_ERROR_DUPLICATE_ATTRIBUTE = 'duplicate attribute';
+
+/** Entities expat knows without a DTD; `scanEntity` leaves them as written. */
+const XML_PREDEFINED_ENTITIES = new Set(['lt', 'gt', 'amp', 'quot', 'apos']);
+
+const XML_NAME = /^[A-Za-z_:][\w.:-]*$/;
+
+/**
+ * A label failure C reports on stderr before dropping the HTML label
+ * (`ctx->error`, parseHTML rv 3). `diagnostics` holds the lines in print
+ * order, each already carrying its `Error: ` prefix where C's agerrorf adds
+ * one; the caller prints them (one `console.error` each) and then C's
+ * `in label of ...` continuation (labels.c:make_label).
+ * @see lib/common/htmllex.c:htmllex
+ */
+export class HtmlLexError extends HtmlParseError {
+  readonly diagnostics: readonly string[];
+
+  constructor(tag: string, message: string, diagnostics: readonly string[]) {
+    super(tag);
+    this.message = message;
+    this.diagnostics = diagnostics;
+  }
+}
+
+/**
+ * `agerrorf("%s in line %lu \n", msg, lineno)` followed by `error_context`.
+ * @see lib/common/htmllex.c:htmlerror
+ * @see lib/common/htmllex.c:error_context
+ */
+export function htmlErrorInLine(message: string, line: number, context: string): HtmlLexError {
+  const text = `${message} in line ${line} `;
+  return new HtmlLexError(message, text, [`Error: ${text}`, `... ${context} ...`]);
+}
+
+/** The C lexer's current and previous "token" (raw chunk) plus open elements. */
+interface ChunkState {
+  stack: string[];
+  prev: string;
+  curr: string;
+}
+
+/** Where a token came from: the raw chunk and the C `error_context` pair. */
+interface ChunkInfo {
+  src: string;
+  pos: number;
+  end: number;
+  context: string;
+}
+
+const chunkInfo = new WeakMap<Token, ChunkInfo>();
+
+/**
+ * expat's line number at `pos`: `\n`, `\r\n` and a lone `\r` each end a line.
+ * @see lib/common/htmllex.c:htmllineno
+ */
+function lineAt(src: string, pos: number): number {
+  let line = 1;
+  for (let k = 0; k < pos; k++) {
+    if (src[k] === '\n' || (src[k] === '\r' && src[k + 1] !== '\n')) line++;
+  }
+  return line;
+}
+
+/**
+ * `XML_GetCurrentLineNumber` after the chunk that produced `tok`: a tag's own
+ * line, or for character data the line of expat's last data piece (pieces
+ * split at each newline).
+ */
+function chunkLine(info: ChunkInfo): number {
+  if (info.src[info.pos] === '<') return lineAt(info.src, info.pos);
+  const last = info.src.lastIndexOf('\n', info.end - 1);
+  if (last < info.pos) return lineAt(info.src, info.pos);
+  return lineAt(info.src, last === info.end - 1 ? last : last + 1);
+}
+
+/**
+ * C's `htmlerror` (yacc error) as it reads when the lexer last returned
+ * `tok`; undefined when the token has no recorded chunk.
+ * @see lib/common/htmllex.c:htmlerror
+ */
+export function htmlErrorAtToken(message: string, tok: Token | undefined): HtmlLexError | undefined {
+  const info = tok === undefined ? undefined : chunkInfo.get(tok);
+  if (info === undefined) return undefined;
+  return htmlErrorInLine(message, chunkLine(info), info.context);
+}
+
+/** Extent of the next chunk: `<..>` or the characters up to the next `<`. */
+function chunkEnd(src: string, i: number): number {
+  const j = src[i] === '<' ? src.indexOf('>', i + 1) : src.indexOf('<', i);
+  if (j < 0) return src.length;
+  return src[i] === '<' ? j + 1 : j;
+}
+
+/** Offset of the first `&name;` that scanEntity leaves for expat to reject. */
+function findUndefinedEntity(text: string): number {
+  for (let t = text.indexOf('&'); t >= 0; t = text.indexOf('&', t + 1)) {
+    if (text[t + 1] === '#') continue;
+    const semi = text.indexOf(';', t + 1);
+    if (semi < 0) continue;
+    const key = text.slice(t + 1, semi);
+    if (XML_NAME.test(key) && !Object.hasOwn(HTML_ENTITIES, key) && !XML_PREDEFINED_ENTITIES.has(key)) {
+      return t;
+    }
+  }
+  return -1;
+}
+
+interface TagChunk {
+  close: boolean;
+  selfClose: boolean;
+  name: string;
+}
+
+/** Element name of a complete `<..>` chunk; undefined for comments etc. */
+function parseTagChunk(chunk: string): TagChunk | undefined {
+  if (!chunk.endsWith('>')) return undefined;
+  const body = chunk.slice(1, -1);
+  if (body.startsWith('!')) return undefined;
+  const close = body.startsWith('/');
+  const name = /^[^\s/>]*/.exec(close ? body.slice(1) : body)?.[0] ?? '';
+  return { close, selfClose: !close && body.endsWith('/'), name };
+}
+
+interface AttrError {
+  message: string;
+  offset: number;
+}
+
+const ATTR_NAME = /^[A-Za-z_:][\w.:-]*/;
+const isSpace = (c: string | undefined): boolean => c !== undefined && /\s/.test(c);
+
+const invalidToken = (offset: number): AttrError => ({ message: XML_ERROR_INVALID_TOKEN, offset });
+
+function skipSpace(chunk: string, i: number): number {
+  let j = i;
+  while (isSpace(chunk[j])) j++;
+  return j;
+}
+
+interface AttrPair {
+  name: string;
+  next: number;
+}
+
+/**
+ * The `name = "value"` pair at `i`, or the error expat raises there;
+ * undefined for an unterminated quote, which is not modelled.
+ */
+function readAttrPair(chunk: string, i: number): AttrPair | AttrError | undefined {
+  const name = ATTR_NAME.exec(chunk.slice(i))?.[0];
+  if (name === undefined) return invalidToken(i);
+  let j = skipSpace(chunk, i + name.length);
+  if (chunk[j] !== '=') return invalidToken(j);
+  j = skipSpace(chunk, j + 1);
+  const q = chunk[j];
+  if (q !== '"' && q !== "'") return invalidToken(j);
+  const end = chunk.indexOf(q, j + 1);
+  return end < 0 ? undefined : { name, next: end + 1 };
+}
+
+/**
+ * Walk the `name="value"` pairs of an open tag as expat does and return the
+ * first well-formedness error with its offset in the chunk. A duplicate is
+ * only reported when no invalid token follows it, as expat checks duplicates
+ * after tokenizing the whole tag.
+ */
+function findAttrError(chunk: string, from: number): AttrError | undefined {
+  const seen = new Set<string>();
+  let dup: AttrError | undefined;
+  let i = skipSpace(chunk, from);
+  while (chunk[i] !== '>' && !(chunk[i] === '/' && chunk[i + 1] === '>')) {
+    const pair = readAttrPair(chunk, i);
+    if (pair === undefined) return undefined;
+    if ('message' in pair) return pair;
+    if (seen.has(pair.name) && dup === undefined) dup = { message: XML_ERROR_DUPLICATE_ATTRIBUTE, offset: i };
+    seen.add(pair.name);
+    i = skipSpace(chunk, pair.next);
+  }
+  return dup;
+}
+
+/**
+ * Raise the error C hits for this tag chunk: expat's mismatched tag first
+ * (it is detected before the end handler runs), then `lexerror`'s unknown
+ * element.
+ * @see lib/common/htmllex.c:lexerror
+ */
+function checkTagChunk(src: string, start: number, st: ChunkState): void {
+  const tag = parseTagChunk(st.curr);
+  if (tag === undefined) return;
+  if (tag.close) {
+    if (st.stack.length > 0 && st.stack.pop() !== tag.name) {
+      throw htmlErrorInLine(XML_ERROR_TAG_MISMATCH, lineAt(src, start), st.prev + st.curr);
+    }
+  } else {
+    const bad = findAttrError(st.curr, 1 + tag.name.length);
+    if (bad !== undefined) {
+      throw htmlErrorInLine(bad.message, lineAt(src, start + bad.offset), st.prev + st.curr);
+    }
+    if (!tag.selfClose) st.stack.push(tag.name);
+  }
+  if (KNOWN_TAGS.has(tag.name.toUpperCase())) return;
+  const text = `Unknown HTML element <${tag.name}> on line ${lineAt(src, start)} `;
+  throw new HtmlLexError(tag.name.toUpperCase(), text, [`Error: ${text}`]);
+}
+
+/** Raise the expat or lexer error C would hit while parsing this chunk. */
+function checkChunk(src: string, start: number, st: ChunkState): void {
+  if (st.curr.startsWith('<')) {
+    checkTagChunk(src, start, st);
+    return;
+  }
+  const off = findUndefinedEntity(st.curr);
+  if (off >= 0) {
+    throw htmlErrorInLine(XML_ERROR_UNDEFINED_ENTITY, lineAt(src, start + off), st.prev + st.curr);
+  }
+}
+
+/** Tokens produced before the first lexical error, plus that error. */
+export interface TokenizeResult {
+  tokens: Token[];
+  error?: HtmlParseError;
+}
+
+/**
+ * Tokenize until the first lexical error and return both. C interleaves
+ * lexing with the yacc parse, so a syntax error in the tokens before the
+ * failing chunk is reported in preference to the lexical error; callers that
+ * parse the partial stream get that precedence.
+ * @see lib/common/htmllex.c:findNext
+ */
+export function tokenizeDeferred(src: string): TokenizeResult {
   const tokens: Token[] = [];
+  const st: ChunkState = { stack: [], prev: '', curr: '' };
   let i = 0;
-  while (i < src.length) {
-    i = src[i] === '<' ? scanTag(src, i, tokens) : scanText(src, i, tokens);
+  try {
+    while (i < src.length) {
+      const first = tokens.length;
+      const start = i;
+      st.prev = st.curr;
+      st.curr = src.slice(i, chunkEnd(src, i));
+      checkChunk(src, i, st);
+      i = src[i] === '<' ? scanTag(src, i, tokens) : scanText(src, i, tokens);
+      const info: ChunkInfo = { src, pos: start, end: i, context: st.prev + st.curr };
+      for (let k = first; k < tokens.length; k++) chunkInfo.set(tokens[k]!, info);
+    }
+  } catch (e) {
+    if (e instanceof HtmlParseError) return { tokens, error: e };
+    throw e;
   }
+  return { tokens };
+}
+
+/** @see lib/common/htmllex.c:findNext */
+export function tokenize(src: string): Token[] {
+  const { tokens, error } = tokenizeDeferred(src);
+  if (error !== undefined) throw error;
   return tokens;
 }

package/src/common/htmltable-parse-attrs.ts

@@ -0,0 +1,166 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * Attribute interpretation for the HTML-like label parser: the values
+ * mkTbl/mkCell/mkBR/mkFont read off a tag, and the table/cell records built
+ * from them.
+ *
+ * @see lib/common/htmllex.c:mkTbl
+ * @see lib/common/htmllex.c:mkCell
+ */
+
+import type {
+  HtmlAlign,
+  HtmlCell,
+  HtmlCellContent,
+  HtmlRow,
+  HtmlTable,
+  HtmlVAlign,
+} from './htmltable-types.js';
+import {
+  BORDER_LEFT,
+  BORDER_TOP,
+  BORDER_RIGHT,
+  BORDER_BOTTOM,
+  BORDER_MASK,
+} from './htmltable-types.js';
+import { htmlEntityUTF8 } from './html-entities.js';
+
+/** Decode XML/HTML entities in an anchor attribute value (href/target), as C's
+ *  HTML parser does. The stored value is the real character (`&` → `&`), so
+ *  imap emits it raw and cmapx re-escapes it. Undefined passes through. */
+function anchorAttr(v: string | undefined): string | undefined {
+  return v === undefined ? undefined : htmlEntityUTF8(v);
+}
+
+// ---------------------------------------------------------------------------
+// Attribute helpers
+// ---------------------------------------------------------------------------
+
+export const parseAlign = (v: string): HtmlAlign | undefined => {
+  const u = v.toUpperCase();
+  if (u === 'LEFT') return 'left';
+  if (u === 'RIGHT') return 'right';
+  if (u === 'CENTER') return 'center';
+  return undefined;
+};
+
+export const parseVAlign = (v: string): HtmlVAlign | undefined => {
+  const u = v.toUpperCase();
+  if (u === 'TOP') return 'top';
+  if (u === 'BOTTOM') return 'bottom';
+  if (u === 'MIDDLE') return 'middle';
+  return undefined;
+};
+
+export const num = (s: string | undefined): number | undefined => {
+  if (s === undefined) return undefined;
+  const n = parseInt(s, 10);
+  return isNaN(n) ? undefined : n;
+};
+
+export const parseFixedSize = (a: Record<string, string>): true | undefined =>
+  a['fixedsize']?.toUpperCase() === 'TRUE' ? true : undefined;
+
+export const parseTitle = (a: Record<string, string>): string | undefined =>
+  a['title'] !== undefined ? a['title'] : a['tooltip'];
+
+/**
+ * Parse SIDES attribute into a bitmask matching C sidesfn().
+ * Unrecognised chars are silently skipped (C issues a warning but continues).
+ * C guard: if (flags != BORDER_MASK) p->flags |= flags — the full-mask case
+ * is a no-op (means "all sides", the default), so we return undefined for it.
+ * @see lib/common/htmllex.c:sidesfn
+ */
+export const parseSides = (v: string | undefined): number | undefined => {
+  if (v === undefined) return undefined;
+  let flags = 0;
+  for (const c of v.toLowerCase()) {
+    if (c === 'l') flags |= BORDER_LEFT;
+    else if (c === 't') flags |= BORDER_TOP;
+    else if (c === 'r') flags |= BORDER_RIGHT;
+    else if (c === 'b') flags |= BORDER_BOTTOM;
+  }
+  // C: if (flags != BORDER_MASK) p->flags |= flags
+  if (flags === 0 || flags === BORDER_MASK) return undefined;
+  return flags;
+};
+
+/**
+ * Parse GRADIENTANGLE attribute — integer in [0, 360].
+ * Out-of-range or non-integer values are ignored (C issues a warning).
+ * @see lib/common/htmllex.c:gradientanglefn
+ */
+export const parseGradientAngle = (v: string | undefined): number | undefined => {
+  if (v === undefined) return undefined;
+  const n = parseInt(v, 10);
+  if (isNaN(n) || String(n) !== v.trim()) return undefined;
+  if (n < 0 || n > 360) return undefined;
+  return n;
+};
+
+/**
+ * Parse COLUMNS attribute — only "*" is valid (sets vrule=true).
+ * @see lib/common/htmllex.c:columnsfn
+ */
+export const parseColumns = (v: string | undefined): true | undefined =>
+  v === '*' ? true : undefined;
+
+/**
+ * Parse ROWS attribute — only "*" is valid (sets hrule=true).
+ * @see lib/common/htmllex.c:rowsfn
+ */
+export const parseRows = (v: string | undefined): true | undefined =>
+  v === '*' ? true : undefined;
+
+export const buildCell = (content: HtmlCellContent[], a: Record<string, string>): HtmlCell => ({
+  kind: 'cell',
+  content,
+  port: a['port'],
+  align: parseAlign(a['align'] !== undefined ? a['align'] : ''),
+  valign: parseVAlign(a['valign'] !== undefined ? a['valign'] : ''),
+  balign: parseAlign(a['balign'] !== undefined ? a['balign'] : ''),
+  bgcolor: a['bgcolor'],
+  color: a['color'],
+  border: num(a['border']),
+  cellpadding: num(a['cellpadding']),
+  cellspacing: num(a['cellspacing']),
+  sides: parseSides(a['sides']),
+  gradientangle: parseGradientAngle(a['gradientangle']),
+  style: a['style'],
+  width: num(a['width']),
+  height: num(a['height']),
+  fixedsize: parseFixedSize(a),
+  colspan: num(a['colspan']),
+  rowspan: num(a['rowspan']),
+  href: anchorAttr(a['href']),
+  title: parseTitle(a),
+  target: anchorAttr(a['target']),
+  id: a['id'],
+});
+
+export const buildTable = (rows: HtmlRow[], a: Record<string, string>): HtmlTable => ({
+  kind: 'table' as const,
+  rows,
+  border: num(a['border']),
+  cellborder: num(a['cellborder']),
+  cellspacing: num(a['cellspacing']),
+  cellpadding: num(a['cellpadding']),
+  bgcolor: a['bgcolor'],
+  color: a['color'],
+  style: a['style'],
+  align: parseAlign(a['align'] !== undefined ? a['align'] : ''),
+  valign: parseVAlign(a['valign'] !== undefined ? a['valign'] : ''),
+  fixedsize: parseFixedSize(a),
+  width: num(a['width']),
+  height: num(a['height']),
+  href: anchorAttr(a['href']),
+  title: parseTitle(a),
+  target: anchorAttr(a['target']),
+  id: a['id'],
+  port: a['port'],
+  sides: parseSides(a['sides']),
+  gradientangle: parseGradientAngle(a['gradientangle']),
+  vrule: parseColumns(a['columns']),
+  hrule: parseRows(a['rows']),
+});
+