fallow-rs/fallow
GitHub: fallow-rs/fallow
Rust 原生的高速 TS/JS 代码库分析器，零配置即可检测死代码、重复代码、循环依赖与复杂度热点，专注于跨模块维度的代码质量问题。
Stars: 25 | Forks: 0
TypeScript 和 JavaScript 的代码库分析器 —— 死代码、重复代码、复杂度与架构。
Rust 原生。零配置。亚秒级。
```
npx fallow
```
```
Dead code 3 unused files, 12 unused exports, 2 unused deps 18ms
Duplication 4 clone groups (2.1% of codebase) 31ms
Complexity 7 functions exceed thresholds 4ms
Total 26 issues across 847 files 53ms
```
84 个框架插件。无需 Node.js 运行时。无需配置文件。
## 安装
```
npx fallow # Run without installing
npm install -g fallow # Or install globally (macOS, Linux, Windows)
cargo install fallow-cli # Or via Cargo
```
## 命令
```
fallow # Run all three analyses
fallow dead-code # Dead code only
fallow dupes # Duplication only
fallow health # Complexity only
fallow audit # Audit changed files (verdict: pass/warn/fail)
fallow fix --dry-run # Preview auto-removal of dead exports and deps
fallow watch # Re-analyze on file changes
```
## 死代码
查找未使用的文件、导出、依赖项、类型、枚举成员、类成员、未解析的导入、未列出的依赖项、重复导出、循环依赖、边界违规、仅类型依赖项以及仅测试用的生产环境依赖项。
```
fallow dead-code # All dead code issues
fallow dead-code --unused-exports # Only unused exports
fallow dead-code --circular-deps # Only circular dependencies
fallow dead-code --boundary-violations # Only boundary violations
fallow dead-code --production # Exclude test/dev files
fallow dead-code --changed-since main # Only changed files (for PRs)
fallow dead-code --group-by owner # Group by CODEOWNERS for team triage
fallow dead-code --group-by directory # Group by first directory component
```
## 重复代码
查找整个代码库中复制粘贴的代码块。采用后缀数组算法 —— 无二次方级的两两比较。
```
fallow dupes # Default (mild mode)
fallow dupes --mode semantic # Catch clones with renamed variables
fallow dupes --skip-local # Only cross-directory duplicates
fallow dupes --trace src/utils.ts:42 # Show all clones of code at this location
```
四种检测模式：**strict**（精确 token）、**mild**（默认，基于 AST）、**weak**（不同的字符串字面量）、**semantic**（重命名的变量和字面量）。
## 复杂度
揭示代码库中最复杂的函数，并明确应在何处投入重构精力。
```
fallow health # Functions exceeding thresholds
fallow health --score # Project health score (0-100) with letter grade
fallow health --min-score 70 # CI gate: fail if score drops below 70
fallow health --top 20 # 20 most complex functions
fallow health --file-scores # Per-file maintainability index (0-100)
fallow health --hotspots # Riskiest files (git churn x complexity)
fallow health --targets # Ranked refactoring recommendations
fallow health --trend # Compare against saved snapshot
fallow health --changed-since main # Only changed files
```
## 审计
针对 AI 生成代码和 PR 的质量关卡。结合了范围限定在已更改文件上的死代码 + 复杂度 + 重复代码。
```
fallow audit # Auto-detects base branch
fallow audit --base main # Explicit base ref
fallow audit --base HEAD~3 # Audit last 3 commits
fallow audit --format json # Structured output with verdict
```
返回裁定结果：**pass**（退出码 0）、**warn**（退出码 0，仅警告级别）或 **fail**（退出码 1）。JSON 输出包含用于 CI 和 agent 集成的 `verdict` 字段。
## CI 集成
```
# GitHub Action
- uses: fallow-rs/fallow@v2
# GitLab CI — 包含 template 并 extend
include:
- remote: 'https://raw.githubusercontent.com/fallow-rs/fallow/main/ci/gitlab-ci.yml'
fallow:
extends: .fallow
# 或直接在任何 CI 上运行
- run: npx fallow --ci
```
`--ci` 启用 SARIF 输出、静默模式以及出现问题时的非零退出。还支持：
- `--group-by owner|directory` -- 按 CODEOWNERS 所有权或目录对输出进行分组，以便团队级别的分类处理
- `--changed-since main` -- 仅分析 PR 中修改的文件
- `--baseline` / `--save-baseline` -- 仅因**新增**问题而失败
- `--fail-on-regression` / `--tolerance 2%` -- 仅在问题**增长**超出容差范围时失败
- `--format sarif` -- 上传至 GitHub Code Scanning
- `--format codeclimate` -- GitLab Code Quality 行内 MR 注解
- `--format annotations` -- GitHub Actions 行内 PR 注解（无需 Action）
- `--format json` / `--format markdown` -- 用于自定义工作流（JSON 包含针对每个问题的机器可执行 `actions`）
- `--format badge` -- 兼容 shields.io 的 SVG 健康徽章（`fallow health --format badge > badge.svg`）
GitHub Action 和 GitLab CI 模板都会根据 lock 文件自动检测您的包管理器（npm/pnpm/yarn），因此评审注释中的安装/卸载命令会与您的项目匹配。
渐进式采用 -- 先暴露问题而不阻塞 CI，然后在准备就绪时进行升级：
```
{ "rules": { "unused-files": "error", "unused-exports": "warn", "circular-dependencies": "off" } }
```
### GitLab CI 富文本 MR 评论
GitLab CI 模板可以直接在合并请求上发布富文本评论 —— 带有可折叠区域的总结评论，以及带有建议块的行内评审讨论。
| 变量 | 默认值 | 描述 |
|---|---|---|
| `FALLOW_COMMENT` | `"false"` | 在 MR 上发布带有每次分析可折叠区域的总结评论 |
| `FALLOW_REVIEW` | `"false"` | 在相关行发布行内 MR 讨论，并为未使用的导出提供 `suggestion` 块 |
| `FALLOW_MAX_COMMENTS` | `"50"` | 行内评审评论的最大数量 |
在 MR 流水线中，`--changed-since` 会自动设置以将分析范围限定在已更改的文件。重新运行时会清理以前的 fallow 评论。
评论合并流水线按文件对未使用的导出进行分组，并对克隆报告进行去重，从而保持 MR 线程的可读性。
建议使用 `GITLAB_TOKEN`（具有 `api` 范围的 PAT）以获取完整功能（建议块、清理之前的评论）。`CI_JOB_TOKEN` 可用于发布，但无法删除之前运行的评论。
```
# .gitlab-ci.yml — 包含丰富 MR 评论的完整示例
include:
- remote: 'https://raw.githubusercontent.com/fallow-rs/fallow/main/ci/gitlab-ci.yml'
fallow:
extends: .fallow
variables:
FALLOW_COMMENT: "true" # Summary comment with collapsible sections
FALLOW_REVIEW: "true" # Inline discussions with suggestion blocks
FALLOW_MAX_COMMENTS: "30" # Cap inline comments (default: 50)
FALLOW_FAIL_ON_ISSUES: "true"
```
## 配置
开箱即用。当您需要自定义时，创建 `.fallowrc.json` 或运行 `fallow init`：
```
// .fallowrc.json
{
"$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
"entry": ["src/workers/*.ts", "scripts/*.ts"],
"ignorePatterns": ["**/*.generated.ts"],
"ignoreDependencies": ["autoprefixer"],
"rules": {
"unused-files": "error",
"unused-exports": "warn",
"unused-types": "off"
},
"health": {
"maxCyclomatic": 20,
"maxCognitive": 15
}
}
```
架构边界预设在层之间实施导入规则，无需手动配置：
```
{ "boundaries": { "preset": "bulletproof" } } // or: layered, hexagonal, feature-sliced
```
运行 `fallow list --boundaries` 以检查展开的规则。也支持 TOML（`fallow init --toml`）。init 命令还会将 `.fallow/` 添加到您的 `.gitignore` 中（缓存和本地数据）。使用 `fallow init --hooks` 搭建 pre-commit 钩子。从 knip 或 jscpd 迁移？运行 `fallow migrate`。
请参阅[完整配置参考](https://docs.fallow.tools/configuration/overview)以了解所有选项。
## 框架插件
84 个内置插件自动检测您的框架的入口点和已使用的导出。
| 类别 | 插件 |
|---|---|
| **框架** | Next.js, Nuxt, Remix, SvelteKit, Gatsby, Astro, Angular, NestJS, Expo, Electron 等 |
| **打包器** | Vite, Webpack, Rspack, Rsbuild, Rollup, Rolldown, Tsup, Tsdown, Parcel |
| **测试** | Vitest, Jest, Playwright, Cypress, Storybook, Mocha, Ava |
| **数据库** | Prisma, Drizzle, Knex, TypeORM, Kysely |
| **Monorepos** | Turborepo, Nx, Changesets, Syncpack |
[完整插件列表](https://docs.fallow.tools/frameworks/built-in) —— 缺少某个？添加[自定义插件](https://docs.fallow.tools/frameworks/custom-plugins)或[提交 issue](https://github.com/fallow-rs/fallow/issues)。
## 编辑器与 AI 支持
- **VS Code 扩展** -- 树视图、状态栏、一键修复、自动下载 LSP 二进制文件（[Marketplace](https://github.com/fallow-rs/fallow/tree/main/editors/vscode))
- **LSP server** -- 实时诊断、悬停信息、代码操作、带有引用计数的 Code Lens
- **MCP server** -- 针对 Claude Code、Cursor、Windsurf 的 AI agent 集成（[fallow-skills](https://github.com/fallow-rs/fallow-skills))
- **JSON `actions` 数组** -- `--format json` 输出中的每个问题都包含带有 `auto_fixable` 标志的修复建议，以便 agent 可以自我纠正
## Fallow 与 Linter
Linter 强制执行风格。Formatter 强制执行一致性。Fallow 强制执行相关性。
ESLint、Biome 和 oxlint 一次只分析一个文件。它们捕获文件边界内的不良模式。Fallow 构建整个项目的模块依赖图，并发现只有在纵览全局时才会出现的问题。
| 内容 | Linter | Fallow |
|---|---|---|
| 函数中未使用的变量 | 是 | 否 |
| 无导入的未使用导出 | 否 | 是 |
| 无导入的文件 | 否 | 是 |
| 跨模块的循环依赖 | 否 | 是 |
| 跨文件的重复代码块 | 否 | 是 |
| package.json 中从未导入的依赖项 | 否 | 是 |
它们是互补的 -- 每次保存时运行您的 linter，每次提交时运行 fallow。
[完整对比：fallow 与 ESLint、Biome、knip、ts-prune](https://docs.fallow.tools/explanations/fallow-vs-linters)
## 性能
基于真实开源项目的基准测试（5 次运行的中位数，Apple M5）。
### 死代码：fallow vs knip
| 项目 | 文件数 | fallow | knip v5 | knip v6 | vs v5 | vs v6 |
|:--------|------:|-------:|--------:|--------:|------:|------:|
| [zod](https://github.com/colinhacks/zod) | 174 | **17ms** | 577ms | 300ms | 34x | 18x |
| [fastify](https://github.com/fastify/fastify) | 286 | **19ms** | 791ms | 232ms | 41x | 12x |
| [preact](https://github.com/preactjs/preact) | 244 | **20ms** | 767ms | 2.02s | 39x | 103x |
| [TanStack/query](https://github.com/TanStack/query) | 901 | **170ms** | 2.50s | 1.28s | 15x | 8x |
| [svelte](https://github.com/sveltejs/svelte) | 3,337 | **359ms** | 1.73s | 749ms | 5x | 2x |
| [next.js](https://github.com/vercel/next.js) | 20,416 | **1.66s** | -- | -- | -- | -- |
knip 在 next.js 上报错。fallow 在 2 秒内完成。
### 重复代码：fallow vs jscpd
| 项目 | 文件数 | fallow | jscpd | 加速比 |
|:--------|------:|-------:|------:|--------:|
| [fastify](https://github.com/fastify/fastify) | 286 | **76ms** | 1.96s | 26x |
| [vue/core](https://github.com/vuejs/core) | 522 | **124ms** | 3.11s | 25x |
| [next.js](https://github.com/vercel/next.js) | 20,416 | **2.89s** | 24.37s | 8x |
无需 TypeScript 编译器，无需 Node.js 运行时。[工作原理](https://docs.fallow.tools/explanations/architecture) | [复现基准测试](https://github.com/fallow-rs/fallow/tree/main/benchmarks)
## 抑制检查结果
```
// fallow-ignore-next-line unused-export
export const keepThis = 1;
// fallow-ignore-file
// Suppress all issues in this file
```
还支持 `/** @public */` JSDoc 标签，用于外部使用的库导出。
## 局限性
fallow 使用语法分析 —— 没有类型信息。这是它快速的原因，但类型级别的死代码不在其范围内。对于边缘情况，请使用[行内抑制注释](#suppressing-findings)或 [`ignoreExports`](https://docs.fallow.tools/configuration/overview#ignoring-specific-exports)。
## 文档
- [入门指南](https://docs.fallow.tools)
- [配置参考](https://docs.fallow.tools/configuration/overview)
- [CI 集成指南](https://docs.fallow.tools/integrations/ci)
- [从 knip 迁移](https://docs.fallow.tools/migration/from-knip)
- [插件编写指南](https://github.com/fallow-rs/fallow/blob/main/docs/plugin-authoring.md)
## 贡献
缺少某个框架插件？发现了误报？[提交 issue](https://github.com/fallow-rs/fallow/issues)。
```
cargo build --workspace && cargo test --workspace
```
## 许可证
MIT
标签：CMS安全, JavaScript, Rust, SOC Prime, TypeScript, 云安全监控, 代码分析, 代码审查, 代码重复, 凭证管理, 前端工程化, 可视化界面, 复杂度分析, 安全插件, 开发工具, 开源框架, 循环依赖, 性能优化, 持续集成, 数据可视化, 暗色界面, 架构分析, 检测绕过, 死代码检测, 网络流量审计, 通知系统, 零配置, 静态分析