@zenuml/core 3.46.0 → 3.46.1

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

@@ -0,0 +1,157 @@
+/*
+ * What this file does:
+ * Assembles the final report object from scored sections and residual attribution.
+ *
+ * High-level flow:
+ * - Pulls in semantic scoring results and residual hotspot attribution.
+ * - Builds the JSON report shape consumed by scripts and humans.
+ * - Produces concise summary lines for labels, numbers, arrows, icons, boxes,
+ *   and residual scopes so the CLI can print a readable digest.
+ *
+ * This module is the boundary between raw analysis results and final report shape.
+ *
+ * Example input:
+ * `caseName`, extracted geometry, and the analyzer's local diff image.
+ *
+ * Example output:
+ * A single report object with JSON-friendly sections plus terminal summary arrays
+ * such as `summary`, `arrow_summary`, and `residual_scope_summary`.
+ */
+import { buildResidualScopes } from "./residual-scopes.mjs";
+import { buildScoredSections } from "./scoring.mjs";
+
+function formatLetterSummary(letter) {
+  if (letter.dx == null || letter.dy == null) {
+    return `${letter.grapheme}: ambiguous`;
+  }
+  const dx = letter.dx.toFixed(2);
+  const dy = letter.dy.toFixed(2);
+  return `${letter.grapheme}: dx=${dx}px dy=${dy}px`;
+}
+
+function formatSectionSummary(prefix, item) {
+  const notes = [];
+  if (item.owner_text) {
+    notes.push(`owner=${item.owner_text}`);
+  }
+  if (item.html_text && item.svg_text && item.html_text !== item.svg_text) {
+    notes.push(`text_mismatch(html=${item.html_text} svg=${item.svg_text})`);
+  }
+  const noteSuffix = notes.length > 0 ? ` [${notes.join("; ")}]` : "";
+  if (!item.letters || item.letters.length === 0) {
+    return `${prefix}:${item.key.kind}:${item.key.text}${noteSuffix} -> ambiguous`;
+  }
+  return `${prefix}:${item.key.kind}:${item.key.text}${noteSuffix} -> ${item.letters.map(formatLetterSummary).join(", ")}`;
+}
+
+function formatArrowSummary(arrow) {
+  if (arrow.status !== "ok") {
+    return "ambiguous";
+  }
+  const parts = [
+    `left_dx=${arrow.left_dx.toFixed(2)}px`,
+    `right_dx=${arrow.right_dx.toFixed(2)}px`,
+    `width_dx=${arrow.width_dx.toFixed(2)}px`,
+  ];
+  if (arrow.key?.kind === "self") {
+    parts.push(`top_dy=${arrow.top_dy.toFixed(2)}px`);
+    parts.push(`bottom_dy=${arrow.bottom_dy.toFixed(2)}px`);
+    parts.push(`height_dy=${arrow.height_dy.toFixed(2)}px`);
+  }
+  return parts.join(" ");
+}
+
+function formatParticipantIconSummary(icon) {
+  const notes = [];
+  if (icon.label_text) {
+    notes.push(`label=${icon.label_text}`);
+  }
+  if (icon.anchor_kind) {
+    notes.push(`anchor=${icon.anchor_kind}`);
+  }
+  if (icon.presence && icon.presence.html !== icon.presence.svg) {
+    notes.push(`presence_mismatch(html=${icon.presence.html} svg=${icon.presence.svg})`);
+  }
+  const noteSuffix = notes.length > 0 ? ` [${notes.join("; ")}]` : "";
+  if (icon.status !== "ok") {
+    return `icon:${icon.name}${noteSuffix} -> ambiguous`;
+  }
+  return `icon:${icon.name}${noteSuffix} -> icon_dx=${icon.icon_dx.toFixed(2)}px icon_dy=${icon.icon_dy.toFixed(2)}px relative_dx=${icon.relative_dx.toFixed(2)}px relative_dy=${icon.relative_dy.toFixed(2)}px`;
+}
+
+function formatParticipantBoxSummary(box) {
+  if (box.status !== "ok") {
+    return `participant-box:${box.name} -> ambiguous`;
+  }
+  return `participant-box:${box.name} -> dx=${box.dx.toFixed(2)}px dy=${box.dy.toFixed(2)}px dw=${box.dw.toFixed(2)}px dh=${box.dh.toFixed(2)}px`;
+}
+
+function formatParticipantColorSummary(color) {
+  if (color.status !== "ok") {
+    return `participant-color:${color.name} -> ambiguous`;
+  }
+  return `participant-color:${color.name} -> bg(html=${color.html_background_color} svg=${color.svg_background_color}) text(html=${color.html_text_color} svg=${color.svg_text_color}) stereotype(html=${color.html_stereotype_color} svg=${color.svg_stereotype_color})`;
+}
+
+function formatGroupSummary(group) {
+  if (group.status !== "ok") {
+    return `participant-group:${group.name} -> ambiguous`;
+  }
+  const namePart = group.name_dx === null || group.name_dy === null
+    ? "name=ambiguous"
+    : `name_dx=${group.name_dx.toFixed(2)}px name_dy=${group.name_dy.toFixed(2)}px`;
+  return `participant-group:${group.name} -> dx=${group.dx.toFixed(2)}px dy=${group.dy.toFixed(2)}px dw=${group.dw.toFixed(2)}px dh=${group.dh.toFixed(2)}px ${namePart}`;
+}
+
+function formatOccurrenceSummary(occ) {
+  if (occ.status !== "ok") {
+    return `occurrence:${occ.participant}#${occ.idx} -> ambiguous`;
+  }
+  return `occurrence:${occ.participant}#${occ.idx} -> dx=${occ.dx.toFixed(2)}px dy=${occ.dy.toFixed(2)}px dw=${occ.dw.toFixed(2)}px dh=${occ.dh.toFixed(2)}px`;
+}
+
+function formatFragmentDividerSummary(div) {
+  if (div.status !== "ok") {
+    return `fragment-divider:#${div.idx} -> ambiguous`;
+  }
+  return `fragment-divider:#${div.idx} -> dx=${div.dx.toFixed(2)}px dy=${div.dy.toFixed(2)}px dw=${div.dw.toFixed(2)}px`;
+}
+
+export function buildReport(caseName, extracted, diffImage) {
+  const sections = buildScoredSections(extracted, diffImage);
+  const residualScopes = buildResidualScopes(extracted, diffImage);
+
+  return {
+    case: caseName,
+    labels: sections.labels,
+    numbers: sections.numbers,
+    arrows: sections.arrows,
+    participant_labels: sections.participantLabels,
+    participant_stereotypes: sections.participantStereotypes,
+    participant_icons: sections.participantIcons,
+    participant_boxes: sections.participantBoxes,
+    participant_colors: sections.participantColors,
+    comments: sections.comments,
+    participant_groups: sections.groups,
+    occurrences: sections.occurrences,
+    fragment_dividers: sections.fragmentDividers,
+    dividers: sections.dividers,
+    residual_scopes: residualScopes.scopes,
+    summary: sections.labels.map((label) => formatSectionSummary("label", label)),
+    number_summary: sections.numbers.map((number) => formatSectionSummary("number", number)),
+    arrow_summary: sections.arrows.map((arrow) => `arrow:${arrow.key.text} -> ${formatArrowSummary(arrow)}`),
+    participant_label_summary: sections.participantLabels.map((label) => formatSectionSummary("participant-label", label)),
+    participant_stereotype_summary: sections.participantStereotypes.map((label) => formatSectionSummary("participant-stereotype", label)),
+    participant_icon_summary: sections.participantIcons.map((icon) => formatParticipantIconSummary(icon)),
+    participant_box_summary: sections.participantBoxes.map((box) => formatParticipantBoxSummary(box)),
+    participant_color_summary: sections.participantColors.map((color) => formatParticipantColorSummary(color)),
+    comment_summary: sections.comments.map((comment) => formatSectionSummary("comment", comment)),
+    participant_group_summary: sections.groups.map((group) => formatGroupSummary(group)),
+    occurrence_summary: sections.occurrences.map((occ) => formatOccurrenceSummary(occ)),
+    fragment_divider_summary: sections.fragmentDividers.map((div) => formatFragmentDividerSummary(div)),
+    divider_summary: sections.dividers.map((d) => `divider:"${d.label}" dy=${d.dy ?? "?"} ${d.status}`),
+    residual_scope_summary: residualScopes.summary,
+    residual_scope_html_only_top: residualScopes.html_only_top,
+    residual_scope_svg_only_top: residualScopes.svg_only_top,
+  };
+}

package/scripts/analyze-compare-case/residual-scopes.mjs

@@ -0,0 +1,325 @@
+/*
+ * What this file does:
+ * Groups remaining diff pixels into residual hotspots and attributes them to nearby elements.
+ *
+ * High-level flow:
+ * - Scans the analyzer's local diff for connected html-only and svg-only clusters.
+ * - Builds candidate scope items from labels, arrows, participant headers, icons,
+ *   boxes, and frame-level containers.
+ * - Picks the nearest and most specific target on each side for each cluster.
+ * - Produces concise residual summaries for terminal and JSON output.
+ *
+ * This module explains "where the remaining diff seems to belong" after the
+ * semantic scoring step.
+ *
+ * Example input:
+ * Extracted geometry plus a diff image containing `html-only` and `svg-only` pixels.
+ *
+ * Example output:
+ * `{ scopes, summary, html_only_top, svg_only_top }`
+ * with each scope carrying a bbox, centroid, and nearest HTML/SVG targets.
+ */
+import { area, intersectionArea, rectBottom, rectRight, round } from "./geometry.mjs";
+
+function scopePriority(category) {
+  switch (category) {
+    case "participant-icon":
+      return 8;
+    case "participant-stereotype":
+    case "label":
+    case "number":
+    case "comment":
+    case "participant-label":
+      return 7;
+    case "arrow":
+    case "fragment-divider":
+      return 6;
+    case "occurrence":
+    case "participant-box":
+    case "participant-group":
+      return 5;
+    case "frame-border":
+      return 2;
+    case "diagram-root":
+      return 1;
+    default:
+      return 0;
+  }
+}
+
+function pointInRect(point, rect) {
+  return point.x >= rect.x && point.x <= rectRight(rect) && point.y >= rect.y && point.y <= rectBottom(rect);
+}
+
+function distanceToRect(point, rect) {
+  const dx = point.x < rect.x ? rect.x - point.x : point.x > rectRight(rect) ? point.x - rectRight(rect) : 0;
+  const dy = point.y < rect.y ? rect.y - point.y : point.y > rectBottom(rect) ? point.y - rectBottom(rect) : 0;
+  return Math.hypot(dx, dy);
+}
+
+function formatScopeName(item) {
+  if (item.owner_text && item.text && item.owner_text !== item.text) {
+    return `${item.owner_text}:${item.text}`;
+  }
+  return item.name ?? item.text ?? item.kind ?? item.category ?? "unknown";
+}
+
+function buildScopeItems(side, extracted) {
+  const items = [];
+
+  function push(category, name, box, extra = {}) {
+    if (!box || box.w <= 0 || box.h <= 0) {
+      return;
+    }
+    items.push({
+      side,
+      category,
+      name,
+      box,
+      ...extra,
+    });
+  }
+
+  const sideKey = side === "html" ? "html" : "svg";
+  const labels = side === "html" ? extracted.htmlLabels : extracted.svgLabels;
+  const numbers = side === "html" ? extracted.htmlNumbers : extracted.svgNumbers;
+  const arrows = side === "html" ? extracted.htmlArrows : extracted.svgArrows;
+  const participants = side === "html" ? extracted.htmlParticipants : extracted.svgParticipants;
+  const comments = side === "html" ? extracted.htmlComments : extracted.svgComments;
+  const groups = side === "html" ? extracted.htmlGroups : extracted.svgGroups;
+  const occurrences = side === "html" ? (extracted.htmlOccurrences || []) : (extracted.svgOccurrences || []);
+  const fragmentDividers = side === "html" ? (extracted.htmlFragmentDividers || []) : (extracted.svgFragmentDividers || []);
+
+  for (const label of labels) {
+    push("label", formatScopeName(label), label.box, {
+      kind: label.kind,
+      text: label.text,
+      owner_text: label.ownerText ?? null,
+    });
+  }
+  for (const number of numbers) {
+    push("number", formatScopeName(number), number.box, {
+      kind: number.kind,
+      text: number.text,
+      owner_text: number.ownerText ?? null,
+    });
+  }
+  for (const arrow of arrows) {
+    push("arrow", formatScopeName(arrow), arrow.box, {
+      kind: arrow.kind,
+      text: arrow.text,
+      owner_text: arrow.labelText ?? null,
+    });
+  }
+  for (const comment of comments) {
+    push("comment", formatScopeName(comment), comment.box, {
+      kind: comment.kind,
+      text: comment.text,
+    });
+  }
+  for (const participant of participants) {
+    push("participant-box", participant.name, participant.participantBox, {
+      kind: "participant",
+      text: participant.labelText ?? participant.name,
+      owner_text: participant.name,
+    });
+    push("participant-label", participant.name, participant.labelBox, {
+      kind: "participant",
+      text: participant.labelText ?? participant.name,
+      owner_text: participant.name,
+    });
+    push("participant-stereotype", participant.name, participant.stereotypeBox, {
+      kind: "participant",
+      text: participant.stereotypeText ?? participant.name,
+      owner_text: participant.name,
+    });
+    push("participant-icon", participant.name, participant.iconBox, {
+      kind: "participant",
+      text: participant.labelText ?? participant.name,
+      owner_text: participant.name,
+    });
+  }
+  for (const group of groups) {
+    push("participant-group", group.name || "group", group.box, {
+      kind: "group",
+      text: group.name,
+    });
+  }
+  for (const occ of occurrences) {
+    push("occurrence", `${occ.participant}#${occ.idx}`, occ.box, {
+      kind: "occurrence",
+      text: occ.participant,
+      owner_text: occ.participant,
+    });
+  }
+  for (const div of fragmentDividers) {
+    push("fragment-divider", `divider#${div.idx}`, { x: div.x, y: div.y, w: div.width, h: 1 }, {
+      kind: "divider",
+      text: div.label || `divider#${div.idx}`,
+    });
+  }
+
+  if (sideKey === "html") {
+    push("diagram-root", "html-root", extracted.htmlRootBox, { kind: "root" });
+  } else {
+    push("frame-border", "frame-border", extracted.svgFrameBorderBox, { kind: "frame" });
+    push("diagram-root", "svg-root", extracted.svgRootBox, { kind: "root" });
+  }
+
+  return items;
+}
+
+function buildDiffClusters(diffImage, targetClass) {
+  const visited = new Uint8Array(diffImage.width * diffImage.height);
+  const clusters = [];
+  const offsets = [-1, 0, 1, 0, -1];
+
+  for (let index = 0; index < diffImage.classData.length; index++) {
+    if (visited[index] || diffImage.classData[index] !== targetClass) {
+      continue;
+    }
+    visited[index] = 1;
+    const queue = [index];
+    let head = 0;
+    let size = 0;
+    let sumX = 0;
+    let sumY = 0;
+    let left = diffImage.width;
+    let top = diffImage.height;
+    let right = -1;
+    let bottom = -1;
+
+    while (head < queue.length) {
+      const current = queue[head++];
+      const x = current % diffImage.width;
+      const y = Math.floor(current / diffImage.width);
+      size++;
+      sumX += x + 0.5;
+      sumY += y + 0.5;
+      left = Math.min(left, x);
+      top = Math.min(top, y);
+      right = Math.max(right, x);
+      bottom = Math.max(bottom, y);
+
+      for (let dir = 0; dir < 4; dir++) {
+        const nx = x + offsets[dir];
+        const ny = y + offsets[dir + 1];
+        if (nx < 0 || nx >= diffImage.width || ny < 0 || ny >= diffImage.height) {
+          continue;
+        }
+        const nextIndex = ny * diffImage.width + nx;
+        if (visited[nextIndex] || diffImage.classData[nextIndex] !== targetClass) {
+          continue;
+        }
+        visited[nextIndex] = 1;
+        queue.push(nextIndex);
+      }
+    }
+
+    clusters.push({
+      class: targetClass === 2 ? "html-only" : "svg-only",
+      size,
+      bbox: {
+        x: left,
+        y: top,
+        w: right - left + 1,
+        h: bottom - top + 1,
+      },
+      centroid: {
+        x: sumX / size,
+        y: sumY / size,
+      },
+    });
+  }
+
+  return clusters.sort((a, b) => b.size - a.size);
+}
+
+function pickScopeTarget(cluster, items) {
+  const centroid = cluster.centroid;
+  let best = null;
+  let bestScore = -Infinity;
+
+  for (const item of items) {
+    const contains = pointInRect(centroid, item.box);
+    const distance = distanceToRect(centroid, item.box);
+    const overlap = intersectionArea(cluster.bbox, item.box);
+    const score = (contains ? 10000 : 0)
+      + overlap * 10
+      - distance * 100
+      + scopePriority(item.category) * 1000
+      - area(item.box) * 0.01;
+
+    if (score > bestScore) {
+      bestScore = score;
+      best = {
+        category: item.category,
+        name: item.name,
+        kind: item.kind ?? null,
+        text: item.text ?? null,
+        owner_text: item.owner_text ?? null,
+        contains_centroid: contains,
+        overlap_area: round(overlap),
+        distance: round(distance),
+        box: {
+          x: round(item.box.x),
+          y: round(item.box.y),
+          w: round(item.box.w),
+          h: round(item.box.h),
+        },
+      };
+    }
+  }
+
+  return best;
+}
+
+function formatResidualScopeSummary(scope) {
+  const htmlTarget = scope.html_target
+    ? `${scope.html_target.category}:${scope.html_target.name}`
+    : "none";
+  const svgTarget = scope.svg_target
+    ? `${scope.svg_target.category}:${scope.svg_target.name}`
+    : "none";
+  return `${scope.class}:${scope.size}px @ (${scope.centroid.x.toFixed(1)},${scope.centroid.y.toFixed(1)}) -> html=${htmlTarget} svg=${svgTarget}`;
+}
+
+export function buildResidualScopes(extracted, diffImage) {
+  const htmlItems = buildScopeItems("html", extracted);
+  const svgItems = buildScopeItems("svg", extracted);
+  const clusters = [
+    ...buildDiffClusters(diffImage, 2),
+    ...buildDiffClusters(diffImage, 3),
+  ].sort((a, b) => b.size - a.size);
+
+  const residualScopes = clusters.map((cluster, index) => ({
+    rank: index + 1,
+    class: cluster.class,
+    size: cluster.size,
+    centroid: {
+      x: round(cluster.centroid.x),
+      y: round(cluster.centroid.y),
+    },
+    bbox: {
+      x: round(cluster.bbox.x),
+      y: round(cluster.bbox.y),
+      w: round(cluster.bbox.w),
+      h: round(cluster.bbox.h),
+    },
+    html_target: pickScopeTarget(cluster, htmlItems),
+    svg_target: pickScopeTarget(cluster, svgItems),
+  }));
+
+  const byClass = residualScopes.reduce((acc, scope) => {
+    acc[scope.class] = acc[scope.class] || [];
+    acc[scope.class].push(scope);
+    return acc;
+  }, {});
+
+  return {
+    scopes: residualScopes,
+    summary: residualScopes.slice(0, 20).map((scope) => formatResidualScopeSummary(scope)),
+    html_only_top: (byClass["html-only"] || []).slice(0, 10),
+    svg_only_top: (byClass["svg-only"] || []).slice(0, 10),
+  };
+}