release-prep — Release Preparation & Code Audit
Deep automated analysis of code quality, documentation completeness, and release readiness for Python packages. Can auto-fix issues found.
Modes
- -
audit (default) — analyze and report only fix — analyze, then auto-fix issues via coding agentrelease — full pipeline: audit → fix → changelog → version bump → tag → publish
Parse mode from user request. Default to audit if unclear.
Phase 1: Deep Code Audit
Run all checks, collect results into a structured report.
1.1 Test Suite
CODEBLOCK0
Report: total tests, passed, failed, skipped, coverage % (if pytest-cov available).
BLOCKER if any test fails.
1.2 Static Analysis
CODEBLOCK1
Report: error count by category. BLOCKER if errors > 0 (warnings are OK).
1.3 Dead Code Detection
CODEBLOCK2
Report: list of potentially dead code. WARNING level.
1.4 API Completeness
CODEBLOCK3
Report: functions missing from __all__. WARNING level.
1.5 Dependency Check
CODEBLOCK4
Report: dependency issues. WARNING level.
Phase 2: Documentation Audit
2.1 Docstring Coverage
CODEBLOCK5
WARNING if coverage < 80%. BLOCKER if < 50%.
2.2 README vs Reality
Check that README.md mentions:
- - All CLI entry points from pyproject.toml INLINECODE5
- Installation instructions
- Basic usage example
- All major features (compare against module-level docstrings)
CODEBLOCK6
WARNING if entry points missing from README.
2.3 Changelog Check
CODEBLOCK7
2.4 Version Consistency
CODEBLOCK8
BLOCKER if version mismatch.
Phase 3: Report
Generate structured report:
CODEBLOCK9
If mode is audit — stop here, present report to user.
Phase 4: Auto-Fix (mode=fix or mode=release)
For each issue found, categorize fix approach:
| Issue Type | Fix Method |
|---|
| Missing docstrings | Coding agent — generate from code |
| Lint errors |
ruff check --fix or coding agent |
| Dead imports |
ruff check --fix --select F401 |
| README gaps | Generate missing sections from code analysis |
| Changelog missing | Generate from
git log (conventional commits) |
| Version mismatch | Update code
__version__ to match pyproject.toml |
| Test failures | Coding agent — investigate and fix |
Rules:
- - Show user what will be fixed before doing it
- Delegate complex fixes (test failures, missing features) to coding agent
- Simple fixes (lint, imports, version sync) — do directly
- After fixes — re-run Phase 1+2 to verify
Phase 5: Changelog Generation (mode=release)
CODEBLOCK10
Group by conventional commit type (feat/fix/refactor/docs/test/chore). Generate markdown. Prepend to CHANGELOG.md.
Show draft to user before writing.
Phase 6: Version & Publish (mode=release)
- 1. Determine version bump (major/minor/patch) from changelog:
-
feat → minor,
fix → patch,
BREAKING CHANGE → major
- 2. Update version in
pyproject.toml and INLINECODE15 - Commit: INLINECODE16
- Tag: INLINECODE17
- Build:
uv build or INLINECODE19 - Ask user before publish: show summary + ask confirmation
- Publish:
uv publish or INLINECODE21 - Push tag: INLINECODE22
Project Detection
Auto-detect project type from files present:
- -
pyproject.toml → Python package (primary) - INLINECODE24 → Node.js (future)
- INLINECODE25 → Rust (future)
Read pyproject.toml for: name, version, entry points, dependencies, build system.
Error Handling
| Error | Action |
|---|
| No pyproject.toml | Stop — "Not a Python package. Looking for pyproject.toml" |
| No tests dir |
WARNING — "No tests found. Consider adding tests before release" |
| No git repo | Stop — "Not a git repository" |
| Dirty working tree | WARNING — "Uncommitted changes detected" |
| ruff/mypy not found | Skip that check, note in report |
release-prep — 发布准备与代码审计
对Python包进行代码质量、文档完整性和发布就绪状态的深度自动化分析。可自动修复发现的问题。
模式
- - audit（默认）— 仅分析和报告
- fix — 分析，然后通过编码代理自动修复问题
- release — 完整流水线：审计 → 修复 → 变更日志 → 版本号更新 → 打标签 → 发布
从用户请求中解析模式。如果不明确，默认为audit。
第一阶段：深度代码审计
运行所有检查，将结果收集到结构化报告中。
1.1 测试套件
bash
运行完整测试套件并生成覆盖率报告
python -m pytest tests/ -q --tb=short --co -q 2>/dev/null | tail -1 # 统计测试数量
python -m pytest tests/ -q --tb=short 2>&1 | tail -5 # 运行测试
报告：总测试数、通过数、失败数、跳过数、覆盖率百分比（如果pytest-cov可用）。
如果任何测试失败，则为阻塞项。
1.2 静态分析
bash
Ruff（如果可用）
ruff check src/ --statistics 2>&1 | tail -20
Mypy（如果可用）
mypy src/ --no-error-summary 2>&1 | grep error: | wc -l
报告：按类别统计的错误数量。如果错误数 > 0，则为阻塞项（警告可接受）。
1.3 死代码检测
bash
查找未使用的导入
ruff check src/ --select F401 2>&1
查找没有调用者的函数（启发式）
grep -rn ^def \|^async def src/ --include=*.py | while read line; do
func=$(echo $line | sed s/.
def \([a-zA-Z_]\).*/\1/)
if [ $func !=
init ] && [ $func !=
]; then
count=$(grep -rn $func src/ --include=*.py | grep -v ^def \|^async def | wc -l)
if [ $count -lt 2 ]; then
echo 可能未使用: $line
fi
fi
done
报告：潜在死代码列表。警告级别。
1.4 API完整性
bash
公共API（all导出）与实际公共函数对比
python3 -c
import ast, sys, pathlib
for f in pathlib.Path(src/).rglob(*.py):
tree = ast.parse(f.read_text())
all_list = [n.value.s for n in ast.walk(tree)
if isinstance(n, ast.Assign)
for t in n.targets if isinstance(t, ast.Name) and t.id ==
all
for elt in n.value.elts if isinstance(elt, ast.Constant)]
if all_list:
funcs = [n.name for n in ast.walk(tree)
if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))
and not n.name.startswith(_)]
missing = [f for f in funcs if f not in all_list]
if missing:
print(f{f}: 公共但不在
all中: {missing})
报告：all中缺失的函数。警告级别。
1.5 依赖检查
bash
检查固定版本与未固定版本依赖
grep -E dependencies|requires pyproject.toml | head -20
检查未使用的依赖（启发式）
for dep in $(python3 -c
import tomllib;
d=tomllib.load(open(pyproject.toml,rb));
print( .join(d.get(project,{}).get(dependencies,[])))
); do
pkg=$(echo $dep | sed s/[>=<].*//)
count=$(grep -rn import $pkg\|from $pkg src/ --include=*.py | wc -l)
if [ $count -eq 0 ]; then
echo 可能未使用的依赖: $dep
fi
done
报告：依赖问题。警告级别。
第二阶段：文档审计
2.1 文档字符串覆盖率
bash
python3 -c
import ast, pathlib
total = missing = 0
for f in pathlib.Path(src/).rglob(*.py):
tree = ast.parse(f.read_text())
for node in ast.walk(tree):
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
if not node.name.startswith(_) or node.name == init:
total += 1
if not ast.get_docstring(node):
missing += 1
print(f 缺失: {f}:{node.lineno} {node.name})
print(f\n文档字符串覆盖率: {(total-missing)/total*100:.0f}% ({total-missing}/{total}))
覆盖率 < 80% 时警告。覆盖率 < 50% 时阻塞。
2.2 README与实际对比
检查README.md是否包含：
- - pyproject.toml [project.scripts]中的所有CLI入口点
- 安装说明
- 基本使用示例
- 所有主要功能（与模块级文档字符串对比）
bash
提取入口点
python3 -c import tomllib; d=tomllib.load(open(pyproject.toml,rb)); [print(k) for k in d.get(project,{}).get(scripts,{}).keys()]
检查README是否提及它们
for ep in $(python3 -c import tomllib; d=tomllib.load(open(pyproject.toml,rb)); [print(k) for k in d.get(project,{}).get(scripts,{}).keys()]); do
grep -q $ep README.md && echo ✅ $ep 在README中 || echo ❌ $ep 不在README中
done
如果入口点缺失于README，则警告。
2.3 变更日志检查
bash
检查CHANGELOG.md是否存在并有近期条目
if [ -f CHANGELOG.md ]; then
head -20 CHANGELOG.md
echo 最后条目日期:
grep -oE [0-9]{4}-[0-9]{2}-[0-9]{2} CHANGELOG.md | head -1
else
echo ❌ 没有CHANGELOG.md
fi
2.4 版本一致性
bash
检查pyproject.toml中的版本与version是否匹配
PYPROJECT_VER=$(python3 -c import tomllib; print(tomllib.load(open(pyproject.toml,rb))[project][version]))
CODE_VER=$(grep -r
version src/ --include=*.py | head -1 | grep -oE [0-9]+\.[0-9]+\.[0-9]+)
echo pyproject.toml: $PYPROJECT_VER
echo 代码
version: $CODE_VER
if [ $PYPROJECT
VER != $CODEVER ]; then
echo ❌ 版本不匹配
fi
如果版本不匹配，则为阻塞项。
第三阶段：报告
生成结构化报告：
╔══════════════════════════════════════╗
║ 发布就绪状态报告 ║
╠══════════════════════════════════════╣
║ 包名: {name} v{version} ║
║ 分支: {branch} ║
║ 提交: {short_sha} ║
╠══════════════════════════════════════╣
║ 🔴 阻塞项: {count} ║
║ 🟡 警告: {count} ║
║ 🟢 通过: {count} ║
╠══════════════════════════════════════╣
║ 测试: {pass}/{total} ✅/❌ ║
║ 代码检查: {errors} 个错误 ║
║ 文档字符串: {pct}% 覆盖率 ║
║ README: {status} ║
║ 版本: {status} ║
║ 变更日志: {status} ║
╚════════════════
