sillyspec 3.27.2 → 3.27.5

package/.claude/worktrees/sillyspec-data-model-research/src/module-impact.js

@@ -0,0 +1,166 @@
+/**
+ * module-impact.js — `sillyspec module-impact` 的归类骨架生成
+ * （2026-08-21 agent-手工产出审计第三批 D3）。
+ *
+ * archive 阶段的 module-impact.md 要求「模块影响矩阵」+「未匹配文件」两章节、≥20 行，
+ * agent 此前从零手写整份矩阵。文件 × 模块的归属是纯机械分类（module-map paths 前缀匹配，
+ * 与 scan diff 归属同源），影响类型判定（逻辑/数据结构/接口/调用关系/配置/新增）是语义——
+ * 骨架预填「模块|文件|状态」三列，影响类型列留 <!--TODO--> 由 agent 逐行填。
+ *
+ * diff 源：resolveVerifyChangedFiles（worktree-aware，与 task-review 同源）；
+ * module-map：.sillyspec/docs/<p>/modules/_module-map.yaml 的 modules.<id>.paths
+ * （目录条目以 / 结尾按前缀匹配，与模块上下文索引读侧口径一致）。
+ */
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { join } from 'path'
+import { resolveVerifyChangedFiles } from './verify-postcheck.js'
+import { resolveSpecDir } from './run/shared.js'
+
+/**
+ * 轻量解析 _module-map.yaml：modules.<id>.paths 列表（手写解析同 parseRepoRegistry 风格，
+ * 只取 paths 平面信息，status/doc 等忽略）。
+ * @returns {Map<string, string[]>} moduleId → paths（posix）
+ */
+export function parseModuleMapPaths(yamlText) {
+  const map = new Map()
+  if (!yamlText) return map
+  let currentModule = null
+  let inPaths = false
+  for (const line of yamlText.split('\n')) {
+    if (!line.trim() || line.trim().startsWith('#')) continue
+    if (!/^\s/.test(line)) {
+      inPaths = line.startsWith('modules:')
+      currentModule = null
+      continue
+    }
+    const modMatch = line.match(/^  ([A-Za-z0-9_.\-]+):\s*$/)
+    if (modMatch) {
+      currentModule = modMatch[1]
+      inPaths = false
+      continue
+    }
+    if (currentModule && /^    paths:\s*$/.test(line)) {
+      inPaths = true
+      if (!map.has(currentModule)) map.set(currentModule, [])
+      continue
+    }
+    if (inPaths && currentModule) {
+      const item = line.match(/^      - (.+)$/)
+      if (item) map.get(currentModule).push(item[1].trim().replace(/\\/g, '/'))
+    }
+  }
+  return map
+}
+
+function classifyFile(posixPath, modulePaths) {
+  for (const [moduleId, paths] of modulePaths) {
+    for (const p of paths) {
+      // 目录条目以 / 结尾 → 前缀匹配；文件条目 → 精确或子路径（与模块上下文索引读侧口径一致）
+      if (p.endsWith('/')) {
+        if (posixPath.startsWith(p)) return moduleId
+      } else if (posixPath === p || posixPath.startsWith(p + '/')) {
+        return moduleId
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * 生成 module-impact.md 骨架。
+ * @param {{ cwd: string, changeName: string, specDir?: string|null }} opts
+ * @returns {{ markdown: string, matchedCount: number, unmatchedCount: number }|null}
+ *   无 module-map / 无 diff → null（无可归类输入，agent 全手写）
+ */
+export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null }) {
+  const specBase = resolveSpecDir(cwd, { specDir })
+
+  // 找 _module-map.yaml（docs/<p>/modules/；多项目取首个含 modules 索引的）
+  let moduleMapPath = null
+  try {
+    for (const p of readdirSync(join(specBase, 'docs'), { withFileTypes: true })) {
+      if (!p.isDirectory()) continue
+      const candidate = join(specBase, 'docs', p.name, 'modules', '_module-map.yaml')
+      if (existsSync(candidate)) {
+        moduleMapPath = candidate
+        break
+      }
+    }
+  } catch { /* 无 docs/ */ }
+  if (!moduleMapPath) return null
+
+  const modulePaths = parseModuleMapPaths(readFileSync(moduleMapPath, 'utf8'))
+  if (modulePaths.size === 0) return null
+
+  // includeWorkingTree 同 verify module 子集（坑 module-subset-zero-hit-uncommitted）：
+  // worktree 未提交改动也计入模块影响面（module-impact 按实际 diff 归属模块）
+  const diffFiles = resolveVerifyChangedFiles(cwd, changeName, null, { includeWorkingTree: true }) || []
+  const sourceFiles = diffFiles.map(f => f.split('\\').join('/')).filter(f => !f.startsWith('.sillyspec/'))
+  if (sourceFiles.length === 0) return null
+
+  const byModule = new Map()
+  const unmatched = []
+  for (const f of sourceFiles) {
+    const mod = classifyFile(f, modulePaths)
+    if (mod) {
+      if (!byModule.has(mod)) byModule.set(mod, [])
+      byModule.get(mod).push(f)
+    } else {
+      unmatched.push(f)
+    }
+  }
+
+  const L = [
+    '# 模块影响分析（骨架由 `sillyspec module-impact --change <变更名>` 生成）',
+    '',
+    '> 文件×模块归属由 CLI 按 _module-map.yaml paths 前缀匹配预填；',
+    '> **影响类型**（逻辑变更/数据结构变更/接口变更/调用关系变更/配置变更/新增）与 review 标记是语义判断，',
+    '> 逐行把 <!--TODO--> 替换为真实结论——以 git diff 为准（真实 > 声明）。',
+    '',
+    '## 模块影响矩阵',
+    '',
+    '| 模块 | 变更文件 | 影响类型 | 需 review |',
+    '|---|---|---|---|',
+  ]
+  const rows = [...byModule.entries()].sort((a, b) => a[0].localeCompare(b[0]))
+  for (const [moduleId, files] of rows) {
+    for (const f of files) {
+      L.push(`| ${moduleId} | \`${f}\` | <!--TODO--> | <!--TODO--> |`)
+    }
+  }
+  L.push('')
+  L.push('## 未匹配文件')
+  L.push('')
+  if (unmatched.length === 0) {
+    L.push('无（全部变更文件已归属到模块）。')
+  } else {
+    L.push('以下变更文件未命中 _module-map.yaml 任何模块 paths——确认是模块索引过期（该跑 `sillyspec modules rebuild`）还是真的游离文件：')
+    L.push('')
+    for (const f of unmatched) L.push(`- \`${f}\` <!--TODO: 归属判定-->`)
+  }
+  L.push('')
+  L.push('## 影响类型说明')
+  L.push('')
+  L.push('逻辑变更 / 数据结构变更 / 接口变更 / 调用关系变更 / 配置变更 / 新增；不确定的影响标 needs review。')
+  L.push('')
+  // 「更新结果」表骨架（2026-08-21 审查 CLI-3）：verify --done 死信门（extractPendingDocSyncRows）
+  // 与 archive 移动前校验同一口径硬校验本表无 pending 行，但骨架此前不产出该表——agent 只能
+  // 从 gate 报错反推格式（plan.js prompt 自认的坑）。此处按矩阵命中模块机械生成行，agent 只回填状态。
+  L.push('## 更新结果')
+  L.push('')
+  L.push('| 目标 | 操作 | 状态 |')
+  L.push('|------|------|------|')
+  for (const [moduleId] of rows) {
+    L.push(`| \`modules/${moduleId}.md\` | 更新${moduleId}模块卡（本次变更涉及） | pending |`)
+  }
+  if (unmatched.length > 0) {
+    L.push('| `_module-map.yaml` | <!--TODO: 有未匹配文件，判定模块索引是否需增改（modules rebuild）--> | pending |')
+  } else {
+    L.push('| `_module-map.yaml` | 无变化（未增删模块） | skipped |')
+  }
+  L.push('')
+  L.push('规则：execute/verify 完成文档同步后把对应行回填 done；确定不同步的行改 skipped 并在操作列写明原因。')
+  L.push('')
+
+  return { markdown: L.join('\n'), matchedCount: sourceFiles.length - unmatched.length, unmatchedCount: unmatched.length }
+}

package/.claude/worktrees/sillyspec-data-model-research/src/module-resolve.js

@@ -0,0 +1,222 @@
+/**
+ * module-resolve.js — 模块卡两级级联解析（token 成本优化 P0a，2026-08-22-token-cost-optimization）
+ *
+ * 背景（multi-agent-platform 2026-08-22 实测）：monorepo 根层 _module-map.yaml 把整个子项目
+ * （backend/**）映射到单张大卡（backend.md 58KB），而子项目细粒度卡（docs/backend/modules/
+ * agent.md，~6KB）由 scan 生成却无人消费——execute 每个 task 子代理都被指引去读整张大卡，
+ * 单卡一项全流程烧 20 万+ tokens 输入，且大卡「变更索引」段每变更追加、单调膨胀。
+ *
+ * 本模块 = 纯机械分类（与 module-impact.js 同性质，CLI 算事实）：
+ *   - collectModuleMaps：收齐 <spec>/docs/<project>/modules/_module-map.yaml 全部层级；
+ *     project 名恰为仓库顶层目录（monorepo 子项目，如 backend/）→ 其 paths 视为相对该
+ *     子目录（effective = `<project>/` + path）；否则视为仓库根相对（根层粗粒度 map）
+ *   - matchModuleCard：跨全部 map 最长有效前缀匹配（细卡 agent/** 胜过粗卡 backend/**）
+ *   - resolveChangeModuleCards：tasks.md 注册表 × tasks/task-NN.md allowed_paths → per-task
+ *     最优卡表；卡的体量（字节数）一并给出，读取建议按体量分级（>12KB 按节读）
+ *
+ * 铁律（对齐仓内先例）：
+ *   - 纯读：不写任何文件，不跑 git
+ *   - 无 map / 无 tasks.md / 无 task 卡 → 空结果（调用方注入占位说明，不抛）
+ *   - 判定语义（哪个模块才是「对的」）仍归 agent——本表只是机械最优匹配
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
+
+/** 模块卡字数预算（字节）：超限在 resolve 表标 ⚠️ 并提示精简——文档是 agent 的读取税
+ * （对标 deepseek-harness verify-doc-budgets 理念：预算只降不升；2026-08-24 起 runtime.md
+ * 28KB/worktree.md 24KB 已在付税）。advisory 不阻断，16 为 dogfood 校准前缺省。 */
+const MODULE_CARD_BUDGET_BYTES = 16 * 1024
+import { join, relative } from 'path'
+import { parseModuleMapSimple } from './modules.js'
+import { parseTaskRegistry } from './stages/execute.js'
+import { parseAllowedPaths } from './stages/plan-postcheck.js'
+
+/** 模块卡「整卡可读」软上限（字节）。超过则建议按节读（契约摘要/注意事项/定位），跳过历史累积段。 */
+export const MODULE_CARD_SOFT_LIMIT_BYTES = 12 * 1024
+
+/**
+ * 收齐 spec 下全部模块映射层。
+ * @param {{ cwd: string, specBase: string }} opts
+ * @returns {Array<{ project: string, mapPath: string, modulesDir: string, prefix: string,
+ *            entries: Map<string, { paths: string[], doc: string|null }> }>}
+ *   prefix：project 名为仓库顶层目录时 `<project>/`（子项目细 map），否则 ''（根层粗 map）
+ */
+export function collectModuleMaps({ cwd, specBase }) {
+  const maps = []
+  const docsDir = join(specBase, 'docs')
+  if (!existsSync(docsDir)) return maps
+  let projects = []
+  try {
+    projects = readdirSync(docsDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name)
+  } catch { return maps }
+  for (const project of projects) {
+    const modulesDir = join(docsDir, project, 'modules')
+    const mapPath = join(modulesDir, '_module-map.yaml')
+    if (!existsSync(mapPath)) continue
+    let parsed = {}
+    try {
+      parsed = parseModuleMapSimple(readFileSync(mapPath, 'utf8'))
+    } catch { continue }
+    const entries = new Map()
+    for (const [id, data] of Object.entries(parsed)) {
+      const paths = Array.isArray(data?.paths) ? data.paths : []
+      if (paths.length === 0) continue
+      entries.set(id, { paths, doc: typeof data?.doc === 'string' ? data.doc : null })
+    }
+    if (entries.size === 0) continue
+    // 子项目判定：project 名恰为仓库顶层目录 → map 的 paths 相对该子目录（monorepo 细 map）。
+    // 根层 map（project = 仓名）paths 本就仓库根相对，prefix=''。
+    let prefix = ''
+    try {
+      const topDir = join(cwd, project)
+      if (existsSync(topDir) && statSync(topDir).isDirectory()) prefix = `${project}/`
+    } catch { /* stat 失败按根层处理 */ }
+    maps.push({ project, mapPath, modulesDir, prefix, entries })
+  }
+  return maps
+}
+
+/**
+ * 路径归一：反斜杠→正斜杠，剥尾部 glob（/** 与 /*）与目录斜杠。
+ * `backend/**` / `backend/` / `backend` → `backend`。
+ */
+function normalizeMapPath(raw) {
+  return String(raw).replace(/\\/g, '/').replace(/\/\*\*$/, '').replace(/\/\*$/, '').replace(/\/$/, '')
+}
+
+/**
+ * 跨全部 map 最长有效前缀匹配一个仓库根相对路径。
+ * @param {string} posixPath 仓库根相对 posix 路径
+ * @param {Array} maps collectModuleMaps 产物
+ * @returns {{ moduleId: string, map: object, effectivePrefix: string }|null}
+ */
+export function matchModuleCard(posixPath, maps) {
+  const p = String(posixPath).replace(/\\/g, '/')
+  let best = null
+  for (const map of maps) {
+    for (const [moduleId, entry] of map.entries) {
+      for (const raw of entry.paths) {
+        const effective = (map.prefix + normalizeMapPath(raw)).replace(/\/+$/, '')
+        if (!effective) continue
+        if (p === effective || p.startsWith(effective + '/')) {
+          if (!best || effective.length > best.effectivePrefix.length) {
+            best = { moduleId, map, effectivePrefix: effective }
+          }
+        }
+      }
+    }
+  }
+  return best
+}
+
+/**
+ * 解析变更全部 task 的最优模块卡。
+ * @param {{ cwd: string, specBase: string, changeName: string }} opts
+ * @returns {{ hasMaps: boolean, rows: Array<{ taskId: string, taskName: string,
+ *            moduleId: string|null, granularity: 'fine'|'coarse'|null,
+ *            cardPath: string|null, cardBytes: number, advice: string,
+ *            matchedCount: number, pathCount: number }> }}
+ *   granularity：按胜者有效前缀段数判——1 段（整子项目）=coarse 大卡，≥2 段=fine 细卡
+ */
+export function resolveChangeModuleCards({ cwd, specBase, changeName }) {
+  const maps = collectModuleMaps({ cwd, specBase })
+  const changeDir = join(specBase, 'changes', changeName || '')
+  let registry = []
+  const tasksMd = join(changeDir, 'tasks.md')
+  if (existsSync(tasksMd)) {
+    registry = parseTaskRegistry(readFileSync(tasksMd, 'utf8'))
+  }
+  const rows = []
+  for (const task of registry) {
+    // 任务路径源：task 卡 allowed_paths（主）> 注册表行内 (文件路径) 尾注（兜底）
+    let paths = []
+    const cardFile = join(changeDir, 'tasks', `${task.id}.md`)
+    if (existsSync(cardFile)) {
+      paths = parseAllowedPaths(readFileSync(cardFile, 'utf8'))
+    }
+    if (paths.length === 0 && task.file) paths = [task.file]
+    paths = paths.map(p => p.replace(/\\/g, '/')).filter(Boolean)
+
+    // 全路径逐个匹配，取「最长有效前缀」的模块为该 task 的最优卡。粒度按有效前缀段数判：
+    // 1 段（backend/frontend 整子项目）=粗层大卡；≥2 段=细层卡（段数与卡体量正相关，
+    // SillyHub 这类根相对细 map 同样正确——不能按 map 的 prefix 有无判，会误标）
+    let winner = null
+    let matchedCount = 0
+    for (const p of paths) {
+      const m = matchModuleCard(p, maps)
+      if (!m) continue
+      matchedCount++
+      if (!winner || m.effectivePrefix.length > winner.effectivePrefix.length) winner = m
+    }
+    let granularity = null
+    if (winner) {
+      const segs = winner.effectivePrefix.split('/').filter(Boolean).length
+      granularity = segs >= 2 ? 'fine' : 'coarse'
+    }
+
+    let cardPath = null
+    let cardBytes = 0
+    let advice = '—'
+    if (winner) {
+      const docRel = winner.map.entries.get(winner.moduleId)?.doc || `modules/${winner.moduleId}.md`
+      const abs = join(winner.map.modulesDir, '..', docRel)
+      if (existsSync(abs)) {
+        const rel = relative(cwd, abs).replace(/\\/g, '/')
+        cardPath = rel.startsWith('..') ? abs.replace(/\\/g, '/') : rel
+        try { cardBytes = statSync(abs).size } catch { cardBytes = 0 }
+        advice = cardBytes > MODULE_CARD_SOFT_LIMIT_BYTES
+          ? `按节读（契约摘要/注意事项/定位；跳过变更索引/人工备注）`
+          : '整卡可读'
+      } else {
+        cardPath = relative(cwd, abs).replace(/\\/g, '/')
+        advice = '卡文件缺失（modules rebuild？）'
+      }
+    }
+    rows.push({
+      taskId: task.id,
+      taskName: task.name,
+      moduleId: winner ? winner.moduleId : null,
+      granularity,
+      cardPath,
+      cardBytes,
+      advice,
+      matchedCount,
+      pathCount: paths.length,
+    })
+  }
+  return { hasMaps: maps.length > 0, rows }
+}
+
+/**
+ * 渲染 per-task 模块卡表（注入 execute「加载上下文」步 prompt 用）。
+ * 无 map → 提示跳过；有 map 无命中行 → 单行说明。恒返回非空字符串（占位符必被替换）。
+ */
+export function renderModuleResolveTable({ cwd, specBase, changeName }) {
+  const { hasMaps, rows } = resolveChangeModuleCards({ cwd, specBase, changeName })
+  if (!hasMaps) return '（未找到 _module-map.yaml——本项目无模块卡，跳过模块文档加载）'
+  const withMatch = rows.filter(r => r.moduleId)
+  if (withMatch.length === 0) {
+    return '（已找到 _module-map.yaml，但当前变更任务未命中任何模块 paths——跳过模块文档加载；游离文件可在 Wave 收尾后跑 `sillyspec modules rebuild`）'
+  }
+  const kb = (n) => n > 0 ? `${(n / 1024).toFixed(1)}KB` : '?'
+  const L = [
+    '| task | 模块 | 粒度 | 模块卡（只读命中的卡，勿按目录整读） | 体量 | 读取建议 |',
+    '|---|---|---|---|---|---|',
+  ]
+  const budgetBreached = new Set()
+  for (const r of rows) {
+    if (r.moduleId) {
+      const over = r.cardBytes > MODULE_CARD_BUDGET_BYTES
+      if (over) budgetBreached.add(r.moduleId)
+      L.push(`| ${r.taskId} | ${r.moduleId} | ${r.granularity === 'fine' ? '细' : '粗'} | \`${r.cardPath}\` | ${kb(r.cardBytes)}${over ? ' ⚠️超预算' : ''} | ${r.advice} |`)
+    } else {
+      L.push(`| ${r.taskId} | — | — | （无命中，跳过模块文档） | — | — |`)
+    }
+  }
+  L.push('')
+  L.push('> 匹配规则：全部 _module-map.yaml 跨层最长前缀（子项目细卡优先于根层大卡），源=tasks 卡 allowed_paths。')
+  L.push('> 细卡整卡可读；仅粗卡命中且体量大时**按节读**——只读「契约摘要/注意事项/定位」，跳过「变更索引/人工备注」历史累积段。')
+  if (budgetBreached.size > 0) {
+    L.push(`> ⚠️ 模块卡超预算（>${Math.round(MODULE_CARD_BUDGET_BYTES / 1024)}KB）：${[...budgetBreached].join('、')}——文档是 agent 的读取税，本次变更触及该模块，收尾时顺手 \`sillyspec modules split-changelog\` 迁出历史段或精简正文（对标 deepseek-harness verify-doc-budgets：预算只降不升）。`)
+  }
+  return L.join('\n')
+}