kld-sdd 2.6.17 → 2.6.21

package/templates/git-hooks/pre-commit-consistency-check.cjs

@@ -3,191 +3,346 @@
  * pre-commit-consistency-check.cjs
  *
  * Pre-commit 门禁：检查活跃变更的 Spec 一致性校验报告。
- * 若 confidence=low 则阻止提交；缺少报告则警告但放行（向后兼容）。
+ * - 默认：缺少报告 / confidence=low → 阻止提交；strict 模式下 medium 也阻止
  *
- * 用法: node pre-commit-consistency-check.cjs --project=<project-root> [--change=<change-name>]
+ * 通过环境变量控制：
+ * - SDD_SKIP_CONSISTENCY_CHECK=1 → 跳过校验
+ * - SDD_STRICT_CONSISTENCY=1 → 严格模式（medium 也阻止）
+ * - SDD_WARN_ONLY=1 → 仅告警不拦截
+ * - 注意：三个环境变量互斥，只能启用一个
  */
-
 'use strict';
 
 const fs = require('fs');
 const path = require('path');
+const { execFileSync } = require('child_process');
 
-function readArg(name) {
+const readArg = (name) => {
   const prefix = `--${name}=`;
-  const found = process.argv.find(arg => arg.startsWith(prefix));
+  const found = process.argv.find(a => a.startsWith(prefix));
   return found ? found.slice(prefix.length) : '';
+};
+
+// --- Spec 根路径解析 ---
+
+function resolveSpecRoot() {
+  // .cjs 位于 <spec-root>/skywalk-sdd/git-hooks/，直接用 __dirname 推算
+  return path.resolve(__dirname, '..', '..');
 }
 
-function hasFlag(name) {
-  return process.argv.includes(`--${name}`);
+function discoverActiveChanges(specRoot) {
+  const changesDir = path.join(specRoot, 'openspec', 'changes');
+  if (!fs.existsSync(changesDir)) return [];
+
+  return fs.readdirSync(changesDir).filter(name => {
+    const p = path.join(changesDir, name);
+    return fs.statSync(p).isDirectory() && !name.startsWith('.') && name !== 'archive';
+  });
 }
 
-/**
- * 从 .sdd-spec-root 文件读取 spec 包裹包相对路径（单仓 mono 布局）
- */
-function resolveSpecRoot(projectRoot) {
-  // 1. 检查 .sdd-spec-root（单仓 mono 模式）
-  const hintPath = path.join(projectRoot, '.sdd-spec-root');
-  if (fs.existsSync(hintPath)) {
-    const rel = fs.readFileSync(hintPath, 'utf8').trim();
-    if (rel) {
-      const specAbs = path.resolve(projectRoot, rel);
-      if (fs.existsSync(specAbs)) {
-        return specAbs;
-      }
-    }
-  }
+// --- 报告查找与解析 ---
 
-  // 2. 查找 *-sdd-specs 子目录（多仓工作区模式）
-  const entries = fs.existsSync(projectRoot) ? fs.readdirSync(projectRoot) : [];
-  for (const name of entries) {
-    if (/-sdd-specs$/i.test(name)) {
-      const candidate = path.join(projectRoot, name);
-      if (fs.statSync(candidate).isDirectory() && fs.existsSync(path.join(candidate, 'openspec'))) {
-        return candidate;
-      }
-    }
+function findReport(specRoot, changeName, type) {
+  const names = type === 'json'
+    ? ['consistency-report-result.json', 'consistency-report-self-review-result.json']
+    : ['consistency-report.md', 'consistency-report-self-review.md'];
+
+  const found = [];
+  for (const n of names) {
+    const p = path.join(specRoot, 'openspec', 'changes', changeName, n);
+    if (fs.existsSync(p)) found.push(p);
   }
 
-  // 3. 项目根本身就是 spec 仓
-  if (fs.existsSync(path.join(projectRoot, 'openspec', 'changes'))) {
-    return projectRoot;
+  // 如果两种模式的报告都存在，返回错误标记
+  if (found.length > 1) {
+    return { error: 'duplicate', paths: found };
   }
 
-  return null;
+  return found.length === 1 ? found[0] : null;
+}
+
+function parseReport(reportPath) {
+  try {
+    const data = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
+    return {
+      confidence: (data.confidence || '').toLowerCase(),
+      reviewMode: data.reviewMode || 'independent-review',
+      humanConfirmed: data.humanConfirmed === true,
+      reportPath,
+    };
+  } catch (err) {
+    return { confidence: '', reviewMode: '', humanConfirmed: false, reportPath, parseError: err.message };
+  }
 }
 
+// --- 变更文件采集（基于配置文件精准定位） ---
+
 /**
- * 发现活跃变更列表
+ * 简易 YAML 解析器：仅提取 code_repos 列表
  */
-function discoverActiveChanges(specRoot, explicitChange) {
-  if (explicitChange) {
-    return [explicitChange];
+function parseCodeRepos(yamlPath) {
+  try {
+    const content = fs.readFileSync(yamlPath, 'utf8');
+    const match = content.match(/code_repos:\s*\n((?:\s+-\s+\S+\n?)+)/);
+    if (!match) return null;
+    return match[1]
+      .split('\n')
+      .map(line => line.replace(/^\s+-\s+/, '').trim())
+      .filter(Boolean);
+  } catch {
+    return null;
   }
+}
 
-  const changesDir = path.join(specRoot, 'openspec', 'changes');
-  if (!fs.existsSync(changesDir)) {
+function gitDiff(repoRoot) {
+  try {
+    return execFileSync('git', ['diff', 'HEAD', '--name-only'], {
+      cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).split(/\r?\n/).filter(Boolean);
+  } catch {
     return [];
   }
+}
+
+function getModifiedFiles(projectRoot) {
+  // 工作区模式：读 .sdd-workspace.yaml 的 code_repos
+  const wsYaml = path.join(projectRoot, '.sdd-workspace.yaml');
+  if (fs.existsSync(wsYaml)) {
+    const repos = parseCodeRepos(wsYaml);
+    if (repos && repos.length > 0) {
+      const files = [];
+      for (const repo of repos) {
+        const repoRoot = path.join(projectRoot, repo);
+        for (const f of gitDiff(repoRoot)) {
+          files.push(path.join(repo, f).replace(/\\/g, '/'));
+        }
+      }
+      return [...new Set(files)];
+    }
+  }
 
-  return fs.readdirSync(changesDir)
-    .filter(name => {
-      const fullPath = path.join(changesDir, name);
-      return fs.statSync(fullPath).isDirectory()
-        && !name.startsWith('.')
-        && name !== 'archive';
-    });
+  // 单仓模式 / 兜底：直接对 projectRoot 做 diff
+  return gitDiff(projectRoot);
 }
 
 /**
- * 查找变更的一致性报告 JSON
+ * 获取报告生成时间：优先用 JSON 中的 generatedAt，降级用文件 mtime
  */
-function findConsistencyReport(specRoot, changeName) {
-  const patterns = [
+function getReportTime(jsonPath) {
+  try {
+    const data = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+    if (data.generatedAt) {
+      const t = new Date(data.generatedAt).getTime();
+      if (!isNaN(t)) return t;
+    }
+  } catch {}
+  // 降级：用文件 mtime
+  return fs.statSync(jsonPath).mtimeMs;
+}
+
+function isReportStale(specRoot, changeName, modifiedFiles, projectRoot) {
+  const jsonPath = findReport(specRoot, changeName, 'json');
+  if (!jsonPath) return false;
+
+  const reportTime = getReportTime(jsonPath);
+
+  // 排除报告文件本身
+  const reportFiles = [
+    'consistency-report.md',
+    'consistency-report-self-review.md',
     'consistency-report-result.json',
     'consistency-report-self-review-result.json',
   ];
 
-  for (const pattern of patterns) {
-    const reportPath = path.join(specRoot, 'openspec', 'changes', changeName, pattern);
-    if (fs.existsSync(reportPath)) {
-      return reportPath;
+  return modifiedFiles.some(file => {
+    if (reportFiles.includes(path.basename(file))) return false;
+    const fp = path.join(projectRoot, file);
+    return fs.existsSync(fp) && fs.statSync(fp).mtimeMs > reportTime;
+  });
+}
+
+// --- 提示信息 ---
+
+function generateInstructions(missing, parseError, lowConfidence, stale, needsConfirmation, warnOnly) {
+  const lines = ['', '=========================================='];
+  const needsRegenerate = [...new Set([...missing, ...parseError, ...lowConfidence, ...stale])];
+
+  if (warnOnly) {
+    lines.push('[SDD commit-consistency-check] ⚠️  仅告警模式（SDD_WARN_ONLY=1），以下问题不会阻止提交：');
+  } else {
+    lines.push('[SDD commit-consistency-check] 以下变更存在问题，拒绝提交：');
+  }
+
+  lines.push('');
+
+  if (missing.length) {
+    lines.push('  缺少一致性报告：');
+    missing.forEach(c => lines.push(`    - ${c}`));
+  }
+
+  if (parseError.length) {
+    lines.push('  报告解析失败（JSON 格式损坏）：');
+    parseError.forEach(c => lines.push(`    - ${c}`));
+  }
+
+  if (lowConfidence.length) {
+    lines.push('  报告置信度不达标：');
+    lowConfidence.forEach(c => lines.push(`    - ${c}`));
+  }
+
+  if (stale.length) {
+    lines.push('  报告已过期（代码在报告生成后被修改）：');
+    stale.forEach(c => lines.push(`    - ${c}`));
+  }
+
+  if (needsConfirmation.length) {
+    lines.push('  自审模式需人工确认：');
+    needsConfirmation.forEach(c => lines.push(`    - ${c}`));
+  }
+
+  // 只有需要重新生成报告时才显示 skill 执行建议
+  if (needsRegenerate.length > 0) {
+    lines.push('');
+    lines.push(warnOnly
+      ? '建议执行 opsx-consistency-check skill 更新报告：'
+      : '请执行 opsx-consistency-check skill 更新报告后再提交：');
+    lines.push('');
+
+    if (needsRegenerate.length === 1) {
+      lines.push(`  skill: opsx-consistency-check ${needsRegenerate[0]}`);
+    } else {
+      lines.push('  skill（逐个执行）：');
+      needsRegenerate.forEach(c => lines.push(`    opsx-consistency-check ${c}`));
     }
+
+    lines.push(
+      '',
+      '  💡 建议：新开对话窗口执行校验，以获得独立、客观的审核结果',
+    );
   }
 
-  return null;
-}
+  // 自审模式人工确认指引
+  if (needsConfirmation.length > 0) {
+    lines.push('');
+    lines.push('  人工确认步骤：');
+    lines.push('  1. 打开 consistency-report-self-review.md，找到「人工确认（自审模式）」章节');
+    lines.push('  2. 逐条核对断言，在「人工确认」列填写 ✅ 已确认 或 ❌ 有误');
+    lines.push('  3. 确认无误后，编辑 consistency-report-self-review-result.json，将 humanConfirmed 从 false 改为 true');
+    lines.push('');
+    lines.push('  报告路径: openspec/changes/<change-name>/consistency-report-self-review.md');
+    lines.push('  JSON 路径: openspec/changes/<change-name>/consistency-report-self-review-result.json');
+  }
 
-/**
- * 解析一致性报告，返回置信度
- */
-function parseReport(reportPath) {
-  try {
-    const content = fs.readFileSync(reportPath, 'utf8');
-    const data = JSON.parse(content);
-    return {
-      confidence: (data.confidence || '').toLowerCase(),
-      overallResult: (data.overallResult || '').toLowerCase(),
-      changeName: data.changeName || '',
-      reportPath,
-    };
-  } catch (err) {
-    return { confidence: '', overallResult: '', changeName: '', reportPath, parseError: err.message };
+  // 如果没有需要重新生成的报告，但有其他问题，显示默认报告路径
+  if (needsRegenerate.length > 0 && needsConfirmation.length === 0) {
+    lines.push(
+      '',
+      '  报告路径: openspec/changes/<change-name>/consistency-report.md',
+      '  JSON 路径: openspec/changes/<change-name>/consistency-report-result.json',
+    );
   }
+
+  lines.push('==========================================', '');
+
+  return lines.join('\n');
 }
 
+// --- 主流程 ---
+
 function main() {
   const projectRoot = path.resolve(readArg('project') || process.env.SDD_PROJECT || process.cwd());
-  const explicitChange = readArg('change') || process.env.SDD_CHANGE || process.env.OPENSPEC_CHANGE || '';
-  const strictMode = hasFlag('strict') || process.env.SDD_STRICT_CONSISTENCY === '1';
 
-  const specRoot = resolveSpecRoot(projectRoot);
-  if (!specRoot) {
-    console.log('SDD consistency-check: 未找到 spec 仓库，跳过一致性校验');
-    return;
+  const skip = process.env.SDD_SKIP_CONSISTENCY_CHECK === '1';
+  const strict = process.env.SDD_STRICT_CONSISTENCY === '1';
+  const warnOnly = process.env.SDD_WARN_ONLY === '1';
+
+  // 互斥检查
+  const activeModes = [skip, strict, warnOnly].filter(Boolean).length;
+  if (activeModes > 1) {
+    console.error('[SDD commit-consistency-check] 错误：SDD_SKIP_CONSISTENCY_CHECK、SDD_STRICT_CONSISTENCY、SDD_WARN_ONLY 三个环境变量互斥，只能启用一个');
+    process.exit(1);
+  }
+
+  if (skip) {
+    console.log('[SDD commit-consistency-check] 跳过校验');
+    process.exit(0);
   }
 
-  const changes = discoverActiveChanges(specRoot, explicitChange);
-  if (changes.length === 0) {
-    console.log('SDD consistency-check: 无活跃变更，跳过一致性校验');
-    return;
+  if (warnOnly) console.log('[SDD commit-consistency-check] 仅告警模式');
+
+  const specRoot = resolveSpecRoot();
+
+  const changes = discoverActiveChanges(specRoot);
+  if (!changes.length) {
+    console.log('[SDD commit-consistency-check] 无活跃变更，跳过');
+    process.exit(0);
   }
 
-  const blockers = [];
+  const modifiedFiles = getModifiedFiles(projectRoot);
   const missing = [];
-  const passed = [];
+  const parseError = [];
+  const lowConfidence = [];
+  const stale = [];
+  const needsConfirmation = [];
+
+  for (const cn of changes) {
+    const rp = findReport(specRoot, cn, 'json');
+    if (!rp) {
+      missing.push(cn);
+      continue;
+    }
 
-  for (const changeName of changes) {
-    const reportPath = findConsistencyReport(specRoot, changeName);
-    if (!reportPath) {
-      missing.push(changeName);
+    // 检查是否存在两种模式的报告
+    if (rp.error === 'duplicate') {
+      console.warn(`[SDD commit-consistency-check] ⚠️  ${cn} 存在两种模式的报告，请删除其中一个：`);
+      rp.paths.forEach(p => console.warn(`    - ${p}`));
+      parseError.push(cn);
       continue;
     }
 
-    const report = parseReport(reportPath);
+    const report = parseReport(rp);
     if (report.parseError) {
-      console.warn(`SDD consistency-check: ⚠️  ${changeName} 报告解析失败: ${report.parseError}`);
-      missing.push(changeName);
+      console.warn(`[SDD commit-consistency-check] ⚠️  ${cn} 报告解析失败`);
+      parseError.push(cn);
       continue;
     }
 
-    if (report.confidence === 'low' || report.overallResult === 'fail') {
-      blockers.push({ changeName, report });
-    } else {
-      passed.push({ changeName, report });
+    if (isReportStale(specRoot, cn, modifiedFiles, projectRoot)) {
+      console.log(`[SDD commit-consistency-check] ⚠️  ${cn}: 报告已过期`);
+      stale.push(cn);
+      continue;
     }
-  }
 
-  // 输出摘要
-  if (passed.length > 0) {
-    for (const item of passed) {
-      console.log(`SDD consistency-check: ✅ ${item.changeName} 置信度=${item.report.confidence}`);
+    // 自审模式需要人工确认
+    if (report.reviewMode === 'self-review' && !report.humanConfirmed) {
+      console.log(`[SDD commit-consistency-check] ⚠️  ${cn}: 自审模式需人工确认`);
+      needsConfirmation.push(cn);
+      continue;
     }
-  }
 
-  if (missing.length > 0) {
-    console.warn(`SDD consistency-check: ⚠️  以下变更缺少一致性校验报告（允许提交，建议执行 opsx-consistency-check）:`);
-    for (const name of missing) {
-      console.warn(`  - ${name}`);
+    const c = report.confidence;
+    if (c === 'low' || (c === 'medium' && strict)) {
+      console.log(`[SDD commit-consistency-check] ❌ ${cn}: 置信度 ${c}`);
+      lowConfidence.push(cn);
+      continue;
     }
+
+    console.log(`[SDD commit-consistency-check] ✅ ${cn}: 置信度 ${c}`);
   }
 
-  if (blockers.length > 0) {
-    console.error(`SDD consistency-check: ❌ 以下变更的一致性校验未通过（confidence=low），阻止提交:`);
-    for (const item of blockers) {
-      console.error(`  - ${item.changeName} (confidence=${item.report.confidence}, result=${item.report.overallResult})`);
-      console.error(`    报告路径: ${item.report.reportPath}`);
+  if (missing.length || parseError.length || lowConfidence.length || stale.length || needsConfirmation.length) {
+    console.log(generateInstructions(missing, parseError, lowConfidence, stale, needsConfirmation, warnOnly));
+
+    if (warnOnly) {
+      console.log('[SDD commit-consistency-check] 仅告警模式，放行提交');
+      process.exit(0);
     }
-    console.error('');
-    console.error('请修复不一致项后重新执行 opsx-consistency-check，或使用 --no-verify 跳过（不推荐）。');
-    process.exit(1);
-  }
 
-  if (strictMode && missing.length > 0) {
-    console.error('SDD consistency-check: ❌ strict 模式已启用，缺少报告的变更不允许提交。');
     process.exit(1);
   }
+
+  console.log('\n[SDD commit-consistency-check] ✅ 所有变更均已通过一致性校验，放行提交');
+  process.exit(0);
 }
 
 main();