@zenuml/core 3.47.9 → 3.48.1

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

@@ -1,102 +0,0 @@
-/*
- * 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:4000",
-  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

@@ -1,101 +0,0 @@
-/*
- * 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

@@ -1,224 +0,0 @@
-/*
- * 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

@@ -1,74 +0,0 @@
-/*
- * 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

@@ -1,114 +0,0 @@
-/*
- * 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,
-  };
-}