发布就绪检查器

在正式发布前运行一次全面的预发布审计。检查代码质量、文档完整性、依赖项状态、CI 构建状态以及常见发布阻碍项，并生成“可发布 / 不可发布”结论报告。

适用场景：当团队提出“我们是否已准备好发布？”、“预发布检查”、“发布审计”、“能否上线此版本？”、“发布核对清单”，或在打版本标签（tag）之前。

命令

1. check — 全量发布就绪审计

执行全部检查项，并输出最终“可发布 / 不可发布”判定结果。

检查 1：版本号已更新

# 检查当前版本
if [ -f "package.json" ]; then
  CURRENT=$(python3 -c "import json; print(json.load(open('package.json')).get('version','none'))" 2>/dev/null)
  echo "Current version: $CURRENT"

  # 与最新 Git tag 比较
  LATEST_TAG=$(git tag --sort=-version:refname 2>/dev/null | head -1)
  echo "Latest tag: ${LATEST_TAG:-none}"

  if [ "$CURRENT" = "${LATEST_TAG#v}" ] || [ "v$CURRENT" = "$LATEST_TAG" ]; then
    echo "⚠️  Version matches latest tag — did you forget to bump?"
  fi
fi

# 在其他文件中检查版本字段
for f in pyproject.toml Cargo.toml setup.py setup.cfg version.txt VERSION; do
  if [ -f "$f" ]; then
    grep -i "version" "$f" | head -3
  fi
done

检查 2：变更日志（Changelog）已更新

# 检查 CHANGELOG 文件是否存在，且包含近期条目
for f in CHANGELOG.md CHANGELOG CHANGES.md HISTORY.md; do
  if [ -f "$f" ]; then
    echo "Found: $f"
    # 检查顶部条目是否匹配当前版本或为 Unreleased
    head -20 "$f"

    # 检查 Unreleased 区域是否有内容
    UNRELEASED=$(sed -n '/[Unreleased]/,/[/p' "$f" 2>/dev/null | wc -l)
    if [ "$UNRELEASED" -le 2 ]; then
      echo "⚠️  Unreleased section appears empty"
    fi
    break
  fi
done

# 若未找到任何 changelog 文件
if [ ! -f "CHANGELOG.md" ] && [ ! -f "CHANGELOG" ] && [ ! -f "CHANGES.md" ]; then
  echo "⚠️  No CHANGELOG file found"
fi

检查 3：无调试代码残留

# 常见调试痕迹
echo "=== Debug Code Check ==="
rg -n "console.log|console.debug|console.warn|debugger;" 
  -g '!node_modules' -g '!vendor' -g '!dist' -g '!build' -g '!*.test.*' -g '!*.spec.*' 
  -g '*.{js,ts,jsx,tsx}' --stats 2>&1 | tail -5

rg -n "print(|breakpoint()|pdb.set_trace|import pdb|import ipdb" 
  -g '!vendor' -g '!dist' -g '*.py' -g '!*test*' --stats 2>&1 | tail -5

rg -n "fmt.Print|log.Print" 
  -g '*.go' -g '!*_test.go' --stats 2>&1 | tail -5

# 关键路径（非测试文件）中的 TODO/FIXME（不包括测试）
CRITICAL_TODOS=$(rg -c "TODO|FIXME|HACK|XXX" 
  -g '!node_modules' -g '!vendor' -g '!dist' -g '!*.test.*' -g '!*.spec.*' 
  --type-not binary 2>/dev/null | awk -F: '{s+=$2} END {print s+0}')
echo "TODO/FIXME count (non-test): $CRITICAL_TODOS"

检查 4：测试全部通过

echo "=== Test Check ==="
# 自动识别测试运行器
if [ -f "package.json" ]; then
  HAS_TEST=$(python3 -c "import json; d=json.load(open('package.json')); print('yes' if d.get('scripts',{}).get('test','') not in ['','echo "Error: no test specified" && exit 1'] else 'no')" 2>/dev/null)
  if [ "$HAS_TEST" = "yes" ]; then
    echo "Test command: npm test"
    echo "(Run 'npm test' to verify — not running automatically to avoid side effects)"
  else
    echo "⚠️  No test script configured in package.json"
  fi
fi

if [ -f "pytest.ini" ] || [ -f "setup.cfg" ] || [ -f "pyproject.toml" ]; then
  if python3 -c "import pytest" 2>/dev/null; then
    echo "Test runner: pytest detected"
  fi
fi

# 检查是否存在测试文件
TEST_COUNT=$(find . -type f ( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" -o -name "*_test.*" ) 
  -not -path '*/node_modules/*' -not -path '*/vendor/*' 2>/dev/null | wc -l)
echo "Test files found: $TEST_COUNT"
if [ "$TEST_COUNT" -eq 0 ]; then
  echo "❌ No test files found"
fi

检查 5：依赖项干净

echo "=== Dependency Check ==="
# 检查过时依赖（主版本）
if [ -f "package-lock.json" ] || [ -f "yarn.lock" ] || [ -f "pnpm-lock.yaml" ]; then
  npm outdated 2>/dev/null | head -15 || true

  # 检查已知漏洞
  npm audit --json 2>/dev/null | python3 -c "
import json, sys
try:
    d = json.load(sys.stdin)
    vulns = d.get('metadata', {}).get('vulnerabilities', {})
    crit = vulns.get('critical', 0)
    high = vulns.get('high', 0)
    if crit > 0: print(f'❌ {crit} critical vulnerabilities')
    elif high > 0: print(f'⚠️  {high} high vulnerabilities')
    else: print('✅ No critical/high vulnerabilities')
except: print('Could not parse npm audit output')
" 2>/dev/null
fi

# Lockfile 新鲜度检查
if [ -f "package-lock.json" ]; then
  LOCK_AGE=$(git log -1 --format="%ar" -- package-lock.json 2>/dev/null)
  echo "Lock file last updated: ${LOCK_AGE:-unknown}"
fi

检查 6：未提交敏感信息

echo "=== Secrets Check ==="
# 常见密钥模式匹配
rg -n "(PRIVATE_KEY|SECRET_KEY|API_KEY|ACCESS_TOKEN|passwords*=s*['"][^'"]+['"])" 
  -g '!node_modules' -g '!vendor' -g '!dist' -g '!*.lock' -g '!*.test.*' 
  --type-not binary -i 2>/dev/null | 
  grep -v "process.env|os.environ|os.getenv|.env|example|sample|template|test|mock|fake|dummy" | head -10

# 检查 .env 是否被 gitignore
if [ -f ".env" ]; then
  if git check-ignore .env >/dev/null 2>&1; then
    echo "✅ .env is gitignored"
  else
    echo "❌ .env is NOT gitignored — potential secret exposure"
  fi
fi

# 检查是否误提交了 .env 类文件
git ls-files '*.env' '.env*' 2>/dev/null | grep -v '.env.example|.env.sample|.env.template' | while read f; do
  echo "⚠️  Committed env file: $f"
done

检查 7：CI 状态正常

echo "=== CI Check ==="
# 检查 GitHub Actions 当前分支构建状态
BRANCH=$(git branch --show-current 2>/dev/null)
if command -v gh &>/dev/null; then
  gh run list --branch "$BRANCH" --limit 3 2>/dev/null || echo "Could not fetch CI status (gh not configured)"
else
  echo "gh CLI not available — check CI manually"
fi

# 检查 CI 配置文件是否存在
for f in .github/workflows/*.yml .github/workflows/*.yaml .gitlab-ci.yml Jenkinsfile .circleci/config.yml; do
  if ls $f 2>/dev/null | head -1 >/dev/null; then
    echo "CI config found: $f"
  fi
done 2>/dev/null

检查 8：文档保持最新

echo "=== Documentation Check ==="
# README 存在且内容充分
if [ -f "README.md" ]; then
  LINES=$(wc -l < README.md)
  echo "README.md: $LINES lines"
  if [ "$LINES" -lt 10 ]; then
    echo "⚠️  README.md seems sparse"
  fi
else
  echo "⚠️  No README.md found"
fi

# 如存在 API 文档目录或文件
for f in docs/ doc/ api-docs/ API.md; do
  if [ -e "$f" ]; then
    echo "Docs found: $f"
  fi
done

# 检查 README 是否引用了当前版本
if [ -f "README.md" ] && [ -n "$CURRENT" ]; then
  if grep -q "$CURRENT" README.md 2>/dev/null; then
    echo "✅ README references current version ($CURRENT)"
  fi
fi

检查 9：Git 工作区干净

echo "=== Git Status ==="
UNCOMMITTED=$(git status --porcelain 2>/dev/null | wc -l)
if [ "$UNCOMMITTED" -gt 0 ]; then
  echo "⚠️  $UNCOMMITTED uncommitted changes"
  git status --short 2>/dev/null | head -10
else
  echo "✅ Working tree clean"
fi

# 检查当前分支是否落后于远程
BRANCH=$(git branch --show-current 2>/dev/null)
AHEAD=$(git rev-list --count origin/$BRANCH..$BRANCH 2>/dev/null || echo "?")
BEHIND=$(git rev-list --count $BRANCH..origin/$BRANCH 2>/dev/null || echo "?")
echo "Branch: $BRANCH (ahead: $AHEAD, behind: $BEHIND)"
if [ "$BEHIND" != "0" ] && [ "$BEHIND" != "?" ]; then
  echo "⚠️  Branch is behind remote — pull before releasing"
fi

2. verdict — “可发布 / 不可发布”汇总结论

完成全部检查后，输出结构化判定结果：

# Release Readiness Report
Project: [name] | Version: [version] | Date: [date]

## Verdict: 🟢 GO / 🟡 CAUTION / 🔴 NO-GO

### Blockers (must fix before release)
- ❌ 3 critical vulnerabilities in dependencies
- ❌ .env file committed to repository

### Warnings (should fix, won't block)
- ⚠️  Version not bumped from last tag
- ⚠️  12 TODO/FIXME comments in source
- ⚠️  5 uncommitted changes

### Passing
- ✅ Changelog updated
- ✅ Tests exist (47 test files)
- ✅ No debug code detected
- ✅ README current (89 lines)
- ✅ CI config present

判定规则：

• NO-GO（不可发布）：存在任一高危漏洞、已提交敏感信息，或完全缺失测试
• CAUTION（需谨慎）：存在未提交变更、依赖项主版本过时、文档严重缺失、检测到调试代码
• GO（可发布）：所有检查均通过，或仅存在次要警告

3. checklist — 交互式核对清单

生成可用于人工复核的 Markdown 格式清单：

## Pre-Release Checklist

### Automated (run `check` to verify)
- [ ] Version bumped
- [ ] Changelog updated
- [ ] No debug code (console.log, debugger, etc.)
- [ ] Tests pass
- [ ] Dependencies clean (no critical vulns)
- [ ] No secrets committed
- [ ] CI green
- [ ] Docs updated
- [ ] Git status clean

### Manual Review
- [ ] Breaking changes documented
- [ ] Migration guide written (if needed)
- [ ] API deprecation notices sent
- [ ] Performance regression check
- [ ] Security review completed
- [ ] Stakeholders notified
- [ ] Release notes drafted
- [ ] Rollback plan documented

4. compare — 与上一发布版本对比

展示自上次打 tag 版本以来的全部变更：

LATEST_TAG=$(git tag --sort=-version:refname 2>/dev/null | head -1)
if [ -n "$LATEST_TAG" ]; then
  echo "Changes since $LATEST_TAG:"
  echo ""
  echo "=== Commits ==="
  git log "$LATEST_TAG"..HEAD --oneline 2>/dev/null | head -30

  echo ""
  echo "=== File Stats ==="
  git diff --stat "$LATEST_TAG"..HEAD 2>/dev/null | tail -5

  echo ""
  echo "=== New Files ==="
  git diff --name-only --diff-filter=A "$LATEST_TAG"..HEAD 2>/dev/null | head -20

  echo ""
  echo "=== Deleted Files ==="
  git diff --name-only --diff-filter=D "$LATEST_TAG"..HEAD 2>/dev/null | head -20

  echo ""
  echo "=== Contributors ==="
  git log "$LATEST_TAG"..HEAD --format="%an" 2>/dev/null | sort -u
fi

输出格式

• text（默认）：面向人类阅读，含状态图标
• json：机器可读格式：{version, verdict, blockers: [], warnings: [], passing: [], checks: {name: {status, details}}}
• markdown：适配 PR 或 Wiki 的报告格式，含表格与核对清单

CI 集成

退出码语义：

• 0：GO（所有检查通过）
• 1：NO-GO（存在阻断性问题）
• 2：CAUTION（仅有警告）

# 在失败时阻止发布
- name: Release readiness check
  run: |
    # Agent runs: release-readiness-checker check
    # Exits 1 if blockers found

# 作为 PR 评论发布报告
- name: Post readiness report
  run: |
    # Agent runs: release-readiness-checker verdict --format markdown > report.md
    gh pr comment $PR_NUMBER --body-file report.md

说明

• 不会自动运行测试（避免副作用）—— 仅报告测试基础设施是否存在，并建议手动执行
• 敏感信息检测基于正则模式匹配，可能存在误报（请人工复核所有标记项）
• 版本比对与分支状态检查依赖 Git 历史记录
• CI 状态检查需已安装并认证 gh CLI 工具
• 自动适配项目类型：通过配置文件识别 Node.js、Python、Go、Rust 等技术栈
• 支持自定义：添加 .release-readiness.json 可调整阈值（如最大允许 TODO 数量、必需文档项等）