fallow：JS/TS 代码库分析工具

项目简介

fallow 是面向 TypeScript 和 JavaScript 的代码库智能分析工具。它会为仓库构建一张图，包含模块、导出、依赖、函数和样式 token，再基于这张图分析复杂度、架构漂移、代码重复、未使用代码以及代码改动带来的风险。

它是一个单独的 Rust 二进制，静态分析不依赖 TypeScript 编译器，也不需要 Node.js 运行时；配合 100 多个内置框架插件，首次运行无需配置。

fallow 有四个入口，它们共用同一份配置文件和同一个分析引擎：

主要功能

• fallow audit：改动文件检查门禁，覆盖复杂度、重复、未使用代码与样式漂移，输出 pass、warn 或 fail。
• fallow health：复杂度热点、0–100 健康分、重构目标，并结合 git churn 与代码所有权。
• fallow architecture / fallow guard：架构边界违规（提供 bulletproof、layered、hexagonal、feature-sliced 预设）与循环依赖。
• fallow dupes：在 JS、TS、CSS 以及 Vue、Svelte、Astro 组件中查找重复代码。
• fallow health --css：发现 CSS 和 CSS-in-JS 中偏离设计系统的地方。
• fallow dead-code / fallow fix：未使用的文件、导出、类型、类和枚举成员、依赖，带自动修复和 dry-run 预览。
• fallow mutation：变异测试，检查源码中的小改动是否有测试能发现（可选，会运行项目测试）。
• fallow security：按从入口点可达性排序的安全候选（可选）。
• fallow similar-code：意图相同但写法不同的函数（可选，使用一次性下载的本地模型）。
• fallow flags：扫描代码库中的 feature flag 模式。
• npx fallow viz：打开交互式 HTML 项目地图，提供健康、重复、架构、未使用代码等视角。

其他特性：加上 --type-aware 可在别名、re-export 和包之间精确识别 TS 符号，减少接口和基类带来的误报；生产环境运行时覆盖率可作为可选项合并进 health 与 audit 报告；支持 npm、yarn、pnpm workspace，用 --workspace <name> 限定单个包；每条命令都有类型化 JSON 输出、文档化的退出码和公开的输出 schema，fallow schema 可打印所有命令、参数、输出格式与退出码；分析在本机或 CI runner 上运行，遥测为可选项。

安装与使用

在任意 JS 或 TS 项目根目录直接运行：

npx fallow

固定到项目中可安装为 dev 依赖：

npm install --save-dev fallow

常用命令：

npx fallow audit
npx fallow fix --dry-run
npx fallow health --score
npx fallow dead-code --trace src/api.ts:client

安装 pre-commit 钩子，在提交离开本机前做检查：

npx fallow hooks install --target git

GitHub Actions 中使用：

- uses: actions/checkout@v4
  with:
    fetch-depth: 0
- uses: fallow-rs/fallow@v3
  with:
    command: audit

接入已有代码库时，可以先运行 npx fallow recommend 检测技术栈并生成建议配置，它不会修改文件；随后在 PR 中只用 fallow audit，只拦截本次改动引入的问题。若要对完整运行保存基线，可用 npx fallow --save-baseline fallow-baseline.json，之后每次运行时加上 --baseline fallow-baseline.json。在 Action 中加 fail-on-issues: false 可以先进入只报告模式。

若要保留有意为之的导出，可以加抑制注释：

// fallow-ignore-next-line unused-export -- kept for plugin consumers
export const keepThis = 1;

// fallow-ignore-file <issue-type> 可抑制整个文件，JSDoc 标签 @public、@internal 可让有意的库 API 保持安静，npx fallow suppressions 列出项目中所有抑制项。

注意事项

• 同样的输入会得到同样的输出，每个发现都有稳定指纹；分析器内部不含 AI，只有可选的 similar-code 使用固定的本地模型。
• fallow audit 只在本次改动引入问题时失败，已有的历史问题不会让检查失败。
• 在 PR 中，Action 会把分析范围限定到改动文件，因此输出可能与本地完整运行不同。
• --type-aware、fallow mutation、fallow security、fallow similar-code 都是可选能力。
• 若结果被缺失入口或生成文件干扰，可在配置中补充入口并排除生成文件。

本作品整理自 GitHub 开源项目 fallow-rs/fallow，原作者 @fallow-rs，许可证 MIT。中文介绍由 AI 根据项目 README 整理，以原仓库为准。