@bovinphang/craft-common 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,27 @@
+# 数据驻留
+
+当图表包含私有架构、未发布产品细节、客户数据或受监管信息时，使用此清单。
+
+## 本地优先
+
+- 写入 workspace 的 `.drawio` 文件是最安全的默认产物，因为它可以本地检查、版本化和打开。
+- 安装 CLI 后，draw.io Desktop 导出会在本机运行。若缺少 CLI，保留源文件并提供 URL 兜底，而不是将图表发送到云端转换器。
+- `diagram-lint.mjs`、`diagram-url.mjs`、`layout-graph.mjs`、`png-embed-fix.mjs` 和代码扫描器都在本地运行。Graphviz 是可选项；安装后也在本地运行。
+
+## URL 模式
+
+- viewer/editor `#R` URL 和 `#create=` URL 会把压缩后的图表内容放在 URL fragment 中。
+- URL fragment 不会作为请求路径发送给普通 HTTP 服务器，但浏览器仍会从所选 diagrams.net host 加载应用代码。
+- 超大型图表可能超过浏览器实际可用的 URL 长度限制。URL 变得难以处理时，回退到本地 `.drawio` 文件。
+- 在 Windows 上，通过 `.url` 快捷方式文件打开长图表 URL，或使用 `diagram-url.mjs` 输出的 JSON `windowsShortcut`；直接通过 `cmd start` 传递 URL 可能丢失 fragment。
+
+## 外部请求
+
+- 品牌 CDN 符号在渲染时需要网络访问，除非已嵌入为 data URI。
+- diagrams.net web editor/viewer 会从配置的 host 加载编辑器代码和资源。
+- 当环境要求受控端点时，可通过 `--base-url` 传入自托管 diagrams.net base URL。
+- 现有 draw.io MCP App 或 Tool server 可作为预览界面使用，但它们是可选项，并受用户配置的 host 和模型提供方约束。
+
+## 交接规则
+
+对于敏感图表，优先交付本地 `.drawio` 源文件和 lint 结果。仅当用户明确需要且数据边界可接受时，再补充 PNG/SVG/PDF 或 URL 输出。

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

@@ -0,0 +1,60 @@
+# 图表模式
+
+当用户要求某类具名技术图时，使用这些约定。
+
+## 架构图
+
+- 按层级分组节点：client、edge、service、data、external。
+- 边界重要时，使用泳道或分组容器。
+- 分层块状架构图优先使用水平层、左侧层标签、按内容收紧的容器，以及用于 security、monitoring 或 governance 的可选横切侧边栏。
+- 将 bus 或 event-stream 节点放在 publisher/subscriber 行的中心附近。
+- 数据库使用圆柱，服务使用圆角矩形，外部系统使用虚线外框。
+- 只有当 data flow 或 dependency direction 重要时才使用箭头；纯能力栈优先用空间分组表达。
+
+## ERD
+
+- 将表建模为容器，列以行展示。
+- 在标签中标记主键和外键。
+- 基数关系不完全明确时，使用虚线关系边。
+- 包含多个关系簇的 schema 优先使用自上而下布局。
+- 使用稳定的表宽和行高，让长列名换行，而不是撑开相邻表格。
+
+## UML 类图
+
+- 使用拆分为名称、字段和方法的类框。
+- 继承使用空心三角箭头，接口实现使用虚线空心三角箭头。
+- 接口或抽象基类放在具体类上方。
+- 关联关系保持正交布线，并将 multiplicity 标签放在其描述的边段附近。
+
+## 序列图
+
+- 参与者从左到右排列，时间从上到下推进。
+- 请求、响应和异步消息的样式保持可视化区分。
+- 只有能澄清嵌套工作时才添加 activation box。
+- 为消息标签留出足够水平间距；如果标签碰撞，换行或将交互拆成多个阶段。
+
+## 机器学习 / 深度学习
+
+- tensor shape 重要时，在第二行展示。
+- 对 encoder、decoder、embedding、attention 和 output 阶段分组。
+- skip connection 绕开主流程布线。
+
+## 流程图
+
+- 开始/结束使用椭圆，过程使用矩形，决策使用菱形。
+- 为决策分支添加标签。
+- 尽可能将分支合并回中心路径。
+- 主路径保持纵向。备选或错误分支横向绕出，再用正交边回到主路径。
+- 可编辑 draw.io 流程图最终交付前遵循 [flowchart-quality.md](flowchart-quality.md)。
+
+## 思维导图
+
+- 将中心概念放在画布中央，一层分支分布到不同象限。
+- 使用无箭头曲线边，并保持每条分支从父节点到叶子的一致配色。
+- 叶子节点从中心向外展开；不要让分支穿过中心标签。
+
+## 网络拓扑
+
+- 使用 internet、edge、switching/routing 和 devices 等层级行。
+- 有线和无线连接应有可视区分，通常实线表示有线，虚线表示无线。
+- 终端设备按行或列对齐，让连接路径易于扫读。

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

@@ -0,0 +1,49 @@
+# 流程图质量
+
+当 draw.io / diagrams.net 交付物是流程、工作流、审批路径、发布路径、事故响应、入职流程或其他需要打开后依然可读的流程图时，使用本参考。
+
+## 可读性约定
+
+- 手工编写的流程图保持窄画布。优先使用 600 到 800 的 `pageWidth`；除非图表明确是横向跨职能表，否则不要超过 800。
+- 将 `dx` 和 `dy` 设置为接近页面尺寸，避免 diagrams.net 初始缩放后文字变得很小。
+- 主路径自上而下推进。备选、失败、重试和异常分支可以横向绕出，但需要用正交连接线回到主路径。
+- 超过五个密集阶段时，优先拆成多张图或多个页面，而不是做成一个超长超宽画布。
+
+## 阶段分组
+
+- 真实阶段、角色、阶段组或边界上下文使用 `swimlane` 容器；当标题和包含关系重要时，不要用松散矩形代替。
+- 阶段容器保持 10px 网格对齐，通常保留 20px 页面外边距，阶段之间保留 30-40px 垂直呼吸空间。
+- 容器标题建立清晰层级：阶段标签约 14-16px、加粗，并使用明确边框色。
+- 阶段容器设置 `connectable="0"` 和 `collapsible=0`，避免连接线误连容器本身，也避免出现折叠控件。
+- 容器尺寸应包住子节点并保留至少 15px 底部留白。单侧大面积空白通常意味着需要重新布局。
+
+## 标签
+
+- 过程框文字默认居中；只有表格类内容确实需要行对齐时才改用其他对齐。
+- 过程节点使用 `whiteSpace=wrap;html=1`，普通正文不小于 12px。
+- 节点标题放在最前，并比正文更醒目。标签保持简洁，把过长实现细节放进备注或 metadata。
+- 图表语言与用户请求一致，保存前转义 XML 属性内容。
+
+## 连接线
+
+- 常规流程图连接线使用 `edgeStyle=orthogonalEdgeStyle`。
+- 阶段到阶段的主路径应比次要边更醒目，例如使用更粗线宽和一致强调色。
+- 决策分支和异常路径需要标注，标签应靠近它描述的边段。
+- 一个节点扇出到多个同级节点时，使用明确的 `entryX`、`entryY`、`exitX` 和 `exitY` 锚点，避免分支互相穿越。
+- 重试、回滚和循环连接线通过左侧或右侧边距及显式 waypoint 绕行，不要斜穿内容。
+
+## 视觉系统
+
+- 使用小型色板，每种阶段类型或角色组一个颜色。过程节点填充保持中性，由边框或标题承载阶段色。
+- 警告、失败、待定和未来状态只用于异常节点；不要把状态色当装饰。
+- 结构性阶段边界使用方角容器；普通过程节点可以使用圆角。
+
+## 最终检查
+
+交付前运行：
+
+```bash
+node skills/cc-drawio-studio/scripts/diagram-lint.mjs diagram.drawio --format markdown --strict
+```
+
+然后手动打开图表，检查主路径连线没有交叉、标签没有截断、阶段没有像折叠态一样不可读，并且 diagrams.net 默认缩放下文字仍然清晰。

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

@@ -0,0 +1,72 @@
+# 布局与导出
+
+## 自动布局
+
+依赖图、代码结构图和超过约 15 个节点的图表使用 `layout-graph.mjs`。较小图表如果坐标、容器和边锚点可以直接审查，也可以手工编写 XML。
+
+```bash
+node skills/cc-drawio-studio/scripts/layout-graph.mjs graph.json --output diagram.drawio --manifest layout.json
+```
+
+输入 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` 是可选项。若缺失，可手动摆放图表，或交付 XML 加 diagrams.net URL。
+
+## 手工布局
+
+- 将可见顶点的 `x` 和 `y` 对齐到 10px 网格。
+- 页面外边距至少保留 60px，并留出足够空间，避免连接线穿过标签。
+- 同一行或同一列的同级节点使用一致尺寸和一致间距，除非内容明确需要不同尺寸。
+- 显式标签换行使用 `
`；不要在 draw.io `value` 属性中写 literal `\n`。
+- 标签包含 `whiteSpace=wrap;html=1`，默认使用 `fontSize=14`，12 是最小可读例外。
+- 容器、侧边栏和泳道应按内容加均衡 padding 后收紧。最后一行不满时，将其居中或拆分分组，不要留下大面积空尾。
+
+## 导出
+
+预览：
+
+```bash
+node skills/cc-drawio-studio/scripts/drawio-export.mjs diagram.drawio --format png --output diagram.png --width 2000
+```
+
+最终可编辑 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
+```
+
+可在不实际调用 draw.io 导出的情况下检查命令：
+
+```bash
+node skills/cc-drawio-studio/scripts/drawio-export.mjs diagram.drawio --format png --output diagram.png --scale 2 --width 2000 --dry-run --json
+```
+
+兜底 URL：
+
+```bash
+node skills/cc-drawio-studio/scripts/diagram-url.mjs diagram.drawio --edit
+```
+
+为 XML、Mermaid 或 CSV 创建/导入 URL：
+
+```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
+```
+
+自托管 diagrams.net 端点使用 `--base-url`。通过 Windows shell 工具打开 URL 时，使用 `--shortcut` 或 JSON `windowsShortcut` 字段。

package/localized/zh-CN/skills/cc-drawio-studio/references/troubleshooting.md

@@ -0,0 +1,29 @@
+# 故障排查
+
+## 缺少 draw.io CLI
+
+生成 `.drawio` 文件，并使用 `diagram-url.mjs --edit` 在浏览器中打开 diagrams.net。
+
+## 缺少 Graphviz
+
+`layout-graph.mjs` 会输出清晰的 Graphviz 提示并退出。保留 graph JSON，然后安装 Graphviz，或手动摆放较小的图表。
+
+## 供应商图形为空
+
+运行 `shape-query.mjs` 并使用返回的 style 字符串。猜测的 `shape=mxgraph.*` 经常会渲染成通用方框。
+
+## 品牌图标未渲染
+
+引用 CDN 的符号在渲染时需要网络访问。需要可移植性时，使用 `brand-symbols.mjs --embed` 生成自包含 data URI。
+
+## 嵌入 PNG 看起来损坏
+
+最终执行 `drawio -e` 导出 PNG 后，运行 `png-embed-fix.mjs`。该命令是幂等的。
+
+## Windows 上浏览器 URL 打开为空白
+
+使用 `diagram-url.mjs --json`，并将输出的 `windowsShortcut` 内容作为 `.url` 文件打开；或运行 `diagram-url.mjs --shortcut`。这样可以保留携带压缩图表的 `#R` 或 `#create=` fragment。
+
+## Mermaid 或 CSV URL 失败
+
+Mermaid 和 CSV 必须使用 `diagram-url.mjs --create --type mermaid|csv`。旧的 viewer/editor `#R` 模式仅适用于 XML。

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

@@ -0,0 +1,58 @@
+# XML 与 Mermaid
+
+使用本参考选择最轻量、且仍满足用户维护性和保真需求的可编辑图表源。
+
+## 路线选择
+
+- 对会保存在 Markdown 中的常见流程图、序列图、类图、状态图、ERD、时间线、思维导图和其他文本优先图表，使用 Mermaid。
+- 当图表需要精确形状、供应商符号、嵌套容器、图层、标签、元数据、自定义颜色或持久 `.drawio` 源文件时，使用 draw.io XML。
+- CSV 只作为组织结构图或简单关系图等表格结构的短导入路径；尽可能保存生成后的可编辑源文件。
+- URL 创建用于预览和交接，不要作为重要图表的唯一产物。
+
+## XML 结构
+
+- 每个图表都包含根单元 `id="0"` 和 `id="1"`。
+- 为每个可见顶点和边提供稳定唯一 id。
+- 将子节点放入视觉容器内：把 `parent` 设为容器 id，并使用相对该容器的坐标。
+- 跨容器边界的边放在 `parent="1"` 下，避免被泳道或分组裁剪。
+- 每条边都必须包含 `<mxGeometry relative="1" as="geometry"/>`；不要使用自闭合边单元。
+- 在 `value` 属性中强制换行时使用 `&#xa;`。literal `\n` 会在 draw.io 中渲染成文本，应视为质量问题。
+- 手工摆放的顶点保持 10px 网格对齐，位于 `pageWidth` / `pageHeight` 内，并使用稳定尺寸，避免 hover、标签和导出造成布局位移。
+- 手工流程图的 `pageWidth` 保持不超过 800，除非图表明确是宽矩阵或跨职能表。
+
+## 容器与流程布局
+
+- actor、tier 或 bounded context 分组使用带标题的泳道。
+- region、VPC、availability zone 和 workload 等真实层级使用嵌套泳道。
+- 当 actor 行和阶段列都重要时，跨职能流程使用表格布局。
+- 仅在不需要视觉边界且分组不应捕获连接线时，使用普通分组。
+
+## 图层、标签与元数据
+
+- 逻辑视图、物理视图、注释或迁移阶段等主要可见性集合使用图层。
+- critical、deprecated、external、v2 或 owner 名称等横切过滤条件使用标签。
+- 当图形表示带有 owner、status、IP、service tier 或 version 等字段的记录时，使用对象元数据和占位符。
+- 可见标签保持简洁；如果次要事实会让图表难以扫读，将它们放入元数据或备注。
+
+## 标签与暗色模式
+
+- 图表标签语言应与用户语言一致。
+- 标签包含 HTML 标记或转义 `<br>` 格式时，添加 `html=1`。
+- 普通形状标签包含 `whiteSpace=wrap;html=1`，让长文本稳定换行。
+- 转义 XML 属性值：`&`、`<`、`>` 和 `"` 必须写成实体。
+- 优先使用自适应颜色和简单色板；仅当自动反色导致标签或形状不清晰时，才指定暗色模式覆盖。
+
+## Mermaid 导入说明
+
+- 有意识地选择 Mermaid header：`flowchart`、`sequenceDiagram`、`classDiagram`、`stateDiagram-v2`、`erDiagram`、`timeline`、`mindmap`、`gantt`、`C4Context` 等 header 会选择不同解析器。
+- 包含标点、空格、括号或非 ASCII 文本的标签需要加引号。
+- 节点 id 保持简单，将展示文本放在 label 中。
+- 对大型、高度样式化或供应商专属图表，最终交付前转为 XML。
+
+## XML 良构性
+
+- 不要包含 XML 注释。
+- 不要在属性值中留下未经转义的 `&` 或尖括号。
+- 不要使用重复 id。
+- 不要留下指向缺失 source 或 target 单元的边。
+- 最终交接前运行 `diagram-lint.mjs`。当导出产物是最终交付件时使用 `--strict`，让重叠、literal line break、缺少 wrapping 样式、字号过小、网格偏移和页面越界等 warning 阻断交付。

package/localized/zh-CN/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/localized/zh-CN/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);