用途
Code Upkeep 用于对 Python 项目进行代码维护审计,主要覆盖两个方面:文档字符串(docstring)和测试覆盖率。它面向已修改的源文件,帮助发现文档缺失、文档过时以及测试缺口,并可直接应用修复。
主要能力
文档字符串审计
对每个目标文件中的公共类、方法和函数检查:
- 缺失 docstring:公共方法或函数完全没有 docstring。
- 过时 docstring:Args、Returns 或 Raises 部分与当前函数签名不匹配。
- 缺失 Pydantic 字段描述:公共模型中的 Field() 调用缺少 description=。
会跳过:私有方法(除非复杂)、双下划线方法、简单属性 getter、平凡的一行函数、测试函数。
测试覆盖率审计
将每个源文件映射到对应测试文件,检查:
- 缺失测试文件:完全不存在测试文件。
- 未测试的公共方法:源方法没有对应测试。
- 过时测试断言:测试引用了旧签名或已移除的参数。
- 过时 mock 夹具:mock 与当前配置或服务签名不匹配。
使用方式
第一步:确定目标文件
确定要审计的 .py 源文件:
- 如果用户指定了文件或目录,使用这些。
- 否则检查 git diff --name-only HEAD 和 git diff --name-only --cached,找出最近修改的 .py 文件。
- 文档字符串审计排除测试文件;测试审计包含源文件。
- 如果没有找到修改过的文件,询问用户要扫描哪个服务或目录。
第二步:确定范围
询问用户(或根据请求推断)要运行哪些阶段:
| 阶段 | 触发短语 |
|---|---|
| 文档字符串 | "update docstrings"、"add docstrings"、"fix docs" |
| 测试 | "update tests"、"add tests"、"check coverage" |
| 两者 | "code upkeep"、"bring up to date",或未具体提及 |
第三步:文档字符串审计(若在范围内)
阅读 python/code-upkeep/references/docstring-convention.md 中的 docstring 约定。然后按上述检查项逐文件审计。
第四步:测试覆盖率审计(若在范围内)
阅读 python/code-upkeep/references/test-patterns.md 中的测试模式。然后按上述检查项逐文件审计。
第五步:呈现发现
以报告形式列出文档字符串审计和测试覆盖率审计的结果,例如:
## Code Upkeep Report
### Docstring Audit
#### worker/services/book_api_client.py
- MISSING: `create_jwt_token()` — no docstring
- STALE: `store_chapters()` — Args section missing `chapter_data` param
- FIELD: `HarvestConfig.timeout` — Field() missing description
### Test Coverage Audit
#### worker/services/book_api_client.py
- NO TEST FILE: tests/test_book_api_client.py does not exist
- Public methods needing tests:
- `BookAPIClient.store_chapters()` — API call with retry
第六步:应用修复
- 文档字符串:使用 Edit 工具应用修复。只修改 docstring,绝不改动实现代码。
- 测试:按照 references/test-patterns.md 中的模式编写测试。生成后运行:
cd {service-directory} && poetry run pytest {test_file} -v
完成前修复任何失败。
规则
- 匹配本地风格:如果服务使用不同约定,遵循它。
- 只触碰 docstring:更新文档时绝不修改实现代码。
- 生成后运行测试:始终执行并修复失败。
- 不要过度 mock:直接测试纯逻辑,无需 mock。
- 测试行为而非实现:断言结果,而非调用次数。
- 每个测试一个断言焦点:每个测试验证一个逻辑行为。
- 使用真实测试数据:示例数据应类似真实负载。
- 检查 conftest.py:使用共享夹具而非重复。
适用场景
- 在提交或合并前更新最近修改的 Python 文件的文档字符串。
- 为新增或修改的公共方法补充测试。
- 检查测试文件是否因签名变更而过时。
- 审计 Pydantic 模型字段描述是否完整。
限制
- 仅针对 Python 代码。
- 只修改 docstring 和测试文件,不修改实现代码。
- 需要项目使用 poetry 运行 pytest(命令中指定)。
- 具体支持的 Python 版本、依赖要求、安装方式等暂未提供。