@andyqiu/teamkit 0.1.1

package/scripts/adr-check.mjs

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+/**
+ * scripts/adr-check.mjs — ADR 体系合规校验（teamkit ADR 体系）
+ *
+ * 简化版（teamkit 是新项目，纯 slug 命名，无 NNNN 历史编号）。
+ *
+ * 校验项：
+ *   A. ADR 文件结构（docs/adr/）
+ *      - 文件命名：纯 slug，小写字母开头，kebab-case，不允许数字开头
+ *      - slug 唯一性（文件名 stem 全局唯一）
+ *      - frontmatter 必填：title / status / date / author
+ *      - status 合法（Proposed / Draft / Accepted / Superseded / Deprecated / Rejected）
+ *      - Superseded 必须有 superseded-by 指向
+ *      - supersedes 必须双向闭环（用 slug stem 互查）
+ *
+ *   B. 三向引用
+ *      - ADR 的 code-refs 列出的文件必须存在（[TBD] / "—" / N/A 跳过；支持 glob）
+ *      - teamkit 无 PRD 章节校验（teamkit 模板无 prd-refs 字段，跳过）
+ *
+ *   C. 触发式历史补全（机制 #5）
+ *      - 检查 git diff 改动文件
+ *      - 对每个 plugins/*.ts、workflows/*.yaml、tools/*.ts、agents/*.md、commands/*.md、lib/*.ts：
+ *        * 该文件必须能 grep 到 `ADR:<slug>` 或 `ADR-NNNN` 注释，或某 ADR 的 code-refs 包含它
+ *        * 没有 → 警告（迁移期 < 7 天）/ 错误（迁移期 >= 7 天）
+ *      - 迁移期起点：.adr-migration-start 文件读取（不存在则今天）
+ *      - 环境变量 ADR_STRICT=1 强制升级为错误（CI 用）
+ *
+ *   D. PR 模板存在性
+ *      - .github/pull_request_template.md 必须存在且含 "ADR" 关键字
+ *      - teamkit Phase 0：.github/pull_request_template.md 尚未创建，warn 跳过不阻塞
+ *
+ *   E. README 索引同步（调 adr-index-sync.mjs --check）
+ *
+ * 退出码：
+ *   0 = 全过 / 仅警告
+ *   1 = 有错误
+ *
+ * 作者：Andy
+ */
+
+// 注意：fs.globSync 在 Node 22+ 才稳定（Node 20 没有），用 namespace import + 运行时能力检测，
+// 避免 import 阶段在 Node 20 直接 ReferenceError。
+import * as nodeFs from "node:fs"
+import * as path from "node:path"
+import { fileURLToPath } from "node:url"
+import { execSync } from "node:child_process"
+
+const { existsSync, promises: fs } = nodeFs
+const globSync = typeof nodeFs.globSync === "function" ? nodeFs.globSync : null
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+const ADR_DIR = path.join(ROOT, "docs", "adr")
+const MIGRATION_FILE = path.join(ROOT, ".adr-migration-start")
+const STRICT = process.env.ADR_STRICT === "1"
+const MIGRATION_DAYS = 7
+
+// ── ADR 文件命名 regex ──
+// 纯 slug：小写字母开头、kebab-case；template.md 与 README.md 排除
+const SLUG_RE = /^[a-z][a-z0-9-]*\.md$/
+const isTemplate = (f) => f === "template.md"
+const isReadme = (f) => f === "README.md"
+const isAdrFile = (f) => !isTemplate(f) && !isReadme(f) && SLUG_RE.test(f)
+
+let failed = 0
+let warned = 0
+let passed = 0
+
+const ok = (msg) => { passed++; console.log(`  ✅ ${msg}`) }
+const warn = (msg) => { warned++; console.log(`  ⚠️  ${msg}`) }
+const bad = (msg) => { failed++; console.log(`  ❌ ${msg}`) }
+const section = (t) => console.log(`\n=== ${t} ===`)
+
+// ─── 工具：解析 ADR frontmatter ──────────────────────────
+async function parseADR(filepath) {
+  const raw = await fs.readFile(filepath, "utf8")
+  const m = raw.match(/^---\n([\s\S]*?)\n---/)
+  if (!m) return null
+  const fm = {}
+  const lines = m[1].split("\n")
+  let curKey = null
+  let curArr = null
+  for (const line of lines) {
+    const kv = line.match(/^([a-z][\w-]*):\s*(.*)$/)
+    if (kv) {
+      curKey = kv[1]
+      const val = kv[2].trim()
+      if (/^\[.*\]$/.test(val)) {
+        // inline array: [acp-protocol] 或 [slug-a, slug-b]
+        fm[curKey] = val.slice(1, -1).split(",")
+          .map(s => s.trim().replace(/^["']|["']$/g, ""))
+          .filter(Boolean)
+        curArr = null
+      } else if (val === "" || val === "[]") {
+        fm[curKey] = []
+        curArr = fm[curKey]
+      } else {
+        fm[curKey] = val.replace(/^["']|["']$/g, "")
+        curArr = null
+      }
+    } else if (curArr && line.startsWith("  - ")) {
+      curArr.push(line.slice(4).trim().replace(/^["']|["']$/g, ""))
+    }
+  }
+  return { fm, raw }
+}
+
+// 取文件的 stem（去 .md 后缀）
+const stemOf = (f) => f.replace(/\.md$/, "")
+
+// ─── A. ADR 文件结构校验 ────────────────────────────────
+
+section("A. ADR 文件结构")
+
+// teamkit 使用 author 字段（不是 deciders）
+const REQUIRED_FIELDS = ["title", "status", "date", "author"]
+const VALID_STATUS = ["Proposed", "Draft", "Accepted", "Superseded", "Deprecated", "Rejected"]
+
+if (!existsSync(ADR_DIR)) {
+  bad(`docs/adr/ 不存在`)
+} else {
+  const all = (await fs.readdir(ADR_DIR)).sort()
+
+  // 防回潮：旧 NNNN- 前缀命名一律报错
+  for (const f of all) {
+    if (/^\d{4}-/.test(f)) {
+      bad(`${f}: 检测到旧 NNNN- 前缀命名，teamkit 使用纯 slug 命名`)
+    }
+  }
+
+  const files = all.filter(isAdrFile)
+  const adrs = []
+  for (const f of files) {
+    const parsed = await parseADR(path.join(ADR_DIR, f))
+    if (!parsed) { bad(`${f}: frontmatter 解析失败`); continue }
+    adrs.push({ file: f, stem: stemOf(f), ...parsed })
+  }
+
+  // slug 唯一性（stem 即 key，文件名层面 fs 已保证不重，但二次防御）
+  const slugMap = new Map()
+  for (const a of adrs) {
+    if (!slugMap.has(a.stem)) slugMap.set(a.stem, [])
+    slugMap.get(a.stem).push(a.file)
+  }
+  let dupFound = false
+  for (const [stem, files] of slugMap) {
+    if (files.length > 1) {
+      bad(`ADR slug 重名："${stem}" 出现在多个文件：${files.join(", ")}`)
+      dupFound = true
+    }
+  }
+  if (!dupFound) ok(`ADR 文件 ${adrs.length} 份，slug 唯一`)
+
+  // byKey map：以 stem 唯一索引
+  const byKey = new Map()
+  for (const a of adrs) byKey.set(a.stem, a)
+
+  // 字段 + status + supersedes 闭环
+  for (const a of adrs) {
+    for (const f of REQUIRED_FIELDS) {
+      if (!a.fm[f] || (Array.isArray(a.fm[f]) && a.fm[f].length === 0 && f === "author")) {
+        bad(`${a.file}: 缺字段 ${f}`)
+      }
+    }
+    if (!VALID_STATUS.includes(a.fm.status)) {
+      bad(`${a.file}: status="${a.fm.status}" 非法`)
+    }
+    // superseded-by slug 存在性校验
+    if (a.fm.status === "Superseded") {
+      const sb = Array.isArray(a.fm["superseded-by"]) ? a.fm["superseded-by"] : []
+      if (sb.length === 0) {
+        bad(`${a.file}: status=Superseded 但 superseded-by 为空`)
+      } else {
+        for (const sbSlug of sb) {
+          const tgtSb = byKey.get(String(sbSlug).trim())
+          if (!tgtSb) bad(`${a.file}: superseded-by "${sbSlug}" 不存在`)
+        }
+      }
+    }
+    // 双向闭环（supersedes / superseded-by 均用 slug stem）
+    const supers = Array.isArray(a.fm.supersedes) ? a.fm.supersedes : []
+    for (const target of supers) {
+      const tgtStr = String(target).trim()
+      const tgt = byKey.get(tgtStr)
+      if (!tgt) { bad(`${a.file}: supersedes ${target} 不存在`); continue }
+      const tgtSb = Array.isArray(tgt.fm["superseded-by"]) ? tgt.fm["superseded-by"] : []
+      const closed = tgtSb.map(String).map((s) => s.trim()).includes(a.stem)
+      if (!closed) {
+        bad(`${a.file} → ${tgt.file}: supersedes 未双向闭环（${tgt.file} 缺 superseded-by: ${a.stem}）`)
+      }
+    }
+  }
+  ok(`字段 / status / supersedes 闭环检查完成`)
+}
+
+// ─── B. 三向引用 ─────────────────────────────────────────
+
+section("B. 三向引用（ADR → Code）")
+
+if (existsSync(ADR_DIR)) {
+  const files = (await fs.readdir(ADR_DIR)).filter(isAdrFile)
+  for (const f of files) {
+    const parsed = await parseADR(path.join(ADR_DIR, f))
+    if (!parsed) continue
+    const refs = Array.isArray(parsed.fm["code-refs"]) ? parsed.fm["code-refs"] : []
+    for (const ref of refs) {
+      // 跳过 N/A 占位
+      if (!ref || ref === "TBD" || ref === "—" || ref === "N/A") continue
+      // 按 (, # 切割，取第一个文件路径（支持 inline # 注释）
+      const filepath = ref.split(/[,(#]/)[0].trim()
+      // glob 模式（含 * ? [ {）→ 展开后检查至少有一个匹配
+      if (/[*?\[\{]/.test(filepath)) {
+        if (!globSync) {
+          warn(`${f}: 当前 Node 不支持 fs.globSync，跳过 code-refs glob "${filepath}" 存在性检查`)
+          continue
+        }
+        try {
+          const matches = globSync(filepath, { cwd: ROOT })
+          if (!matches || matches.length === 0) {
+            warn(`${f}: code-refs glob "${filepath}" 无任何匹配（追溯型 ADR 可忽略）`)
+          }
+        } catch (err) {
+          warn(`${f}: code-refs glob "${filepath}" 解析失败：${err.message}`)
+        }
+        continue
+      }
+      const abs = path.join(ROOT, filepath)
+      if (!existsSync(abs)) {
+        warn(`${f}: code-refs "${filepath}" 不存在（Phase 0：代码尚未实现，可忽略）`)
+      }
+    }
+  }
+  ok(`code-refs 文件存在性检查完成`)
+}
+
+// ─── B'. PRD 引用（teamkit 无 PRD 章节号校验，跳过）──────
+
+section("B'. PRD ↔ ADR 双向引用")
+warn(`teamkit 模板无 prd-refs 字段，跳过 PRD 章节校验（不阻塞）`)
+
+
+// ─── C. 触发式历史补全 ──────────────────────────────────
+
+section("C. 触发式补全（git diff 模式）")
+
+// 迁移期起点
+let migrationStart
+if (existsSync(MIGRATION_FILE)) {
+  migrationStart = new Date(await fs.readFile(MIGRATION_FILE, "utf8"))
+} else {
+  migrationStart = new Date()
+  await fs.writeFile(MIGRATION_FILE, migrationStart.toISOString())
+  console.log(`  ℹ️  初始化迁移期起点：${migrationStart.toISOString()}`)
+}
+const daysSince = Math.floor((Date.now() - migrationStart.getTime()) / 86400000)
+const grace = daysSince < MIGRATION_DAYS && !STRICT
+console.log(`  迁移期已过 ${daysSince} / ${MIGRATION_DAYS} 天，模式：${grace ? "warn" : "error"}（STRICT=${STRICT}）`)
+
+// 收 git diff
+let diffFiles = []
+try {
+  // 双 diff 模式：staged（pre-commit）或 last-commit（CI）
+  const diffMode = process.env.ADR_DIFF_MODE === "last-commit" ? "last-commit" : "staged"
+  const diffCmd = diffMode === "last-commit"
+    ? "git diff --name-status HEAD~1 HEAD"
+    : "git diff --cached --name-status"
+  console.log(`  ℹ️  diff 模式：${diffMode}（${diffCmd}）`)
+  const out = execSync(diffCmd, { cwd: ROOT, stdio: ["ignore", "pipe", "ignore"] })
+  diffFiles = out.toString()
+    .split("\n")
+    .map((x) => x.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const parts = line.split("\t")
+      const status = parts[0]
+      const file = parts[parts.length - 1]
+      return { status, file }
+    })
+    .filter(({ status }) => !status.startsWith("D"))
+    .map(({ file }) => file)
+} catch {
+  console.log(`  ℹ️  无 git diff（首次提交或非 git 仓库），跳过 C 校验`)
+  diffFiles = []
+}
+
+// 收集所有 ADR 的 code-refs（含 glob 展开）
+const allCodeRefs = new Set()
+if (existsSync(ADR_DIR)) {
+  const files = (await fs.readdir(ADR_DIR)).filter(isAdrFile)
+  for (const f of files) {
+    const parsed = await parseADR(path.join(ADR_DIR, f))
+    if (!parsed) continue
+    const refs = Array.isArray(parsed.fm["code-refs"]) ? parsed.fm["code-refs"] : []
+    for (const r of refs) {
+      const fp = String(r).split(/[,(#]/)[0].trim().replace(/\\/g, "/")
+      if (!fp || fp === "TBD" || fp === "—" || fp === "N/A") continue
+      if (/[*?\[\{]/.test(fp)) {
+        if (globSync) {
+          try {
+            for (const match of globSync(fp, { cwd: ROOT })) {
+              allCodeRefs.add(String(match).replace(/\\/g, "/"))
+            }
+          } catch (err) {
+            warn(`${f}: code-refs glob "${fp}" 展开失败：${err.message}`)
+            allCodeRefs.add(fp)
+          }
+        } else {
+          warn(`${f}: 当前 Node 不支持 fs.globSync，跳过 code-refs glob "${fp}" 展开`)
+          allCodeRefs.add(fp)
+        }
+      } else {
+        allCodeRefs.add(fp)
+      }
+    }
+  }
+}
+
+const TARGET_PATTERNS = [/^plugins\/.+\.ts$/, /^workflows\/.+\.yaml$/, /^tools\/.+\.ts$/, /^agents\/.+\.md$/, /^commands\/.+\.md$/, /^lib\/.+\.ts$/]
+// 注释格式：新格式 `ADR:<slug>`（冒号 + kebab-case）或旧格式 `ADR-NNNN`（四位数字）
+const ADR_COMMENT_RE = /ADR:[a-z][a-z0-9-]+|ADR-\d{4}/
+let trigChecked = 0
+for (const file of diffFiles) {
+  const norm = file.replace(/\\/g, "/")
+  if (!TARGET_PATTERNS.some((p) => p.test(norm))) continue
+  trigChecked++
+  let hasComment = false
+  try {
+    const content = await fs.readFile(path.join(ROOT, file), "utf8")
+    if (ADR_COMMENT_RE.test(content)) hasComment = true
+  } catch { /* 文件可能被删 */ }
+  const inRefs = allCodeRefs.has(norm)
+  if (!hasComment && !inRefs) {
+    const msg = `${file}: 改动了但找不到 ADR 引用（既无注释 ADR:<slug>/ADR-NNNN 也无 ADR code-refs）`
+    grace ? warn(msg) : bad(msg)
+  }
+}
+ok(`触发式补全检查完成（扫描 ${trigChecked} 个改动文件）`)
+
+// ─── D. PR 模板 ──────────────────────────────────────────
+
+section("D. PR 模板")
+const PR_TEMPLATE = path.join(ROOT, ".github", "pull_request_template.md")
+if (!existsSync(PR_TEMPLATE)) {
+  warn(`.github/pull_request_template.md 不存在（teamkit Phase 0：尚未创建，不阻塞）`)
+} else {
+  const content = await fs.readFile(PR_TEMPLATE, "utf8")
+  if (!/ADR/.test(content)) bad(`PR 模板未含 "ADR" 关键字`)
+  else ok(`PR 模板存在且含 ADR checklist`)
+}
+
+// ─── E. README 索引同步 ──────────────────────────────────
+
+section("E. README 索引同步")
+try {
+  execSync("node scripts/adr-index-sync.mjs --check", { cwd: ROOT, stdio: "pipe" })
+  ok(`README 索引与 ADR 文件同步`)
+} catch {
+  warn(`README 索引未同步 — 跑 \`npm run adr:sync\` 修复`)
+}
+
+
+// ─── 总结 ───────────────────────────────────────────────
+
+console.log(`\n=== 总结 ===`)
+console.log(`  ✅ 通过：${passed}`)
+console.log(`  ⚠️  警告：${warned}`)
+console.log(`  ❌ 失败：${failed}`)
+
+process.exit(failed === 0 ? 0 : 1)

package/scripts/adr-index-sync.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * scripts/adr-index-sync.mjs — 自动同步 docs/adr/README.md 索引表（teamkit ADR 体系）
+ *
+ * teamkit 是新项目，纯 slug 命名，无 NNNN 历史编号。
+ *
+ * 用法：
+ *   node scripts/adr-index-sync.mjs           # 默认：写回 README.md
+ *   node scripts/adr-index-sync.mjs --check   # 仅检查，不写；不同步退出码 1
+ *
+ * 工作原理：
+ *   1. 扫 docs/adr/*.md（纯 slug 格式）取 frontmatter
+ *   2. 按 date 升序排序（同 date 按 id 二级排序）生成索引行
+ *   3. 在 README.md 找 "## 当前 ADR 列表" marker → 表头 → 替换到下一段
+ *   4. --check 模式不写文件，diff 不为空则 exit 1
+ *
+ * 作者：Andy
+ */
+
+import { existsSync, promises as fs } from "node:fs"
+import * as path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+const ADR_DIR = path.join(ROOT, "docs", "adr")
+const README = path.join(ADR_DIR, "README.md")
+const CHECK_ONLY = process.argv.includes("--check")
+
+// 与 adr-check.mjs 同步的命名 regex：纯 slug
+const SLUG_RE = /^[a-z][a-z0-9-]*\.md$/
+const isTemplate = (f) => f === "template.md"
+const isReadme = (f) => f === "README.md"
+const isAdrFile = (f) => !isTemplate(f) && !isReadme(f) && SLUG_RE.test(f)
+
+// 内联简化版 frontmatter parser（保持脚本独立，不 import adr-check.mjs）
+async function parseADR(filepath) {
+  const raw = await fs.readFile(filepath, "utf8")
+  const m = raw.match(/^---\n([\s\S]*?)\n---/)
+  if (!m) return null
+  const fm = {}
+  let curArr = null
+  for (const line of m[1].split("\n")) {
+    const kv = line.match(/^([a-z][\w-]*):\s*(.*)$/)
+    if (kv) {
+      const v = kv[2].trim()
+      if (/^\[.*\]$/.test(v)) {
+        // inline array: [acp-protocol] 或 [slug-a, slug-b]
+        fm[kv[1]] = v.slice(1, -1).split(",")
+          .map(s => s.trim().replace(/^["']|["']$/g, ""))
+          .filter(Boolean)
+        curArr = null
+      } else if (v === "" || v === "[]") {
+        fm[kv[1]] = []
+        curArr = fm[kv[1]]
+      } else {
+        fm[kv[1]] = v.replace(/^["']|["']$/g, "")
+        curArr = null
+      }
+    } else if (curArr && line.startsWith("  - ")) {
+      curArr.push(line.slice(4).trim().replace(/^["']|["']$/g, ""))
+    }
+  }
+  return fm
+}
+
+async function buildIndex() {
+  const files = (await fs.readdir(ADR_DIR)).filter(isAdrFile)
+  const rows = []
+  for (const f of files) {
+    const fm = await parseADR(path.join(ADR_DIR, f))
+    if (!fm) continue
+    // ID = 文件 stem（纯 slug）
+    const id = f.replace(/\.md$/, "")
+    const date = String(fm.date || "").trim() || "—"
+    const title = String(fm.title || "").replace(/^["']|["']$/g, "")
+    const status = fm.status || "?"
+    const sb = Array.isArray(fm["superseded-by"]) ? fm["superseded-by"].filter(Boolean) : []
+    const sup = Array.isArray(fm.supersedes) ? fm.supersedes.filter(Boolean) : []
+    let rel = "—"
+    if (sb.length) rel = `by ${sb.map((x) => String(x).trim()).join(", ")}`
+    else if (sup.length) rel = `Supersedes ${sup.map((x) => String(x).trim()).join(", ")}`
+    const statusCell = status === "Superseded" ? `**${status}**` : status
+    const titleCell = `[${title}](./${f})`
+    rows.push({ id, date, title, status, sb, sup, file: f, line: `| ${id} | ${date} | ${titleCell} | ${statusCell} | ${rel} |` })
+  }
+  // 排序：按 date 升序，同 date 按 id 二级
+  rows.sort((a, b) => a.date.localeCompare(b.date) || a.id.localeCompare(b.id))
+  return rows.map((r) => r.line)
+}
+
+async function main() {
+  if (!existsSync(README)) {
+    console.error(`✗ 未找到 ${README}`)
+    process.exit(1)
+  }
+  const old = await fs.readFile(README, "utf8")
+  const rows = await buildIndex()
+  const tableHeader = "| Slug | Date | 标题 | 状态 | Superseded-by |\n|---|---|---|---|---|"
+  const tableBlock = `${tableHeader}\n${rows.join("\n")}`
+
+  // marker：## 当前 ADR 列表 + 空行 + 表格（到下一段 ## 或文档末尾）
+  const markerRe = /(## 当前 ADR 列表\n\n)(\|[\s\S]*?)(?=\n\n##|\n\n<!--|\n---\n|$)/
+  const m = old.match(markerRe)
+  if (!m) {
+    console.error(`✗ README 找不到 "## 当前 ADR 列表" 段或表格 marker`)
+    process.exit(1)
+  }
+
+  const newContent = old.replace(markerRe, `$1${tableBlock}\n`)
+
+  if (CHECK_ONLY) {
+    if (newContent === old) {
+      console.log(`✓ README 索引与 ADR 文件同步（${rows.length} 行）`)
+      process.exit(0)
+    } else {
+      console.error(`✗ README 索引与 ADR 文件不同步`)
+      console.error(`  跑 \`node scripts/adr-index-sync.mjs\` 自动修复`)
+      process.exit(1)
+    }
+  }
+
+  if (newContent === old) {
+    console.log(`✓ README 索引已是最新（${rows.length} 行），未改动`)
+  } else {
+    await fs.writeFile(README, newContent, "utf8")
+    console.log(`✓ README 索引已更新：${rows.length} 行`)
+  }
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})