scrum-skills 0.3.2 → 0.3.3

package/tools/diagram-lint.mjs

@@ -0,0 +1,518 @@
+#!/usr/bin/env node
+/**
+ * 图例产物质检（零依赖，node >= 18）
+ *
+ * 这是 diagram-design 上游 `scripts/self_check.py` 的 Node 移植版。
+ * 上游那份是纯标准库、纯静态分析、不启浏览器的检查器，为了不让用户装 Python，
+ * 我们按它的判定口径重写一遍（同一套七组检查、同样「拿不准就跳过、绝不误报」的策略）。
+ * 上游是 MIT（© cathrynlavery），见 .agents/skills/diagram-design/LICENSE。
+ *
+ * 用法:
+ *   node tools/diagram-lint.mjs <file...> [--offline] [--skill <dir>]
+ * 退出码: 0 通过, 1 有错误
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_SKILL = resolve(HERE, '..', '.agents/skills/diagram-design');
+
+const UNSAFE_TAGS = new Set(['base', 'embed', 'object', 'iframe']);
+const VOID_TAGS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr',
+]);
+// 内容按原文处理、不当标签解析：style / script 里的 `>` 是合法的比较符号
+const RAW_TEXT = new Set(['style', 'script', 'textarea', 'title']);
+const UNPAINTED = new Set(['defs', 'symbol', 'marker', 'pattern', 'clippath', 'mask', 'foreignobject']);
+const PAINTED = new Set(['rect', 'line', 'circle', 'ellipse', 'polygon', 'polyline', 'text']);
+const MOTION_MODES = new Set(['none', 'reveal', 'step', 'loop']);
+const MOTION_ACTIONS = ['play', 'pause', 'replay', 'prev', 'next'];
+const REF_ATTRS = ['src', 'href', 'xlink:href', 'poster', 'srcset', 'action', 'formaction'];
+const CSS_REF_ATTRS = ['style', 'fill', 'stroke', 'filter', 'clip-path', 'mask', 'marker-start', 'marker-mid', 'marker-end', 'cursor'];
+/** viewBox 容差：和上游一致，抗浮点误差与描边外扩 */
+const VIEWBOX_TOLERANCE = 2.0;
+
+// ---------- 极简 HTML 解析 ----------
+
+/** 找开标签的 `>`，跳过引号里的内容 */
+function tagEnd(src, from) {
+  let quote = '';
+  for (let i = from; i < src.length; i++) {
+    const ch = src[i];
+    if (quote) { if (ch === quote) quote = ''; continue; }
+    if (ch === '"' || ch === "'") { quote = ch; continue; }
+    if (ch === '>') return i;
+  }
+  return -1;
+}
+
+const decodeEntities = s => s
+  .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+  .replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, ' ');
+
+function parseAttrs(raw) {
+  const attrs = {};
+  const order = [];
+  const re = /([^\s"'>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>`]+)))?/g;
+  let m;
+  while ((m = re.exec(raw))) {
+    const name = m[1].toLowerCase();
+    if (name === '/' || name === '') continue;
+    attrs[name] = decodeEntities(m[2] ?? m[3] ?? m[4] ?? '');
+    order.push(name);
+  }
+  return { attrs, order };
+}
+
+/**
+ * 解析成树。HTML 那套容错语义只覆盖我们需要的部分：
+ * 注释 / CDATA / 声明直接跳过，raw-text 元素整体吞掉，其余按栈配对。
+ * 末尾仍留在栈上的就是未闭合元素（对应上游的标签平衡检查）。
+ */
+function parse(src) {
+  const root = { name: '#root', attrs: {}, order: [], children: [], parent: null, text: '' };
+  const stack = [root];
+  const unclosed = [];
+  let i = 0;
+  const lower = src.toLowerCase();
+
+  const pushText = t => { if (t.trim()) stack[stack.length - 1].text += t; };
+
+  while (i < src.length) {
+    const lt = src.indexOf('<', i);
+    if (lt === -1) { pushText(src.slice(i)); break; }
+    if (lt > i) pushText(src.slice(i, lt));
+
+    if (src.startsWith('<!--', lt)) {
+      const end = src.indexOf('-->', lt + 4);
+      i = end === -1 ? src.length : end + 3;
+      continue;
+    }
+    if (src.startsWith('<![CDATA[', lt)) {
+      const end = src.indexOf(']]>', lt + 9);
+      i = end === -1 ? src.length : end + 3;
+      continue;
+    }
+    if (src.startsWith('<!', lt)) {
+      const end = src.indexOf('>', lt + 2);
+      i = end === -1 ? src.length : end + 1;
+      continue;
+    }
+    if (src.startsWith('</', lt)) {
+      const end = src.indexOf('>', lt + 2);
+      if (end === -1) { i = src.length; break; }
+      const name = src.slice(lt + 2, end).trim().toLowerCase();
+      // 找到最近一个同名开标签再一起弹栈；中间没闭合的记下来
+      let hit = -1;
+      for (let k = stack.length - 1; k > 0; k--) if (stack[k].name === name) { hit = k; break; }
+      if (hit > 0) {
+        for (let k = stack.length - 1; k > hit; k--) unclosed.push(stack[k]);
+        stack.length = hit;
+      }
+      i = end + 1;
+      continue;
+    }
+
+    const end = tagEnd(src, lt + 1);
+    if (end === -1) { pushText(src.slice(lt)); break; }
+    const inner = src.slice(lt + 1, end);
+    const m = /^([a-zA-Z][^\s/>]*)/.exec(inner);
+    if (!m) { i = end + 1; continue; }
+    const name = m[1].toLowerCase();
+    const selfClose = /\/\s*$/.test(inner);
+    const { attrs, order } = parseAttrs(inner.slice(m[1].length));
+    const node = { name, attrs, order, children: [], parent: stack[stack.length - 1], text: '', selfClose };
+    stack[stack.length - 1].children.push(node);
+    i = end + 1;
+
+    if (selfClose || VOID_TAGS.has(name)) continue;
+    if (RAW_TEXT.has(name)) {
+      const close = lower.indexOf(`</${name}`, i);
+      if (close === -1) { node.text = src.slice(i); unclosed.push(node); i = src.length; break; }
+      node.text = src.slice(i, close);
+      const gt = src.indexOf('>', close);
+      i = gt === -1 ? src.length : gt + 1;
+      continue;
+    }
+    stack.push(node);
+  }
+  if (stack.length > 1) unclosed.push(...stack.slice(1));
+  return { root, unclosed };
+}
+
+const walk = (node, fn, parents = []) => {
+  for (const c of node.children) {
+    fn(c, parents);
+    walk(c, fn, [...parents, c]);
+  }
+};
+
+const elements = root => {
+  const out = [];
+  walk(root, n => out.push(n));
+  return out;
+};
+
+/** 解码 CSS 十六进制转义（`\75 rl(` → `url(`），防止绕过引用检查 */
+const decodeCss = css => css
+  .replace(/\\([0-9a-fA-F]{1,6})\s?/g, (_, hex) => String.fromCodePoint(parseInt(hex, 16)))
+  .replace(/\\(.)/g, '$1');
+
+const stripComments = s => s.replace(/<!--[\s\S]*?-->/g, '').replace(/\/\*[\s\S]*?\*\//g, '');
+
+const isRemote = ref => /^(?:https?:)?\/\//i.test(ref) || /^[a-z][a-z0-9+.-]*:\/\//i.test(ref);
+
+// ---------- 单文件校验 ----------
+
+function checkFile(file, { offline, skillDir }) {
+  const errors = [];
+  const warns = [];
+  const err = m => errors.push(m);
+  const warn = m => warns.push(m);
+
+  const src = readFileSync(file, 'utf8');
+  const { root, unclosed } = parse(src);
+  const all = elements(root);
+
+  // ① 安全边界
+  for (const el of all) {
+    if (UNSAFE_TAGS.has(el.name)) err(`[unsafe] 禁用标签 <${el.name}>：产物必须是单文件，不许嵌外部文档`);
+    for (const key of Object.keys(el.attrs)) {
+      if (key.startsWith('on')) err(`[unsafe] <${el.name}> 上不许有事件属性 ${key}`);
+      if (key === 'srcdoc') err(`[unsafe] <${el.name}> 上不许有 srcdoc`);
+    }
+  }
+
+  // ② 文档完整性（截断 / 乱码 / 未闭合）
+  const noComments = stripComments(src).trim();
+  if (!/<\/html>\s*$/i.test(noComments)) err('[doc] 文档没有以 </html> 结尾，疑似被截断');
+  const bad = src.indexOf('\ufffd');
+  if (bad !== -1) {
+    const line = src.slice(0, bad).split('\n').length;
+    err(`[doc] 第 ${line} 行出现 U+FFFD 替换字符：多字节内容被截断了`);
+  }
+  const seen = new Set();
+  for (const el of unclosed) {
+    if (seen.has(el.name)) continue;
+    seen.add(el.name);
+    err(`[doc] <${el.name}> 未闭合（容器标签必须成对）`);
+  }
+
+  // ③ CSS 引用 + ④ 资源引用
+  const styleText = all.filter(e => e.name === 'style').map(e => e.text).join('\n');
+  const css = decodeCss(styleText);
+  if (/@import/i.test(css)) err('[css] 不许用 @import 引外部样式');
+  if (/image-set\s*\(/i.test(css)) err('[css] 不许用 image-set() 引外部图片');
+  if (/(?:https?:)?\/\//i.test(stripComments(css))) err('[css] 样式里出现远程地址：产物必须自包含');
+
+  const checkRef = (ref, where) => {
+    const v = ref.trim();
+    if (!v) return;
+    if (/^javascript:/i.test(v)) return err(`[ref] ${where} 使用了 javascript: 伪协议`);
+    if (/^data:text\/html/i.test(v)) return err(`[ref] ${where} 内嵌了 data:text/html`);
+    if (/^data:/i.test(v) && !/^data:image\//i.test(v)) return err(`[ref] ${where} 的 data: 只允许图片类型`);
+    if (isRemote(v)) return err(`[ref] ${where} 引用了远程地址 ${v.slice(0, 60)}：看板里跑在 sandbox iframe 中，外链会直接白屏`);
+  };
+
+  for (const el of all) {
+    for (const key of REF_ATTRS) {
+      const v = el.attrs[key];
+      if (!v) continue;
+      // Google Fonts 是唯一白名单；--offline 下连它也不许
+      if (el.name === 'link' && key === 'href') {
+        let u;
+        try { u = new URL(v); } catch { err(`[ref] <link> 的 href ${v} 不是合法地址`); continue; }
+        const ok = u.protocol === 'https:' && u.host === 'fonts.googleapis.com' && u.pathname.startsWith('/css2');
+        if (!ok) err(`[ref] <link rel=stylesheet> 只允许 https://fonts.googleapis.com/css2，实际 ${v}`);
+        else if (offline) err('[ref] --offline 模式下不许有任何网络请求（包括 Google Fonts）');
+        continue;
+      }
+      if (key === 'srcset') { v.split(',').forEach(part => checkRef(part.trim().split(/\s+/)[0], '<srcset>')); continue; }
+      checkRef(v, `<${el.name} ${key}>`);
+    }
+    for (const key of CSS_REF_ATTRS) {
+      const v = el.attrs[key];
+      if (!v) continue;
+      const decoded = decodeCss(v);
+      if (/@import/i.test(decoded)) err(`[css] ${key} 里出现 @import`);
+      for (const m of decoded.matchAll(/url\(\s*(['"]?)([^'")]+)\1\s*\)/gi)) {
+        const ref = m[2].trim();
+        if (!ref.startsWith('#')) checkRef(ref, `<${el.name} ${key}> 的 url()`);
+      }
+      if (key !== 'style' && !/^url\(/i.test(decoded) && isRemote(decoded)) checkRef(decoded, `<${el.name} ${key}>`);
+    }
+  }
+
+  // ⑤ SVG 无障碍契约
+  const svgs = all.filter(e => e.name === 'svg');
+  const accessible = svgs.filter(e => e.attrs['aria-hidden'] !== 'true');
+  if (!accessible.length) err('[svg] 至少需要一个可访问的 <svg>（aria-hidden 的不算）');
+  const ids = new Map();
+  for (const el of all) {
+    const id = el.attrs.id;
+    if (!id) continue;
+    if (ids.has(id)) err(`[svg] id "${id}" 重复：同一页多张图会互相串台`);
+    ids.set(id, el);
+  }
+  for (const svg of accessible) {
+    if (svg.attrs.role !== 'img') err('[svg] 可访问的 <svg> 必须带 role="img"');
+    const first = svg.children.find(c => c.name !== '#text');
+    if (!first || first.name !== 'title') err('[svg] <title> 必须是 <svg> 的第一个子元素');
+    const title = svg.children.find(c => c.name === 'title');
+    const desc = svg.children.find(c => c.name === 'desc');
+    if (!title) err('[svg] 缺少 <title>');
+    else {
+      if (!title.text.trim()) err('[svg] <title> 不能为空');
+      if (!title.attrs.id || ['title', 'desc'].includes(title.attrs.id)) err('[svg] <title> 的 id 必须带图表前缀（不能是裸的 title）');
+    }
+    if (desc) {
+      if (!desc.text.trim()) err('[svg] <desc> 不能为空');
+      if (!desc.attrs.id || ['title', 'desc'].includes(desc.attrs.id)) err('[svg] <desc> 的 id 必须带图表前缀（不能是裸的 desc）');
+    }
+    const labelled = svg.attrs['aria-labelledby'];
+    if (title && desc) {
+      const want = `${title.attrs.id} ${desc.attrs.id}`;
+      if (labelled !== want) err(`[svg] aria-labelledby 必须是「title 的 id 然后 desc 的 id」：期望 "${want}"，实际 "${labelled ?? ''}"`);
+    } else if (labelled && title && labelled !== title.attrs.id) {
+      err('[svg] aria-labelledby 与 <title> 的 id 不一致');
+    }
+  }
+
+  // ⑥ viewBox 越界（静态近似：只认 translate，其余一律跳过）
+  const dynamicSelectors = [];
+  for (const m of stripComments(styleText).matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+    const decl = m[2];
+    if (!/(transform|translate|rotate|scale|display|visibility|clip-path|mask|animation|offset)/i.test(decl)) continue;
+    const sel = m[1].split(',').map(s => s.trim().split(/\s+/).pop()).filter(Boolean);
+    dynamicSelectors.push(...sel);
+  }
+  const matchesDynamic = el => dynamicSelectors.some(sel => {
+    if (sel.startsWith('.')) return (el.attrs.class ?? '').split(/\s+/).includes(sel.slice(1));
+    if (sel.startsWith('#')) return el.attrs.id === sel.slice(1);
+    return el.name === sel.toLowerCase();
+  });
+  const isStatic = el => {
+    if (el.attrs.transform && !/^\s*translate\s*\(/i.test(el.attrs.transform)) return false;
+    const style = el.attrs.style ?? '';
+    if (/(transform|translate|rotate|scale|clip-path|mask|animation|offset)/i.test(style)) return false;
+    if (/display\s*:\s*none/i.test(style) || /visibility\s*:\s*hidden/i.test(style)) return false;
+    if (el.attrs['clip-path'] || el.attrs.mask) return false;
+    if (matchesDynamic(el)) return false;
+    return true;
+  };
+  const num = v => {
+    const n = Number.parseFloat(v);
+    return Number.isFinite(n) ? n : null;
+  };
+  const boxOf = (el, tx, ty) => {
+    const a = el.attrs;
+    const rect = (x, y, w, h) => ({ minX: tx + x, minY: ty + y, maxX: tx + x + w, maxY: ty + y + h });
+    switch (el.name) {
+      case 'rect': {
+        const x = num(a.x) ?? 0, y = num(a.y) ?? 0, w = num(a.width), h = num(a.height);
+        return w === null || h === null ? null : rect(x, y, w, h);
+      }
+      case 'line': {
+        const x1 = num(a.x1), y1 = num(a.y1), x2 = num(a.x2), y2 = num(a.y2);
+        if ([x1, y1, x2, y2].some(v => v === null)) return null;
+        return { minX: tx + Math.min(x1, x2), minY: ty + Math.min(y1, y2), maxX: tx + Math.max(x1, x2), maxY: ty + Math.max(y1, y2) };
+      }
+      case 'circle': {
+        const cx = num(a.cx), cy = num(a.cy), r = num(a.r);
+        if ([cx, cy, r].some(v => v === null)) return null;
+        return { minX: tx + cx - r, minY: ty + cy - r, maxX: tx + cx + r, maxY: ty + cy + r };
+      }
+      case 'ellipse': {
+        const cx = num(a.cx), cy = num(a.cy), rx = num(a.rx), ry = num(a.ry);
+        if ([cx, cy, rx, ry].some(v => v === null)) return null;
+        return { minX: tx + cx - rx, minY: ty + cy - ry, maxX: tx + cx + rx, maxY: ty + cy + ry };
+      }
+      case 'polygon': case 'polyline': {
+        const pts = (a.points ?? '').trim().split(/[\s,]+/).map(Number);
+        if (pts.length < 2 || pts.some(v => !Number.isFinite(v))) return null;
+        const xs = pts.filter((_, i) => i % 2 === 0), ys = pts.filter((_, i) => i % 2 === 1);
+        return { minX: tx + Math.min(...xs), minY: ty + Math.min(...ys), maxX: tx + Math.max(...xs), maxY: ty + Math.max(...ys) };
+      }
+      case 'text': {
+        // 文本不排版，只按锚点算（上游同样不算字体实际宽度）
+        const x = num(a.x), y = num(a.y);
+        if (x === null || y === null) return null;
+        return { minX: tx + x, minY: ty + y, maxX: tx + x, maxY: ty + y };
+      }
+      default: return null;
+    }
+  };
+
+  for (const svg of svgs) {
+    const vb = (svg.attrs.viewbox ?? '').trim().split(/[\s,]+/).map(Number);
+    if (vb.length !== 4 || vb.some(v => !Number.isFinite(v))) {
+      if (svg.attrs.viewbox !== undefined) err('[svg] viewBox 必须是 4 个数字');
+      continue;
+    }
+    const [minX, minY, w, h] = vb;
+    const maxX = minX + w, maxY = minY + h;
+
+    const visit = (el, tx, ty, skip) => {
+      const skipped = skip || !isStatic(el) || UNPAINTED.has(el.name);
+      let ntx = tx, nty = ty;
+      const tr = el.attrs.transform;
+      if (tr && /^\s*translate\s*\(/i.test(tr)) {
+        const nums = tr.replace(/^\s*translate\s*\(/i, '').replace(/\)\s*$/, '').split(/[\s,]+/).map(Number);
+        if (Number.isFinite(nums[0])) ntx += nums[0];
+        if (Number.isFinite(nums[1])) nty += nums[1];
+      }
+      if (!skipped && PAINTED.has(el.name)) {
+        const box = boxOf(el, ntx, nty);
+        if (box) {
+          const over = [
+            ['左', minX - box.minX], ['上', minY - box.minY],
+            ['右', box.maxX - maxX], ['下', box.maxY - maxY],
+          ].filter(([, v]) => v > VIEWBOX_TOLERANCE).sort((a, b) => b[1] - a[1]);
+          if (over.length) {
+            const [edge, amount] = over[0];
+            err(`[viewBox] <${el.name}> 超出 ${edge}边界 ${amount.toFixed(1)}px（容差 ${VIEWBOX_TOLERANCE}）：渲染时会被裁掉`);
+          }
+        }
+      }
+      for (const child of el.children) visit(child, ntx, nty, skipped || (el.name === 'svg' && el !== svg));
+    };
+    for (const child of svg.children) visit(child, 0, 0, false);
+  }
+
+  // ⑦ 脚本与动画契约
+  const scripts = all.filter(e => e.name === 'script');
+  if (scripts.length > 1) err(`[script] 最多允许一个 <script>，实际 ${scripts.length} 个`);
+  let canonical = null;
+  const templateFile = join(skillDir, 'assets/template-motion.html');
+  if (existsSync(templateFile)) {
+    const tpl = readFileSync(templateFile, 'utf8');
+    const found = [...tpl.matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script>/gi)];
+    if (found.length === 1) canonical = found[0][2].replace(/\r\n/g, '\n').trim();
+    else warn('[script] 模板 template-motion.html 里的 controller 不唯一，跳过逐字比对');
+  } else {
+    warn(`[script] 找不到 ${templateFile}，跳过 controller 逐字比对（--skill 可指定 skill 目录）`);
+  }
+  for (const s of scripts) {
+    const keys = s.order.filter(k => k !== '/');
+    if (keys.length !== 1 || keys[0] !== 'data-diagram-controls' || (s.attrs[keys[0]] ?? '') !== '') {
+      err(`[script] <script> 的属性只允许一个 data-diagram-controls=""，实际 ${keys.join(' ') || '（无）'}`);
+    }
+    if (canonical !== null && s.text.replace(/\r\n/g, '\n').trim() !== canonical) {
+      err('[script] 控制器脚本体与 template-motion.html 不一致：动画图必须逐字复制规范控制器');
+    }
+  }
+
+  const motionRoots = all.filter(e => 'data-motion-root' in e.attrs);
+  const motionItems = all.filter(e => 'data-motion-item' in e.attrs);
+  const controls = all.filter(e => 'data-motion-controls' in e.attrs);
+  const status = all.filter(e => 'data-motion-status' in e.attrs);
+
+  if (motionRoots.length || motionItems.length || scripts.length) {
+    if (motionRoots.length > 1) err(`[motion] data-motion-root 只能有一个，实际 ${motionRoots.length}`);
+    for (const rootEl of motionRoots) {
+      const mode = rootEl.attrs['data-motion-mode'] ?? '';
+      if (!MOTION_MODES.has(mode)) err(`[motion] data-motion-mode 必须是 ${[...MOTION_MODES].join('/')}，实际 "${mode}"`);
+      const rawCount = rootEl.attrs['data-step-count'];
+      const minStep = mode === 'none' ? 0 : 1;
+      if (rawCount !== undefined && !/^\d+$/.test(rawCount)) {
+        err(`[motion] data-step-count 必须是十进制整数，实际 "${rawCount}"`);
+      } else if (rawCount !== undefined) {
+        const count = Number(rawCount);
+        if (count < minStep || count > 8) err(`[motion] data-step-count ${count} 越界：${mode} 模式允许 ${minStep}~8`);
+      }
+      if (motionItems.length > 12) err(`[motion] 动画分步元素最多 12 个，实际 ${motionItems.length}`);
+      const steps = new Map();
+      for (const item of motionItems) {
+        const step = item.attrs['data-step'];
+        if (step === undefined || !/^\d+$/.test(step)) err(`[motion] 每个 data-motion-item 都必须有十进制的 data-step`);
+        const decorative = item.attrs['aria-hidden'] === 'true';
+        if (decorative) {
+          if (item.attrs.focusable !== 'false') err('[motion] 装饰性分步元素必须同时带 aria-hidden="true" 与 focusable="false"');
+        } else {
+          const label = (item.attrs['aria-label'] ?? '').trim();
+          if (!label) err('[motion] 语义分步元素必须有非空的 aria-label（读屏要知道这一步是什么）');
+          else if (/^#[0-9a-f]{3,8}$/i.test(label)) err('[motion] aria-label 不能只有一个颜色值');
+        }
+        const style = item.attrs.style ?? '';
+        if (/display\s*:\s*none/i.test(style) || /visibility\s*:\s*hidden/i.test(style) || /opacity\s*:\s*0(?:[^\d.]|$)/i.test(style)) {
+          err('[motion] 分步元素不许在源码里隐藏：静态回退必须可见');
+        }
+        if (!decorative && step !== undefined) {
+          const n = Number(step);
+          if (!steps.has(n)) steps.set(n, 0);
+          steps.set(n, steps.get(n) + 1);
+        }
+      }
+      for (const [n, count] of steps) if (count > 2) err(`[motion] 第 ${n} 步最多 2 个语义元素，实际 ${count}`);
+
+      const controlled = mode === 'step' || scripts.length > 0;
+      if (mode === 'none' || mode === 'loop') {
+        if (scripts.length) err(`[motion] ${mode} 模式不许带脚本`);
+        if (controls.length) err(`[motion] ${mode} 模式不许带播放控件`);
+        if (status.length) err(`[motion] ${mode} 模式不许带 live status`);
+      }
+      if (controlled) {
+        if (controls.length !== 1) err(`[motion] 受控动画必须有且只有一个 data-motion-controls，实际 ${controls.length}`);
+        const actions = all.filter(e => e.attrs['data-motion-action']).map(e => e.attrs['data-motion-action']);
+        const missing = MOTION_ACTIONS.filter(a => !actions.includes(a));
+        if (missing.length) err(`[motion] 播放控件缺少 action：${missing.join('、')}`);
+        if (status.length !== 1) err(`[motion] 受控动画必须有且只有一个 data-motion-status`);
+        for (const st of status) {
+          if (st.attrs.role !== 'status' || st.attrs['aria-live'] !== 'polite' || st.attrs['aria-atomic'] !== 'true')
+            err('[motion] status 必须带 role="status" aria-live="polite" aria-atomic="true"');
+          let p = st.parent, inside = false;
+          while (p) { if ('data-motion-controls' in (p.attrs ?? {})) { inside = true; break; } p = p.parent; }
+          if (inside) err('[motion] status 必须放在播放控件之外');
+        }
+        if (!scripts.length) err('[motion] 受控动画必须有脚本（否则按钮点了没反应）');
+      }
+    }
+    if (scripts.length) {
+      if (!/prefers-reduced-motion\s*:\s*reduce/i.test(css)) err('[motion] 有脚本就必须有 prefers-reduced-motion: reduce 回退');
+      if (!/@media\s+print/i.test(css)) err('[motion] 有脚本就必须有 @media print 打印回退');
+    }
+  }
+
+  return { errors, warns };
+}
+
+// ---------- CLI ----------
+
+const argv = process.argv.slice(2);
+const files = [];
+let offline = false;
+let skillDir = DEFAULT_SKILL;
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '--offline') offline = true;
+  else if (a === '--skill') { skillDir = resolve(argv[++i] ?? DEFAULT_SKILL); }
+  else if (a.startsWith('--')) { console.error(`✘ 未知参数: ${a}`); process.exit(1); }
+  else files.push(a);
+}
+if (!files.length) {
+  console.error('用法: node tools/diagram-lint.mjs <file...> [--offline] [--skill <dir>]');
+  process.exit(1);
+}
+
+let failed = false;
+for (const file of files) {
+  let out;
+  try {
+    out = checkFile(file, { offline, skillDir });
+  } catch (e) {
+    failed = true;
+    console.error(`✘ ${file}\n  - [io] 读不了文件: ${e.message}`);
+    continue;
+  }
+  for (const w of out.warns) console.warn(`WARN ${file}: ${w}`);
+  if (out.errors.length) {
+    failed = true;
+    console.error(`✘ ${file} 未通过质检（${out.errors.length} 处）：`);
+    for (const e of out.errors) console.error(`  - ${e}`);
+  } else {
+    console.log(`OK ${file}`);
+  }
+}
+process.exit(failed ? 1 : 0);