发现死代码。了解其消亡原因。安全地将其删除。
`fossil` 是一款命令行取证工具，它不仅能够检测死代码，还能解释其*历史* —— 它在**何时**消亡，**什么**导致了它的消亡，是**谁**编写的，**为什么**会存在，以及是否真的**可以安全删除**。
它将静态分析、git 历史挖掘和模式检测结合到一个终端命令中，并在 3 秒内给出结果。
## 为什么选择 fossil？
每个成熟的代码库都会积累死代码。现有的工具只能告诉你**什么**是死代码。但没有一个工具能告诉你**为什么**。
| 问题 | 其他工具 | fossil |
|----------|-------------|--------|
| 这个文件是否在任何地方被导入？ | ✅ | ✅ |
| 它是何时变成死代码的？ | ❌ | ✅ — 包含确切日期的消亡提交 |
| 哪个 PR 替代了它？ | ❌ | ✅ — PR 编号、标题、作者 |
| 最初是谁编写的？ | ❌ | ✅ — 来自 git blame 的原作者 |
| 是否有“暂时保留”的注释？ | ❌ | ✅ — 检测并验证条件 |
| 可以安全删除吗？ | ❌ | ✅ — 0–100% 的置信度评分 |
| 能否为我自动删除？ | ❌ | ✅ — 使用 `--yolo` 创建 PR |
## 安装说明
```
pip install fossil-code
```
## 快速开始
```
# 单个文件的完整取证报告
fossil explain src/billing/legacy_processor.py
# 扫描整个目录
fossil scan ./src
# 机器可读的 JSON 输出
fossil explain src/billing/legacy_processor.py --json
# 优先删除积压
fossil clean ./src --threshold 85
# 纯文本模式（用于管道 / CI）
fossil explain src/billing/legacy_processor.py --plain
```
## 示例输出
```
╭─────────────────────────────────── fossil ───────────────────────────────────╮
│ │
│ FORENSIC REPORT src/billing/legacy_processor.py │
│ Status ● DEAD Language Python │
│ ╭─────────────────────────────── History ────────────────────────────────╮ │
│ │ Dead since 2023-03-14 │ │
│ │ Death commit a3f9b21 "Migrate to Stripe v3 — replace legacy │ │
│ │ SCA handler (#441)" │ │
│ │ PR #441 · Migrate to Stripe v3 — replace legacy SCA │ │
│ │ handler (#441) │ │
│ │ Original by Sarah Chen · first committed 2022-06-12 │ │
│ ╰────────────────────────────────────────────────────────────────────────╯ │
│ ╭──────────────────────────── Temporary Hold ────────────────────────────╮ │
│ │ Pattern "keeping this around until Q2 rollout completes" (line 3) │ │
│ │ Status ✓ RESOLVED — PR #489 merged April 12, 2023 │ │
│ ╰────────────────────────────────────────────────────────────────────────╯ │
│ ╭─────────────────────────── Static Analysis ────────────────────────────╮ │
│ │ Call sites 0 Dynamic imports 0 │ │
│ │ Import refs 0 Reflection None detected │ │
│ │ Test references 0 Config refs 0 │ │
│ ╰────────────────────────────────────────────────────────────────────────╯ │
│ ╭────────────────────────────── Confidence ──────────────────────────────╮ │
│ │ 91% ██████████████████░░ HIGH CONFIDENCE · LOW RISK │ │
│ ╰────────────────────────────────────────────────────────────────────────╯ │
│ Suggested rm src/billing/legacy_processor.py │
│ Auto-PR fossil explain src/billing/legacy_processor.py --yolo │
│ Analysis duration: 1840ms │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
```
## 工作原理
对于分析的每个文件，`fossil` 会在 3 秒内运行五个阶段：
```
flowchart LR
Static[Static
Analysis]
Git[Git History
Mining]
Pattern[Pattern
Detection]
Scoring[Confidence
Scoring]
Render[Output
Rendering]
Static --> Git --> Pattern --> Scoring --> Render
subgraph Details
direction LR
S1(imports, calls
dynamic, reflection) -.- Static
G1(death commit
PR, author) -.- Git
P1(TODO: remove
DEPRECATED) -.- Pattern
C1(14 signals
0-100% score) -.- Scoring
end
style Static fill:#0d1117,stroke:#58a6ff,stroke-width:2px,color:#c9d1d9
style Git fill:#0d1117,stroke:#3fb950,stroke-width:2px,color:#c9d1d9
style Pattern fill:#0d1117,stroke:#d2a8ff,stroke-width:2px,color:#c9d1d9
style Scoring fill:#0d1117,stroke:#ff7b72,stroke-width:2px,color:#c9d1d9
style Render fill:#0d1117,stroke:#a5d6ff,stroke-width:2px,color:#c9d1d9
style Details fill:none,stroke:none
linkStyle 0,1,2,3 stroke:#8b949e,stroke-width:2px
```
### 置信度评分
置信度评分汇总了 14 个加权信号：
| 信号 | 权重 | 方向 |
|--------|--------|-----------|
| 零调用点（静态） | +30 | 正向 |
| 无动态引用 | +20 | 正向 |
| 已确定消亡提交 | +15 | 正向 |
| 临时保留已解决 | +10 | 正向 |
| 无反射模式 | +10 | 正向 |
| 死亡文件超过 90 天 | +8 | 正向 |
| 找到 PR/迁移上下文 | +7 | 正向 |
| 检测到动态导入 | −30 | 负向 |
| 检测到反射/getattr | −20 | 负向 |
| 文件在 30 天内被修改过 | −20 | 负向 |
| 未解决的“暂时保留” | −15 | 负向 |
| 语言未知（回退） | −15 | 负向 |
| 发现测试文件引用 | −10 | 负向 |
| 消亡提交不明确 | −10 | 负向 |
**风险标签：** `85–100%` 高置信度 · 低风险 · `70–84%` 中高置信度 · `55–69%` 中等置信度 · `<55%` 低置信度 · 高风险
## 命令
### `fossil explain
`
单个文件的完整取证报告。
```
fossil explain src/billing/legacy.py # Rich panel output
fossil explain src/billing/legacy.py --json # JSON output
fossil explain src/billing/legacy.py --plain # Plain text
fossil explain src/billing/legacy.py --no-cache # Skip cache
fossil explain src/billing/legacy.py --depth 2000 # Deeper git history
```
| 标志 | 默认值 | 描述 |
|------|---------|-------------|
| `--json` | false | 机器可读的 JSON 输出 |
| `--plain` | false | 纯文本（无 Rich 格式） |
| `--no-color` | false | 禁用 ANSI 颜色 |
| `--no-cache` | false | 跳过缓存读/写 |
| `--depth N` | 500 | 要遍历的最大 git 提交数 |
| `--remote` | auto | 强制指定远程仓库：`github`、`gitlab`、`none`、`auto` |
| `--yolo` | false | 如果置信度 ≥ 90%，则创建删除 PR |
| `--force-yolo` | false | 无论置信度如何，均创建删除 PR |
| `--narrate` | false | LLM 解说（需要配置提供商） |
### `fossil scan [directory]`
扫描目录以查找置信度高于阈值的死文件。
```
fossil scan ./src # Scan with default 70% threshold
fossil scan ./src --threshold 85 # Only high-confidence results
fossil scan ./src --language py,js # Filter by language
fossil scan ./src --exclude "**/test*" # Exclude patterns
fossil scan ./src --json # JSON for CI pipelines
```
### `fossil clean [directory]`
优先删除积压任务 —— 按置信度排序。
```
fossil clean ./src --threshold 80 # Show deletion candidates
fossil clean ./src --dry-run # Preview what would be done
fossil clean ./src --json # Machine-readable output
```
### `fossil config`
```
fossil config set github_token ghp_xxxx # Store GitHub token
fossil config set llm_provider openai # Configure LLM provider
fossil config show # Show config (tokens masked)
```
### `fossil cache`
```
fossil cache clear # Delete analysis cache
fossil cache stats # Show cache statistics
```
## 退出代码
| 代码 | 含义 | CI 用途 |
|------|---------|--------|
| `0` | 发现死代码，已生成报告 | 使 CI 检查失败 |
| `1` | 意外错误 | 使 CI 检查失败 |
| `2` | 未找到文件 | 使 CI 检查失败 |
| `3` | 不是 git 仓库 | 使 CI 检查失败 |
| `4` | 文件不是死代码（正在使用中） | 通过 CI 检查 |
## CI 集成
### GitHub Actions
```
- name: Check for dead code
run: |
pip install fossil-code
fossil scan . --threshold 90 --json > dead_report.json
# Exit 0 = dead code found above 90% → fail the step
# Exit 4 = no dead code above 90% → pass
```
### Pre-commit Hook
```
#!/bin/bash
fossil scan . --threshold 90 --json --no-cache > /dev/null 2>&1
if [ $? -eq 0 ]; then
echo "⚠️ Dead code detected above 90% confidence. Run 'fossil scan .' for details."
exit 1
fi
```
## 配置
### 用户配置：`~/.config/fossil/config.toml`
```
github_token = ""
gitlab_token = ""
llm_api_key = ""
llm_provider = "openai"
llm_model = "gpt-4o-mini"
default_depth = 500
cache_ttl_hours = 24
```
### 项目配置：`.fossil.toml`
将其提交到你的仓库根目录，以便整个团队共享设置：
```
[analysis]
languages = ["py", "js", "ts"]
exclude_patterns = ["**/migrations/**", "**/generated/**"]
[thresholds]
minimum_confidence = 70
yolo_minimum_confidence = 90
[pr]
base_branch = "main"
pr_labels = ["dead-code-cleanup", "automated"]
```
### 环境变量
所有环境变量都会覆盖配置文件中的值：
| 变量 | 用途 |
|----------|---------|
| `GITHUB_TOKEN` | GitHub API 身份验证 |
| `GITLAB_TOKEN` | GitLab API 身份验证 |
| `FOSSIL_LLM_API_KEY` | LLM 提供商 API 密钥 |
| `FOSSIL_LLM_PROVIDER` | LLM 提供商（`openai` / `anthropic` / `ollama`） |
| `FOSSIL_LLM_MODEL` | LLM 模型名称 |
| `NO_COLOR` | 禁用 ANSI 颜色（[no-color.org](https://no-color.org)） |
## 语言支持
| 语言 | 分析器 | 能力 |
|----------|----------|------------|
| **Python** | `ast` 模块 | 深度导入、调用、动态导入、反射分析 |
| JavaScript | 文本回退 | 文件名/符号引用搜索 |
| TypeScript | 文本回退 | 文件名/符号引用搜索 |
| Java | 文本回退 | 文件名/符号引用搜索 |
| Go | 文本回退 | 文件名/符号引用搜索 |
| 其他 | 文本回退 | 文件名引用搜索 |
## 默认离线
`fossil` 可以在**零网络访问**的情况下工作。核心分析流水线（静态分析 → git 挖掘 → 模式检测 → 置信度评分）完全在离线状态下运行。
网络仅用于三个**可选**功能：
- GitHub/GitLab API — PR 标题/正文查找，`--yolo` PR 创建
- LLM API — `--narrate` 自然语言解释
## 开发
```
git clone https://github.com/iamvvek/fossil.git
cd fossil
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
# 运行测试（85+ 个测试）
pytest -v
# Lint
ruff check src/ tests/
```
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取完整的开发指南。
## 路线图
- [x] **阶段 1** — 带有 Rich 输出的 Python 取证
- [x] **阶段 2** — 多语言扫描、模式检测、并行处理
- [ ] **阶段 3** — GitHub/GitLab API 集成，`--yolo` PR 创建
- [ ] **阶段 4** — LLM 解说，VS Code 扩展
## 许可证
[MIT](LICENSE) — 使用它，派生它，发布它。