kld-sdd 2.6.15 → 2.6.17

package/templates/git-hooks/commit-msg

@@ -0,0 +1,46 @@
+#!/bin/sh
+# KLD SDD Commit-MSG Hook
+# 自动查找 commit-msg-sdd-trailer.cjs，兼容单仓库/多仓库/单仓mono布局
+# marker: KLD SDD quality gate
+
+# 从 hook 所在目录推算 git 根目录
+hook_dir="$(cd "$(dirname "$0")" && pwd)"
+git_dir="$(dirname "$hook_dir")"
+git_root="$(dirname "$git_dir")"
+
+script=""
+
+# 方法1: git config sdd.specPath（多仓布局：spec 是独立 clone）
+spec_path=$(git config --local sdd.specPath 2>/dev/null)
+if [ -n "$spec_path" ] && [ -f "$spec_path/skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs" ]; then
+  script="$spec_path/skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs"
+fi
+
+# 方法2: .sdd-spec-root（单仓 mono 布局：skywalk-sdd 在 spec 包裹包子目录内）
+if [ -z "$script" ] && [ -f "$git_root/.sdd-spec-root" ]; then
+  spec_rel=$(cat "$git_root/.sdd-spec-root" | head -1 | tr -d '[:space:]')
+  if [ -n "$spec_rel" ] && [ -f "$git_root/$spec_rel/skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs" ]; then
+    script="$git_root/$spec_rel/skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs"
+  fi
+fi
+
+# 方法3: 从 git 根向上搜索 skywalk-sdd/git-hooks（spec 仓本身或父级）
+if [ -z "$script" ]; then
+  search_dir="$git_root"
+  while [ "$search_dir" != "/" ] && [ "$search_dir" != "" ]; do
+    if [ -f "$search_dir/skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs" ]; then
+      script="$search_dir/skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs"
+      break
+    fi
+    search_dir="$(dirname "$search_dir")"
+  done
+fi
+
+if [ -z "$script" ]; then
+  echo "[SDD] 未找到 commit-msg-sdd-trailer.cjs，跳过 commit-msg trailer"
+  exit 0
+fi
+
+# $1 = Git 传入的 commit message 文件路径
+# --project 告诉 .cjs 脚本代码仓根目录（用于解析 spec 布局）
+node "$script" "$1" --project="$git_root"

package/templates/git-hooks/pre-commit

@@ -0,0 +1,57 @@
+#!/bin/sh
+# KLD SDD Pre-Commit Hook
+# 远程引用 spec 仓 skywalk-sdd/git-hooks/ 下的 .cjs 脚本
+# 兼容单仓库/多仓库/单仓mono布局
+# marker: KLD SDD quality gate
+
+# 从 hook 所在目录推算 git 根目录
+hook_dir="$(cd "$(dirname "$0")" && pwd)"
+git_dir="$(dirname "$hook_dir")"
+git_root="$(dirname "$git_dir")"
+
+hooks_dir=""
+
+# 方法1: git config sdd.specPath（多仓布局：spec 是独立 clone）
+spec_path=$(git config --local sdd.specPath 2>/dev/null)
+if [ -n "$spec_path" ] && [ -d "$spec_path/skywalk-sdd/git-hooks" ]; then
+  hooks_dir="$spec_path/skywalk-sdd/git-hooks"
+fi
+
+# 方法2: .sdd-spec-root（单仓 mono 布局：skywalk-sdd 在 spec 包裹包子目录内）
+if [ -z "$hooks_dir" ] && [ -f "$git_root/.sdd-spec-root" ]; then
+  spec_rel=$(cat "$git_root/.sdd-spec-root" | head -1 | tr -d '[:space:]')
+  if [ -n "$spec_rel" ] && [ -d "$git_root/$spec_rel/skywalk-sdd/git-hooks" ]; then
+    hooks_dir="$git_root/$spec_rel/skywalk-sdd/git-hooks"
+  fi
+fi
+
+# 方法3: 从 git 根向上搜索 skywalk-sdd/git-hooks（spec 仓本身或父级）
+if [ -z "$hooks_dir" ]; then
+  search_dir="$git_root"
+  while [ "$search_dir" != "/" ] && [ "$search_dir" != "" ]; do
+    if [ -d "$search_dir/skywalk-sdd/git-hooks" ]; then
+      hooks_dir="$search_dir/skywalk-sdd/git-hooks"
+      break
+    fi
+    search_dir="$(dirname "$search_dir")"
+  done
+fi
+
+if [ -z "$hooks_dir" ]; then
+  echo "[SDD] 未找到 spec 仓的 skywalk-sdd/git-hooks 目录，跳过 pre-commit 检查"
+  exit 0
+fi
+
+echo "[SDD] 执行提交前检查..."
+
+# 1. tasks.md 完成度检查
+if [ -f "$hooks_dir/pre-commit-sdd-check.cjs" ]; then
+  node "$hooks_dir/pre-commit-sdd-check.cjs" --project="$git_root" "$@" || exit 1
+fi
+
+# 2. 代码-spec 一致性检查
+if [ -f "$hooks_dir/pre-commit-consistency-check.cjs" ]; then
+  node "$hooks_dir/pre-commit-consistency-check.cjs" --project="$git_root" "$@" || exit 1
+fi
+
+echo "[SDD] ✅ 所有 pre-commit 检查通过"

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

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+/**
+ * pre-commit-consistency-check.cjs
+ *
+ * Pre-commit 门禁：检查活跃变更的 Spec 一致性校验报告。
+ * 若 confidence=low 则阻止提交；缺少报告则警告但放行（向后兼容）。
+ *
+ * 用法: node pre-commit-consistency-check.cjs --project=<project-root> [--change=<change-name>]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function readArg(name) {
+  const prefix = `--${name}=`;
+  const found = process.argv.find(arg => arg.startsWith(prefix));
+  return found ? found.slice(prefix.length) : '';
+}
+
+function hasFlag(name) {
+  return process.argv.includes(`--${name}`);
+}
+
+/**
+ * 从 .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;
+      }
+    }
+  }
+
+  // 3. 项目根本身就是 spec 仓
+  if (fs.existsSync(path.join(projectRoot, 'openspec', 'changes'))) {
+    return projectRoot;
+  }
+
+  return null;
+}
+
+/**
+ * 发现活跃变更列表
+ */
+function discoverActiveChanges(specRoot, explicitChange) {
+  if (explicitChange) {
+    return [explicitChange];
+  }
+
+  const changesDir = path.join(specRoot, 'openspec', 'changes');
+  if (!fs.existsSync(changesDir)) {
+    return [];
+  }
+
+  return fs.readdirSync(changesDir)
+    .filter(name => {
+      const fullPath = path.join(changesDir, name);
+      return fs.statSync(fullPath).isDirectory()
+        && !name.startsWith('.')
+        && name !== 'archive';
+    });
+}
+
+/**
+ * 查找变更的一致性报告 JSON
+ */
+function findConsistencyReport(specRoot, changeName) {
+  const patterns = [
+    '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 null;
+}
+
+/**
+ * 解析一致性报告，返回置信度
+ */
+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 };
+  }
+}
+
+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 changes = discoverActiveChanges(specRoot, explicitChange);
+  if (changes.length === 0) {
+    console.log('SDD consistency-check: 无活跃变更，跳过一致性校验');
+    return;
+  }
+
+  const blockers = [];
+  const missing = [];
+  const passed = [];
+
+  for (const changeName of changes) {
+    const reportPath = findConsistencyReport(specRoot, changeName);
+    if (!reportPath) {
+      missing.push(changeName);
+      continue;
+    }
+
+    const report = parseReport(reportPath);
+    if (report.parseError) {
+      console.warn(`SDD consistency-check: ⚠️  ${changeName} 报告解析失败: ${report.parseError}`);
+      missing.push(changeName);
+      continue;
+    }
+
+    if (report.confidence === 'low' || report.overallResult === 'fail') {
+      blockers.push({ changeName, report });
+    } else {
+      passed.push({ changeName, report });
+    }
+  }
+
+  // 输出摘要
+  if (passed.length > 0) {
+    for (const item of passed) {
+      console.log(`SDD consistency-check: ✅ ${item.changeName} 置信度=${item.report.confidence}`);
+    }
+  }
+
+  if (missing.length > 0) {
+    console.warn(`SDD consistency-check: ⚠️  以下变更缺少一致性校验报告（允许提交，建议执行 opsx-consistency-check）:`);
+    for (const name of missing) {
+      console.warn(`  - ${name}`);
+    }
+  }
+
+  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}`);
+    }
+    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);
+  }
+}
+
+main();

package/templates/git-hooks/pre-push

@@ -0,0 +1,57 @@
+#!/bin/sh
+# KLD SDD Pre-Push Hook
+# 远程引用 spec 仓 skywalk-sdd/git-hooks/ 下的 .cjs 脚本
+# 兼容单仓库/多仓库/单仓mono布局
+# marker: KLD SDD quality gate
+
+# 从 hook 所在目录推算 git 根目录
+hook_dir="$(cd "$(dirname "$0")" && pwd)"
+git_dir="$(dirname "$hook_dir")"
+git_root="$(dirname "$git_dir")"
+
+hooks_dir=""
+
+# 方法1: git config sdd.specPath（多仓布局：spec 是独立 clone）
+spec_path=$(git config --local sdd.specPath 2>/dev/null)
+if [ -n "$spec_path" ] && [ -d "$spec_path/skywalk-sdd/git-hooks" ]; then
+  hooks_dir="$spec_path/skywalk-sdd/git-hooks"
+fi
+
+# 方法2: .sdd-spec-root（单仓 mono 布局：skywalk-sdd 在 spec 包裹包子目录内）
+if [ -z "$hooks_dir" ] && [ -f "$git_root/.sdd-spec-root" ]; then
+  spec_rel=$(cat "$git_root/.sdd-spec-root" | head -1 | tr -d '[:space:]')
+  if [ -n "$spec_rel" ] && [ -d "$git_root/$spec_rel/skywalk-sdd/git-hooks" ]; then
+    hooks_dir="$git_root/$spec_rel/skywalk-sdd/git-hooks"
+  fi
+fi
+
+# 方法3: 从 git 根向上搜索 skywalk-sdd/git-hooks（spec 仓本身或父级）
+if [ -z "$hooks_dir" ]; then
+  search_dir="$git_root"
+  while [ "$search_dir" != "/" ] && [ "$search_dir" != "" ]; do
+    if [ -d "$search_dir/skywalk-sdd/git-hooks" ]; then
+      hooks_dir="$search_dir/skywalk-sdd/git-hooks"
+      break
+    fi
+    search_dir="$(dirname "$search_dir")"
+  done
+fi
+
+if [ -z "$hooks_dir" ]; then
+  echo "[SDD] 未找到 spec 仓的 skywalk-sdd/git-hooks 目录，跳过 pre-push 检查"
+  exit 0
+fi
+
+echo "[SDD] 执行推送前检查..."
+
+# 1. doctor 质量门禁检查
+if [ -f "$hooks_dir/pre-push-sdd-check.cjs" ]; then
+  node "$hooks_dir/pre-push-sdd-check.cjs" --project="$git_root" "$@" || exit 1
+fi
+
+# 2. 代码-spec 一致性检查（推送前更严格）
+if [ -f "$hooks_dir/pre-push-consistency-check.cjs" ]; then
+  node "$hooks_dir/pre-push-consistency-check.cjs" --project="$git_root" "$@" || exit 1
+fi
+
+echo "[SDD] ✅ 所有 pre-push 检查通过"

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

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * pre-push-consistency-check.cjs
+ *
+ * Pre-push 门禁：检查活跃变更的 Spec 一致性校验报告。
+ * 与 pre-commit-consistency-check.cjs 类似，但更严格：
+ *   - confidence=low → 阻止推送
+ *   - 缺少报告 → 警告（默认放行）；strict 模式下阻止推送
+ *
+ * 用法: node pre-push-consistency-check.cjs --project=<project-root> [--change=<change-name>]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function readArg(name) {
+  const prefix = `--${name}=`;
+  const found = process.argv.find(arg => arg.startsWith(prefix));
+  return found ? found.slice(prefix.length) : '';
+}
+
+function hasFlag(name) {
+  return process.argv.includes(`--${name}`);
+}
+
+/**
+ * 从 .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;
+      }
+    }
+  }
+
+  // 3. 项目根本身就是 spec 仓
+  if (fs.existsSync(path.join(projectRoot, 'openspec', 'changes'))) {
+    return projectRoot;
+  }
+
+  return null;
+}
+
+/**
+ * 发现活跃变更列表
+ */
+function discoverActiveChanges(specRoot, explicitChange) {
+  if (explicitChange) {
+    return [explicitChange];
+  }
+
+  const changesDir = path.join(specRoot, 'openspec', 'changes');
+  if (!fs.existsSync(changesDir)) {
+    return [];
+  }
+
+  return fs.readdirSync(changesDir)
+    .filter(name => {
+      const fullPath = path.join(changesDir, name);
+      return fs.statSync(fullPath).isDirectory()
+        && !name.startsWith('.')
+        && name !== 'archive';
+    });
+}
+
+/**
+ * 查找变更的一致性报告 JSON
+ */
+function findConsistencyReport(specRoot, changeName) {
+  const patterns = [
+    '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 null;
+}
+
+/**
+ * 解析一致性报告，返回置信度
+ */
+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 };
+  }
+}
+
+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 looseMode = hasFlag('no-strict') || process.env.SDD_LOOSE_CONSISTENCY === '1';
+
+  const specRoot = resolveSpecRoot(projectRoot);
+  if (!specRoot) {
+    console.log('SDD consistency-check (pre-push): 未找到 spec 仓库，跳过一致性校验');
+    return;
+  }
+
+  const changes = discoverActiveChanges(specRoot, explicitChange);
+  if (changes.length === 0) {
+    console.log('SDD consistency-check (pre-push): 无活跃变更，跳过一致性校验');
+    return;
+  }
+
+  const blockers = [];
+  const missing = [];
+  const passed = [];
+
+  for (const changeName of changes) {
+    const reportPath = findConsistencyReport(specRoot, changeName);
+    if (!reportPath) {
+      missing.push(changeName);
+      continue;
+    }
+
+    const report = parseReport(reportPath);
+    if (report.parseError) {
+      console.warn(`SDD consistency-check (pre-push): ⚠️  ${changeName} 报告解析失败: ${report.parseError}`);
+      missing.push(changeName);
+      continue;
+    }
+
+    if (report.confidence === 'low' || report.overallResult === 'fail') {
+      blockers.push({ changeName, report });
+    } else {
+      passed.push({ changeName, report });
+    }
+  }
+
+  // 输出摘要
+  if (passed.length > 0) {
+    for (const item of passed) {
+      console.log(`SDD consistency-check (pre-push): ✅ ${item.changeName} 置信度=${item.report.confidence}`);
+    }
+  }
+
+  if (missing.length > 0) {
+    console.warn(`SDD consistency-check (pre-push): ⚠️  以下变更缺少一致性校验报告:`);
+    for (const name of missing) {
+      console.warn(`  - ${name}`);
+    }
+    if (strictMode && !looseMode) {
+      console.error('SDD consistency-check (pre-push): ❌ strict 模式已启用，缺少报告的变更不允许推送。');
+      console.error('请先执行 opsx-consistency-check 生成报告，或使用 --no-verify 跳过（不推荐）。');
+      process.exit(1);
+    }
+    console.warn('  → 推送已放行，建议尽快执行 opsx-consistency-check');
+  }
+
+  if (blockers.length > 0) {
+    console.error(`SDD consistency-check (pre-push): ❌ 以下变更的一致性校验未通过（confidence=low），阻止推送:`);
+    for (const item of blockers) {
+      console.error(`  - ${item.changeName} (confidence=${item.report.confidence}, result=${item.report.overallResult})`);
+      console.error(`    报告路径: ${item.report.reportPath}`);
+    }
+    console.error('');
+    console.error('请修复不一致项后重新执行 opsx-consistency-check，或使用 --no-verify 跳过（不推荐）。');
+    process.exit(1);
+  }
+}
+
+main();