@bovinphang/frontend-craft 2.7.0 → 2.9.0

package/skills/fec-image-generation/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/skills/fec-image-generation/scripts/png-qa.mjs

@@ -3,7 +3,10 @@
 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) {
@@ -26,6 +29,8 @@ try {
   process.exit(1);
 }
 
+}
+
 function parseArgs(values) {
   const parsed = { format: "markdown", strict: false, help: false };
   for (let index = 0; index < values.length; index += 1) {
@@ -50,6 +55,7 @@ function printHelp() {
 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 : [],
@@ -188,6 +194,8 @@ function analyze(image, manifest, strict) {
       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],
   };
@@ -243,7 +251,7 @@ 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);
 }
 
-function analyzeManifest(image, manifest, issues, nextActions, strict) {
+export function analyzeManifest(image, manifest, issues, nextActions, strict) {
   if (manifest.canvas && (manifest.canvas.width !== image.width || manifest.canvas.height !== image.height)) {
     addIssue(
       issues,
@@ -254,12 +262,26 @@ function analyzeManifest(image, manifest, issues, nextActions, strict) {
     );
   }
 
-  const boxes = manifest.boxes.map(normalizeBox).filter(Boolean);
+  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 (box.label && estimateLabelOverflow(box, strict)) {
+    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.");
     }
   }
@@ -277,9 +299,12 @@ function analyzeManifest(image, manifest, issues, nextActions, strict) {
   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)) {
@@ -306,6 +331,7 @@ 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),
@@ -347,6 +373,10 @@ function overlapArea(left, right) {
 }
 
 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 }],
@@ -399,7 +429,8 @@ function rangesOverlap(left, right) {
 
 function addIssue(issues, nextActions, code, message, action) {
   issues.push({ code, message, action });
-  nextActions.add(action);
+  if (typeof nextActions.add === "function") nextActions.add(action);
+  else if (!nextActions.includes(action)) nextActions.push(action);
 }
 
 function renderMarkdown(report) {