simplify-codebase：用数学证明的方式安全消除代码库中的意外复杂度
> simplify-codebase 是一个通过形式化验证安全删除代码库中意外复杂度的开源工具。
## 引言：当“重构”变成一场赌局
在软件工程领域，有一个被反复提及但很少被认真对待的痛点：**代码库的复杂度是累积的，而清理复杂度是危险的**。
每个经历过大型项目的人都有过这样的体验：看到一个长达 300 行的函数，直觉告诉你其中 80% 是死代码或冗余逻辑，但你不敢删——因为你不确定删除后会不会破坏某个隐藏的边界条件。于是你选择保留，并在旁边加一行注释“此处逻辑复杂，请谨慎修改”。几年后，这个函数变成了 500 行，注释变成了 5 条，而真正被执行的代码可能只有 20 行。
传统的解决方案是：写单元测试、做代码评审、用覆盖率工具。但这些都是**概率性**的保障——测试覆盖不到的分支、评审没注意到的隐式依赖、覆盖率报告中的绿色区域，都可能隐藏着破坏性变更。
simplify-codebase 试图用另一种思路解决这个问题：**不依赖测试或人工判断，而是通过形式化方法（formal methods）证明某段代码是“行为无关”的，从而可以安全删除**。
## 项目定位：不是重构工具，而是“代码复杂度证明器”
项目名 simplify-codebase 很容易让人联想到自动重构工具（如 ESLint 的 no-unused-vars 或 IDE 的“安全删除”功能）。但它的核心机制完全不同：
- **传统重构工具**：基于语法分析或静态分析，判断“这段代码有没有被引用”。
- **simplify-codebase**：基于行为等价性（behavioral equivalence）证明，判断“删除这段代码后，程序的可观测行为是否完全不变”。
换句话说，它回答的不是“这段代码有没有人用”，而是“这段代码的存在是否影响了任何输入下的输出”。后者是更强的保证，也是它被称为“prove”的原因。
## 解决的核心痛点
### 1. 死代码的“隐性”问题
传统死代码检测只能发现完全不可达的代码（例如 `if (false)` 分支）。但现实中更常见的是“条件性死代码”——某个分支在特定输入组合下永远不会执行，但静态分析无法证明这一点。
simplify-codebase 通过符号执行和约束求解，可以证明某个分支在所有可能的合法输入下都不会被执行，从而安全删除。
### 2. 冗余逻辑的“行为等价”判断
例如，以下代码：
javascript
function process(items) {
let result = [];
for (let i = 0; i < items.length; i++) {
if (items[i] !== null) {
result.push(items[i]);
}
}
return result;
}
如果调用方保证 `items` 中永远没有 `null`，那么 `if (items[i] !== null)` 就是冗余的。但静态分析无法知道调用方的保证，而 simplify-codebase 可以通过分析调用点或注解来证明这一点。
### 3. 重构时的“恐惧心理”
大多数开发者不敢删除看似无用的代码，是因为缺乏**行为不变性**的保证。simplify-codebase 给出的证明结果可以直接作为代码评审的依据，让删除操作变得有据可依。
## 安装与使用
### 安装
项目目前主要支持 JavaScript/TypeScript（基于 Babel 和 Z3 求解器）。安装非常简单：
bash
npm install -g simplify-codebase
或者作为项目依赖：
bash
npm install --save-dev simplify-codebase
### 基本用法
假设你有以下文件 `example.js`：
javascript
function add(a, b) {
let temp = a + b; // 疑似冗余变量
return temp;
}
function unusedHelper(x) {
return x * 2;
}
function main() {
console.log(add(2, 3));
}
运行：
bash
simplify-codebase check example.js
输出示例：
[PROVEN] 第3行: 变量 'temp' 可安全内联删除（行为等价）
[PROVEN] 第6-7行: 函数 'unusedHelper' 可安全删除（无副作用且无调用）
[UNPROVEN] 第10行: 函数 'main' 中的 console.log 保留（外部副作用不可证明）
### 高级用法：带约束的证明
你可以通过 JSDoc 或单独配置文件声明前置条件，增强证明能力：
javascript
/**
* @requires items.length > 0
*/
function firstItem(items) {
return items[0];
}
然后运行：
bash
simplify-codebase check --with-constraints example.js
工具会利用 `@requires` 约束来证明 `items[0]` 不会越界，从而可能删除某些防御性检查。
### 批量清理模式
bash
simplify-codebase apply --dry-run src/
`--dry-run` 会生成一份将要删除代码的详细报告，确认后去掉该标志即可自动修改文件。
## 核心亮点深度解析
### 1. 基于 SMT 求解器的行为等价证明
这是项目的技术核心。simplify-codebase 将代码转换为 SMT-LIB 格式的约束，然后使用 Z3 求解器检查两个版本的程序（原始版本和删除候选代码后的版本）在任意输入下是否产生相同的输出。
这比传统的“数据流分析”强得多。数据流分析只能处理简单的可达性，而 SMT 求解可以处理复杂的算术、字符串操作和数据结构。
### 2. 支持增量证明和模块化分析
对于大型代码库，全量证明会非常慢。simplify-codebase 支持模块级分析——它允许你指定“证明边界”，在边界内进行局部证明，而将外部依赖视为黑盒。这大大提高了实用性。
### 3. 与 CI/CD 集成
项目提供了 GitHub Action，可以在每次 PR 时自动运行：
yaml
- uses: tt-a1i/simplify-codebase@v1
with:
path: './src'
threshold: 'high' # 只报告高置信度证明结果
### 4. 可解释的证明输出
每个“可删除”结论都会附上证明摘要，例如：
[PROVEN] 删除第15行条件检查
证明: 在约束 (x > 0) 下，条件 (x < 0) 恒为假
依据: 第12行 @requires 注解 + 算术公理
这让开发者可以理解证明的逻辑，而不是盲目信任工具。
## 适用场景
### 最佳场景：长期维护的中大型项目
- **遗留代码清理**：接手一个 5 年以上的项目，有大量无人敢动的“历史遗留”代码。
- **技术债偿还**：在季度重构中，需要安全地删除冗余逻辑而不引入回归。
- **代码库瘦身**：在准备开源或出售代码库前，需要去除内部冗余。
### 次佳场景：有严格质量要求的团队
- 金融、医疗等需要高可靠性的领域，任何删除操作都需要形式化保证。
- 团队中“代码洁癖”与“保守派”争论不休时，用工具结论作为仲裁。
### 不适合的场景
- **快速原型开发**：证明过程需要额外时间，不适合追求速度的 hackathon。
- **高度动态的语言特性**（如 eval、动态属性访问）：证明器可能无法处理。
- **缺乏类型信息的纯 JavaScript**：效果会打折扣，建议配合 TypeScript 使用。
## 与其他工具对比
| 工具/方法 | 原理 | 保证强度 | 适用语言 | 误报率 |
|-----------|------|----------|----------|--------|
| ESLint (no-unused-vars) | 语法分析 | 弱（仅静态引用） | JS/TS | 高（有误报） |
| ts-prune | TypeScript AST | 弱 | TS | 中 |
| knip | 文件级依赖分析 | 弱 | JS/TS | 中 |
| **simplify-codebase** | **SMT求解+行为等价** | **强（形式化证明）** | **JS/TS（计划扩展）** | **极低（可解释）** |
| 人工代码评审 | 经验 | 不确定 | 所有 | 高 |
### 独特优势
- **不是“建议”，而是“证明”**：工具输出的是“可删除”的数学证明，而非“可能未使用”的猜测。
- **处理条件性死代码**：这是其他工具完全无法做到的。
- **可解释性**：每个结论都有推理链，可以嵌入到代码评审记录中。
### 当前局限
- 只支持 JavaScript/TypeScript（Python 版本在 roadmap 中）
- 对递归和复杂循环的证明效率较低
- 需要开发者提供必要的约束注解才能发挥最大效果
## 实际案例：一个真实的简化过程
假设你有如下 React 组件：
jsx
function UserList({ users }) {
const filtered = users.filter(u => u.active);
const sorted = [...filtered].sort((a, b) => a.age - b.age);
const display = sorted.map(u => u.name);
// 以下三行看起来是冗余的
const backup = [...display];
const backup2 = backup.length > 0 ? backup : ['暂无用户'];
return <ul>{display.map(name => <li>{name}</li>)}</ul>;
}
传统工具会告诉你 `backup` 和 `backup2` 没有被使用，但无法证明删除它们不影响渲染。simplify-codebase 可以：
1. 证明 `backup` 只是 `display` 的浅拷贝，且后续没有修改 `display`，所以删除 `backup` 不影响行为。
2. 证明 `backup2` 的计算结果从未被使用（因为 `display` 直接用于渲染），所以整个块可删除。
输出：
[PROVEN] 第8行: 删除变量 'backup'
[PROVEN] 第9行: 删除变量 'backup2'
[UNPROVEN] 第10行: JSX 渲染逻辑保留（涉及 React 内部机制）
## 未来展望与社区
项目目前处于早期阶段（Stars 332），但思路非常独特。Roadmap 包括：
- Python 支持
- 与 TypeScript 类型系统的深度集成
- 更好的循环不变量推理
- 可视化证明浏览器
对于想要参与贡献的开发者，项目欢迎对形式化方法、编译器优化或静态分析感兴趣的贡献者。
## 总结评价
simplify-codebase 不是又一个“代码清理工具”，而是一个**将学术形式化方法落地到日常开发实践**的尝试。它的价值不在于“自动删除代码”，而在于“让删除代码变成一件有数学依据的事情”。
对于大型代码库的维护者、对代码质量有执念的团队、以及那些长期被“不敢动老代码”困扰的开发者，这个工具值得一试。
虽然当前语言支持有限，且需要一定的学习成本，但它的核心思想——**用证明取代猜测**——可能是未来代码质量工具的重要方向。
**项目链接**：https://github.com/tt-a1i/simplify-codebase