sillyspec 3.24.8 → 3.25.0

package/src/stage-contract.js

@@ -9,7 +9,7 @@ import { existsSync, readdirSync, readFileSync } from 'fs'
 import { join, basename } from 'path'
 import { execFileSync } from 'child_process'
 import { detectChangeRisk, checkIntegrationEvidence } from './change-risk-profile.js'
-import { SCAN_REQUIRED_DOCS } from './constants.js'
+import { SCAN_REQUIRED_DOCS, AUXILIARY_STAGES } from './constants.js'
 
 /**
  * 校验结果
@@ -691,10 +691,8 @@ function validateExecuteOutputs(cwd, changeName, context = {}) {
  */
 const mainFlowStages = ['brainstorm', 'plan', 'execute', 'verify']
 
-/**
- * 辅助阶段（可独立运行，无严格转换顺序）
- */
-const auxiliaryStages = ['scan', 'quick', 'explore', 'archive', 'status', 'doctor']
+// 辅助阶段（可独立运行，无严格转换顺序）定义在 constants.js 的 AUXILIARY_STAGES，
+// 与 stages/index.js 共用单一真相源，避免两处逐字重复分叉。
 
 /**
  * @type {Object<string, StageContract>}
@@ -805,7 +803,7 @@ export function checkTransition(fromStage, toStage, options = {}) {
   }
 
   // 辅助阶段随时可执行（archive 除外：从主流程进入 archive 需要校验）
-  if (auxiliaryStages.includes(toStage) && toStage !== 'archive') {
+  if (AUXILIARY_STAGES.includes(toStage) && toStage !== 'archive') {
     return { allowed: true }
   }
 
@@ -831,14 +829,14 @@ export function checkTransition(fromStage, toStage, options = {}) {
       return { allowed: true }
     }
     // 独立运行 archive（无前置）也允许
-    if (!fromStage || auxiliaryStages.includes(fromStage)) {
+    if (!fromStage || AUXILIARY_STAGES.includes(fromStage)) {
       return { allowed: true }
     }
     return { allowed: false, reason: 'archive 的前置阶段是 verify，不能从 ' + fromStage + ' 跳转' }
   }
 
   // 从辅助阶段进入主流程：允许
-  if (auxiliaryStages.includes(fromStage)) {
+  if (AUXILIARY_STAGES.includes(fromStage)) {
     return { allowed: true }
   }
 
@@ -892,4 +890,4 @@ export function runValidators(stageName, cwd, changeName, context = {}) {
 /**
  * 获取所有主流程阶段
  */
-export { mainFlowStages, auxiliaryStages }
+export { mainFlowStages, AUXILIARY_STAGES as auxiliaryStages }

package/src/stages/index.js

@@ -26,4 +26,4 @@ export const stageRegistry = {
 }
 
 // 辅助命令（在无活跃变更时也可执行）
-export const auxiliaryStages = ['scan', 'quick', 'explore', 'archive', 'status', 'doctor']
+export { AUXILIARY_STAGES as auxiliaryStages } from '../constants.js'

package/src/verify-postcheck.js

@@ -18,6 +18,7 @@
 import { execSync } from 'child_process'
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
+import { verifyApiParity } from './contract-matrix.js'
 
 // 测试命令最长执行时间；超时视为失败（防止 CLI 被挂起的测试卡死）
 const TEST_TIMEOUT_MS = Number(process.env.SILLYSPEC_TEST_TIMEOUT_MS) || 10 * 60 * 1000
@@ -504,3 +505,43 @@ export function printVerifyTestCheck(result) {
     console.log(`📄 实测结果已写入: ${result.resultPath}`)
   }
 }
+
+/**
+ * API parity 对账（advisory）：前端调用 vs execute 提取的后端 endpoint artifact。
+ * 三态：skipped（无 provider artifact → 非全栈项目不打扰）/ warning（missingBackend>0）/ passed。
+ * 启发式正则、多假阳源 → advisory 不阻断 verify 完成（与 SillySpec 确定性校验定位一致）。
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd - 扫描前端调用的根（主工作区，verify 时代码在此）
+ * @param {string} opts.specBase
+ * @param {string|null} [opts.changeName]
+ * @param {string|null} [opts.runtimeRoot]
+ * @returns {{ status: 'skipped'|'warning'|'passed', missingBackend: Array, unusedBackend: Array, summary: string, reason: string|null }}
+ */
+export function runVerifyParityCheck({ cwd, specBase, changeName = null, runtimeRoot = null }) {
+  const r = verifyApiParity(specBase, cwd, runtimeRoot, changeName)
+  // 无 provider artifact（execute 未提取 / 非后端项目）→ 不打扰
+  if (r.backendCount === 0) {
+    return { status: 'skipped', missingBackend: [], unusedBackend: [], summary: r.summary, reason: '无后端契约 artifact（非全栈项目或 execute 未提取端点）' }
+  }
+  if (r.missingBackend.length > 0) {
+    return { status: 'warning', missingBackend: r.missingBackend, unusedBackend: r.unusedBackend, summary: r.summary, reason: null }
+  }
+  return { status: 'passed', missingBackend: [], unusedBackend: r.unusedBackend, summary: r.summary, reason: null }
+}
+
+/** 打印 parity 对账结果（advisory，不阻断） */
+export function printVerifyParityCheck(result) {
+  if (result.status === 'skipped') return  // 静默，不打扰非全栈项目
+  if (result.status === 'passed') {
+    console.log(`\n✅ API parity 对账通过：${result.summary}`)
+    return
+  }
+  // warning
+  console.warn(`\n⚠️  API parity 对账发现 ${result.missingBackend.length} 个前端调用无对应后端端点（advisory，不阻断归档）：`)
+  for (const m of result.missingBackend.slice(0, 20)) {
+    console.warn(`   - ${m.method} ${m.path}  ← ${m.consumerFile}:${m.consumerLine}`)
+  }
+  if (result.missingBackend.length > 20) console.warn(`   …还有 ${result.missingBackend.length - 20} 个`)
+  console.warn('   提示：检查是否后端漏实现，或前端调用了尚未实现的端点。确认无误可在 design.md 标注豁免。')
+}

package/src/worktree-apply.js

@@ -49,14 +49,34 @@ export function filterDeliverableFiles(files) {
 }
 
 /**
- * 获取文件在 git 中的 blob hash（基于某个 commit/tree）
- * @param {string} cwd - git 工作区路径
- * @param {string} treeish - commit hash、分支等
- * @param {string} filePath - 相对路径
- * @returns {string|null} blob hash，文件不存在返回 null
+ * 批量获取多个文件在某个 treeish 中的 blob hash（一次 git ls-tree 替代 N 次 rev-parse）。
+ *
+ * 语义等价于对每个文件调 `git rev-parse <treeish>:<path>`：
+ *   - 文件在 tree 中 → Map<f, hash>（与 rev-parse 返回的同一 blob hash）
+ *   - 文件不在 tree 中 → 不在 Map 中（调用方 map.get(f) ?? null 得 null，等同 rev-parse 失败→null）
+ * ls-tree 输出 "<mode> <type> <hash>\t<path>"。path 恒为文件路径（来自 git diff/ls-files），
+ * 非目录，故不带 -r 也正确——文件在 tree 时 rev-parse treeish:path 与 ls-tree 都给同一 hash，
+ * 不在时都不给，等价。（沿用 git() 字符串拼接模式，不引入新的引号/空格破法。）
+ *
+ * @param {string} cwd
+ * @param {string} treeish
+ * @param {string[]} files
+ * @returns {Map<string, string>} path → blob hash（仅含存在于 tree 中的文件）
  */
-function getFileBlobHash(cwd, treeish, filePath) {
-  return gitQuiet(cwd, `rev-parse ${treeish}:${filePath}`);
+function getBlobHashMap(cwd, treeish, files) {
+  const map = new Map();
+  if (files.length === 0) return map; // 空 pathspec 会让 ls-tree 列出整棵树，必须拦截
+  const raw = gitQuiet(cwd, `ls-tree ${treeish} -- ${files.join(' ')}`);
+  if (!raw) return map;
+  for (const line of raw.split('\n')) {
+    if (!line) continue;
+    const tabIdx = line.indexOf('\t');
+    if (tabIdx === -1) continue;
+    const filePath = line.slice(tabIdx + 1);
+    const hash = line.slice(0, tabIdx).split(' ')[2]; // "<mode> <type> <hash>"
+    if (hash) map.set(filePath, hash);
+  }
+  return map;
 }
 
 /**
@@ -203,10 +223,14 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
   }
 
   // 5b. 对比 worktree 的 baseHash 和主工作区 HEAD 中每个清单文件的 blob hash
+  // 批量化：两次 ls-tree（worktree 的 baseHash + 主仓库 HEAD）各建一张 path→hash Map，
+  // 替代 per-file getFileBlobHash × 2（原 2N spawn → 固定 2）。语义等价见 getBlobHashMap。
   const targetFiles = hasAllowList ? [...allowSet] : changedFiles;
+  const wtHashMap = getBlobHashMap(worktreePath, baseHash, targetFiles);
+  const mainHashMap = getBlobHashMap(projectRoot, 'HEAD', targetFiles);
   for (const f of targetFiles) {
-    const wtBlob = getFileBlobHash(worktreePath, baseHash, f);
-    const mainBlob = getFileBlobHash(projectRoot, 'HEAD', f);
+    const wtBlob = wtHashMap.get(f) ?? null;
+    const mainBlob = mainHashMap.get(f) ?? null;
 
     // 两者都为 null（文件在 base 时不存在）→ OK
     if (wtBlob === null && mainBlob === null) continue;
@@ -234,7 +258,6 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
   const patchFiles = hasAllowList
     ? [...allowSet].filter(f => changedFiles.includes(f))
     : changedFiles;
-  const fileArgs = patchFiles.length > 0 ? `-- ${patchFiles.join(' ')}` : '';
 
   // 创建临时文件
   const tmpDir = mkdtempSync(join(tmpdir(), 'sillyspec-patch-'));
@@ -245,14 +268,18 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
     let patchContent = '';
 
     // 分 tracked 变更和 untracked 新文件生成 patch
-    const trackedFiles = patchFiles.filter(f => {
-      // 文件在 diffBase 的 tree 中存在 → tracked（包括 rename 目标可能的情况）
-      if (gitQuiet(worktreePath, `cat-file -e ${diffBase}:${f}`) !== null) return true;
-      // 文件在工作区 index 中已存在（比如被 git mv 处理过）→ 也视为 tracked
-      if (gitQuiet(worktreePath, `ls-files --error-unmatch ${f}`) !== null) return true;
-      return false;
-    });
-    const untrackedPatchFiles = patchFiles.filter(f => !trackedFiles.includes(f));
+    // 批量化：一次 ls-tree（diffBase tree 中存在的文件）+ 一次 ls-files（index 中存在的文件）
+    // 建集合，替代 per-file cat-file -e / ls-files --error-unmatch（原至多 2N spawn → 固定 2）。
+    // 语义等价：cat-file -e diffBase:f 成功 ⟺ f 在 ls-tree diffBase 输出（getBlobHashMap key）；
+    // ls-files --error-unmatch f 成功 ⟺ f 在 ls-files -- 输出。
+    const inTree = getBlobHashMap(worktreePath, diffBase, patchFiles);
+    const inIndexList = patchFiles.length > 0
+      ? (gitQuiet(worktreePath, `ls-files -- ${patchFiles.join(' ')}`) || '').split('\n').filter(Boolean)
+      : [];
+    const inIndex = new Set(inIndexList);
+    const trackedFiles = patchFiles.filter(f => inTree.has(f) || inIndex.has(f));
+    const trackedSet = new Set(trackedFiles);
+    const untrackedPatchFiles = patchFiles.filter(f => !trackedSet.has(f));
 
     // tracked 文件：git diff baseHash
     if (trackedFiles.length > 0) {

package/src/worktree.js

@@ -18,6 +18,11 @@ const WORKTREES_REL = '.sillyspec/.runtime/worktrees';
 const BRANCH_PREFIX = 'sillyspec/';
 const META_FILE = 'meta.json';
 
+// 进程级缓存：cwd → 主仓库根目录。避免每次 new WorktreeManager 都 spawn 一次
+// `git rev-parse --git-common-dir`（Windows 上每次 spawn 约 30-100ms，execute 一次命令
+// 会 new 多个 WorktreeManager）。git-common-dir 在进程内对同一 cwd 稳定，缓存安全。
+const _mainRepoRootByCwd = new Map();
+
 /**
  * 检测当前目录的隔离状态
  * 返回 { inWorktree: boolean, inSubmodule: boolean }
@@ -224,24 +229,27 @@ export class WorktreeManager {
    * @private
    */
   _resolveMainRepoRoot() {
+    const cached = _mainRepoRootByCwd.get(this.cwd);
+    if (cached !== undefined) return cached;
+
+    let root = this.cwd;
     try {
       // git-common-dir 在主仓库内 = <main>/.git
       // 在 linked worktree 内 = <main>/.git（git 共享 .git 目录）
       const commonDir = gitQuiet(this.cwd, 'rev-parse --git-common-dir');
-      if (!commonDir) return this.cwd;
-
       // commonDir 应该是 <main-repo>/.git
       // dirname(commonDir) = <main-repo>
-      if (existsSync(commonDir)) {
+      if (commonDir && existsSync(commonDir)) {
         const st = statSync(commonDir);
         if (st.isDirectory()) {
-          return dirname(commonDir);
+          root = dirname(commonDir);
         }
       }
     } catch (e) {
       // 静默 fallback：主仓库内执行或 git 异常
     }
-    return this.cwd;
+    _mainRepoRootByCwd.set(this.cwd, root);
+    return root;
   }
 
   /**