@bovinphang/craft-common 0.0.0-stage → 1.0.0

package/localized/zh-CN/skills/cc-technical-diagrams/scripts/mermaid-render.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// @ts-check
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+
+// Use installed tools only. Never invoke npx or a shell that could download packages.
+try {
+  /** @type {Record<string,string>} */
+  const args = {};
+  for (let i = 2; i < process.argv.length; i += 2) {
+    const key = process.argv[i];
+    if (!key.startsWith("--") || !process.argv[i + 1]) throw new Error("Expected --input source.mmd --output image.svg [--cli path] [--theme default|dark|neutral|forest] [--timeout 30000] [--report file.json]");
+    if (!["input", "output", "cli", "theme", "timeout", "report", "format"].includes(key.slice(2))) throw new Error(`Unknown argument: ${key}`);
+    args[key.slice(2)] = process.argv[i + 1];
+  }
+  if (!args.input || !args.output) throw new Error("--input and --output are required.");
+  const input = path.resolve(args.input), output = path.resolve(args.output);
+  if (!fs.existsSync(input)) throw new Error(`Input does not exist: ${input}`);
+  if (!/\.(svg|png|pdf)$/i.test(output)) throw new Error("Output must end in .svg, .png or .pdf.");
+  const theme = args.theme === "light" ? "default" : args.theme ?? "default";
+  if (args.format && !["json","markdown"].includes(args.format)) throw new Error("--format must be json or markdown");
+  if (!["default", "dark", "neutral", "forest"].includes(theme)) throw new Error("Unsupported Mermaid theme.");
+  const timeout = Number(args.timeout ?? 30000);
+  if (!Number.isFinite(timeout) || timeout < 100 || timeout > 300000) throw new Error("--timeout must be between 100 and 300000 milliseconds.");
+  /** @type {string[]} */
+  const candidates = args.cli ? [path.resolve(args.cli)] : (process.env.PATH ?? "").split(path.delimiter).flatMap((dir) => [path.join(dir, "mmdc"), path.join(dir, "mmdc.cmd")]);
+  let cli = candidates.find((candidate) => fs.existsSync(candidate));
+  if (cli?.endsWith(".cmd")) {
+    // npm Windows shims are shell scripts. Execute their installed JS entry directly.
+    const entry = path.join(path.dirname(cli), "node_modules", "@mermaid-js", "mermaid-cli", "src", "cli.js");
+    cli = fs.existsSync(entry) ? entry : undefined;
+  }
+  if (!cli) throw new Error("Mermaid CLI unavailable. Use the JSON/HTML renderer or provide an installed mmdc JS entry with --cli. No packages were installed.");
+  const js = /\.[cm]?js$/i.test(cli);
+  const command = js ? process.execPath : cli;
+  const prefix = js ? [cli] : [];
+  const version = spawnSync(command, [...prefix, "--version"], { encoding: "utf8", timeout, windowsHide: true });
+  if (version.error || version.status !== 0) throw new Error(`Mermaid CLI unavailable: ${version.error?.message ?? version.stderr}`);
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "fec-mermaid-"));
+  try {
+    const artifact = path.join(dir, `diagram${path.extname(output)}`);
+    const result = spawnSync(command, [...prefix, "-i", input, "-o", artifact, "-t", theme], { encoding: "utf8", timeout, windowsHide: true });
+    if (result.error || result.status !== 0) throw new Error(`Mermaid render failed: ${result.error?.message ?? result.stderr}`);
+    if (!fs.existsSync(artifact) || fs.statSync(artifact).size === 0) throw new Error("Mermaid render failed: no fresh artifact produced.");
+    const bytes = fs.readFileSync(artifact);
+    if (output.endsWith(".svg") && !bytes.toString("utf8").includes("<svg")) throw new Error("Mermaid render failed: invalid SVG.");
+    if (output.endsWith(".png") && bytes.subarray(0, 8).toString("hex") !== "89504e470d0a1a0a") throw new Error("Mermaid render failed: invalid PNG.");
+    fs.mkdirSync(path.dirname(output), { recursive: true });
+    fs.copyFileSync(artifact, output);
+    if (args.report) {
+      fs.mkdirSync(path.dirname(path.resolve(args.report)), { recursive: true });
+      fs.writeFileSync(args.report, JSON.stringify({ ok:true,engine:"mermaid",format:path.extname(output).slice(1),verified:false,route: "mermaid", version: version.stdout.trim(), input, output, theme, status: "rendered", visualQA: "pending" }, null, 2) + "\n");
+    }
+    const report = {ok:true,engine:"mermaid",version:version.stdout.trim(),input,output,format:path.extname(output).slice(1),verified:false,reason:"Final image visual QA is pending."};
+    console.log(args.format === "json" ? JSON.stringify(report) : `Rendered Mermaid diagram: ${output}\nVisual QA: pending`);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/localized/zh-CN/skills/cc-technical-diagrams/scripts/png-qa.mjs

@@ -0,0 +1,462 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import fs from "node:fs";
+import path from "node:path";
+import zlib from "node:zlib";
+import { segmentHits } from "./diagram-layout.mjs";
+import { pathToFileURL } from "node:url";
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+const args = parseArgs(process.argv.slice(2));
+
+if (!args.png || args.help) {
+  printHelp();
+  process.exit(args.help ? 0 : 1);
+}
+
+try {
+  const image = readPng(args.png);
+  const manifest = args.manifest ? readManifest(args.manifest) : undefined;
+  const report = analyze(image, manifest, Boolean(args.strict));
+  if ((args.format ?? "markdown") === "json") {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(renderMarkdown(report));
+  }
+  process.exit(report.ok ? 0 : 2);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+}
+
+function parseArgs(values) {
+  const parsed = { format: "markdown", strict: false, help: false };
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+    if (value === "--help" || value === "-h") parsed.help = true;
+    else if (value === "--strict") parsed.strict = true;
+    else if (value === "--png") parsed.png = values[++index];
+    else if (value === "--manifest") parsed.manifest = values[++index];
+    else if (value === "--format") parsed.format = values[++index];
+    else throw new Error(`Unknown argument: ${value}`);
+  }
+  if (parsed.format !== "json" && parsed.format !== "markdown") {
+    throw new Error("--format must be json or markdown");
+  }
+  return parsed;
+}
+
+function printHelp() {
+  console.log(`Usage: node skills/cc-technical-diagrams/scripts/png-qa.mjs --png <file> [--manifest <layout.json>] [--format json|markdown] [--strict]`);
+}
+
+function readManifest(filePath) {
+  const manifest = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  return {
+    ...manifest,
+    canvas: manifest.canvas,
+    boxes: Array.isArray(manifest.boxes) ? manifest.boxes : [],
+    connectors: Array.isArray(manifest.connectors) ? manifest.connectors : [],
+  };
+}
+
+function readPng(filePath) {
+  const buffer = fs.readFileSync(filePath);
+  const signature = "89504e470d0a1a0a";
+  if (buffer.subarray(0, 8).toString("hex") !== signature) {
+    throw new Error(`Not a PNG file: ${filePath}`);
+  }
+
+  let offset = 8;
+  let ihdr;
+  const idat = [];
+  while (offset < buffer.length) {
+    const length = buffer.readUInt32BE(offset);
+    const type = buffer.subarray(offset + 4, offset + 8).toString("ascii");
+    const data = buffer.subarray(offset + 8, offset + 8 + length);
+    offset += 12 + length;
+    if (type === "IHDR") {
+      ihdr = {
+        width: data.readUInt32BE(0),
+        height: data.readUInt32BE(4),
+        bitDepth: data[8],
+        colorType: data[9],
+        compression: data[10],
+        filter: data[11],
+        interlace: data[12],
+      };
+    } else if (type === "IDAT") {
+      idat.push(data);
+    } else if (type === "IEND") {
+      break;
+    }
+  }
+
+  if (!ihdr) throw new Error("PNG is missing IHDR");
+  if (ihdr.bitDepth !== 8) throw new Error(`Unsupported PNG bit depth: ${ihdr.bitDepth}`);
+  if (ihdr.compression !== 0 || ihdr.filter !== 0 || ihdr.interlace !== 0) {
+    throw new Error("Unsupported PNG compression/filter/interlace settings");
+  }
+
+  const channels = channelsForColorType(ihdr.colorType);
+  const inflated = zlib.inflateSync(Buffer.concat(idat));
+  const pixels = unfilter(inflated, ihdr.width, ihdr.height, channels);
+  return {
+    path: path.resolve(filePath),
+    width: ihdr.width,
+    height: ihdr.height,
+    colorType: ihdr.colorType,
+    channels,
+    pixels,
+  };
+}
+
+function channelsForColorType(colorType) {
+  if (colorType === 0) return 1;
+  if (colorType === 2) return 3;
+  if (colorType === 4) return 2;
+  if (colorType === 6) return 4;
+  throw new Error(`Unsupported PNG color type: ${colorType}`);
+}
+
+function unfilter(data, width, height, channels) {
+  const stride = width * channels;
+  const output = Buffer.alloc(stride * height);
+  let sourceOffset = 0;
+
+  for (let y = 0; y < height; y += 1) {
+    const filterType = data[sourceOffset];
+    sourceOffset += 1;
+    const rowOffset = y * stride;
+    const previousRowOffset = (y - 1) * stride;
+
+    for (let x = 0; x < stride; x += 1) {
+      const raw = data[sourceOffset + x];
+      const left = x >= channels ? output[rowOffset + x - channels] : 0;
+      const up = y > 0 ? output[previousRowOffset + x] : 0;
+      const upLeft = y > 0 && x >= channels ? output[previousRowOffset + x - channels] : 0;
+      let value;
+      if (filterType === 0) value = raw;
+      else if (filterType === 1) value = raw + left;
+      else if (filterType === 2) value = raw + up;
+      else if (filterType === 3) value = raw + Math.floor((left + up) / 2);
+      else if (filterType === 4) value = raw + paeth(left, up, upLeft);
+      else throw new Error(`Unsupported PNG filter type: ${filterType}`);
+      output[rowOffset + x] = value & 0xff;
+    }
+    sourceOffset += stride;
+  }
+
+  return output;
+}
+
+function paeth(left, up, upLeft) {
+  const estimate = left + up - upLeft;
+  const leftDistance = Math.abs(estimate - left);
+  const upDistance = Math.abs(estimate - up);
+  const upLeftDistance = Math.abs(estimate - upLeft);
+  if (leftDistance <= upDistance && leftDistance <= upLeftDistance) return left;
+  if (upDistance <= upLeftDistance) return up;
+  return upLeft;
+}
+
+function analyze(image, manifest, strict) {
+  const issues = [];
+  const nextActions = new Set();
+  const ink = measureInk(image, strict ? 10 : 18);
+
+  if (image.width < 64 || image.height < 64) {
+    addIssue(issues, nextActions, "image-too-small", "PNG is too small for reliable visual QA.", "Export a larger PNG before review.");
+  }
+
+  if (ink.coverage < (strict ? 0.001 : 0.0002)) {
+    addIssue(issues, nextActions, "blank-image", "PNG appears blank or nearly blank.", "Check the renderer/export target and regenerate the image.");
+  }
+
+  if (ink.bounds) {
+    const pad = strict ? 6 : 3;
+    if (ink.bounds.minX <= pad || ink.bounds.minY <= pad || image.width - ink.bounds.maxX <= pad || image.height - ink.bounds.maxY <= pad) {
+      addIssue(issues, nextActions, "edge-clipping", "Visible content is very close to the PNG edge.", "Increase canvas/viewBox padding or reduce subject scale.");
+    }
+  }
+
+  if (manifest) analyzeManifest(image, manifest, issues, nextActions, strict);
+
+  return {
+    ok: issues.length === 0,
+    image: {
+      path: image.path,
+      width: image.width,
+      height: image.height,
+      colorType: image.colorType,
+      inkCoverage: Number(ink.coverage.toFixed(6)),
+      inkBounds: ink.bounds,
+    },
+    measurement: manifest?.measurement ?? "image-only",
+    verification: { image: "checked", geometry: manifest ? "checked" : "unavailable", text: manifest?.measurement === "browser" ? "browser-measured" : "estimated-or-unavailable", visual: "pending" },
+    issues,
+    nextActions: [...nextActions],
+  };
+}
+
+function measureInk(image, threshold) {
+  const first = samplePixel(image, 0, 0);
+  let inkPixels = 0;
+  let minX = image.width;
+  let minY = image.height;
+  let maxX = -1;
+  let maxY = -1;
+
+  for (let y = 0; y < image.height; y += 1) {
+    for (let x = 0; x < image.width; x += 1) {
+      const pixel = samplePixel(image, x, y);
+      const differs = colorDistance(pixel, first) > threshold && pixel.a > 8;
+      if (differs) {
+        inkPixels += 1;
+        minX = Math.min(minX, x);
+        minY = Math.min(minY, y);
+        maxX = Math.max(maxX, x);
+        maxY = Math.max(maxY, y);
+      }
+    }
+  }
+
+  return {
+    coverage: inkPixels / (image.width * image.height),
+    bounds: inkPixels > 0 ? { minX, minY, maxX, maxY } : null,
+  };
+}
+
+function samplePixel(image, x, y) {
+  const offset = (y * image.width + x) * image.channels;
+  if (image.channels === 1) {
+    const value = image.pixels[offset];
+    return { r: value, g: value, b: value, a: 255 };
+  }
+  if (image.channels === 2) {
+    const value = image.pixels[offset];
+    return { r: value, g: value, b: value, a: image.pixels[offset + 1] };
+  }
+  return {
+    r: image.pixels[offset],
+    g: image.pixels[offset + 1],
+    b: image.pixels[offset + 2],
+    a: image.channels === 4 ? image.pixels[offset + 3] : 255,
+  };
+}
+
+function colorDistance(left, right) {
+  return Math.abs(left.r - right.r) + Math.abs(left.g - right.g) + Math.abs(left.b - right.b) + Math.abs(left.a - right.a);
+}
+
+export function analyzeManifest(image, manifest, issues, nextActions, strict) {
+  if (manifest.canvas && (manifest.canvas.width !== image.width || manifest.canvas.height !== image.height)) {
+    addIssue(
+      issues,
+      nextActions,
+      "manifest-canvas-mismatch",
+      `Manifest canvas ${manifest.canvas.width}x${manifest.canvas.height} does not match PNG ${image.width}x${image.height}.`,
+      "Regenerate the manifest from the final export dimensions.",
+    );
+  }
+
+  for (const box of manifest.boxes) if (![box.x,box.y,box.width,box.height].every(Number.isFinite) || box.width <= 0 || box.height <= 0) addIssue(issues,nextActions,"invalid-box-geometry",`Invalid geometry for "${box.id}".`,"Correct source dimensions.");
+  const allBoxes = manifest.boxes.map(normalizeBox).filter(Boolean);
+  const boxes = allBoxes.filter((box) => box.kind !== "group");
+  for (const issue of manifest.issues ?? []) addIssue(issues, nextActions, issue.code, issue.message, "Fix the source layout and render again.");
+  const labels = manifest.labels ?? [];
+  for (const label of labels) {
+    const owner = allBoxes.find((box) => box.id === label.owner);
+    if (label.kind === "node" && !owner) addIssue(issues,nextActions,"label-owner-missing",`Label "${label.id}" has an unknown node owner.`,"Correct label ownership in the manifest.");
+    if (![label.x,label.y,label.width,label.height].every(Number.isFinite) || label.width < 0 || label.height < 0) addIssue(issues,nextActions,"invalid-label-geometry",`Label "${label.id}" has invalid bounds.`,"Measure source labels again.");
+    if (label.x < 0 || label.y < 0 || label.x + label.width > image.width || label.y + label.height > image.height) addIssue(issues, nextActions, "label-out-of-bounds", `Label "${label.id}" exceeds the canvas.`, "Expand the canvas or adjust the source label position.");
+    if (label.kind === "node" && owner && (label.x < owner.x || label.y < owner.y || label.x + label.width > owner.x + owner.width || label.y + label.height > owner.y + owner.height)) addIssue(issues, nextActions, "node-text-overflow", `Label "${label.id}" exceeds node "${owner.id}".`, "Expand the source node or adjust its text layout.");
+    if (Array.isArray(label.lines) && label.lines.join("").replace(/\r?\n/g, "") !== String(label.text ?? "").replace(/\r?\n/g, "")) addIssue(issues, nextActions, "label-content-loss", `Label "${label.id}" does not preserve source text.`, "Restore the complete source label.");
+    if (label.kind === "edge") for (const box of boxes) if (overlapArea(label, box) > 0) addIssue(issues, nextActions, "edge-label-collision", `Label "${label.id}" overlaps node "${box.id}".`, "Move the edge label to a clear route segment.");
+  }
+  for (let i = 0; i < labels.length; i++) for (let j = i + 1; j < labels.length; j++) if (overlapArea(labels[i], labels[j]) > 0) addIssue(issues, nextActions, "text-overlap", `Labels "${labels[i].id}" and "${labels[j].id}" overlap.`, "Increase label spacing in the source.");
+  for (const box of boxes) {
+    if (box.x < 0 || box.y < 0 || box.x + box.width > image.width || box.y + box.height > image.height) {
+      addIssue(issues, nextActions, "box-out-of-bounds", `Box "${box.id}" is outside the canvas.`, "Move out-of-bounds nodes inside the canvas or expand the canvas.");
+    }
+    if (!labels.length && box.label && estimateLabelOverflow(box, strict)) {
+      addIssue(issues, nextActions, "label-overflow", `Box "${box.id}" label is likely to overflow.`, "Wrap or shorten labels, widen boxes, or increase export scale.");
+    }
+  }
+
+  for (let i = 0; i < boxes.length; i += 1) {
+    for (let j = i + 1; j < boxes.length; j += 1) {
+      const overlap = overlapArea(boxes[i], boxes[j]);
+      if (overlap > 0) {
+        addIssue(issues, nextActions, "box-overlap", `Boxes "${boxes[i].id}" and "${boxes[j].id}" overlap by ${Math.round(overlap)}px^2.`, "Increase node spacing or split dense groups.");
+      }
+    }
+  }
+
+  const boxById = new Map(boxes.map((box) => [box.id, box]));
+  const segments = [];
+  for (const connector of manifest.connectors) {
+    const points = normalizePoints(connector.points);
+    if(points.some(point=>point.x<0||point.y<0||point.x>image.width||point.y>image.height)) addIssue(issues,nextActions,"connector-out-of-bounds",`Connector "${connector.id}" exceeds the canvas.`,"Correct explicit waypoints or expand the source canvas.");
+    if (points.length < 2 || points.every((point) => point.x === points[0].x && point.y === points[0].y)) addIssue(issues, nextActions, "degenerate-connector", `Connector "${connector.id ?? "unnamed"}" has no visible path.`, "Give self calls a loop and other connectors distinct endpoints.");
+    for (let index = 0; index < points.length - 1; index += 1) {
+      const segment = { connector, a: points[index], b: points[index + 1] };
+      segments.push(segment);
+      for (const label of labels) if (segmentHits([segment.a.x,segment.a.y],[segment.b.x,segment.b.y],label)) addIssue(issues,nextActions,"connector-through-text",`Connector "${connector.id}" crosses label "${label.id}".`,"Move the source label or route around its text.");
+      for (const box of boxes) {
+        if (box.id === connector.from || box.id === connector.to) continue;
+        if (segmentIntersectsBox(segment, box)) {
+          addIssue(issues, nextActions, "connector-through-label", `Connector "${connector.id ?? "unnamed"}" crosses box "${box.id}".`, "Add waypoints around labels or use orthogonal routing.");
+        }
+      }
+    }
+    if ((connector.from && !boxById.has(connector.from)) || (connector.to && !boxById.has(connector.to))) {
+      addIssue(issues, nextActions, "connector-endpoint-missing", `Connector "${connector.id ?? "unnamed"}" references a missing endpoint.`, "Update connector endpoints to match manifest box ids.");
+    }
+  }
+
+  for (let i = 0; i < segments.length; i += 1) {
+    for (let j = i + 1; j < segments.length; j += 1) {
+      if (segments[i].connector === segments[j].connector) continue;
+      if (segmentsStack(segments[i], segments[j], strict ? 4 : 2)) {
+        addIssue(issues, nextActions, "connector-stacking", "Two connector segments are stacked or nearly stacked.", "Offset parallel connectors or bundle them into a labeled shared route.");
+      }
+    }
+  }
+}
+
+function normalizeBox(box) {
+  if (!box || typeof box.id !== "string") return null;
+  const normalized = {
+    id: box.id,
+    kind: box.kind,
+    x: Number(box.x),
+    y: Number(box.y),
+    width: Number(box.width),
+    height: Number(box.height),
+    label: typeof box.label === "string" ? box.label : "",
+  };
+  if ([normalized.x, normalized.y, normalized.width, normalized.height].some((value) => !Number.isFinite(value))) return null;
+  return normalized;
+}
+
+function normalizePoints(points) {
+  if (!Array.isArray(points)) return [];
+  return points
+    .map((point) => {
+      if (Array.isArray(point)) return { x: Number(point[0]), y: Number(point[1]) };
+      return { x: Number(point?.x), y: Number(point?.y) };
+    })
+    .filter((point) => Number.isFinite(point.x) && Number.isFinite(point.y));
+}
+
+function estimateLabelOverflow(box, strict) {
+  const label = box.label.trim();
+  if (!label) return false;
+  const lines = label.split(/\r?\n/);
+  const maxLine = Math.max(...lines.map((line) => visualLength(line)));
+  const estimatedWidth = maxLine * (strict ? 7.5 : 7);
+  const estimatedHeight = lines.length * (strict ? 18 : 16);
+  return estimatedWidth > Math.max(0, box.width - 12) || estimatedHeight > Math.max(0, box.height - 8);
+}
+
+function visualLength(value) {
+  return [...value].reduce((total, char) => total + (/[\u4e00-\u9fff]/.test(char) ? 2 : 1), 0);
+}
+
+function overlapArea(left, right) {
+  const width = Math.max(0, Math.min(left.x + left.width, right.x + right.width) - Math.max(left.x, right.x));
+  const height = Math.max(0, Math.min(left.y + left.height, right.y + right.height) - Math.max(left.y, right.y));
+  return width * height;
+}
+
+function segmentIntersectsBox(segment, box) {
+  return segmentHits([segment.a.x,segment.a.y],[segment.b.x,segment.b.y],box);
+}
+
+function legacySegmentIntersectsBox(segment, box) {
+  if (pointInsideBox(segment.a, box) || pointInsideBox(segment.b, box)) return true;
+  const edges = [
+    [{ x: box.x, y: box.y }, { x: box.x + box.width, y: box.y }],
+    [{ x: box.x + box.width, y: box.y }, { x: box.x + box.width, y: box.y + box.height }],
+    [{ x: box.x + box.width, y: box.y + box.height }, { x: box.x, y: box.y + box.height }],
+    [{ x: box.x, y: box.y + box.height }, { x: box.x, y: box.y }],
+  ];
+  return edges.some(([a, b]) => segmentsIntersect(segment.a, segment.b, a, b));
+}
+
+function pointInsideBox(point, box) {
+  return point.x >= box.x && point.x <= box.x + box.width && point.y >= box.y && point.y <= box.y + box.height;
+}
+
+function segmentsIntersect(a, b, c, d) {
+  const o1 = orientation(a, b, c);
+  const o2 = orientation(a, b, d);
+  const o3 = orientation(c, d, a);
+  const o4 = orientation(c, d, b);
+  if (o1 !== o2 && o3 !== o4) return true;
+  return false;
+}
+
+function orientation(a, b, c) {
+  const value = (b.y - a.y) * (c.x - b.x) - (b.x - a.x) * (c.y - b.y);
+  if (Math.abs(value) < 0.0001) return 0;
+  return value > 0 ? 1 : 2;
+}
+
+function segmentsStack(left, right, tolerance) {
+  const leftHorizontal = Math.abs(left.a.y - left.b.y) <= tolerance;
+  const rightHorizontal = Math.abs(right.a.y - right.b.y) <= tolerance;
+  const leftVertical = Math.abs(left.a.x - left.b.x) <= tolerance;
+  const rightVertical = Math.abs(right.a.x - right.b.x) <= tolerance;
+
+  if (leftHorizontal && rightHorizontal && Math.abs(left.a.y - right.a.y) <= tolerance) {
+    return rangesOverlap([left.a.x, left.b.x], [right.a.x, right.b.x]) > tolerance;
+  }
+  if (leftVertical && rightVertical && Math.abs(left.a.x - right.a.x) <= tolerance) {
+    return rangesOverlap([left.a.y, left.b.y], [right.a.y, right.b.y]) > tolerance;
+  }
+  return false;
+}
+
+function rangesOverlap(left, right) {
+  const a = [Math.min(...left), Math.max(...left)];
+  const b = [Math.min(...right), Math.max(...right)];
+  return Math.max(0, Math.min(a[1], b[1]) - Math.max(a[0], b[0]));
+}
+
+function addIssue(issues, nextActions, code, message, action) {
+  issues.push({ code, message, action });
+  if (typeof nextActions.add === "function") nextActions.add(action);
+  else if (!nextActions.includes(action)) nextActions.push(action);
+}
+
+function renderMarkdown(report) {
+  const lines = [
+    "# PNG QA Report",
+    "",
+    `- Status: ${report.ok ? "ok" : "issues-found"}`,
+    `- Image: ${report.image.width}x${report.image.height}`,
+    `- Ink coverage: ${report.image.inkCoverage}`,
+  ];
+  if (report.image.inkBounds) {
+    lines.push(`- Ink bounds: ${JSON.stringify(report.image.inkBounds)}`);
+  }
+  lines.push("", "## Issues");
+  if (report.issues.length === 0) {
+    lines.push("- None");
+  } else {
+    for (const issue of report.issues) {
+      lines.push(`- ${issue.code}: ${issue.message}`);
+    }
+  }
+  lines.push("", "## Next Actions");
+  if (report.nextActions.length === 0) {
+    lines.push("- None");
+  } else {
+    for (const action of report.nextActions) lines.push(`- ${action}`);
+  }
+  return `${lines.join("\n")}\n`;
+}