scrum-skills 0.3.2 → 0.3.4

package/tools/diagram.mjs

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+/**
+ * 图例入库工具（零依赖，node >= 18）
+ *
+ * AI 用内置的 diagram-design skill 画完图后，不要手改 agile/diagrams.json：
+ * 走这条命令。它负责「质检 → 分配 id → 落盘 → 建索引 → 数据校验 → 失败整体回滚」，
+ * 和 last-change.mjs 是同一套「写后校验、错了就还原」的模式。
+ *
+ * 用法:
+ *   node tools/diagram.mjs add <artifact.html> --title "登录时序" --kind sequence \
+ *        [--story S-001] [--task S-001-T1] [--catalog sequence] [--summary "..."] \
+ *        [--id DG-003] [--no-lint] [--root <dir>]
+ *   node tools/diagram.mjs list
+ *   node tools/diagram.mjs check          # 索引有文件缺失 / 文件在但索引没有
+ *   node tools/diagram.mjs doctor         # 内置 skill、模板、质检脚本是否就绪
+ * 退出码: 0 成功, 1 失败
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, readdirSync, rmSync, renameSync } from 'node:fs';
+import { join, resolve, dirname, basename } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const TOOLS = dirname(fileURLToPath(import.meta.url));
+const LINT = join(TOOLS, 'diagram-lint.mjs');
+const IMPORT = join(TOOLS, 'diagram-import.mjs');
+const VALIDATE = join(TOOLS, 'validate.mjs');
+
+/** kind 是我们自己的筛选维度：diagram-design 的 45 种图型再多也不用改代码，原始图型名进 catalog */
+export const KINDS = ['architecture', 'sequence', 'flow', 'erd', 'state', 'deploy', 'other'];
+export const KIND_LABEL = {
+  architecture: '架构', sequence: '时序', flow: '流程', erd: 'ER 关系',
+  state: '状态', deploy: '部署', other: '其它',
+};
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+const flag = name => {
+  const i = args.indexOf(`--${name}`);
+  return i === -1 ? undefined : args[i + 1];
+};
+const has = name => args.includes(`--${name}`);
+/** 位置参数：跳过命令与所有 --flag 的值 */
+function positional() {
+  const out = [];
+  const takesValue = new Set([
+    'title', 'kind', 'story', 'task', 'catalog', 'summary', 'id', 'root', 'skill', 'aspect',
+  ]);
+  for (let i = 1; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--')) { if (takesValue.has(a.slice(2))) i++; continue; }
+    out.push(a);
+  }
+  return out;
+}
+
+const fail = msg => { console.error(`✘ ${msg}`); process.exit(1); };
+const readJson = (p, fallback) => {
+  if (!existsSync(p)) return fallback;
+  try { return JSON.parse(readFileSync(p, 'utf8')); } catch (e) { fail(`${p} 解析失败: ${e.message}`); }
+};
+const today = () => {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+};
+
+function resolveRoot() {
+  // add 的第一个位置参数是产物路径，不是项目目录；其余命令才接受 `list <dir>` 这种写法
+  const positionalRoot = cmd === 'add' ? undefined : positional()[0];
+  const root = resolve(flag('root') ?? positionalRoot ?? process.cwd());
+  if (!existsSync(join(root, 'agile'))) fail(`${root} 下没有 agile/ 目录：请在项目根目录执行，或用 --root 指定`);
+  return root;
+}
+
+function skillDir(root) {
+  if (flag('skill')) return resolve(flag('skill'));
+  // 目标项目里 init 出来的那份；仓库内开发时退回包内那份
+  for (const p of [
+    join(root, '.agents/skills/diagram-design'),
+    resolve(TOOLS, '..', '.agents/skills/diagram-design'),
+  ]) if (existsSync(p)) return p;
+  return join(root, '.agents/skills/diagram-design');
+}
+
+/**
+ * 从产物里抽第一个 <svg>，做成**自包含**的一份导出（失败不影响入库）。
+ *
+ * 为什么要把 <style> 搬进 SVG：看板「下载 PNG」是把这个 SVG 当图片画进 canvas 的。
+ * 样式留在 HTML 的 head 里，独立加载的 SVG 就只剩黑块——这是 PNG 导出最容易踩的坑。
+ */
+function extractSvg(html) {
+  // 按标签配对扫描，不能用非贪婪正则：图标本身就是内联 <svg>，`<svg[\s\S]*?</svg>`
+  // 会停在图标那一层的闭合标签上，导出的 SVG 缺右半边，浏览器当图片加载直接失败。
+  const open = /<svg\b[^>]*>/i.exec(html);
+  if (!open) return null;
+  const start = open.index;
+  let depth = 1;
+  let end = -1;
+  // 注释与 CDATA 整体跳过：里面的 <svg / </svg 不算标签
+  const tag = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<\/svg\s*>|<svg\b[^>]*>/gi;
+  tag.lastIndex = start + open[0].length;
+  let m;
+  while ((m = tag.exec(html))) {
+    if (m[0].startsWith('</')) {
+      depth -= 1;
+      if (depth === 0) { end = m.index + m[0].length; break; }
+    } else if (!m[0].startsWith('<!')) depth += 1;
+  }
+  if (end < 0) return null;                 // 没闭合就当没有：宁可不出 SVG，也不落一份坏文件
+  let svg = html.slice(start, end);
+  if (!/\bxmlns=/.test(svg.slice(0, svg.indexOf('>')))) {
+    svg = svg.replace(/^<svg\b/i, '<svg xmlns="http://www.w3.org/2000/svg"');
+  }
+  if (/<style[\s>]/i.test(svg)) return svg;
+  const css = [...html.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)]
+    .map(x => x[1]).join('\n').trim();
+  if (!css) return svg;
+  // 插到 <svg> 开标签之后：:root 变量、类选择器都还在作用域内
+  return svg.replace(/^(<svg\b[^>]*>)/i, `$1\n<style>${css}</style>`);
+}
+
+function runLint(file, skill, { offline } = {}) {
+  const cli = [LINT, '--skill', skill, ...(offline ? ['--offline'] : []), file];
+  return spawnSync(process.execPath, cli, { encoding: 'utf8' });
+}
+
+function validate(root) {
+  const r = spawnSync(process.execPath, [VALIDATE, root], { encoding: 'utf8' });
+  return { ok: r.status === 0, out: `${r.stdout ?? ''}${r.stderr ?? ''}`.trim() };
+}
+
+function add() {
+  const [artifact] = positional();
+  if (!artifact) fail('缺少产物文件：node tools/diagram.mjs add <artifact.html> --title ...');
+  const file = resolve(artifact);
+  if (!existsSync(file)) fail(`找不到产物 ${file}`);
+
+  const root = resolveRoot();
+  const title = flag('title');
+  if (!title) fail('缺少 --title（图例标题，看板列表里显示的就是它）');
+  const kind = flag('kind') ?? 'other';
+  if (!KINDS.includes(kind)) fail(`--kind 必须是 ${KINDS.join(' / ')}，实际 ${kind}`);
+  const skill = skillDir(root);
+  const offline = has('offline') || /--offline\b/.test(readFileSync(file, 'utf8'));
+
+  // ① 门禁：质检不过不许入库
+  if (!has('no-lint')) {
+    const r = runLint(file, skill);
+    if (r.status !== 0) {
+      console.error(r.stdout ?? '');
+      console.error(r.stderr ?? '');
+      fail('产物未通过质检（node tools/diagram-lint.mjs）：修好再来，或确实要跳过时加 --no-lint');
+    }
+  }
+
+  const dir = join(root, 'agile/diagrams');
+  mkdirSync(dir, { recursive: true });
+  const indexPath = join(root, 'agile/diagrams.json');
+  const doc = readJson(indexPath, { schemaVersion: 3, diagrams: [] });
+  if (!Array.isArray(doc.diagrams)) fail('agile/diagrams.json 的 diagrams 必须是数组');
+
+  const used = new Set(doc.diagrams.map(d => d.id));
+  const nextId = () => {
+    const max = doc.diagrams.reduce((a, d) => Math.max(a, Number(String(d.id).replace(/\D/g, '')) || 0), 0);
+    let n = max + 1;
+    while (used.has(`DG-${String(n).padStart(3, '0')}`)) n += 1;
+    return `DG-${String(n).padStart(3, '0')}`;
+  };
+  const id = flag('id') ?? nextId();
+  if (!/^DG-\d{3,}$/.test(id)) fail(`id 必须形如 DG-001，实际 ${id}`);
+
+  const existing = doc.diagrams.find(d => d.id === id);
+  const rel = `agile/diagrams/${id}.html`;
+  const dest = join(root, rel);
+  const html = readFileSync(file);
+  const svg = extractSvg(html.toString('utf8'));
+
+  // ② 落盘 + 建索引（先备份索引，任何一步失败都还原）
+  const backup = `${indexPath}.bak-${Date.now()}`;
+  if (existsSync(indexPath)) copyFileSync(indexPath, backup);
+  const hadDest = existsSync(dest);
+  const oldDest = hadDest ? readFileSync(dest) : null;
+
+  try {
+    writeFileSync(dest, html);
+    const svgRel = svg ? `agile/diagrams/${id}.svg` : undefined;
+    if (svg) writeFileSync(join(root, svgRel), svg);
+
+    const entry = {
+      id,
+      title,
+      kind,
+      catalog: flag('catalog') ?? kind,
+      storyIds: flag('story') ? [flag('story')] : [],
+      taskId: flag('task') ?? undefined,
+      summary: flag('summary') ?? existing?.summary ?? '',
+      file: rel,
+      svg: svgRel,
+      aspect: flag('aspect') ?? existing?.aspect ?? '3:2',
+      source: existing?.source ?? 'diagram-design',
+      lint: has('no-lint') ? 'skipped' : 'pass',
+      createdAt: existing?.createdAt ?? today(),
+      updatedAt: today(),
+      supersedes: existing?.supersedes ?? undefined,
+    };
+    for (const k of Object.keys(entry)) if (entry[k] === undefined) delete entry[k];
+
+    if (existing) Object.assign(existing, entry);
+    else doc.diagrams.push(entry);
+    // 按 id 排序，diff 才稳定
+    doc.diagrams.sort((a, b) => a.id.localeCompare(b.id));
+    writeFileSync(indexPath, JSON.stringify(doc, null, 2) + '\n');
+
+    // ③ 写后校验：数据不合规就整体回滚
+    const v = validate(root);
+    if (!v.ok) throw new Error(`数据校验未通过，已回滚：\n${v.out}`);
+  } catch (e) {
+    if (existsSync(backup)) renameSync(backup, indexPath);
+    if (hadDest && oldDest) writeFileSync(dest, oldDest);
+    else if (existsSync(dest)) rmSync(dest);
+    fail(e.message);
+  }
+  if (existsSync(backup)) rmSync(backup);
+
+  console.log(`✔ 已入库 ${id}「${title}」
+  - 产物：${rel}${svg ? ` + ${id}.svg` : ''}
+  - 索引：agile/diagrams.json（${doc.diagrams.length} 张）
+  - 质检：${has('no-lint') ? '已跳过（--no-lint）' : '通过 node tools/diagram-lint.mjs'}
+  - 校验：通过 node tools/validate.mjs`);
+}
+
+function list() {
+  const root = resolveRoot();
+  const doc = readJson(join(root, 'agile/diagrams.json'), { diagrams: [] });
+  if (!doc.diagrams.length) {
+    console.log('还没有图例。先画一张，再 node tools/diagram.mjs add <file> --title ...');
+    return;
+  }
+  for (const d of doc.diagrams) {
+    const stories = (d.storyIds ?? []).join(',') || '—';
+    console.log(`${d.id}  ${KIND_LABEL[d.kind] ?? d.kind}\t${d.title}\t${stories}\t${d.updatedAt}`);
+  }
+}
+
+function check() {
+  const root = resolveRoot();
+  const doc = readJson(join(root, 'agile/diagrams.json'), { diagrams: [] });
+  const dir = join(root, 'agile/diagrams');
+  let bad = 0;
+  for (const d of doc.diagrams) {
+    const p = join(root, d.file ?? '');
+    if (!d.file || !existsSync(p)) { console.error(`✘ ${d.id}「${d.title}」的产物不存在：${d.file}`); bad += 1; }
+    if (d.svg && !existsSync(join(root, d.svg))) { console.warn(`WARN ${d.id} 缺少 SVG 导出：${d.svg}`); }
+  }
+  const indexed = new Set(doc.diagrams.map(d => basename(d.file ?? '')));
+  if (existsSync(dir)) {
+    for (const name of readdirSync(dir)) {
+      if (!/\.html?$/i.test(name)) continue;
+      if (!indexed.has(name)) { console.error(`✘ agile/diagrams/${name} 没有进索引：用 add 登记，或删掉这个孤儿文件`); bad += 1; }
+    }
+  }
+  const v = validate(root);
+  if (!v.ok) { console.error(v.out); bad += 1; }
+  if (bad) fail(`图例检查发现 ${bad} 处问题`);
+  console.log(`✔ 图例检查通过：${doc.diagrams.length} 张，产物与索引一致`);
+}
+
+function doctor() {
+  const root = resolveRoot();
+  const skill = skillDir(root);
+  const checks = [
+    ['Node 版本', () => Number(process.versions.node.split('.')[0]) >= 18, `v${process.versions.node}`],
+    ['内置 skill', () => existsSync(join(skill, 'SKILL.md')), skill],
+    ['动画模板', () => existsSync(join(skill, 'assets/template-motion.html')), join(skill, 'assets/template-motion.html')],
+    ['质检脚本', () => existsSync(LINT), LINT],
+    ['导入摘要', () => existsSync(IMPORT), IMPORT],
+    ['图例目录', () => existsSync(join(root, 'agile/diagrams')) || existsSync(join(root, 'agile')), join(root, 'agile/diagrams')],
+  ];
+  let bad = 0;
+  for (const [name, ok, detail] of checks) {
+    const pass = ok();
+    if (!pass) bad += 1;
+    console.log(`${pass ? '[PASS]' : '[FAIL]'} ${name}\t${detail}`);
+  }
+  console.log('[INFO] Python\t本项目不依赖 Python：上游 scripts/*.py 未随包分发，门禁由 diagram-lint 接管');
+  if (bad) fail(`${bad} 项检查未通过`);
+  console.log('✔ 图例工具链就绪');
+}
+
+switch (cmd) {
+  case 'add': add(); break;
+  case 'list': list(); break;
+  case 'check': check(); break;
+  case 'doctor': doctor(); break;
+  case undefined: case 'help': case '-h': case '--help':
+    console.log('用法:\n  node tools/diagram.mjs add <artifact.html> --title "..." --kind sequence [--story S-001] [--task S-001-T1]\n  node tools/diagram.mjs list\n  node tools/diagram.mjs check\n  node tools/diagram.mjs doctor');
+    break;
+  default:
+    fail(`未知命令 ${cmd}`);
+}