kld-sdd 2.7.3 → 2.7.8

package/templates/git-hooks/consistency-check-core.cjs

@@ -0,0 +1,1087 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * consistency-check-core.cjs
+ *
+ * pre-commit / pre-push 一致性校验 hook 的共享核心（非独立插件，不在 hooks.config 中登记）。
+ * 两个入口脚本通过 require 引用本模块，注入各自差异配置：
+ * - diff 采集方式（pre-commit: git diff HEAD；pre-push: 待推送范围 @{push}..HEAD）
+ * - 是否检查置信度（pre-commit 检查；pre-push 轻量跳过）
+ * - strict 模式（仅 pre-commit 支持 SDD_STRICT_CONSISTENCY）
+ * - 过期比对来源（pre-commit: 工作区内容；pre-push: HEAD 已提交内容，staleFromHead）
+ * - 提示文案（提交 / 推送）
+ *
+ * 核心行为（简化版）：
+ * - diff 驱动：仅检查 diff 文件与报告 coveredFiles 有交集的 change，无关 change 跳过
+ * - 多仓归属过滤：报告 repositories 已声明覆盖仓库且不含当前仓的 change 静默跳过（不输出、不拦截）
+ * - 纯注释/空行/空格变更过滤：diff 中所有变更行均为注释/空行/空格的文件直接跳过，不参与校验
+ * - 报告存在性：活跃 change 无报告 → 阻止
+ * - 报告过期：diff 业务代码与 coveredFiles 交集文件内容变化（size 短路 + SHA-256）→ 阻止
+ * - 置信度门禁（仅 pre-commit）：low → 阻止；strict 时 medium 也阻止
+ * - 无活跃 change 但 diff 有业务代码 → 阻止（提示先执行 opsx-propose）
+ * - 变更范围采集失败 → 阻止（避免静默放行的 fail-open）
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+
+function readArg(name) {
+  const prefix = `--${name}=`;
+  const found = process.argv.find(a => a.startsWith(prefix));
+  return found ? found.slice(prefix.length) : '';
+}
+
+// --- Spec 根路径解析 ---
+
+function resolveSpecRoot() {
+  return path.resolve(__dirname, '..', '..');
+}
+
+/**
+ * 内置 sdd.config.yaml active_changes 解析。
+ */
+function parseActiveChangesFromYaml(content) {
+  const keys = [];
+  let inActive = false;
+  for (const raw of content.split(/\r?\n/)) {
+    const line = raw.replace(/#.*$/, '').replace(/\s+$/, '');
+    if (!line.trim()) continue;
+    if (/^active_changes:\s*(\[\s*\])?\s*$/.test(line)) { inActive = true; continue; }
+    if (inActive) {
+      const m = /^\s+-\s+change-key:\s*(\S+)/.exec(line);
+      if (m) keys.push(m[1]);
+    }
+  }
+  return { keys, sawSection: inActive };
+}
+
+/**
+ * 发现活跃 change：以 sdd.config.yaml 注册表为权威源，
+ * 注册表缺失/损坏时降级为扫描 openspec/changes/ 目录。
+ */
+function discoverActiveChanges(specRoot) {
+  const configPath = path.join(specRoot, 'sdd.config.yaml');
+  if (fs.existsSync(configPath)) {
+    try {
+      const { keys, sawSection } = parseActiveChangesFromYaml(fs.readFileSync(configPath, 'utf8'));
+      if (sawSection) return keys;
+    } catch {
+      // 降级为目录扫描
+    }
+  }
+
+  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';
+  });
+}
+
+// --- 报告查找与解析 ---
+
+const REPORT_JSON_NAME = 'consistency-report-result.json';
+
+const VALID_CONFIDENCE = new Set(['high', 'medium', 'low']);
+
+function findReportJson(specRoot, changeName) {
+  const p = path.join(specRoot, 'openspec', 'changes', changeName, REPORT_JSON_NAME);
+  return fs.existsSync(p) ? p : null;
+}
+
+function parseReport(reportPath) {
+  try {
+    const data = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
+    let generatedAtMs = null;
+    let generatedAtFormatError = null;
+    if (data.generatedAt) {
+      const raw = String(data.generatedAt);
+      const normalized = /T\d{2}:\d{2}/.test(raw)
+        ? raw.replace('T', ' ').replace(/(Z|[+-]\d{2}:?\d{2})$/, '')
+        : raw;
+      const t = new Date(normalized.replace(/-/g, '/')).getTime();
+      if (!isNaN(t)) {
+        generatedAtMs = t + 1000;
+      } else {
+        generatedAtFormatError = `generatedAt 无法解析（实际: ${raw}，应为 YYYY-MM-DD HH:mm:ss 本地时间）`;
+      }
+    }
+    return {
+      confidence: (data.confidence || '').toLowerCase(),
+      coveredFiles: Array.isArray(data.coveredFiles) ? data.coveredFiles : null,
+      repositories: Array.isArray(data.repositories) ? data.repositories : [],
+      generatedAtMs,
+      generatedAtFormatError,
+      reportPath,
+    };
+  } catch (err) {
+    return { confidence: '', coveredFiles: null, repositories: [], generatedAtMs: null, generatedAtFormatError: null, reportPath, parseError: err.message };
+  }
+}
+
+/**
+ * 报告字段合法性校验（仅校验 confidence 枚举 + generatedAt 格式）。
+ * @returns {string[]} 错误描述列表；空数组表示合法
+ */
+function validateReportFields(report) {
+  const errors = [];
+
+  if (!VALID_CONFIDENCE.has(report.confidence)) {
+    errors.push(`confidence 非法（只能是 high/medium/low，实际: ${report.confidence || '缺失'}）`);
+  }
+
+  if (report.generatedAtFormatError) {
+    errors.push(report.generatedAtFormatError);
+  }
+
+  return errors;
+}
+
+// --- 变更文件采集 ---
+
+/**
+ * 简易 YAML 解析器：仅提取 code_repos 列表
+ */
+function parseCodeRepos(yamlPath) {
+  try {
+    const content = fs.readFileSync(yamlPath, 'utf8');
+    const match = content.match(/code_repos:\s*\n((?:[ \t]*(?:#[^\n]*\n)?[ \t]*-[ \t]*\S+[ \t]*(?:#[^\n]*)?\n?)+)/);
+    if (!match) return null;
+    return match[1]
+      .split('\n')
+      .map(line => line.replace(/#.*$/, '').replace(/^\s+-\s+/, '').trim())
+      .filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+function gitUntracked(repoRoot) {
+  try {
+    return execFileSync('git', ['-c', 'core.quotePath=false', 'ls-files', '--others', '--exclude-standard'], {
+      cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).split(/\r?\n/).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+// --- 注释/空行/空格变更过滤 ---
+
+/**
+ * 判断 diff 行是否为"无实质意义"变更（注释、空行、纯空格）。
+ * 仅对 diff 中新增(+)和删除(-)的行内容做判断。
+ * @param {string} line 去掉 +/- 前缀后的行内容
+ * @returns {boolean} true=无实质意义（可跳过）
+ */
+function isTrivialDiffLine(line) {
+  const trimmed = line.trim();
+  if (trimmed === '') return true; // 空行/纯空格
+  if (trimmed.startsWith('//')) return true; // 行注释 (JS/TS/Java/C/C++ 等)
+  if (trimmed.startsWith('#')) {
+    // 排除 C/C++ 预处理指令
+    const rest = trimmed.slice(1).trimStart();
+    if (/^(include|define|ifdef|ifndef|endif|else|elif|undef|pragma|error|warning|line|region|endregion)\b/.test(rest)) {
+      return false;
+    }
+    return true; // Python/Shell/YAML 注释
+  }
+  if (trimmed.startsWith('/*') || trimmed.endsWith('*/')) return true; // 块注释开始/结束
+  if (trimmed.startsWith('*')) return true; // 块注释续行 (* ... 或 ** ...)
+  if (trimmed.startsWith('<!--')) return true; // HTML/XML 注释
+  return false;
+}
+
+/**
+ * 从 diff 头部行解析文件路径。
+ * @param {string} headerLine 如 "+++ b/src/Svc.java" 或 "+++ \"b/src/文件.java\""
+ * @returns {string|null} 归一化后的文件路径（去掉 a/ b/ 前缀），/dev/null 返回 null
+ */
+function parseDiffPath(headerLine) {
+  let p = headerLine.slice(4); // 去掉 "+++ " 或 "--- "
+  if (p === '/dev/null') return null;
+  if (p.startsWith('"') && p.endsWith('"')) {
+    p = p.slice(1, -1).replace(/\\(.)/g, '$1');
+  }
+  if (p.startsWith('a/') || p.startsWith('b/')) {
+    p = p.slice(2);
+  }
+  return p;
+}
+
+/**
+ * 解析 git diff --unified=0 输出，返回所有变更仅为注释/空行/空格的文件集合。
+ * @param {string} diffOutput git diff --unified=0 的完整输出
+ * @returns {Set<string>} 文件路径集合（已归一化，去掉 b/ 前缀）
+ */
+function parseDiffForTrivialFiles(diffOutput) {
+  const trivialFiles = new Set();
+  let currentFile = null;
+  let hasSubstantive = false;
+  let hasAnyChange = false;
+
+  for (const line of diffOutput.split(/\r?\n/)) {
+    if (line.startsWith('--- ')) {
+      if (currentFile !== null && hasAnyChange && !hasSubstantive) {
+        trivialFiles.add(currentFile);
+      }
+      currentFile = null;
+      hasSubstantive = false;
+      hasAnyChange = false;
+      continue;
+    }
+    if (line.startsWith('+++ ')) {
+      currentFile = parseDiffPath(line);
+      continue;
+    }
+    if (line.startsWith('\\')) continue; // ""
+    if (line.startsWith('Binary files')) {
+      hasSubstantive = true;
+      hasAnyChange = true;
+      continue;
+    }
+    if (line.startsWith('+') && !line.startsWith('+++')) {
+      hasAnyChange = true;
+      if (!isTrivialDiffLine(line.slice(1))) hasSubstantive = true;
+      continue;
+    }
+    if (line.startsWith('-') && !line.startsWith('---')) {
+      hasAnyChange = true;
+      if (!isTrivialDiffLine(line.slice(1))) hasSubstantive = true;
+      continue;
+    }
+  }
+  if (currentFile !== null && hasAnyChange && !hasSubstantive) {
+    trivialFiles.add(currentFile);
+  }
+  return trivialFiles;
+}
+
+/**
+ * 获取变更仅为注释/空行/空格的文件集合（仅对候选文件做 patch 逐行分析）。
+ * 多级降级保证兼容性：--ignore-blank-lines 需 git ≥ 2.30，老版本自动降级。
+ * @param {string} repoRoot 代码仓根目录
+ * @param {string[]} baseArgs git diff 基础参数（如 ['diff', 'HEAD']）
+ * @param {string[]} files 候选文件（已由 -w 预筛排除纯空白/空行变更）
+ * @returns {Set<string>} 文件路径集合
+ */
+function getTrivialDiffFiles(repoRoot, baseArgs, files) {
+  if (!files || files.length === 0) return new Set();
+  const variants = [
+    [...baseArgs, '-w', '--ignore-blank-lines', '--unified=0', '--', ...files], // 首选：忽略空白+空行
+    [...baseArgs, '-w', '--unified=0', '--', ...files],                          // 老 git：仅忽略空白
+    [...baseArgs, '--unified=0', '--', ...files],                                // 最老：不忽略（保守）
+  ];
+  for (const args of variants) {
+    try {
+      const out = execFileSync('git', ['-c', 'core.quotePath=false', ...args], {
+        cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      return parseDiffForTrivialFiles(out);
+    } catch {
+      // 尝试下一个变体；全部失败时返回空 Set（不过滤，保守策略）
+    }
+  }
+  return new Set();
+}
+
+/**
+ * 单仓 diff 采集（一次 git 调用拿 modified + deleted）。
+ * 纯注释/空行/空格变更的文件会被过滤掉，不参与一致性校验。
+ *
+ * 性能优化（上百文件批量加注释/调格式场景）：
+ * 1. 用 git 原生 `-w --ignore-blank-lines --name-status` 预筛：纯空白/空行变更的文件
+ *    根本不会出现在输出中（一次轻量调用同时拿列表+删除+过滤空白），
+ *    避免先把全量 patch 读入内存再逐行丢弃；
+ * 2. 全部变更均为纯空白/空行时输出为空 → 直接放行，零 patch 解析；
+ * 3. 仅对剩余候选文件（可能是注释变更）执行 --unified=0 patch 分析，
+ *    patch 也带 -w 预筛，体积大幅缩小。
+ * @returns {{files: string[], deleted: string[], ok: boolean}}
+ */
+function gitDiffNameStatus(repoRoot, baseArgs) {
+  const run = (args) => execFileSync('git', ['-c', 'core.quotePath=false', ...args], {
+    cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  try {
+    // -w 预筛 + 列表采集一次完成；--ignore-blank-lines 老 git 不支持时降级为纯 -w
+    let out;
+    try {
+      out = run([...baseArgs, '-w', '--ignore-blank-lines', '--name-status']);
+    } catch {
+      out = run([...baseArgs, '--name-status']);
+    }
+    const files = [];
+    const deleted = [];
+    for (const line of out.split(/\r?\n/)) {
+      if (!line) continue;
+      const tab = line.indexOf('\t');
+      if (tab < 0) continue;
+      const status = line[0].toUpperCase();
+      const rest = line.slice(tab + 1);
+      const parts = rest.split('\t');
+      const filePath = parts.length > 1 ? parts[parts.length - 1] : parts[0];
+      if (!filePath) continue;
+      if (status === 'D') {
+        deleted.push(filePath);
+      } else {
+        files.push(filePath);
+      }
+    }
+    // 无修改文件（仅删除）或全部为纯空白变更（-w 后无输出）→ 无需 patch 分析
+    if (files.length === 0) return { files, deleted, ok: true };
+
+    // 过滤纯注释/空行/空格变更的文件（patch 已 -w 预筛，仅候选文件）
+    const trivialFiles = getTrivialDiffFiles(repoRoot, baseArgs, files);
+    const filtered = files.filter(f => !trivialFiles.has(f));
+    return { files: filtered, deleted, ok: true };
+  } catch {
+    return { files: [], deleted: [], ok: false };
+  }
+}
+
+/**
+ * 采集变更文件：对每个代码仓执行入口注入的 diffFn，按需合并 untracked，归一化为工作区相对路径。
+ * @param {string} projectRoot
+ * @param {(repoRoot: string) => {files: string[], deleted: string[], ok: boolean}} diffFn
+ * @param {object} [options]
+ * @param {boolean} [options.includeUntracked=true]
+ * @returns {{files: string[], deleted: string[], failed: boolean}}
+ */
+function getModifiedFiles(projectRoot, diffFn, options = {}) {
+  const includeUntracked = options.includeUntracked !== false;
+  const files = [];
+  const deleted = [];
+  let failed = false;
+
+  const collect = (repoRoot, prefix) => {
+    const r = diffFn(repoRoot);
+    if (!r || r.ok === false) {
+      failed = true;
+      return;
+    }
+    const repoFiles = includeUntracked
+      ? [...(r.files || []), ...gitUntracked(repoRoot)]
+      : (r.files || []);
+    for (const f of repoFiles) {
+      files.push(prefix ? `${prefix}/${f}` : f);
+    }
+    for (const f of (r.deleted || [])) {
+      deleted.push(prefix ? `${prefix}/${f}` : f);
+    }
+  };
+
+  // 工作区模式：读 .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) {
+      for (const repo of repos) {
+        const prefix = String(repo).replace(/\\/g, '/').replace(/\/+$/, '');
+        collect(path.join(projectRoot, repo), prefix);
+      }
+      return {
+        files: [...new Set(files.map(f => f.replace(/\\/g, '/')))],
+        deleted: [...new Set(deleted.map(f => f.replace(/\\/g, '/')))],
+        failed,
+      };
+    }
+  }
+
+  // 单仓模式 / 兜底
+  collect(projectRoot, '');
+  return {
+    files: [...new Set(files.map(f => f.replace(/\\/g, '/')))],
+    deleted: [...new Set(deleted.map(f => f.replace(/\\/g, '/')))],
+    failed,
+  };
+}
+
+// --- 配置加载（hooks.config [consistency] 段，单一实现） ---
+
+/**
+ * 解析 INI 风格的 [consistency] 段，返回段内所有 key=value。
+ */
+function parseConsistencySection() {
+  const configPath = path.join(__dirname, 'hooks.config');
+  const values = {};
+  try {
+    const content = fs.readFileSync(configPath, 'utf8');
+    let inSection = false;
+    for (const raw of content.split(/\r?\n/)) {
+      const line = raw.trim();
+      if (/^\[.+\]$/.test(line)) {
+        if (inSection) break;
+        inSection = line.toLowerCase() === '[consistency]';
+        continue;
+      }
+      if (!inSection) continue;
+      if (line.startsWith('#') || !line) continue;
+      const m = /^(\w+)\s*=\s*(.*)$/.exec(line);
+      if (!m) continue;
+      values[m[1].toLowerCase()] = m[2].trim();
+    }
+  } catch {
+    // 配置缺失：返回空对象，由调用方判定缺失语义
+  }
+  return { configPath, values };
+}
+
+const CONSISTENCY_CONFIG = parseConsistencySection();
+
+/**
+ * 业务代码扩展名白名单（business_code_exts，唯一来源为 hooks.config，无内置默认值）。
+ * @returns {{exts: Set<string>, source: 'config'|'missing'|'empty', configPath: string|null}}
+ */
+function loadBusinessCodeExts() {
+  const { configPath, values } = CONSISTENCY_CONFIG;
+  const rawValue = Object.prototype.hasOwnProperty.call(values, 'business_code_exts')
+    ? values.business_code_exts : null;
+
+  if (rawValue === null) {
+    return { exts: new Set(), source: 'missing', configPath };
+  }
+
+  const exts = new Set();
+  for (const token of rawValue.split(/[,，\s]+/).filter(Boolean)) {
+    const ext = token.toLowerCase().startsWith('.') ? token.toLowerCase() : `.${token.toLowerCase()}`;
+    if (/^\.[a-z0-9]+$/.test(ext)) exts.add(ext);
+  }
+  if (!exts.size) {
+    return { exts: new Set(), source: 'empty', configPath };
+  }
+  return { exts, source: 'config', configPath };
+}
+
+/**
+ * 布尔配置项（skip / strict / warn_only）。
+ * @returns {{skip: boolean, strict: boolean, warnOnly: boolean}}
+ */
+function loadConsistencyMode() {
+  const { values } = CONSISTENCY_CONFIG;
+  const isTrue = v => v === '1' || v === 'true' || v === 'yes';
+  return {
+    skip: isTrue((values.skip || '').toLowerCase()),
+    strict: isTrue((values.strict || '').toLowerCase()),
+    warnOnly: isTrue((values.warn_only || values.warnonly || '').toLowerCase()),
+  };
+}
+
+const BUSINESS_CODE_EXTS_INFO = loadBusinessCodeExts();
+const BUSINESS_CODE_EXTS = BUSINESS_CODE_EXTS_INFO.exts;
+const CONSISTENCY_MODE = loadConsistencyMode();
+
+// 工具链配置文件排除规则
+const TOOLCHAIN_CONFIG_RE = /^(?:vite|vitest|next|nuxt|astro|svelte|remix|webpack|rollup|babel|jest|playwright|cypress|eslint|prettier|tailwind|postcss|karma|wrangler|nest-cli|angular|vue|craco|rspack|metro|tsconfig|jsconfig|turbo|nx)\.(?:config|conf)\.[a-z]+$/i;
+const DOTFILE_CONFIG_RE = /^\.?(?:eslintrc|babelrc|prettierrc|stylelintrc)\.[a-z]+$/i;
+
+function isBusinessCode(file) {
+  const normalized = String(file).replace(/\\/g, '/');
+  const base = normalized.split('/').pop() || '';
+
+  const dot = base.lastIndexOf('.');
+  if (dot < 0) return false;
+  const ext = base.slice(dot).toLowerCase();
+  if (!BUSINESS_CODE_EXTS.has(ext)) return false;
+
+  if (/\.d\.tsx?$/i.test(base)) return false;
+  if (/(^|\/)(dist|build|target|out|node_modules)\//.test(normalized)) return false;
+  if (/\.min\.(js|css)$/i.test(base)) return false;
+  if (/(^|\/)(__tests__|tests?|e2e|cypress|fixtures|mocks?)(\/|$)/i.test(normalized)) return false;
+  if (/(^|\/)[^/]*(?:\.test|\.spec|_test)\.[a-z]+$/i.test(normalized)) return false;
+  if (TOOLCHAIN_CONFIG_RE.test(base)) return false;
+  if (DOTFILE_CONFIG_RE.test(base)) return false;
+
+  return true;
+}
+
+// --- 路径归一化：报告 coveredFiles → 代码仓相对 ---
+
+/**
+ * 多仓布局下，用报告 repositories[].path 做前缀剥离，归一化到代码仓相对路径。
+ * 单仓布局两者天然一致，直接返回。
+ * 返回 Map<path, Array<{size, sha256}>>（key 小写）。
+ *
+ * 兜底：repositories 未声明（旧报告）时，用 currentRepoName 做前缀剥离。
+ * 场景：多仓布局下旧报告缺 repositories，coveredFiles 带仓前缀（如 user-info-mgmt/src/...），
+ * hook 在代码仓根运行采集无前缀 diff（src/...），需剥离前缀才能命中交集。
+ * currentRepoName 是客观的代码仓目录名，不会误剥普通路径段。
+ */
+function normalizeCoveredFiles(report, currentRepoName) {
+  if (!report.coveredFiles) return null;
+  const repoPrefixes = (report.repositories || [])
+    .map(r => (r.path || '').replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase())
+    .filter(Boolean);
+
+  const fallbackPrefix = (repoPrefixes.length === 0 && currentRepoName)
+    ? currentRepoName.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase()
+    : null;
+
+  const result = new Map();
+  for (const item of report.coveredFiles) {
+    if (!item || typeof item !== 'object') continue; // 仅接受对象条目（path+size+sha256）
+    const normalized = String(item.path || '').replace(/\\/g, '/');
+    if (!normalized) continue;
+    const meta = { size: item.size, sha256: item.sha256 };
+
+    const originalLower = normalized.toLowerCase();
+    let stripped = originalLower;
+    for (const prefix of repoPrefixes) {
+      if (stripped === prefix) { stripped = ''; break; }
+      if (stripped.startsWith(prefix + '/')) { stripped = stripped.slice(prefix.length + 1); break; }
+    }
+    // 兜底剥离：repositories 为空且未命中任何显式前缀时，用 currentRepoName 剥离
+    if (fallbackPrefix && stripped === originalLower) {
+      if (stripped === fallbackPrefix) { stripped = ''; }
+      else if (stripped.startsWith(fallbackPrefix + '/')) { stripped = stripped.slice(fallbackPrefix.length + 1); }
+    }
+    if (!stripped) continue;
+
+    const existing = result.get(stripped) || [];
+    existing.push(meta);
+    result.set(stripped, existing);
+  }
+  return result;
+}
+
+// --- 过期判断（size 短路 + SHA-256） ---
+
+function getReportTime(report) {
+  if (typeof report.generatedAtMs === 'number') return report.generatedAtMs;
+  return fs.statSync(report.reportPath).mtimeMs;
+}
+
+function readWorkingFile(fp) {
+  try {
+    return fs.readFileSync(fp);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 批量读取 HEAD 已提交版本的文件内容（pre-push 过期检查用）。
+ * 用 cat-file --batch --filters 一次进程读取 N 个文件。
+ * 单个文件读取失败（不在 HEAD / git 版本过老不支持 --batch --filters）返回 null，
+ * 由过期判断按"内容已变"处理（fail-closed）。
+ * @param {string} projectRoot
+ * @param {string[]} relFiles 代码仓相对路径列表
+ * @returns {Map<string, Buffer|null>} key=原始路径，value=内容（null=不可读）
+ */
+function gitShowHeadContentBatch(projectRoot, relFiles) {
+  const result = new Map();
+  if (!relFiles.length) return result;
+
+  try {
+    const input = relFiles.map(f => `HEAD:${String(f).replace(/\\/g, '/')}`).join('\n') + '\n';
+    const out = execFileSync('git', ['cat-file', '--batch', '--filters'], {
+      cwd: projectRoot, encoding: 'buffer', input, stdio: ['pipe', 'pipe', 'ignore'],
+    });
+
+    let offset = 0;
+    for (const relFile of relFiles) {
+      const nlIdx = out.indexOf(0x0a, offset);
+      if (nlIdx < 0) { result.set(relFile, null); break; }
+      const header = out.slice(offset, nlIdx).toString('ascii');
+      offset = nlIdx + 1;
+
+      const parts = header.split(' ');
+      if (parts.length < 2 || parts[1] === 'missing') {
+        result.set(relFile, null);
+        continue;
+      }
+
+      const size = parseInt(parts[parts.length - 1], 10);
+      if (isNaN(size)) {
+        result.set(relFile, null);
+        continue;
+      }
+
+      if (offset + size > out.length) {
+        result.set(relFile, null);
+        break;
+      }
+      result.set(relFile, out.slice(offset, offset + size));
+      offset += size + 1;
+    }
+    return result;
+  } catch {
+    // --batch --filters 整体失败（如极老版本 git）：全部判不可读 → 过期（fail-closed）
+    for (const relFile of relFiles) {
+      result.set(relFile, null);
+    }
+    return result;
+  }
+}
+
+function normalizeEolLf(buf) {
+  const str = buf.toString('binary');
+  return Buffer.from(str.replace(/\r\n/g, '\n'), 'binary');
+}
+
+/**
+ * 单文件过期判断（mtime 快速跳过 + size 短路 + SHA-256，行尾归一化）。
+ * mtime 快速路径：文件修改时间早于报告生成时间 → 报告生成后从未被碰过 → 内容必然未变，
+ * 跳过读取和哈希（大变更场景省 100-300ms/百文件）。mtime 晚于报告时间才做精确哈希判断，
+ * 因此 git pull/checkout 重置 mtime（内容未变）只会多算一次哈希，不会误判过期。
+ */
+function isFileChangedOnDisk(fp, metas, reportTime, readContent = readWorkingFile, relFile = '') {
+  const list = Array.isArray(metas) ? metas : (metas ? [metas] : []);
+  const hashed = list.filter(m => m && m.sha256);
+
+  if (hashed.length) {
+    // mtime 快速跳过：仅在能拿到本地文件时（readContent 为工作区读取）且 mtime 可信时启用
+    if (readContent === readWorkingFile) {
+      try {
+        if (fs.statSync(fp).mtimeMs <= reportTime) return false;
+      } catch {
+        return true; // 文件不存在 → 过期
+      }
+    }
+    const content = readContent(fp, relFile);
+    if (content === null) return true;
+    const normalized = normalizeEolLf(content);
+    const candidates = hashed.filter(m =>
+      !(typeof m.size === 'number' && normalized.length !== m.size));
+    if (!candidates.length) return true;
+    const hash = crypto.createHash('sha256').update(normalized).digest('hex');
+    return !candidates.some(m => hash === String(m.sha256).toLowerCase());
+  }
+
+  // 无哈希条目：mtime 比较
+  let stat;
+  try {
+    stat = fs.statSync(fp);
+  } catch {
+    return true;
+  }
+  return stat.mtimeMs > reportTime;
+}
+
+/**
+ * 报告过期判断：仅对 coveredFiles 与 diff（含删除文件）的交集做内容比对。
+ */
+function isReportStale(report, covered, diffFiles, projectRoot, readContent = readWorkingFile) {
+  const reportTime = getReportTime(report);
+
+  return diffFiles.some(file => {
+    if (!covered.has(file.toLowerCase())) return false;
+    const fp = path.join(projectRoot, file);
+    return isFileChangedOnDisk(fp, covered.get(file.toLowerCase()), reportTime, readContent, file);
+  });
+}
+
+// --- 提示信息 ---
+
+function generateInstructions(opts, result, warnOnly) {
+  const { label, actionNoun, checkConfidence } = opts;
+  const { parseError, invalid, lowConfidence, stale, missing } = result;
+  const lines = ['', '=========================================='];
+
+  if (warnOnly) {
+    lines.push(`${label} ⚠️  仅告警模式（SDD_WARN_ONLY=1），以下问题不会阻止${actionNoun}：`);
+  } else {
+    lines.push(`${label} 以下变更存在问题，拒绝${actionNoun}：`);
+  }
+
+  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 (invalid.length) {
+    lines.push('  报告字段不合法：');
+    invalid.forEach(({ cn, errors }) => {
+      lines.push(`    - ${cn}`);
+      errors.forEach(e => lines.push(`        · ${e}`));
+    });
+  }
+
+  if (stale.length) {
+    lines.push('  报告已过期（代码在报告生成后被修改或删除）：');
+    stale.forEach(c => lines.push(`    - ${c}`));
+  }
+
+  if (checkConfidence && lowConfidence.length) {
+    lines.push('  报告置信度不达标：');
+    lowConfidence.forEach(c => lines.push(`    - ${c}`));
+  }
+
+  const needsRegenerate = [...new Set([
+    ...missing, ...parseError, ...invalid.map(i => i.cn),
+    ...(checkConfidence ? lowConfidence : []),
+    ...stale,
+  ])];
+
+  if (needsRegenerate.length > 0) {
+    lines.push('');
+    lines.push(warnOnly
+      ? '建议执行 opsx-consistency-check skill 更新报告：'
+      : `请执行 opsx-consistency-check skill 更新报告后再${actionNoun}：`);
+    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(
+      '',
+      '  💡 建议：新开对话窗口执行校验，以获得独立、客观的审核结果',
+    );
+  }
+
+  lines.push(
+    '',
+    '  报告路径: openspec/changes/<change-name>/consistency-report.md',
+    '  JSON 路径: openspec/changes/<change-name>/consistency-report-result.json',
+  );
+
+  lines.push('==========================================', '');
+
+  return lines.join('\n');
+}
+
+// --- 主流程 ---
+
+/**
+ * 一致性校验主流程（由入口脚本调用）。
+ * @param {object} opts 入口差异配置
+ */
+function runConsistencyCheck(opts) {
+  const {
+    label, actionNoun, diffFn,
+    checkConfidence = false, includeUntracked = true,
+    staleFromHead = false,
+  } = opts;
+  const projectRoot = path.resolve(readArg('project') || process.env.SDD_PROJECT || process.cwd());
+
+  // 模式解析
+  const envSkip = process.env.SDD_SKIP_CONSISTENCY_CHECK;
+  const envStrict = process.env.SDD_STRICT_CONSISTENCY;
+  const envWarnOnly = process.env.SDD_WARN_ONLY;
+  const skip = envSkip !== undefined ? envSkip === '1' : CONSISTENCY_MODE.skip;
+  const strict = envStrict !== undefined ? envStrict === '1' : CONSISTENCY_MODE.strict;
+  const warnOnly = envWarnOnly !== undefined ? envWarnOnly === '1' : CONSISTENCY_MODE.warnOnly;
+
+  // 互斥检查
+  const activeModes = [skip, strict, warnOnly].filter(Boolean).length;
+  if (activeModes > 1) {
+    const names = [
+      ...(skip ? ['SDD_SKIP_CONSISTENCY_CHECK' + (envSkip === undefined ? '(hooks.config)' : '')] : []),
+      ...(strict ? ['SDD_STRICT_CONSISTENCY' + (envStrict === undefined ? '(hooks.config)' : '')] : []),
+      ...(warnOnly ? ['SDD_WARN_ONLY' + (envWarnOnly === undefined ? '(hooks.config)' : '')] : []),
+    ];
+    console.error(`${label} 错误：${names.join('、')} 互斥，只能启用一个`);
+    process.exit(1);
+  }
+
+  if (skip) {
+    console.log(`${label} 跳过校验`);
+    process.exit(0);
+  }
+
+  if (warnOnly) console.log(`${label} 仅告警模式`);
+
+  // 配置缺失/空清单显式告警
+  if (BUSINESS_CODE_EXTS_INFO.source !== 'config') {
+    const reason = BUSINESS_CODE_EXTS_INFO.source === 'missing'
+      ? '未配置 business_code_exts（hooks.config 缺失或无 [consistency] 段）'
+      : 'business_code_exts 为空清单';
+    console.warn(`${label} ⚠️  ${reason}，一致性校验不拦截任何业务代码文件（仅保留报告存在性/过期检查）`);
+    console.warn(`${label} ℹ️  请在 ${BUSINESS_CODE_EXTS_INFO.configPath || path.join(__dirname, 'hooks.config')} 的 [consistency] 段配置 business_code_exts`);
+  }
+
+  const specRoot = resolveSpecRoot();
+
+  // 1. 采集 diff 文件
+  const { files: modifiedFiles, deleted: deletedFiles, failed: diffFailed } =
+    getModifiedFiles(projectRoot, diffFn, { includeUntracked });
+
+  if (diffFailed) {
+    console.log(`${label} ❌ 无法确定本次${actionNoun}的变更范围（git diff 采集失败），拒绝${actionNoun}`);
+    if (warnOnly) {
+      console.log(`${label} 仅告警模式，放行${actionNoun}`);
+      process.exit(0);
+    }
+    process.exit(1);
+  }
+
+  // 2. 筛选业务代码文件
+  const diffBusinessFiles = modifiedFiles.filter(isBusinessCode);
+  const deletedBusinessFiles = deletedFiles.filter(isBusinessCode);
+
+  // 3. 无业务代码文件 → 放行
+  if (diffBusinessFiles.length === 0 && deletedBusinessFiles.length === 0) {
+    console.log(`${label} 本次${actionNoun}无业务代码文件，跳过一致性校验`);
+    process.exit(0);
+  }
+
+  // 4. 活跃 change 发现
+  const changes = discoverActiveChanges(specRoot);
+  if (!changes.length) {
+    console.log([
+      '', '==========================================',
+      `${label} 存在业务代码变更但无活跃 change 可归属，拒绝${actionNoun}：`,
+      '',
+      '  请先执行 opsx-propose 创建变更（登记到 sdd.config.yaml 的 active_changes），',
+      '  再执行 opsx-consistency-check 生成一致性报告。',
+      '==========================================', '',
+    ].join('\n'));
+    if (warnOnly) {
+      console.log(`${label} 仅告警模式，放行${actionNoun}`);
+      process.exit(0);
+    }
+    process.exit(1);
+  }
+
+  // 5. 逐 change 解析报告
+  const parseError = [];
+  const invalid = [];
+  const lowConfidence = [];
+  const stale = [];
+  const missing = [];
+  const parsedReports = new Map();
+
+  // 当前代码仓目录名（多仓布局下用于报告归属过滤 + normalizeCoveredFiles 兜底前缀剥离）
+  const currentRepoName = path.basename(projectRoot).toLowerCase();
+
+  for (const cn of changes) {
+    const rp = findReportJson(specRoot, cn);
+    if (!rp) {
+      missing.push(cn);
+      continue;
+    }
+
+    const report = parseReport(rp);
+    if (report.parseError) {
+      console.warn(`${label} ⚠️  ${cn} 报告解析失败`);
+      parseError.push(cn);
+      continue;
+    }
+
+    // 旧格式报告（无 coveredFiles）
+    if (!report.coveredFiles) {
+      console.log(`${label} ⚠️  ${cn}: 报告为旧格式（缺少 coveredFiles），建议重新生成`);
+      missing.push(cn);
+      continue;
+    }
+
+    // 字段合法性校验（仅 confidence + generatedAt）
+    const fieldErrors = validateReportFields(report);
+    if (fieldErrors.length) {
+      console.warn(`${label} ⚠️  ${cn} 报告字段不合法：${fieldErrors.join('；')}`);
+      invalid.push({ cn, errors: fieldErrors });
+      continue;
+    }
+
+    const covered = normalizeCoveredFiles(report, currentRepoName);
+    parsedReports.set(cn, { report, covered });
+  }
+
+  // 6. 对 diff（含删除）与 coveredFiles 有交集的 change 检查报告
+  const checkFiles = [...new Set([...diffBusinessFiles, ...deletedBusinessFiles])];
+  const checkFilesLower = checkFiles.map(f => f.toLowerCase());
+
+  let headContentCache = null;
+  const readContent = staleFromHead
+    ? (fp, relFile) => {
+        if (headContentCache === null) {
+          headContentCache = gitShowHeadContentBatch(projectRoot, checkFiles);
+        }
+        const fromHead = headContentCache.get(relFile);
+        return fromHead !== undefined && fromHead !== null ? fromHead : readWorkingFile(fp);
+      }
+    : readWorkingFile;
+
+  for (const [cn, { report, covered }] of parsedReports) {
+    // 多仓归属过滤：报告显式声明了覆盖仓库且不含当前仓 → 与本仓无关，静默跳过
+    // （repositories 为空视为未声明，保持原交集判断行为，兼容单仓与旧报告）
+    const declaredRepos = (report.repositories || [])
+      .map(r => String(r && r.path || '').replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase())
+      .filter(Boolean);
+    if (declaredRepos.length && !declaredRepos.includes(currentRepoName)) {
+      continue;
+    }
+
+    const hasIntersection = checkFilesLower.some(f => covered.has(f));
+    if (!hasIntersection) {
+      console.log(`${label} ⏭️  ${cn}: 与本次${actionNoun}无交集，跳过`);
+      continue;
+    }
+
+    if (isReportStale(report, covered, checkFiles, projectRoot, readContent)) {
+      console.log(`${label} ⚠️  ${cn}: 报告已过期`);
+      stale.push(cn);
+      continue;
+    }
+
+    if (checkConfidence) {
+      const c = report.confidence;
+      if (c === 'low' || (c === 'medium' && strict)) {
+        console.log(`${label} ❌ ${cn}: 置信度 ${c}`);
+        lowConfidence.push(cn);
+        continue;
+      }
+      console.log(`${label} ✅ ${cn}: 置信度 ${c}`);
+    } else {
+      console.log(`${label} ✅ ${cn}: 报告有效`);
+    }
+  }
+
+  const result = {
+    missing, parseError, invalid, lowConfidence, stale,
+  };
+
+  const hasBlocking = missing.length || parseError.length || invalid.length || lowConfidence.length
+    || stale.length;
+
+  if (hasBlocking) {
+    console.log(generateInstructions(opts, result, warnOnly));
+
+    if (warnOnly) {
+      console.log(`${label} 仅告警模式，放行${actionNoun}`);
+      process.exit(0);
+    }
+
+    process.exit(1);
+  }
+
+  console.log(`\n${label} ✅ 本次${actionNoun}涉及的业务代码均已通过一致性校验，放行${actionNoun}`);
+  process.exit(0);
+}
+
+// --- CLI 筛选模式（skill 调用，机械筛选与 hook 单一实现） ---
+
+function runFilterMode() {
+  const filesArg = readArg('files');
+
+  let input = [];
+  if (filesArg) {
+    if (filesArg.startsWith('@')) {
+      input = fs.readFileSync(filesArg.slice(1), 'utf8').split(/\r?\n/);
+    } else {
+      input = filesArg.split(',');
+    }
+  } else {
+    input = fs.readFileSync(0, 'utf8').split(/\r?\n/);
+  }
+
+  const normalized = [...new Set(input.map(f => f.trim().replace(/\\/g, '/')).filter(Boolean))];
+  const businessFiles = normalized.filter(isBusinessCode);
+  const excluded = normalized.filter(f => !isBusinessCode(f));
+
+  process.stdout.write(JSON.stringify({ businessFiles, excluded }, null, 2));
+}
+
+if (process.argv.includes('--filter')) {
+  runFilterMode();
+  process.exit(0);
+}
+
+// --- CLI 采集模式（skill 调用：diff 采集 + 多仓合并 + 机械筛选一体化） ---
+// 可选 flag：
+// - --business-only：精简输出，仅 businessFiles + deletedFiles（excluded 长清单会撑爆工具输出导致截断重试）
+// - --hash：businessFiles 就地计算 size/sha256（LF 归一化，与 hook 过期判断同规则），
+//   采集+筛选+哈希一次调用完成，skill 无需再单独跑 batch-hash
+
+function runCollectMode() {
+  const projectRoot = path.resolve(readArg('project') || process.cwd());
+  const includeUntracked = readArg('include-untracked') !== '0';
+  const businessOnly = process.argv.includes('--business-only');
+  const withHash = process.argv.includes('--hash');
+
+  const diffFn = (repoRoot) => {
+    const bases = [['diff', 'HEAD'], ['diff', '--cached']];
+    for (const base of bases) {
+      const r = gitDiffNameStatus(repoRoot, base);
+      if (r.ok) return r;
+    }
+    return { files: [], deleted: [], ok: false };
+  };
+
+  const { files, deleted, failed } = getModifiedFiles(projectRoot, diffFn, { includeUntracked });
+  if (failed) {
+    process.stderr.write('collect failed: unable to determine changed files (git diff failed)\n');
+    process.exit(1);
+  }
+
+  const businessFiles = files.filter(isBusinessCode);
+  const excluded = files.filter(f => !isBusinessCode(f));
+
+  let hashedBusiness = null;
+  let unreadableFiles = null;
+  if (withHash) {
+    hashedBusiness = [];
+    unreadableFiles = [];
+    for (const rel of businessFiles) {
+      const content = readWorkingFile(path.join(projectRoot, rel));
+      if (content === null) {
+        unreadableFiles.push(rel);
+        continue;
+      }
+      const buf = normalizeEolLf(content);
+      hashedBusiness.push({
+        path: rel,
+        size: buf.length,
+        sha256: crypto.createHash('sha256').update(buf).digest('hex'),
+      });
+    }
+  }
+
+  const output = businessOnly
+    ? { businessFiles: withHash ? hashedBusiness : businessFiles, deletedFiles: deleted }
+    : {
+        allChangedFiles: files,
+        deletedFiles: deleted,
+        businessFiles: withHash ? hashedBusiness : businessFiles,
+        excluded,
+      };
+  if (withHash && unreadableFiles.length) output.unreadableFiles = unreadableFiles;
+
+  process.stdout.write(JSON.stringify(output, null, 2));
+}
+
+if (process.argv.includes('--collect')) {
+  runCollectMode();
+  process.exit(0);
+}
+
+module.exports = {
+  resolveSpecRoot,
+  discoverActiveChanges,
+  findReportJson,
+  parseReport,
+  validateReportFields,
+  parseCodeRepos,
+  gitDiffNameStatus,
+  getModifiedFiles,
+  isBusinessCode,
+  normalizeCoveredFiles,
+  getReportTime,
+  readWorkingFile,
+  gitShowHeadContentBatch,
+  isFileChangedOnDisk,
+  isReportStale,
+  generateInstructions,
+  loadBusinessCodeExts,
+  loadConsistencyMode,
+  runConsistencyCheck,
+  runFilterMode,
+  runCollectMode,
+  isTrivialDiffLine,
+  parseDiffForTrivialFiles,
+  getTrivialDiffFiles,
+};