DonaldMurillo/statico

# statico [](https://blog.rust-lang.org/2025/02/20/Rust-2024-edition.html) [](#license) statico 是一个针对 TypeScript 和 Rust 项目的静态代码分析器。它能够检测死代码、未使用的 export/type、循环依赖、代码重复以及特定框架的陷阱，计算出一个 0-100 的健康评分，并提供专为人类和 LLM 设计的输出结果。 ## statico 的优势 - **多语言项目。** 适用于旁边的 TypeScript 应用和 Rust 服务的同一款工具。无需上下文切换，一份报告搞定。 - **AI 辅助工作流。** `--format ai`（约 500 token）和 `--format context`（约 100 token）可直接对接 Claude / Cursor / Codex / 需要代码健康快照的智能体。`.claude/skills/` 和 `.pi/skills/` 下的项目技能由 `statico setup` 生成。 - **可定制。** JSON-RPC 插件系统允许你使用 TypeScript、Rust、Python 或任何支持 stdin/stdout 的语言来编写项目特定的规则。参见 [`examples/plugins/coverage-gap`](examples/plugins/coverage-gap)，这是一个端到端演示该协议的多钩子插件。 - **对 CI 友好。** 生成适用于 GitHub Code Scanning 的 SARIF。提供基线文件以逐步减少问题。使用 `statico fix` 进行安全的自动清理。 - **无守护进程，无服务器，无锁定。** 单一二进制文件，JSON 输出，按需的退出代码。可以将其输出通过管道传递到任何地方。 ## 目前 statico **不**擅长的地方 - **大规模分析时的速度。** statico 不是该类别中最快的分析器。在大型 monorepo 上，knip 和 oxlint 的运行速度会更快。statico 在追求原始吞吐量之前，优先考虑了输出灵活性和规则可扩展性。增量缓存在热运行时非常有帮助（`~5–10×`）；冷运行是它的弱项。 - **稳定性保证。** 处于 1.0 版本之前。输出 schema、插件协议和 CLI 标志可能会在不同版本之间发生变化。基线文件格式是有版本控制的；其他 JSON 结构则没有。 - **覆盖所有框架。** 内置配置文件覆盖了 Next.js、Angular、Vue、Svelte、Astro、Remix、NestJS、Payload CMS 和 shadcn/ui —— 但检测是基于规则的且不够全面。对于小众框架，正确的解决方案是使用插件，而不是依赖内置功能。 - **替代你的 Linter。** statico 是一个项目级别的分析器，用于处理 ESLint / clippy 不易察觉的问题（跨文件的死代码、导入循环、重复模式）。请与你的 Linter 并行运行它，而不是替代它。 ## 检测到的问题 - **死代码** — 从任何入口点都无法访问的文件 - **未使用的 export** — 从未在其他地方导入的命名导出 - **未使用的类型** — 从未被引用的已导出 TypeScript 接口/类型 - **未使用的依赖** — `package.json` 中从未被导入的包 - **未列出的依赖** — 导入了不在 `package.json` 中的包 - **循环依赖** — 文件之间的导入循环 - **重复代码** — 克隆组、镜像目录、重复的模式 - **框架陷阱** — 特定于你框架的易出错模式 - **未解析的导入** — 无法解析到真实文件的导入说明符 - **插件问题** — 你的自定义规则发现的任何问题 0-100 的 **健康评分** 结合了问题密度和重复率。你可以使用 `--min-confidence` 进行调整，以过滤掉低信噪比的干扰信息。 ## 安装 ### Cargo ``` cargo install statico ``` ### npm (macOS / Linux × x86_64 / aarch64) ``` npm install -D @statico/cli npx statico analyze . ``` ### 预构建版本 ``` # 示例：macOS arm64 curl -fsSL https://github.com/DonaldMurillo/statico/releases/latest/download/statico-macos-aarch64.tar.gz \ | tar -xz sudo install -m 0755 statico /usr/local/bin/statico ``` ### GitHub Action ``` - uses: DonaldMurillo/statico/.github/actions/statico@main with: format: sarif min-confidence: '0.5' ``` ### 从源码构建 ``` git clone https://github.com/DonaldMurillo/statico.git cd statico cargo install --path . ``` 源码构建的先决条件：[Rust](https://rustup.rs/) 1.91+（Edition 2024）。 ## 快速开始 分析当前项目： ``` statico analyze . ``` 当 stdout 是终端时，默认输出是人类可读的 Markdown。当通过管道输出时，则是 enriched JSON。 获取适用于 LLM 的摘要： ``` statico analyze . --format ai ``` 仅针对新问题让 CI 失败（由基线控制）： ``` statico analyze . --update-baseline statico-baseline.json # one-time statico analyze . --baseline statico-baseline.json --exit-code ``` 应用安全的自动修复（未使用的 export + 未使用的 npm 依赖），先进行 dry-run（演练）： ``` statico fix . statico fix . --apply ``` Watch 模式： ``` statico analyze . --watch ``` 比较两个快照： ``` statico analyze . --format json > before.json # … 进行更改 … statico analyze . --format json > after.json statico diff before.json after.json --format markdown ``` 交互式 TUI： ``` statico tui . ``` ## CLI 参考 ``` statico [OPTIONS] Commands: analyze Analyze a project for code-quality issues fix Apply safe automated fixes (unused exports + unused deps) diff Compare two analysis outputs tui Interactive terminal dashboard plugin Manage plugins (init / build / run / list / doctor / schema / docs) setup Generate AI-assistant skills (.claude / .pi / .cursor) init Set up shell alias and completions doctor Diagnose installation issues update Self-update to latest release completions Print shell completion script Global options: --quiet Suppress progress output ``` ### `statico analyze` | 标志 | 类型 | 默认值 | 描述 | |---|---|---|---| | `--format` | string | tty: `markdown`, 管道: `json` | `json` `sarif` `markdown` `html` `ai` `context` `mermaid` `pr-comment` `fix` | | `--min-confidence` | float | `0.0` (analyze), `0.5` (tui) | 丢弃低于此置信度 (0.0–1.0) 的问题 | | `--exit-code` | flag | false | 如果在基线 + 置信度过滤后仍有问题遗留，则以退出代码 1 退出 | | `--no-cache` | flag | false | 跳过增量缓存；强制进行完整的重新解析 | | `--baseline` | path | — | 抑制指纹列于此文件中的问题 | | `--update-baseline` | path | — | 将当前问题写为基线文件并退出 | | `--watch` | flag | false | 在文件更改时重新运行（使用缓存） | ### `statico fix` | 标志 | 类型 | 默认值 | 描述 | |---|---|---|---| | `--apply` | flag | false | 实际重写文件（默认是 dry-run） | | `--unused-exports` / `--no-unused-exports` | flag | 开启 | 从未使用其导出的声明中删除 `export` 关键字 | | `--unused-deps` / `--no-unused-deps` | flag | 开启 | 从 `package.json` 中移除未使用的条目 | ### `statico diff` ``` statico diff [--format json|markdown] ``` 如果 `after` 引入了新问题，则以退出代码 1 退出。 ### `statico tui` ``` statico tui [--min-confidence 0.5] ``` ## 输出格式 | 格式 | 用途 | |---|---| | `json` | 工具集成，用于 `statico diff` 的快照 | | `sarif` | GitHub Code Scanning，Azure DevOps | | `markdown` | PR 评论，人类阅读（tty 上的默认值） | | `html` | 自包含的交互式报告（离线） | | `ai` | LLM 工具调用（约 500 token，前 20 个问题 + 每文件风险） | | `context` | System-prompt / `AGENTS.md` 注入（约 100 token） | | `pr-comment` | GitHub PR 审查评论，带 emoji 的 GFM | | `mermaid` | 依赖图（按颜色区分入口/死代码/热点） | | `fix` | dry-run 清理提示（用 `git show` 行以便审查） | 详情请见 [`docs/output-formats.md`](docs/output-formats.md)。 ## 配置 项目根目录下的 `.statico.toml`，所有键均为可选： ``` # 默认输出格式（以 CLI --format 为准） format = "json" # 过滤低信号问题（以 CLI --min-confidence 为准） min_confidence = 0.0 # 遇到问题则 Exit 1（以 CLI --exit-code 为准） exit_code = false # 要跳过的 Glob 模式 exclude = ["node_modules", "dist", "build", "**/*.generated.ts"] # 覆盖 exclude 的 Glob 模式 include = ["src/**/*.ts", "src/**/*.tsx"] # 跳过大于此大小的文件（字节）；内部上限为 50 MB max_file_size = 1_000_000 # Worker 线程（0 = 自动检测） threads = 0 # 自动发现 .statico/plugins/ 下的插件 plugin_auto_discover = true # 显式插件条目（与自动发现合并） [[plugin]] name = "my-rule" path = "./tools/my-rule" enabled = true languages = ["typescript"] [plugin.settings] # 作为 plugin_settings 转发给插件的 `init` 调用 strict = true ``` 完整的 schema 请见 [`docs/configuration.md`](docs/configuration.md)。 ## 插件 statico 的插件系统允许你使用任何可以通过 stdin/stdout 读写 JSON 的语言来编写项目特定的规则。插件作为子进程生成，并使用 JSON-RPC 2.0 通信。 ``` # Scaffold (typescript / rust / python) statico plugin init my-rule --lang typescript # 构建（仅限 Rust 插件 — TS/Python 插件不编译） statico plugin build --name my-rule # 针对单个文件运行 statico plugin run my-rule --file src/foo.ts # 检查发现的内容 statico plugin list statico plugin doctor # check Bun / cargo runtime readiness ``` 插件会从项目根目录的 `.statico/plugins/` 中自动发现。 每个插件都可以挂钩到： - `analyze_file` — 单文件分析（添加或覆盖内置） - `discover_entries` — 替换内置的入口点检测 - `resolve_import` — 替换内置的导入解析 - `post_analysis` — 在完整分析遍历后添加跨领域问题 - `format_output` — 替换给定格式的内置格式化器 有关可用的多钩子示例，请参见 [`examples/plugins/coverage-gap`](examples/plugins/coverage-gap) — 它使用 `analyze_file` 收集每个文件的导出 + 被测试的名称，然后使用 `post_analysis` 标记没有测试引用的导出，并从插件的 `settings` 块中读取配置。 完整的协议参考：[`docs/plugins.md`](docs/plugins.md)。 ## 框架配置文件 | 框架 | 检测方式 | 入口点 | 陷阱规则 | |---|---|---|---| | **Next.js** | `next.config.*` | `page.tsx` `layout.tsx` `route.ts` `loading.tsx` `error.tsx` `not-found.tsx` | 条件 Hook，缺失的 key | | **Angular** | `angular.json` | Components，directives，pipes，services，modules | — | | **Vue** | `vue.config.*` / `nuxt.config.*` / Vite + Vue 插件 | `.vue` SFCs | — | | **Svelte** | `svelte.config.*` | `.svelte` 组件，`+page.svelte`，`+layout.svelte` | — | | **Astro** | `astro.config.*` | `.astro` 页面和布局 | — | | **Remix** | `remix.config.*` | `app/routes/` 中的路由文件 | — | | **NestJS** | `nest-cli.json` | Controllers，modules，services，guards，pipes | — | | **Payload CMS** | `payload.config.*` | Collections，blocks，globals，fields | — | | **shadcn/ui** | `components.json` | UI 组件文件 | — | | **Generic** | 始终激活 | 测试文件，e2e 规范，脚本 | — | 配置文件可以叠加 —— 一个 Next.js + Payload + shadcn 项目会同时激活这三个配置文件集。检测会针对标记文件和 `package.json` 依赖项运行，在 monorepo 中还会包含工作区包目录。 ## AI 集成 statico 的设计旨在让人类和 LLM 都能轻松读取： - **`--format ai`** — 带有 schema 版本的 JSON，约 500 token，影响排名前 20 的问题，并附带 `safe-to-delete` / `remove` / `investigate` 建议。 - **`--format context`** — 约 100 token 的纯文本，用于 `AGENTS.md` / `CLAUDE.md` / system-prompt 注入。 - **`statico setup`** — 为 Claude Code (`.claude/skills/`)、pi (`.pi/skills/`) 和 Cursor (`.cursor/rules/`) 生成技能文件，以便助手无需额外提示即可将 statico 作为工具调用。 - **对 MCP 友好的输出** — `ai` 和 `context` 格式都已足够稳定，可以在今天直接嵌入到 MCP 工具描述中。 ## 状态，稳定性以及未来方向 - **v0.1.0 = 首个公开的 alpha 标签。** 在该分支的 CI 冒烟测试中通过的所有功能均可正常工作；不作其他任何承诺。 - **输出 schema 可能会改变。** enriched JSON、AI JSON、基线格式和 SARIF 输出均已进行版本控制，但在 1.0 版本之前，次版本号可能会更改字段名称。 - **插件协议可能会改变。** 当前版本为由 `statico plugin schema --format json` 打印的 schema。处于 1.0 之前。 - **路线图** 范围较窄：循环检测的确定性、按规则调整置信度、语言插件（通过目前支持 TS+Rust 的相同 trait 支持 Python/Go）、针对更多规则的 `--fix`。 ## 许可证 根据您的选择，采用 [MIT](LICENSE-MIT) 或 [Apache 2.0](LICENSE-APACHE) 双重许可。参与贡献即表示您同意相同的双重许可条款。

标签：AST解析器, Cursor, DevSecOps, GitHub代码扫描, JSON-RPC, LLM集成, Rust, SARIF, TypeScript, 上游代理, 人工智能辅助, 代码安全, 代码审查, 代码规范, 代码重复检测, 健康度评分, 单文件二进制, 可视化界面, 多语言分析, 威胁情报, 安全插件, 开发者工具, 开源, 循环依赖, 数据管道, 无用代码检测, 模块化设计, 漏洞枚举, 网络流量审计, 自动化修复, 软件工程, 通知系统, 错误基检测, 静态代码分析