dev-playbooks-cn 1.0.0

package/skills/devbooks-entropy-monitor/scripts/entropy-report.sh

@@ -0,0 +1,303 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================================================
+# entropy-report.sh
+# ============================================================================
+# Generates a human-readable markdown report from entropy metrics.
+#
+# Reference: "The Mythical Man-Month" Chapter 16 "No Silver Bullet" - Controlling complexity is key to software development
+# ============================================================================
+
+usage() {
+  cat <<'EOF' >&2
+usage: entropy-report.sh [--input <file>] [--output <file>] [--project-root <dir>] [--truth-root <dir>]
+
+Generates a markdown report from entropy metrics JSON.
+
+Options:
+  --input          Input metrics JSON file (default: latest in <truth-root>/_meta/entropy/)
+  --output         Output markdown file (default: <truth-root>/_meta/entropy/entropy-report-YYYY-MM-DD.md)
+  --project-root   Project root directory (default: pwd)
+  --truth-root     Truth root directory (default: specs)
+
+Examples:
+  entropy-report.sh
+  entropy-report.sh --input metrics-2024-01-15.json --output report.md
+EOF
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+project_root="${DEVBOOKS_PROJECT_ROOT:-$(pwd)}"
+truth_root="${DEVBOOKS_TRUTH_ROOT:-specs}"
+input_file=""
+output_file=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --input)
+      input_file="${2:-}"
+      shift 2
+      ;;
+    --output)
+      output_file="${2:-}"
+      shift 2
+      ;;
+    --project-root)
+      project_root="${2:-}"
+      shift 2
+      ;;
+    --truth-root)
+      truth_root="${2:-}"
+      shift 2
+      ;;
+    *)
+      usage
+      exit 2
+      ;;
+  esac
+done
+
+# Normalize paths
+project_root="${project_root%/}"
+truth_root="${truth_root%/}"
+
+if [[ "$truth_root" = /* ]]; then
+  truth_dir="$truth_root"
+else
+  truth_dir="${project_root}/${truth_root}"
+fi
+
+entropy_dir="${truth_dir}/_meta/entropy"
+
+# Find latest metrics file if not specified
+if [[ -z "$input_file" ]]; then
+  input_file=$(find "$entropy_dir" -name "metrics-*.json" -type f 2>/dev/null | sort -r | head -1)
+  if [[ -z "$input_file" ]]; then
+    echo "error: no metrics file found in ${entropy_dir}" >&2
+    echo "hint: run entropy-measure.sh first" >&2
+    exit 1
+  fi
+fi
+
+if [[ ! -f "$input_file" ]]; then
+  echo "error: input file not found: ${input_file}" >&2
+  exit 1
+fi
+
+# Set default output file
+if [[ -z "$output_file" ]]; then
+  output_file="${entropy_dir}/entropy-report-$(date +%Y-%m-%d).md"
+fi
+
+# Ensure output directory exists
+mkdir -p "$(dirname "$output_file")"
+
+echo "generating report from: ${input_file}"
+
+# ============================================================================
+# Extract metrics
+# ============================================================================
+
+timestamp=$(jq -r '.timestamp' "$input_file")
+project=$(jq -r '.project_root' "$input_file")
+days=$(jq -r '.analysis_period_days' "$input_file")
+
+# Structural metrics
+file_p95=$(jq -r '.metrics.structural.file_lines_p95 // "N/A"' "$input_file")
+file_mean=$(jq -r '.metrics.structural.file_lines_mean // "N/A"' "$input_file")
+complexity_mean=$(jq -r '.metrics.structural.complexity_mean // "N/A"' "$input_file")
+complexity_p95=$(jq -r '.metrics.structural.complexity_p95 // "N/A"' "$input_file")
+
+# Change metrics
+hotspot_count=$(jq -r '.metrics.change.hotspot_count // "N/A"' "$input_file")
+total_files=$(jq -r '.metrics.change.total_files // "N/A"' "$input_file")
+hotspot_ratio=$(jq -r '.metrics.change.hotspot_ratio // "N/A"' "$input_file")
+
+# Test metrics
+test_lines=$(jq -r '.metrics.test.test_lines // "N/A"' "$input_file")
+code_lines=$(jq -r '.metrics.test.code_lines // "N/A"' "$input_file")
+test_code_ratio=$(jq -r '.metrics.test.test_code_ratio // "N/A"' "$input_file")
+flaky_ratio=$(jq -r '.metrics.test.flaky_ratio // "N/A"' "$input_file")
+coverage=$(jq -r '.metrics.test.coverage // "N/A"' "$input_file")
+
+# Dependency metrics
+outdated=$(jq -r '.metrics.dependency.outdated // "N/A"' "$input_file")
+total_deps=$(jq -r '.metrics.dependency.total // "N/A"' "$input_file")
+outdated_ratio=$(jq -r '.metrics.dependency.outdated_ratio // "N/A"' "$input_file")
+vulnerabilities=$(jq -r '.metrics.dependency.vulnerabilities // "N/A"' "$input_file")
+
+# Thresholds
+t_file_p95=$(jq -r '.thresholds.structural.file_lines_p95 // 500' "$input_file")
+t_hotspot=$(jq -r '.thresholds.change.hotspot_ratio // 0.1' "$input_file")
+t_test_ratio=$(jq -r '.thresholds.test.test_code_ratio_min // 0.5' "$input_file")
+t_outdated=$(jq -r '.thresholds.dependency.outdated_ratio // 0.2' "$input_file")
+
+# Alerts
+alert_count=$(jq -r '.summary.total_alerts' "$input_file")
+healthy_count=$(jq -r '.summary.dimensions_healthy' "$input_file")
+
+# Health status helper
+health_status() {
+  local value="$1"
+  local threshold="$2"
+  local compare="${3:-lt}"  # lt = less than is healthy, gt = greater than is healthy
+
+  if [[ "$value" == "N/A" || "$value" == "null" ]]; then
+    echo "⚪"
+    return
+  fi
+
+  local result
+  if [[ "$compare" == "lt" ]]; then
+    result=$(echo "$value <= $threshold" | bc -l 2>/dev/null || echo 0)
+  else
+    result=$(echo "$value >= $threshold" | bc -l 2>/dev/null || echo 0)
+  fi
+
+  if [[ "$result" -eq 1 ]]; then
+    echo "🟢"
+  else
+    echo "🔴"
+  fi
+}
+
+# ============================================================================
+# Generate report
+# ============================================================================
+
+cat > "$output_file" << EOF
+# System Entropy Report
+
+> Generated: ${timestamp}
+> Project path: ${project}
+> Analysis period: ${days} days
+
+---
+
+## Overview
+
+| Dimension | Health Status | Key Metric |
+|-----------|---------------|------------|
+| Structural Entropy | $(health_status "$file_p95" "$t_file_p95" "lt") | File lines P95: ${file_p95} |
+| Change Entropy | $(health_status "$hotspot_ratio" "$t_hotspot" "lt") | Hotspot file ratio: ${hotspot_ratio} |
+| Test Entropy | $(health_status "$test_code_ratio" "$t_test_ratio" "gt") | Test/code ratio: ${test_code_ratio} |
+| Dependency Entropy | $(health_status "$outdated_ratio" "$t_outdated" "lt") | Outdated dependency ratio: ${outdated_ratio} |
+
+**Healthy dimensions**: ${healthy_count}/4 | **Alerts**: ${alert_count}
+
+---
+
+## A) Structural Entropy
+
+> Source: Static code analysis
+
+| Metric | Current Value | Threshold | Status |
+|--------|---------------|-----------|--------|
+| File lines P95 | ${file_p95} | < ${t_file_p95} | $(health_status "$file_p95" "$t_file_p95" "lt") |
+| File lines mean | ${file_mean} | - | ⚪ |
+| Cyclomatic complexity mean | ${complexity_mean} | < 10 | ⚪ |
+| Cyclomatic complexity P95 | ${complexity_p95} | < 20 | ⚪ |
+
+**Recommendation**: Focus on files above P95, consider splitting.
+
+---
+
+## B) Change Entropy
+
+> Source: Git history analysis (past ${days} days)
+
+| Metric | Current Value | Threshold | Status |
+|--------|---------------|-----------|--------|
+| Hotspot file count | ${hotspot_count} / ${total_files} | - | ⚪ |
+| Hotspot file ratio | ${hotspot_ratio} | < ${t_hotspot} | $(health_status "$hotspot_ratio" "$t_hotspot" "lt") |
+
+**Hotspot definition**: Files modified more than 5 times during the analysis period
+
+**Recommendation**: Frequently modified files may need refactoring or splitting.
+
+---
+
+## C) Test Entropy
+
+> Source: Test file statistics
+
+| Metric | Current Value | Threshold | Status |
+|--------|---------------|-----------|--------|
+| Test code lines | ${test_lines} | - | ⚪ |
+| Production code lines | ${code_lines} | - | ⚪ |
+| Test/code ratio | ${test_code_ratio} | > ${t_test_ratio} | $(health_status "$test_code_ratio" "$t_test_ratio" "gt") |
+| Flaky test ratio | ${flaky_ratio} | < 0.01 | ⚪ |
+| Code coverage | ${coverage} | > 0.7 | ⚪ |
+
+**Recommendation**: When test/code ratio is below 0.5, prioritize adding tests.
+
+---
+
+## D) Dependency Entropy
+
+> Source: Dependency analysis
+
+| Metric | Current Value | Threshold | Status |
+|--------|---------------|-----------|--------|
+| Outdated dependency count | ${outdated} / ${total_deps} | - | ⚪ |
+| Outdated dependency ratio | ${outdated_ratio} | < ${t_outdated} | $(health_status "$outdated_ratio" "$t_outdated" "lt") |
+| Security vulnerability count | ${vulnerabilities} | = 0 | $(health_status "$vulnerabilities" "0" "lt") |
+
+**Recommendation**: Regularly update dependencies, prioritize fixing security vulnerabilities.
+
+---
+
+## Alert Details
+
+EOF
+
+# Add alerts
+if [[ "$alert_count" -gt 0 ]]; then
+  jq -r '.alerts[] | "- **[\(.level | ascii_upcase)]** \(.dimension): \(.message)"' "$input_file" >> "$output_file"
+else
+  echo "No alerts" >> "$output_file"
+fi
+
+cat >> "$output_file" << EOF
+
+---
+
+## Trend Analysis
+
+> Trend charts can be generated after multiple data collections
+
+View historical data: \`${entropy_dir}/history.json\`
+
+---
+
+## Recommended Actions
+
+EOF
+
+# Generate recommendations based on alerts
+if [[ "$alert_count" -gt 0 ]]; then
+  echo "1. Address high-priority issues from the alerts above" >> "$output_file"
+  echo "2. Run \`change-check.sh\` to ensure change package completeness" >> "$output_file"
+  echo "3. Consider using \`devbooks-proposal-author\` to initiate refactoring proposal" >> "$output_file"
+else
+  echo "No urgent action needed currently, recommend regular monitoring of entropy metrics." >> "$output_file"
+fi
+
+cat >> "$output_file" << EOF
+
+---
+
+*Report automatically generated by entropy-report.sh*
+*Reference: "The Mythical Man-Month" Chapter 16 "No Silver Bullet"*
+EOF
+
+echo "ok: report generated: ${output_file}"

package/skills/devbooks-entropy-monitor/templates/thresholds.json

@@ -0,0 +1,99 @@
+{
+  "version": "1.0.0",
+  "description": "Entropy thresholds configuration for DevBooks entropy-monitor",
+  "last_updated": "YYYY-MM-DD",
+  "updated_by": "YOUR_NAME",
+
+  "structural": {
+    "_comment": "Static code complexity metrics",
+    "complexity_mean": {
+      "value": 10,
+      "description": "Average cyclomatic complexity per function",
+      "action": "Refactor complex functions into smaller units"
+    },
+    "complexity_p95": {
+      "value": 20,
+      "description": "95th percentile cyclomatic complexity",
+      "action": "Review and simplify extremely complex functions"
+    },
+    "file_lines_p95": {
+      "value": 500,
+      "description": "95th percentile file line count",
+      "action": "Split large files into focused modules"
+    },
+    "function_lines_p95": {
+      "value": 50,
+      "description": "95th percentile function line count",
+      "action": "Extract helper functions from long methods"
+    }
+  },
+
+  "change": {
+    "_comment": "Git history analysis metrics",
+    "hotspot_ratio": {
+      "value": 0.1,
+      "description": "Ratio of frequently-changed files (>5 changes in period)",
+      "action": "Investigate and refactor hotspot files"
+    },
+    "coupling_ratio": {
+      "value": 0.3,
+      "description": "Ratio of files that change together",
+      "action": "Review architectural boundaries"
+    },
+    "churn_ratio": {
+      "value": 0.5,
+      "description": "Ratio of code added then removed within period",
+      "action": "Improve upfront design and planning"
+    }
+  },
+
+  "test": {
+    "_comment": "Test quality metrics",
+    "flaky_ratio": {
+      "value": 0.01,
+      "description": "Ratio of tests with inconsistent results",
+      "action": "Fix or quarantine flaky tests immediately"
+    },
+    "coverage_min": {
+      "value": 0.7,
+      "description": "Minimum code coverage ratio",
+      "action": "Add tests for uncovered critical paths"
+    },
+    "test_code_ratio_min": {
+      "value": 0.5,
+      "description": "Minimum test lines / production lines ratio",
+      "action": "Increase test investment"
+    }
+  },
+
+  "dependency": {
+    "_comment": "External dependency health metrics",
+    "outdated_ratio": {
+      "value": 0.2,
+      "description": "Ratio of dependencies >2 major versions behind",
+      "action": "Schedule dependency update sprint"
+    },
+    "vulnerabilities": {
+      "value": 0,
+      "description": "Number of high/critical security vulnerabilities",
+      "action": "Fix security issues immediately"
+    },
+    "depth_p95": {
+      "value": 10,
+      "description": "95th percentile of transitive dependency depth",
+      "action": "Evaluate alternative lighter dependencies"
+    }
+  },
+
+  "alert_levels": {
+    "_comment": "When to escalate alerts",
+    "warning": {
+      "description": "Single threshold exceeded",
+      "action": "Document in next sprint planning"
+    },
+    "critical": {
+      "description": "Multiple thresholds exceeded or 2x single threshold",
+      "action": "Create immediate remediation proposal"
+    }
+  }
+}

package/skills/devbooks-federation/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: devbooks-federation
+description: devbooks-federation：跨仓库联邦分析与契约同步。当变更涉及对外 API/契约、或需要分析跨仓库影响时使用。用户说"跨仓库影响/联邦分析/契约同步/上下游依赖/多仓库"等时使用。
+tools:
+  - Glob
+  - Read
+  - Bash
+  - mcp__ckb__analyzeImpact
+  - mcp__ckb__findReferences
+  - mcp__github__search_code
+  - mcp__github__create_issue
+---
+
+# DevBooks：跨仓库联邦分析（Federation Analysis）
+
+## 触发条件
+
+以下任一条件满足时自动执行：
+1. 用户说"跨仓库影响/联邦分析/契约同步/上下游依赖/多仓库"
+2. `devbooks-impact-analysis` 检测到变更涉及 `federation.yaml` 中定义的契约文件
+3. 用户在 `proposal.md` 中标记了 `Impact: Cross-Repo`
+
+## 前置条件
+
+- 项目根目录存在 `.devbooks/federation.yaml` 或 `dev-playbooks/federation.yaml`
+- 如需跨仓库搜索，需要 GitHub MCP 已配置
+
+## 执行流程
+
+### Step 1: 加载联邦配置
+
+```bash
+# 检测联邦配置文件
+if [ -f ".devbooks/federation.yaml" ]; then
+  FEDERATION_CONFIG=".devbooks/federation.yaml"
+elif [ -f "dev-playbooks/federation.yaml" ]; then
+  FEDERATION_CONFIG="dev-playbooks/federation.yaml"
+else
+  echo "未找到联邦配置，请先创建 federation.yaml"
+  exit 1
+fi
+```
+
+读取配置后提取：
+- 上游依赖列表（我依赖谁）
+- 下游消费者列表（谁依赖我）
+- 契约文件列表
+
+### Step 2: 识别契约变更
+
+检查本次变更是否涉及契约文件：
+
+```
+变更文件 ∩ 契约文件 = 契约变更集
+```
+
+契约变更分类：
+- **Breaking**：删除/重命名导出、修改必填参数、改变返回类型
+- **Deprecation**：新增 `@deprecated` 注解
+- **Enhancement**：新增可选参数、新增导出
+- **Patch**：内部实现变更，不影响签名
+
+### Step 3: 跨仓库影响分析
+
+对于涉及契约变更的情况：
+
+1. **本地分析**（使用 CKB）
+   ```
+   mcp__ckb__findReferences(symbolId=<契约符号>)
+   mcp__ckb__analyzeImpact(symbolId=<契约符号>)
+   ```
+
+2. **远程搜索**（使用 GitHub MCP）
+   ```
+   mcp__github__search_code(query="<契约名> org:<org>")
+   ```
+
+3. **整合结果**
+   - 本仓库内引用
+   - 下游仓库引用（来自 GitHub 搜索）
+   - 潜在影响范围估算
+
+### Step 4: 生成联邦影响报告
+
+输出格式：
+
+```markdown
+# 跨仓库影响分析报告
+
+## 变更概要
+
+| 契约文件 | 变更类型 | 影响级别 |
+|---------|---------|---------|
+| `src/api/v1/user.ts` | Breaking | 🔴 Critical |
+| `src/types/order.ts` | Enhancement | 🟢 Safe |
+
+## 本仓库影响
+
+- 内部引用数：15
+- 受影响模块：`services/`, `handlers/`
+
+## 跨仓库影响
+
+### 下游消费者
+
+| 仓库 | 引用数 | 状态 |
+|-----|-------|------|
+| org/web-app | 8 | ⚠️ 需要同步 |
+| org/mobile-app | 3 | ⚠️ 需要同步 |
+
+### 建议动作
+
+1. [ ] 在 org/web-app 创建适配 Issue
+2. [ ] 在 org/mobile-app 创建适配 Issue
+3. [ ] 更新 CHANGELOG
+4. [ ] 发送 Slack 通知
+
+## 兼容性策略
+
+- [ ] 保持旧 API 可用（双写期）
+- [ ] 添加 `@deprecated` 注解
+- [ ] 设置移除日期：YYYY-MM-DD
+```
+
+### Step 5: 自动通知（可选）
+
+如果配置了 `notify_on_change: true`：
+
+1. 在下游仓库创建 Issue（使用 GitHub MCP）
+2. 发送 Slack 通知（需配置 webhook）
+
+Issue 模板：
+```markdown
+## 上游契约变更通知
+
+**来源仓库**：org/my-service
+**变更类型**：Breaking Change
+**预计移除日期**：YYYY-MM-DD
+
+### 受影响的契约
+
+- `UserService.getUser()` - 参数签名变更
+
+### 建议动作
+
+请在 [deadline] 前完成以下适配：
+1. 更新调用处以适配新签名
+2. 运行测试确保兼容
+
+### 相关链接
+
+- 变更 PR：org/my-service#123
+- 迁移指南：[链接]
+```
+
+## 脚本支持
+
+### 联邦检查脚本
+
+```bash
+# 检查联邦约束
+bash skills/devbooks-federation/scripts/federation-check.sh \
+  --project-root "$(pwd)" \
+  --change-files "src/api/v1/user.ts,src/types/order.ts"
+```
+
+### 契约同步脚本
+
+```bash
+# 生成下游通知
+bash skills/devbooks-federation/scripts/federation-notify.sh \
+  --project-root "$(pwd)" \
+  --change-type breaking \
+  --dry-run
+```
+
+## 与其他 Skills 的协作
+
+- `devbooks-impact-analysis`：检测到跨仓库影响时自动调用本 Skill
+- `devbooks-spec-contract`：契约定义变更时同步触发（合并了原 spec-delta + contract-data）
+- `devbooks-proposal-author`：在 proposal.md 中自动标记 Cross-Repo Impact
+
+## 注意事项
+
+1. 跨仓库搜索依赖 GitHub MCP，需要适当的访问权限
+2. 大型组织的搜索可能耗时较长，建议缩小搜索范围
+3. 联邦配置应与团队同步，确保上下游信息准确
+4. Breaking 变更建议使用语义版本控制（SemVer）
+
+## 参考
+
+- [API Versioning Best Practices](https://swagger.io/resources/articles/best-practices-in-api-versioning/)
+
+---
+
+## 上下文感知
+
+本 Skill 在执行前自动检测上下文，选择合适的分析范围。
+
+检测规则参考：`skills/_shared/context-detection-template.md`
+
+### 检测流程
+
+1. 检测 `federation.yaml` 是否存在
+2. 检测本次变更是否涉及契约文件
+3. 检测是否有跨仓库影响标记
+
+### 本 Skill 支持的模式
+
+| 模式 | 触发条件 | 行为 |
+|------|----------|------|
+| **本地分析** | 契约变更但无跨仓库配置 | 只分析本仓库内引用 |
+| **联邦分析** | federation.yaml 存在 | 分析上下游仓库影响 |
+| **通知模式** | 配置 notify_on_change=true | 自动创建下游 Issue |
+
+### 检测输出示例
+
+```
+检测结果：
+- federation.yaml：存在
+- 契约变更：2 个文件
+- 跨仓库标记：是
+- 运行模式：联邦分析
+```
+
+---
+
+## MCP 增强
+
+本 Skill 支持 MCP 运行时增强，自动检测并启用高级功能。
+
+MCP 增强规则参考：`skills/_shared/mcp-enhancement-template.md`
+
+### 依赖的 MCP 服务
+
+| 服务 | 用途 | 超时 |
+|------|------|------|
+| `mcp__ckb__analyzeImpact` | 符号级影响分析 | 2s |
+| `mcp__ckb__findReferences` | 本仓库引用查找 | 2s |
+| `mcp__github__search_code` | 跨仓库代码搜索 | 5s |
+| `mcp__github__create_issue` | 创建下游通知 Issue | 5s |
+
+### 检测流程
+
+1. 调用 `mcp__ckb__findReferences` 检测本仓库引用（2s 超时）
+2. 若需跨仓库分析 → 调用 `mcp__github__search_code`（5s 超时）
+3. 若 GitHub MCP 不可用 → 跳过跨仓库搜索，只输出本仓库分析
+
+### 增强模式 vs 基础模式
+
+| 功能 | 增强模式 | 基础模式 |
+|------|----------|----------|
+| 本仓库引用 | CKB 精确分析 | Grep 文本搜索 |
+| 跨仓库搜索 | GitHub API 搜索 | 不可用 |
+| 自动通知 | 创建下游 Issue | 手动通知 |
+
+### 降级提示
+
+当 MCP 不可用时，输出以下提示：
+
+```
+⚠️ GitHub MCP 不可用，无法进行跨仓库搜索。
+只能分析本仓库内的引用情况，跨仓库影响需手动确认。
+```