CodeClone 2.0.0b1：基于基线的 Python 代码健康度分析
CodeClone 2.0.0b1 从简单的代码克隆检测工具，进化为 CI 流水线中 Python 项目结构健康度的监控系统。其核心聚焦于基线对比——精准区分历史技术债与新引入的退化问题。支持健康评分、无用代码检测及结构性发现，并通过确定性契约实现与流水线的无缝集成。
基线：CI 合约的基石
在 2.0 版本中，基线已发展为经过验证的项目状态快照。它将已知问题与近期变更区分开来，参与指标门禁控制，并在 CI 环境中表现稳定可靠。
关键原则：
- 基于信任语义的模式校验。
- 明确区分已知问题与新增问题（包括克隆、复杂度等指标）。
- 锁定当前状态作为基线，防止主分支引入新的退化。
这使得质量门禁得以实施，而不会因遗留债务阻塞整个项目。
健康评分：模块化的质量指标
新的健康评分整合了多项信号：
| 指标 | 说明 |
|--------------|--------------------------------------|
| 克隆 | 结构重复 |
| 复杂度 | 函数圈复杂度 |
| 耦合 | 模块间依赖程度 |
| 内聚 | 模块内部一致性 |
| 无用代码 | 未使用的代码 |
| 依赖 | 依赖循环 |
| 覆盖率 | 测试覆盖率 |
评分可细化至细节：生产代码与测试代码的贡献占比，以及高风险区域。HTML 报告包含仪表盘、关键绩效卡片和雷达图，便于快速洞察。
无需启发式规则的无用代码检测
无用代码检测器充分考虑 Python 特有的模式：框架钩子、反射机制、插件加载逻辑。不再依赖隐式排除规则，而是采用内联抑制方式：
# codeclone: ignore[dead-code]
def handle_exception(exc: Exception) -> None:
...或
class Middleware: # codeclone: ignore[dead-code]
...抑制规则仅在局部生效，不影响其他分析。相关元素仍会出现在报告中，但不计入健康评分。
超越克隆的结构性发现
新增一层用于捕捉早期架构信号：
duplicated_branches—— 重复的控制流分支。clone_guard_exit_divergence—— 克隆代码块退出点的差异。clone_cohort_drift—— 相似结构家族间的漂移现象。
核心生成标准 JSON 格式的事实数据；前端界面直接可视化，无需额外渲染。
统一来源的报告输出
所有输出均为标准 JSON 的投影：
- HTML 格式：含概览、管理层摘要与源码拆解。
- JSON 格式：供自动化脚本调用。
- 文本/Markdown 格式：用于日志记录。
- SARIF 格式：包含 baselineState、%SRCROOT% 及 IDE/代码扫描工具兼容的元数据。
通过稳定排序与负载标准化，确保结果的确定性。
更低阈值与性能优化
为扩大覆盖范围，阈值已放宽：
--min-loc（函数最小行数）：从 15 降至 10。- 块/段落门禁设置更宽松。
代价是分析量增加，但通过缓存与报告契约的优化予以补偿。
底层契约保障稳定性
严格规范设计：
- 基线契约：模式 + 语义定义。
- 缓存契约：行为可预测。
- 报告契约：格式一致。
- CLI 退出码：语义清晰明确。
有效减少因隐藏变更导致的流水线失败。
核心价值
- 基线实现技术债与退化问题的隔离，真正支撑现实场景的 CI 门禁。
- 健康评分精细颗粒度，重点评估生产代码质量。
- 内联抑制保持无用代码分析的透明性。
- 结构性发现可在克隆形成前及时预警。
- 支持 SARIF 格式，轻松对接 GitHub Actions、Azure DevOps 等平台。
— Editorial Team
暂无评论。