@zenuml/core 3.46.0 → 3.46.1

package/scripts/analyze-compare-case/config.mjs

@@ -0,0 +1,102 @@
+/*
+ * What this file does:
+ * Owns the analyzer's command-line contract and default runtime settings.
+ *
+ * High-level flow:
+ * - Defines the default case, base URL, diff tolerances, and viewport.
+ * - Parses CLI flags into a normalized options object used by the entrypoint.
+ * - Keeps argument handling separate so it can be tested without Playwright.
+ *
+ * Example input:
+ * `["--case", "async-2a", "--user-data-dir", "/Users/pengxiao/Library/Application Support/Google/Chrome", "--profile-directory", "Profile 8", "--json"]`
+ *
+ * Example output:
+ * `{ caseName: "async-2a", userDataDir: "/Users/.../Chrome", profileDirectory: "Profile 8", jsonOnly: true, ... }`
+ */
+export const DEFAULTS = {
+  caseName: "async-2a",
+  baseUrl: "http://localhost:8080",
+  lumaThreshold: 240,
+  channelTolerance: 12,
+  positionTolerance: 0,
+  viewport: { width: 1600, height: 2200 },
+  userDataDir: process.env.PLAYWRIGHT_USER_DATA_DIR || null,
+  profileDirectory: process.env.PLAYWRIGHT_PROFILE_DIRECTORY || null,
+  browserChannel: process.env.PLAYWRIGHT_CHANNEL || null,
+  headless: process.env.PLAYWRIGHT_HEADLESS === "1",
+};
+
+export function parseArgs(argv) {
+  const args = { ...DEFAULTS, jsonOnly: false, summaryOnly: false, outputDir: null };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = argv[i + 1];
+    if ((arg === "--case" || arg === "-c") && next) {
+      args.caseName = next;
+      i++;
+      continue;
+    }
+    if ((arg === "--base-url" || arg === "-b") && next) {
+      args.baseUrl = next;
+      i++;
+      continue;
+    }
+    if (arg === "--user-data-dir" && next) {
+      args.userDataDir = next;
+      i++;
+      continue;
+    }
+    if (arg === "--profile-directory" && next) {
+      args.profileDirectory = next;
+      i++;
+      continue;
+    }
+    if (arg === "--channel" && next) {
+      args.browserChannel = next;
+      i++;
+      continue;
+    }
+    if (arg === "--json") {
+      args.jsonOnly = true;
+      continue;
+    }
+    if (arg === "--summary-only") {
+      args.summaryOnly = true;
+      continue;
+    }
+    if (arg === "--output-dir" && next) {
+      args.outputDir = next;
+      i++;
+      continue;
+    }
+    if (arg === "--luma" && next) {
+      args.lumaThreshold = Number(next);
+      i++;
+      continue;
+    }
+    if (arg === "--ctol" && next) {
+      args.channelTolerance = Number(next);
+      i++;
+      continue;
+    }
+    if (arg === "--ptol" && next) {
+      args.positionTolerance = Number(next);
+      i++;
+      continue;
+    }
+    if (arg === "--headed") {
+      args.headless = false;
+      continue;
+    }
+    if (arg === "--headless") {
+      args.headless = true;
+      continue;
+    }
+    if (!arg.startsWith("-") && args.caseName === DEFAULTS.caseName) {
+      args.caseName = arg;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+  return args;
+}

package/scripts/analyze-compare-case/geometry.mjs

@@ -0,0 +1,101 @@
+/*
+ * What this file does:
+ * Provides the shared math helpers used across the analyzer.
+ *
+ * High-level flow:
+ * - Normalizes offsets and rounding for stable report output.
+ * - Computes rectangle relationships such as union, overlap, and centers.
+ * - Centralizes these primitives so extraction, scoring, and residual attribution
+ *   all use the same geometry rules.
+ *
+ * Example input:
+ * `unionRect([{ x: 10, y: 20, w: 5, h: 5 }, { x: 14, y: 18, w: 6, h: 10 }])`
+ *
+ * Example output:
+ * `{ x: 10, y: 18, w: 10, h: 12 }`
+ */
+export function round(value, digits = 2) {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+}
+
+export function normalizeOffset(value) {
+  const rounded = round(value);
+  return Math.abs(rounded) < 0.05 ? 0 : rounded;
+}
+
+export function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+
+export function segmentGraphemes(text) {
+  if (typeof Intl !== "undefined" && typeof Intl.Segmenter === "function") {
+    return Array.from(new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(text)).map(
+      (part) => ({ grapheme: part.segment, index: part.index }),
+    );
+  }
+
+  const chars = Array.from(text);
+  let offset = 0;
+  return chars.map((grapheme) => {
+    const part = { grapheme, index: offset };
+    offset += grapheme.length;
+    return part;
+  });
+}
+
+export function keyForLabel(label) {
+  return `${label.kind}\u0000${label.pairText ?? label.text}\u0000${label.textOrder}`;
+}
+
+export function rectRight(rect) {
+  return rect.x + rect.w;
+}
+
+export function rectBottom(rect) {
+  return rect.y + rect.h;
+}
+
+export function area(rect) {
+  return Math.max(0, rect.w) * Math.max(0, rect.h);
+}
+
+export function unionRect(rects) {
+  if (!rects || rects.length === 0) {
+    return { x: 0, y: 0, w: 0, h: 0 };
+  }
+  const left = Math.min(...rects.map((rect) => rect.x));
+  const top = Math.min(...rects.map((rect) => rect.y));
+  const right = Math.max(...rects.map((rect) => rect.x + rect.w));
+  const bottom = Math.max(...rects.map((rect) => rect.y + rect.h));
+  return { x: left, y: top, w: right - left, h: bottom - top };
+}
+
+export function arrowEndpointsFromBox(box) {
+  return {
+    left_x: box.x,
+    right_x: box.x + box.w,
+    width: box.w,
+  };
+}
+
+export function intersectionArea(a, b) {
+  const left = Math.max(a.x, b.x);
+  const top = Math.max(a.y, b.y);
+  const right = Math.min(rectRight(a), rectRight(b));
+  const bottom = Math.min(rectBottom(a), rectBottom(b));
+  return Math.max(0, right - left) * Math.max(0, bottom - top);
+}
+
+export function rectCenter(rect) {
+  return {
+    x: rect.x + rect.w / 2,
+    y: rect.y + rect.h / 2,
+  };
+}
+
+export function iou(a, b) {
+  const inter = intersectionArea(a, b);
+  const union = area(a) + area(b) - inter;
+  return union <= 0 ? 0 : inter / union;
+}

package/scripts/analyze-compare-case/native-diff.mjs

@@ -0,0 +1,224 @@
+/*
+ * What this file does:
+ * Builds the analyzer's local pixel diff from native HTML and SVG screenshots.
+ *
+ * High-level flow:
+ * - Flattens captured PNGs onto white so alpha does not skew comparison.
+ * - Compares HTML and SVG pixels with configurable channel and position tolerance.
+ * - Classifies pixels into match, html-only, svg-only, and color-diff buckets.
+ * - Exposes slot-level diff summaries used later by letter and icon scoring.
+ *
+ * Note:
+ * This module only produces the analyzer-side diff. It is not the live diff-panel
+ * source of truth used by the current dia-scoring policy.
+ *
+ * Example input:
+ * Two flattened images of the HTML and SVG roots plus options like
+ * `{ lumaThreshold: 240, channelTolerance: 12, positionTolerance: 0 }`
+ *
+ * Example output:
+ * `{ width, height, diffData, classData, stats: { matched, htmlOnly, svgOnly, colorDiff, pixelPct } }`
+ */
+import { PNG } from "pngjs";
+
+import { clamp, round } from "./geometry.mjs";
+
+function rgbaToLuma(r, g, b) {
+  return 0.3 * r + 0.59 * g + 0.11 * b;
+}
+
+export function flattenToWhite(png) {
+  const data = new Uint8ClampedArray(png.width * png.height * 4);
+  for (let i = 0; i < png.data.length; i += 4) {
+    const alpha = png.data[i + 3] / 255;
+    data[i] = Math.round(png.data[i] * alpha + 255 * (1 - alpha));
+    data[i + 1] = Math.round(png.data[i + 1] * alpha + 255 * (1 - alpha));
+    data[i + 2] = Math.round(png.data[i + 2] * alpha + 255 * (1 - alpha));
+    data[i + 3] = 255;
+  }
+  return { width: png.width, height: png.height, data };
+}
+
+function padImage(image, width, height) {
+  const data = new Uint8ClampedArray(width * height * 4);
+  data.fill(255);
+  for (let y = 0; y < image.height; y++) {
+    for (let x = 0; x < image.width; x++) {
+      const srcIndex = (y * image.width + x) * 4;
+      const dstIndex = (y * width + x) * 4;
+      data[dstIndex] = image.data[srcIndex];
+      data[dstIndex + 1] = image.data[srcIndex + 1];
+      data[dstIndex + 2] = image.data[srcIndex + 2];
+      data[dstIndex + 3] = 255;
+    }
+  }
+  return data;
+}
+
+function pixelsClose(a, b, tolerance) {
+  return (
+    Math.abs(a[0] - b[0]) <= tolerance &&
+    Math.abs(a[1] - b[1]) <= tolerance &&
+    Math.abs(a[2] - b[2]) <= tolerance
+  );
+}
+
+function getPixel(data, width, x, y) {
+  const index = (y * width + x) * 4;
+  return [data[index], data[index + 1], data[index + 2]];
+}
+
+function hasNearbyMatch(srcData, srcWidth, dstData, dstWidth, x, y, width, height, options) {
+  const pixel = getPixel(srcData, srcWidth, x, y);
+  for (let dy = -options.positionTolerance; dy <= options.positionTolerance; dy++) {
+    for (let dx = -options.positionTolerance; dx <= options.positionTolerance; dx++) {
+      const nx = x + dx;
+      const ny = y + dy;
+      if (nx < 0 || nx >= width || ny < 0 || ny >= height) {
+        continue;
+      }
+      const other = getPixel(dstData, dstWidth, nx, ny);
+      if (rgbaToLuma(other[0], other[1], other[2]) < options.lumaThreshold && pixelsClose(pixel, other, options.channelTolerance)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+export function computeNativeDiff(htmlImage, svgImage, options) {
+  const width = Math.max(htmlImage.width, svgImage.width);
+  const height = Math.max(htmlImage.height, svgImage.height);
+  const htmlData = padImage(htmlImage, width, height);
+  const svgData = padImage(svgImage, width, height);
+  const diffData = new Uint8ClampedArray(width * height * 4);
+  const classData = new Uint8Array(width * height);
+
+  let total = 0;
+  let matched = 0;
+  let htmlOnly = 0;
+  let svgOnly = 0;
+  let colorDiff = 0;
+
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const index = (y * width + x) * 4;
+      const a = [htmlData[index], htmlData[index + 1], htmlData[index + 2]];
+      const b = [svgData[index], svgData[index + 1], svgData[index + 2]];
+      const isHtmlContent = rgbaToLuma(a[0], a[1], a[2]) < options.lumaThreshold;
+      const isSvgContent = rgbaToLuma(b[0], b[1], b[2]) < options.lumaThreshold;
+
+      if (!isHtmlContent && !isSvgContent) {
+        diffData[index] = 240;
+        diffData[index + 1] = 240;
+        diffData[index + 2] = 240;
+        diffData[index + 3] = 255;
+        continue;
+      }
+
+      total++;
+      const matchHtml = hasNearbyMatch(htmlData, width, svgData, width, x, y, width, height, options);
+      const matchSvg = hasNearbyMatch(svgData, width, htmlData, width, x, y, width, height, options);
+
+      if (isHtmlContent && isSvgContent) {
+        if (matchHtml || matchSvg) {
+          matched++;
+          classData[y * width + x] = 1;
+          diffData[index] = 0;
+          diffData[index + 1] = 100;
+          diffData[index + 2] = 0;
+        } else {
+          colorDiff++;
+          classData[y * width + x] = 4;
+          diffData[index] = 255;
+          diffData[index + 1] = 0;
+          diffData[index + 2] = 255;
+        }
+      } else if (isHtmlContent) {
+        if (matchHtml) {
+          matched++;
+          classData[y * width + x] = 1;
+          diffData[index] = 0;
+          diffData[index + 1] = 100;
+          diffData[index + 2] = 0;
+        } else {
+          htmlOnly++;
+          classData[y * width + x] = 2;
+          diffData[index] = 255;
+          diffData[index + 1] = 0;
+          diffData[index + 2] = 0;
+        }
+      } else if (matchSvg) {
+        matched++;
+        classData[y * width + x] = 1;
+        diffData[index] = 0;
+        diffData[index + 1] = 100;
+        diffData[index + 2] = 0;
+      } else {
+        svgOnly++;
+        classData[y * width + x] = 3;
+        diffData[index] = 0;
+        diffData[index + 1] = 0;
+        diffData[index + 2] = 255;
+      }
+      diffData[index + 3] = 255;
+    }
+  }
+
+  return {
+    width,
+    height,
+    diffData,
+    classData,
+    stats: {
+      matched,
+      total,
+      htmlOnly,
+      svgOnly,
+      colorDiff,
+      pixelPct: total > 0 ? round((matched / total) * 100, 2) : 100,
+    },
+  };
+}
+
+export function buildPngBuffer(width, height, data) {
+  const png = new PNG({ width, height });
+  png.data = Buffer.from(data);
+  return PNG.sync.write(png);
+}
+
+export function analyzeDiffSlot(diffImage, slot) {
+  const x1 = clamp(Math.floor(slot.x), 0, diffImage.width);
+  const y1 = clamp(Math.floor(slot.y), 0, diffImage.height);
+  const x2 = clamp(Math.ceil(slot.x + slot.w), 0, diffImage.width);
+  const y2 = clamp(Math.ceil(slot.y + slot.h), 0, diffImage.height);
+
+  let redCount = 0;
+  let blueCount = 0;
+  let redSumX = 0;
+  let redSumY = 0;
+  let blueSumX = 0;
+  let blueSumY = 0;
+
+  for (let y = y1; y < y2; y++) {
+    for (let x = x1; x < x2; x++) {
+      const cls = diffImage.classData[y * diffImage.width + x];
+      if (cls === 2) {
+        redCount++;
+        redSumX += x + 0.5;
+        redSumY += y + 0.5;
+      } else if (cls === 3) {
+        blueCount++;
+        blueSumX += x + 0.5;
+        blueSumY += y + 0.5;
+      }
+    }
+  }
+
+  return {
+    redCount,
+    blueCount,
+    redCentroid: redCount > 0 ? { x: redSumX / redCount, y: redSumY / redCount } : null,
+    blueCentroid: blueCount > 0 ? { x: blueSumX / blueCount, y: blueSumY / blueCount } : null,
+  };
+}

package/scripts/analyze-compare-case/output.mjs

@@ -0,0 +1,74 @@
+/*
+ * What this file does:
+ * Handles the analyzer's side effects after the report has been built.
+ *
+ * High-level flow:
+ * - Optionally writes screenshot and diff artifacts plus report.json to disk.
+ * - Renders report output in one of three modes: summary-only, JSON-only, or both.
+ * - Keeps file IO and stdout formatting out of the entrypoint and scoring logic.
+ *
+ * Example input:
+ * A finished report object, screenshot buffers, diff data, and CLI mode flags.
+ *
+ * Example output:
+ * Either files on disk like `html.png`, `svg.png`, `diff.png`, `report.json`,
+ * or text written to stdout in JSON-only, summary-only, or mixed mode.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { buildPngBuffer } from "./native-diff.mjs";
+
+export async function maybeWriteArtifacts(outputDir, htmlBuffer, svgBuffer, diffImage, report) {
+  if (!outputDir) {
+    return null;
+  }
+
+  await fs.mkdir(outputDir, { recursive: true });
+  const paths = {
+    html: path.join(outputDir, "html.png"),
+    svg: path.join(outputDir, "svg.png"),
+    diff: path.join(outputDir, "diff.png"),
+    report: path.join(outputDir, "report.json"),
+  };
+
+  await Promise.all([
+    fs.writeFile(paths.html, htmlBuffer),
+    fs.writeFile(paths.svg, svgBuffer),
+    fs.writeFile(paths.diff, buildPngBuffer(diffImage.width, diffImage.height, diffImage.diffData)),
+    fs.writeFile(paths.report, JSON.stringify(report, null, 2)),
+  ]);
+
+  return paths;
+}
+
+export function writeReportOutput(stdout, report, options) {
+  const summaryBlock = [
+    report.summary,
+    report.number_summary,
+    report.arrow_summary,
+    report.participant_label_summary,
+    report.participant_stereotype_summary,
+    report.participant_icon_summary,
+    report.participant_box_summary,
+    report.participant_color_summary,
+    report.comment_summary,
+    report.participant_group_summary,
+    report.occurrence_summary,
+    report.fragment_divider_summary,
+    report.residual_scope_summary,
+  ].flat().join("\n");
+
+  if (options.summaryOnly) {
+    stdout.write(`${summaryBlock}\n`);
+    return;
+  }
+
+  if (!options.jsonOnly) {
+    stdout.write(`${JSON.stringify(report, null, 2)}\n\n`);
+    stdout.write(`${summaryBlock}\n`);
+    return;
+  }
+
+  stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}

package/scripts/analyze-compare-case/panel-diff.mjs

@@ -0,0 +1,114 @@
+/*
+ * What this file does:
+ * Uses the page's live `#diff-panel canvas` as the analyzer's pixel-diff source.
+ *
+ * High-level flow:
+ * - Renders the compare-case diff into the page's diff panel from captured screenshots.
+ * - Reads the panel canvas pixels back into Node.
+ * - Classifies panel colors into match, html-only, svg-only, and color-diff classes.
+ * - Returns a `diffImage` object compatible with the analyzer's scoring modules.
+ *
+ * Example input:
+ * A Playwright `page` plus HTML/SVG PNG buffers captured from the compare-case roots.
+ *
+ * Example output:
+ * `{ width, height, diffData, classData, stats, badgeText, panelStats }`
+ */
+import { round } from "./geometry.mjs";
+
+function classifyPanelPixel(r, g, b) {
+  const isBackground = r >= 230 && g >= 230 && b >= 230;
+  if (isBackground) {
+    return 0;
+  }
+  if (r >= 220 && g <= 120 && b <= 160 && r > b) {
+    return 2;
+  }
+  if (b >= 220 && r <= 120 && g <= 120 && b > r) {
+    return 3;
+  }
+  if (r >= 200 && b >= 200 && g <= 140) {
+    return 4;
+  }
+  if (g >= 50 && g >= r && g >= b) {
+    return 1;
+  }
+  return 0;
+}
+
+export function buildDiffImageFromPanel(width, height, rgbaData) {
+  const diffData = new Uint8ClampedArray(rgbaData);
+  const classData = new Uint8Array(width * height);
+
+  let matched = 0;
+  let htmlOnly = 0;
+  let svgOnly = 0;
+  let colorDiff = 0;
+
+  for (let i = 0; i < classData.length; i++) {
+    const offset = i * 4;
+    const cls = classifyPanelPixel(
+      diffData[offset],
+      diffData[offset + 1],
+      diffData[offset + 2],
+    );
+    classData[i] = cls;
+    if (cls === 1) matched++;
+    else if (cls === 2) htmlOnly++;
+    else if (cls === 3) svgOnly++;
+    else if (cls === 4) colorDiff++;
+  }
+
+  const total = matched + htmlOnly + svgOnly + colorDiff;
+  const posMatched = matched + colorDiff;
+
+  return {
+    width,
+    height,
+    diffData,
+    classData,
+    stats: {
+      matched,
+      posMatched,
+      total,
+      htmlOnly,
+      svgOnly,
+      colorDiff,
+      pixelPct: total > 0 ? round((matched / total) * 100, 2) : 100,
+      posPct: total > 0 ? round((posMatched / total) * 100, 2) : 100,
+    },
+  };
+}
+
+export async function renderAndReadDiffPanel(page, htmlBuffer, svgBuffer) {
+  const htmlDataUrl = `data:image/png;base64,${htmlBuffer.toString("base64")}`;
+  const svgDataUrl = `data:image/png;base64,${svgBuffer.toString("base64")}`;
+
+  const panel = await page.evaluate(async ({ htmlDataUrl, svgDataUrl }) => {
+    if (typeof window.diffFromImages !== "function") {
+      throw new Error("window.diffFromImages is not available on compare-case.html");
+    }
+
+    const panelStats = await window.diffFromImages(htmlDataUrl, svgDataUrl);
+    const canvas = document.querySelector("#diff-panel canvas");
+    if (!canvas) {
+      throw new Error("#diff-panel canvas was not rendered");
+    }
+
+    const ctx = canvas.getContext("2d");
+    const image = ctx.getImageData(0, 0, canvas.width, canvas.height);
+    return {
+      width: canvas.width,
+      height: canvas.height,
+      data: Array.from(image.data),
+      badgeText: document.getElementById("match-badge")?.textContent?.trim() || "",
+      panelStats,
+    };
+  }, { htmlDataUrl, svgDataUrl });
+
+  return {
+    ...buildDiffImageFromPanel(panel.width, panel.height, panel.data),
+    badgeText: panel.badgeText,
+    panelStats: panel.panelStats,
+  };
+}