@bovinphang/craft-common 0.0.0-stage → 1.0.0

package/skills/cc-drawio-studio/references/data-residency.md

@@ -0,0 +1,27 @@
+# Data Residency
+
+Use this checklist when a diagram contains private architecture, unreleased product details, customer data or regulated information.
+
+## Local First
+
+- A `.drawio` file written in the workspace is the safest default artifact because it can be inspected, versioned and opened locally.
+- draw.io Desktop export runs on the local machine when the CLI is installed. If the CLI is missing, keep the source file and offer a URL fallback instead of sending the diagram to a cloud converter.
+- `diagram-lint.mjs`, `diagram-url.mjs`, `layout-graph.mjs`, `png-embed-fix.mjs` and code scanners run locally. Graphviz is optional and local when installed.
+
+## URL Modes
+
+- Viewer/editor `#R` URLs and `#create=` URLs place compressed diagram content in the URL fragment.
+- URL fragments are not sent to ordinary HTTP servers as request paths, but the browser still loads application code from the chosen diagrams.net host.
+- Very large diagrams can exceed practical browser URL limits. Fall back to a local `.drawio` file when the URL becomes unwieldy.
+- On Windows, open long diagram URLs through a `.url` shortcut file or use the JSON `windowsShortcut` output from `diagram-url.mjs`; passing the URL directly through `cmd start` can lose the fragment.
+
+## External Requests
+
+- Brand CDN symbols require network access when rendered unless embedded as data URIs.
+- diagrams.net web editor/viewer loads editor code and assets from the configured host.
+- A self-hosted diagrams.net base URL can be passed with `--base-url` when the environment requires a controlled endpoint.
+- Existing draw.io MCP App or Tool servers may be useful as preview surfaces, but they are optional and governed by the user's configured host and model provider.
+
+## Handoff Rule
+
+For sensitive diagrams, deliver the local `.drawio` source plus lint results first. Add PNG/SVG/PDF or URL outputs only when the user explicitly needs them and the data boundary is acceptable.

package/skills/cc-drawio-studio/references/diagram-patterns.md

@@ -0,0 +1,60 @@
+# Diagram Patterns
+
+Use these conventions when a user asks for a named technical diagram.
+
+## Architecture
+
+- Group nodes by tier: client, edge, service, data, external.
+- Use swimlanes or grouped containers when boundaries matter.
+- For layered block architecture, prefer horizontal tiers with left-side tier labels, content-driven containers, and optional cross-cutting sidebars for security, monitoring or governance.
+- Put bus or event-stream nodes near the center of publisher/subscriber rows.
+- Use cylinders for databases, rounded rectangles for services, dashed outlines for external systems.
+- Use arrows only when data flow or dependency direction matters; use spatial grouping for pure capability stacks.
+
+## ERD
+
+- Model tables as containers with rows for columns.
+- Mark primary keys and foreign keys in labels.
+- Use dashed relationship edges when cardinality is not fully known.
+- Prefer top-to-bottom layout for schemas with multiple relation clusters.
+- Use stable table widths and row heights so long column names wrap instead of resizing neighboring tables.
+
+## UML Class
+
+- Use a class box split into name, fields and methods.
+- Use hollow triangle arrows for inheritance, dashed hollow triangle for interface implementation.
+- Keep interfaces or abstract bases above concrete classes.
+- Keep associations orthogonal and label multiplicity near the edge segment it describes.
+
+## Sequence
+
+- Lay participants left-to-right and time top-to-bottom.
+- Keep request, response and async message styles visually distinct.
+- Add activation boxes only when they clarify nested work.
+- Leave enough horizontal spacing for message labels; if labels collide, wrap text or split the interaction into phases.
+
+## ML / Deep Learning
+
+- Show tensor shape on a second line when it matters.
+- Group encoder, decoder, embedding, attention and output stages.
+- Route skip connections around the primary flow.
+
+## Flowchart
+
+- Use ovals for start/end, rectangles for process, diamonds for decisions.
+- Label decision branches.
+- Merge branches back to a central path when possible.
+- Keep the primary path vertical. Route alternate or error branches sideways and back to the main path with orthogonal edges.
+- For editable draw.io flowcharts, follow [flowchart-quality.md](flowchart-quality.md) before final delivery.
+
+## Mindmap
+
+- Put the central concept in the middle and distribute first-level branches across quadrants.
+- Use curved edges without arrowheads and keep each branch color consistent from parent to leaves.
+- Fan leaves away from the center; do not let branches cross through the central label.
+
+## Network Topology
+
+- Use hierarchical rows such as internet, edge, switching/routing and devices.
+- Distinguish wired and wireless links visually, usually solid for wired and dashed for wireless.
+- Keep endpoint devices aligned in rows or columns so connection paths remain scannable.

package/skills/cc-drawio-studio/references/flowchart-quality.md

@@ -0,0 +1,49 @@
+# Flowchart Quality
+
+Use this reference when a draw.io / diagrams.net deliverable is a process, workflow, approval path, release path, incident response path, onboarding flow or other flowchart that must remain readable after opening in diagrams.net.
+
+## Readability Contract
+
+- Keep manually authored flowcharts narrow. Prefer `pageWidth` between 600 and 800; do not exceed 800 unless the diagram is intentionally a wide cross-functional table.
+- Set `dx` and `dy` close to the page dimensions so diagrams.net does not initially zoom the drawing until labels become tiny.
+- Put the primary path top-to-bottom. Use side branches only for alternatives, failures, retries and exceptions, then return them to the main path with orthogonal connectors.
+- Split more than five dense stages into multiple diagrams or pages instead of making one oversized canvas.
+
+## Stage Grouping
+
+- Use `swimlane` containers for real stages, actors, phases or bounded groups; avoid loose rectangles when a title and containment relationship matter.
+- Keep stage containers on a 10px grid, normally with a 20px outer page margin and 30-40px vertical breathing room between stages.
+- Give container headers a readable hierarchy: stage labels around 14-16px, bold, with a clear border color.
+- Set stage containers to `connectable="0"` and `collapsible=0` so connectors target intentional nodes and the diagram does not gain collapse controls.
+- Size containers to fit their children with 15px or more bottom padding. A container with large one-sided blank space usually needs a layout pass.
+
+## Labels
+
+- Keep node text centered for process boxes unless a table-like artifact genuinely needs aligned rows.
+- Use `whiteSpace=wrap;html=1` on process nodes, and keep normal body text at 12px or larger.
+- Put the node title first, visually stronger than the body. Use concise labels and move long implementation detail into notes or metadata.
+- Use the same language as the user's request, and escape XML attribute content before saving.
+
+## Connectors
+
+- Use `edgeStyle=orthogonalEdgeStyle` for normal flowchart connectors.
+- Make the main stage-to-stage path visually stronger than secondary edges, for example with a thicker stroke and a consistent accent color.
+- Label decision branches and exception paths close to the edge segment they describe.
+- For fan-out from one node to several peers, use explicit `entryX`, `entryY`, `exitX` and `exitY` anchors so branches do not cross.
+- Route retry, rollback and loop connectors around the left or right margin with explicit waypoints instead of diagonal shortcuts through content.
+
+## Visual System
+
+- Use a small palette with one color per stage type or actor group. Keep process node fills neutral and let borders or headers carry the stage color.
+- Reserve warning, failure, pending and future states for exceptional nodes; do not use status colors as decoration.
+- Keep container corners square when the stage boundary is structural; rounded corners are fine for ordinary process nodes.
+
+## Final Review
+
+Before delivery, run:
+
+```bash
+node skills/cc-drawio-studio/scripts/diagram-lint.mjs diagram.drawio --format markdown --strict
+```
+
+Then manually check that the opened diagram has no crossed main-path connectors, no clipped labels, no collapsed-looking stages, and no unreadably small text at the default diagrams.net zoom.

package/skills/cc-drawio-studio/references/layout-and-export.md

@@ -0,0 +1,72 @@
+# Layout And Export
+
+## Auto Layout
+
+Use `layout-graph.mjs` for dependency graphs, code structure maps and diagrams with more than about 15 nodes. For smaller diagrams, manual XML is acceptable when the coordinates, containers and edge anchors can be reviewed directly.
+
+```bash
+node skills/cc-drawio-studio/scripts/layout-graph.mjs graph.json --output diagram.drawio --manifest layout.json
+```
+
+Input graph:
+
+```json
+{
+  "direction": "TB",
+  "nodes": [
+    { "id": "client", "label": "Web Client", "group": "Client" },
+    { "id": "api", "label": "API", "group": "Service" }
+  ],
+  "edges": [
+    { "source": "client", "target": "api", "label": "HTTPS" }
+  ]
+}
+```
+
+Graphviz `dot` is optional. If it is missing, hand-place the diagram or deliver XML plus a diagrams.net URL.
+
+## Manual Layout
+
+- Align visible vertex `x` and `y` values to the 10px grid.
+- Keep at least 60px outer page margin and enough space that connectors do not cross labels.
+- Use equal sizes and equal gaps for sibling nodes in the same row or column unless content requires a different size.
+- Encode explicit label breaks as `
`; do not put literal `\n` in draw.io `value` attributes.
+- Include `whiteSpace=wrap;html=1` on labels and use `fontSize=14` by default, with 12 as the smallest readable exception.
+- Size containers, sidebars and swimlanes to their content plus balanced padding. If a final row is incomplete, center it or split the group instead of leaving a large empty tail.
+
+## Export
+
+Preview:
+
+```bash
+node skills/cc-drawio-studio/scripts/drawio-export.mjs diagram.drawio --format png --output diagram.png --width 2000
+```
+
+Final editable PNG:
+
+```bash
+node skills/cc-drawio-studio/scripts/drawio-export.mjs diagram.drawio --format png --output diagram.drawio.png --scale 2 --embed
+node skills/cc-drawio-studio/scripts/png-embed-fix.mjs diagram.drawio.png
+```
+
+Preview export can be checked without draw.io side effects:
+
+```bash
+node skills/cc-drawio-studio/scripts/drawio-export.mjs diagram.drawio --format png --output diagram.png --scale 2 --width 2000 --dry-run --json
+```
+
+Fallback URL:
+
+```bash
+node skills/cc-drawio-studio/scripts/diagram-url.mjs diagram.drawio --edit
+```
+
+Create/import URL for XML, Mermaid or CSV:
+
+```bash
+node skills/cc-drawio-studio/scripts/diagram-url.mjs diagram.drawio --create --type xml --json
+node skills/cc-drawio-studio/scripts/diagram-url.mjs flow.mmd --create --type mermaid
+node skills/cc-drawio-studio/scripts/diagram-url.mjs org.csv --create --type csv --lightbox
+```
+
+Use `--base-url` for a self-hosted diagrams.net endpoint. Use `--shortcut` or the JSON `windowsShortcut` field when opening the URL through Windows shell tooling.

package/skills/cc-drawio-studio/references/troubleshooting.md

@@ -0,0 +1,29 @@
+# Troubleshooting
+
+## draw.io CLI Missing
+
+Generate the `.drawio` file and use `diagram-url.mjs --edit` to open diagrams.net in the browser.
+
+## Graphviz Missing
+
+`layout-graph.mjs` exits with a clear Graphviz message. Keep the graph JSON and either install Graphviz or hand-place a smaller diagram.
+
+## Blank Vendor Shape
+
+Run `shape-query.mjs` and use the returned style string. A guessed `shape=mxgraph.*` often renders as a generic box.
+
+## Brand Icon Does Not Render
+
+CDN-referenced symbols require network access during render. Use `brand-symbols.mjs --embed` for a self-contained data URI when portability matters.
+
+## Embedded PNG Looks Corrupt
+
+Run `png-embed-fix.mjs` after final `drawio -e` PNG export. The command is idempotent.
+
+## Browser URL Opens Blank On Windows
+
+Use `diagram-url.mjs --json` and open the emitted `windowsShortcut` content as a `.url` file, or run `diagram-url.mjs --shortcut`. This preserves the `#R` or `#create=` fragment that carries the compressed diagram.
+
+## Mermaid Or CSV URL Fails
+
+Mermaid and CSV must use `diagram-url.mjs --create --type mermaid|csv`. The older viewer/editor `#R` mode is XML-only.

package/skills/cc-drawio-studio/references/xml-and-mermaid.md

@@ -0,0 +1,58 @@
+# XML And Mermaid
+
+Use this reference to choose the lightest editable diagram source that still meets the user's maintenance and fidelity needs.
+
+## Route Choice
+
+- Use Mermaid for common flowcharts, sequence diagrams, class diagrams, state diagrams, ERDs, timelines, mind maps and other text-first diagrams that will live in Markdown.
+- Use draw.io XML when the diagram needs exact shapes, vendor symbols, nested containers, layers, tags, metadata, custom colors or a durable `.drawio` source.
+- Use CSV only as a short import path for tabular structures such as org charts or simple relationship maps; save the resulting editable source when possible.
+- Use URL creation for preview and handoff, not as the only artifact for important diagrams.
+
+## XML Structure
+
+- Include root cells `id="0"` and `id="1"` in every diagram.
+- Give every visible vertex and edge a stable unique id.
+- Put child nodes inside their visual container by setting `parent` to the container id and using coordinates relative to that container.
+- Put edges that cross container boundaries at `parent="1"` so they are not clipped by a lane or group.
+- Every edge must contain `<mxGeometry relative="1" as="geometry"/>`; do not use self-closing edge cells.
+- Use `&#xa;` for forced line breaks in `value` attributes. Literal `\n` renders as text in draw.io and should be treated as a quality issue.
+- Keep manually placed vertices on a 10px grid, within `pageWidth` / `pageHeight`, and with stable dimensions so hover, labels and exports do not shift the layout.
+- For manually authored flowcharts, keep `pageWidth` at or below 800 unless the diagram is deliberately a wide matrix or cross-functional table.
+
+## Containers And Process Layout
+
+- Use titled swimlanes for actor, tier or bounded-context groupings.
+- Use nested swimlanes for real hierarchy such as region, VPC, availability zone and workload.
+- Use a table layout for cross-functional flows where both actor rows and phase columns matter.
+- Use plain groups only when a visual boundary is unnecessary and the group should not capture connectors.
+
+## Layers, Tags And Metadata
+
+- Use layers for major visibility sets, such as logical view, physical view, annotations or migration phases.
+- Use tags for cross-cutting filters such as critical, deprecated, external, v2 or owner names.
+- Use object metadata and placeholders when a shape represents a record with fields such as owner, status, IP, service tier or version.
+- Keep visible labels concise; put secondary facts in metadata or notes when the diagram would otherwise become hard to scan.
+
+## Labels And Dark Mode
+
+- Match diagram label language to the user's language.
+- Add `html=1` whenever labels contain HTML markup or escaped `<br>` formatting.
+- Include `whiteSpace=wrap;html=1` on normal shape labels so long text wraps consistently.
+- Escape XML attribute values: `&`, `<`, `>`, and `"` must be entities.
+- Prefer adaptive colors and simple palettes; specify dark-mode overrides only when automatic inversion makes labels or shapes unclear.
+
+## Mermaid Import Notes
+
+- Pick the Mermaid header deliberately: `flowchart`, `sequenceDiagram`, `classDiagram`, `stateDiagram-v2`, `erDiagram`, `timeline`, `mindmap`, `gantt`, `C4Context` and similar headers select different parsers.
+- Quote labels that include punctuation, spaces, parentheses or non-ASCII text.
+- Keep node ids simple and put display text in labels.
+- For large, highly styled or vendor-specific diagrams, move to XML before final delivery.
+
+## XML Well-Formedness
+
+- Do not include XML comments.
+- Do not leave raw ampersands or angle brackets inside attribute values.
+- Do not use duplicate ids.
+- Do not leave edges pointing to missing source or target cells.
+- Run `diagram-lint.mjs` before final handoff. Use `--strict` when the exported artifact is a final deliverable so warnings such as overlaps, literal line breaks, missing wrapping styles, tiny fonts, grid drift and page overflow block the handoff.

package/skills/cc-drawio-studio/scripts/brand-symbols.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { parseArgs, skillDir } from "./studio-core.mjs";
+
+const MANIFEST = path.join(skillDir, "data", "brand-icons.json");
+const STYLE_PREFIX = "shape=image;html=1;imageAspect=0;aspect=fixed;verticalLabelPosition=bottom;verticalAlign=top;image=";
+const SIMPLE = new Map([
+  ["qdrant", "qdrant"], ["milvus", "milvus"], ["supabase", "supabase"], ["redis", "redis"],
+  ["postgresql", "postgresql"], ["postgres", "postgresql"], ["mongodb", "mongodb"],
+  ["elasticsearch", "elasticsearch"], ["neo4j", "neo4j"], ["kafka", "apachekafka"],
+  ["clickhouse", "clickhouse"], ["duckdb", "duckdb"], ["mysql", "mysql"], ["sqlite", "sqlite"],
+]);
+
+export function loadFamilies() {
+  const manifest = JSON.parse(fs.readFileSync(MANIFEST, "utf8"));
+  const families = new Map();
+  for (const icon of manifest.icons) {
+    const base = icon.replace(/-(color|text)$/, "");
+    if (!families.has(base)) families.set(base, new Set());
+    families.get(base).add(icon);
+  }
+  return { cdn: manifest.cdn, families };
+}
+
+export async function queryBrand(query, options = {}) {
+  const { cdn, families } = loadFamilies();
+  const hits = rankBrands(families, query).slice(0, Number(options.limit ?? 8));
+  const size = Number(options.size ?? 48);
+  const variant = options.variant ?? "color";
+  const results = [];
+  for (const brand of hits) {
+    const file = pickVariant(brand, families.get(brand), variant);
+    const url = `${cdn}${file}.svg`;
+    results.push({ brand, file, w: size, h: size, style: STYLE_PREFIX + (options.embed ? await dataUri(url) : url) });
+  }
+  if (results.length === 0) {
+    const slug = SIMPLE.get(squish(query));
+    if (slug) {
+      const url = `https://cdn.simpleicons.org/${slug}`;
+      results.push({ brand: squish(query), file: `simpleicons:${slug}`, w: size, h: size, style: STYLE_PREFIX + (options.embed ? await dataUri(url) : url) });
+    }
+  }
+  return results;
+}
+
+function rankBrands(families, query) {
+  const needle = squish(query);
+  const tokens = String(query).toLowerCase().match(/[a-z0-9]+/g) ?? [];
+  const scored = [];
+  for (const brand of families.keys()) {
+    const base = squish(brand);
+    let score = 0;
+    if (base === needle) score = 100;
+    else if (base.startsWith(needle)) score = 70;
+    else if (base.includes(needle) || needle.includes(base)) score = 45;
+    for (const token of tokens) {
+      if (base === token) score = Math.max(score, 90);
+      else if (token.length >= 3 && base.includes(token)) score = Math.max(score, 35);
+    }
+    if (score > 0) scored.push([brand, score]);
+  }
+  return scored.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([brand]) => brand);
+}
+
+function pickVariant(base, variants, preference) {
+  const order = preference === "mono" ? ["", "-color", "-text"] : preference === "text" ? ["-text", "-color", ""] : ["-color", "", "-text"];
+  for (const suffix of order) if (variants.has(base + suffix)) return base + suffix;
+  return [...variants].sort()[0];
+}
+
+function squish(value) {
+  return String(value ?? "").toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+async function dataUri(url) {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`failed to fetch ${url}: ${response.status}`);
+  const svg = Buffer.from(await response.arrayBuffer()).toString("base64");
+  return `data:image/svg+xml;base64,${svg}`;
+}
+
+const args = parseArgs(process.argv.slice(2));
+const query = args._.join(" ");
+if (!query && !args.list) {
+  console.error("usage: node brand-symbols.mjs <brand> [--variant color|mono|text] [--embed] [--json]");
+  process.exit(2);
+}
+if (args.list) {
+  process.stdout.write([...loadFamilies().families.keys()].sort().join("\n") + "\n");
+} else {
+  const results = await queryBrand(query, args);
+  if (results.length === 0) {
+    console.error(`no brand symbol matched ${JSON.stringify(query)}`);
+    process.exit(1);
+  }
+  if (args.json) process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
+  else for (const item of results) process.stdout.write(`${item.brand} (${item.file}, ${item.w}x${item.h})\n  ${item.style.slice(0, 180)}${item.style.length > 180 ? "..." : ""}\n`);
+}

package/skills/cc-drawio-studio/scripts/diagram-lint.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+import { formatResult, parseArgs, readText } from "./studio-core.mjs";
+
+export function lintDrawio(xml) {
+  const errors = [];
+  const warnings = [];
+  if (/<!--/.test(xml) || /-->/.test(xml)) errors.push("XML comments are not allowed in draw.io diagram sources");
+  if (!/<mx(Cell|file|GraphModel)\b/.test(xml)) warnings.push("No draw.io graph markers found");
+  if (/<mxCell\b[^>]*\bedge="1"[^>]*\/>/.test(xml)) errors.push("edge mxCell must not be self-closing; add mxGeometry relative=\"1\"");
+
+  const graphModel = attrsOf(xml.match(/<mxGraphModel\b([^>]*)>/)?.[1] ?? "");
+  const pageWidth = Number(graphModel.pageWidth);
+  const pageHeight = Number(graphModel.pageHeight);
+  const viewportWidth = Number(graphModel.dx);
+  const viewportHeight = Number(graphModel.dy);
+  if (Number.isFinite(pageWidth) && pageWidth > 800) warnings.push(`pageWidth ${pageWidth} is above the readable manual-flowchart maximum of 800`);
+  if (Number.isFinite(pageWidth) && Number.isFinite(viewportWidth) && viewportWidth < pageWidth * 0.75) {
+    warnings.push(`dx ${viewportWidth} is much smaller than pageWidth ${pageWidth}; diagrams.net may initially zoom labels too small`);
+  }
+  if (Number.isFinite(pageHeight) && Number.isFinite(viewportHeight) && viewportHeight < pageHeight * 0.5) {
+    warnings.push(`dy ${viewportHeight} is much smaller than pageHeight ${pageHeight}; diagrams.net may initially zoom labels too small`);
+  }
+  const cellRe = /<mxCell\b([^>]*?)(?:\/>|>([\s\S]*?)<\/mxCell>)/g;
+  const objectByCellIndex = objectsByCellIndex(xml);
+  const cells = [];
+  const ids = new Map();
+  for (const match of xml.matchAll(cellRe)) {
+    const objectAttrs = objectByCellIndex.get(match.index) ?? {};
+    const attrs = attrsOf(match[1]);
+    if (!attrs.id && objectAttrs.id) attrs.id = objectAttrs.id;
+    if (!attrs.value && objectAttrs.label) attrs.value = objectAttrs.label;
+    const body = match[2] ?? "";
+    const id = attrs.id;
+    if (!id) {
+      errors.push("mxCell without id");
+      continue;
+    }
+    if (ids.has(id)) errors.push(`duplicate id ${id}`);
+    ids.set(id, attrs);
+    for (const [name, value] of rawAttrsOf(match[1])) {
+      if (hasUnescapedAmpersand(value)) errors.push(`cell ${id} attribute ${name} contains an unescaped ampersand`);
+      if (/[<>]/.test(value)) errors.push(`cell ${id} attribute ${name} contains an unescaped angle bracket`);
+      if (name === "value" && /\\n/.test(value)) warnings.push(`cell ${id} value contains literal \\n; use &#xa; for draw.io line breaks`);
+    }
+    const geom = body.match(/<mxGeometry\b([^>]*?)(?:\/>|>)/)?.[1];
+    cells.push({ id, attrs, body, geom: geom ? attrsOf(geom) : null });
+  }
+
+  if (cells.length > 0) {
+    if (!ids.has("0")) errors.push("missing root cell id 0");
+    if (!ids.has("1")) errors.push("missing default layer cell id 1");
+  }
+
+  for (const cell of cells) {
+    const { attrs, id, geom } = cell;
+    if ((attrs.vertex === "1" || attrs.edge === "1") && (id === "0" || id === "1")) {
+      errors.push(`reserved id used by graph cell ${id}`);
+    }
+    if (attrs.parent && !ids.has(attrs.parent)) errors.push(`cell ${id} parent ${attrs.parent} does not exist`);
+    for (const end of ["source", "target"]) {
+      if (attrs[end] && !ids.has(attrs[end])) errors.push(`edge ${id} ${end} ${attrs[end]} does not exist`);
+    }
+    if (attrs.edge === "1" && !geom) errors.push(`edge ${id} is missing mxGeometry`);
+    if (attrs.edge === "1" && (!attrs.source || !attrs.target)) warnings.push(`edge ${id} has no source or target`);
+    if (attrs.edge === "1" && attrs.style && !styleHas(attrs.style, "edgeStyle", "orthogonalEdgeStyle")) {
+      warnings.push(`edge ${id} should use orthogonalEdgeStyle for readable technical diagram routing`);
+    }
+    if (attrs.vertex === "1") {
+      if (looksLikeHtml(attrs.value) && !styleHas(attrs.style, "html", "1")) warnings.push(`cell ${id} label contains HTML but style does not include html=1`);
+      if (!styleHas(attrs.style, "whiteSpace", "wrap")) warnings.push(`cell ${id} style should include whiteSpace=wrap for label wrapping`);
+      if (!styleHas(attrs.style, "html", "1")) warnings.push(`cell ${id} style should include html=1 for predictable label rendering`);
+      const fontSize = styleNumber(attrs.style, "fontSize");
+      if (Number.isFinite(fontSize) && fontSize < 12) warnings.push(`cell ${id} fontSize ${fontSize} is below the readable minimum of 12`);
+      if (isSwimlane(attrs.style)) {
+        if (attrs.connectable !== "0") warnings.push(`swimlane ${id} should set connectable="0" so connectors target intentional nodes`);
+        if (styleValue(attrs.style, "collapsible") !== "0") warnings.push(`swimlane ${id} should set collapsible=0 to avoid collapse controls in deliverables`);
+        if (styleValue(attrs.style, "rounded") !== "0") warnings.push(`swimlane ${id} should use rounded=0 for clear structural stage boundaries`);
+        if (Number.isFinite(fontSize) && fontSize < 14) warnings.push(`swimlane ${id} title fontSize ${fontSize} is below the recommended flowchart stage range of 14-16`);
+      } else if (isLikelyProcessNode(attrs.style)) {
+        const align = styleValue(attrs.style, "align");
+        if (align && align !== "center") warnings.push(`process node ${id} should use align=center for flowchart readability`);
+      }
+      if (!geom) errors.push(`vertex ${id} is missing mxGeometry`);
+      else {
+        const rect = rectOf(geom);
+        if (!Number.isFinite(rect.w) || !Number.isFinite(rect.h)) errors.push(`vertex ${id} has invalid size`);
+        else if (rect.w <= 0 || rect.h <= 0) warnings.push(`vertex ${id} has non-positive size`);
+        if (rect.x < 0 || rect.y < 0) warnings.push(`vertex ${id} has negative position`);
+        if (!onGrid(rect.x) || !onGrid(rect.y)) warnings.push(`vertex ${id} position should align to the 10px grid`);
+        if (Number.isFinite(pageWidth) && rect.x + rect.w > pageWidth) warnings.push(`vertex ${id} extends beyond pageWidth ${pageWidth}`);
+        if (Number.isFinite(pageHeight) && rect.y + rect.h > pageHeight) warnings.push(`vertex ${id} extends beyond pageHeight ${pageHeight}`);
+      }
+    }
+  }
+
+  const leafVertices = cells
+    .filter((cell) => cell.attrs.vertex === "1" && cell.geom)
+    .filter((cell) => !cells.some((candidate) => candidate.attrs.parent === cell.id))
+    .map((cell) => ({ id: cell.id, parent: cell.attrs.parent ?? "1", rect: rectOf(cell.geom) }))
+    .filter((item) => Number.isFinite(item.rect.w) && Number.isFinite(item.rect.h));
+  for (let i = 0; i < leafVertices.length; i += 1) {
+    for (let j = i + 1; j < leafVertices.length; j += 1) {
+      if (leafVertices[i].parent === leafVertices[j].parent && overlaps(leafVertices[i].rect, leafVertices[j].rect)) {
+        warnings.push(`vertices ${leafVertices[i].id} and ${leafVertices[j].id} overlap`);
+      }
+    }
+  }
+  if (cells.filter((cell) => cell.attrs.vertex === "1").length === 0) warnings.push("diagram has no vertex cells");
+  return { title: "Diagram Lint", errors, warnings, ok: errors.length === 0 };
+}
+
+function objectsByCellIndex(xml) {
+  const out = new Map();
+  const objectRe = /<object\b([^>]*)>([\s\S]*?)<\/object>/g;
+  for (const match of xml.matchAll(objectRe)) {
+    const inner = match[2] ?? "";
+    const cellOffset = inner.search(/<mxCell\b/);
+    if (cellOffset < 0) continue;
+    const index = match.index + match[0].indexOf("<mxCell");
+    out.set(index, attrsOf(match[1]));
+  }
+  return out;
+}
+
+function attrsOf(raw) {
+  const attrs = {};
+  for (const match of raw.matchAll(/([A-Za-z_:][-A-Za-z0-9_:.]*)="([^"]*)"/g)) attrs[match[1]] = decode(match[2]);
+  return attrs;
+}
+
+function rawAttrsOf(raw) {
+  return [...raw.matchAll(/([A-Za-z_:][-A-Za-z0-9_:.]*)="([^"]*)"/g)].map((match) => [match[1], match[2]]);
+}
+
+function decode(value) {
+  return value.replaceAll("&quot;", '"').replaceAll("&gt;", ">").replaceAll("&lt;", "<").replaceAll("&amp;", "&");
+}
+
+function hasUnescapedAmpersand(value) {
+  return /&(?!amp;|lt;|gt;|quot;|apos;|#[0-9]+;|#x[0-9a-fA-F]+;)/.test(value);
+}
+
+function looksLikeHtml(value = "") {
+  return /<\/?[A-Za-z][^>]*>/.test(value);
+}
+
+function styleHas(style = "", key, expected) {
+  return style.split(";").some((part) => {
+    const [partKey, value] = part.split("=", 2);
+    return partKey === key && value === expected;
+  });
+}
+
+function styleNumber(style = "", key) {
+  for (const part of style.split(";")) {
+    const [partKey, value] = part.split("=", 2);
+    if (partKey === key) return Number(value);
+  }
+  return NaN;
+}
+
+function styleValue(style = "", key) {
+  for (const part of style.split(";")) {
+    const [partKey, value] = part.split("=", 2);
+    if (partKey === key) return value ?? "";
+  }
+  return undefined;
+}
+
+function isSwimlane(style = "") {
+  return style.split(";").some((part) => part === "swimlane" || part === "shape=swimlane");
+}
+
+function isLikelyProcessNode(style = "") {
+  const shape = styleValue(style, "shape");
+  if (shape) return ["process", "rectangle", "rhombus", "terminator"].includes(shape);
+  return style.includes("rounded=1") || style.includes("whiteSpace=wrap");
+}
+
+function rectOf(geom) {
+  return {
+    x: Number(geom.x ?? 0),
+    y: Number(geom.y ?? 0),
+    w: Number(geom.width),
+    h: Number(geom.height),
+  };
+}
+
+function onGrid(value, grid = 10) {
+  return Number.isFinite(value) && Math.abs(value / grid - Math.round(value / grid)) < 1e-9;
+}
+
+function overlaps(a, b) {
+  return a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
+}
+
+const args = parseArgs(process.argv.slice(2));
+const input = args._[0];
+if (!input) {
+  console.error("usage: node diagram-lint.mjs <file.drawio> [--format markdown|json] [--strict]");
+  process.exit(2);
+}
+const result = lintDrawio(readText(input));
+process.stdout.write(formatResult(result, args.format ?? (args.json ? "json" : "markdown")));
+if (!result.ok || (args.strict && result.warnings.length > 0)) process.exit(1);