Typiqally/lintropy

Lintropy 是一款 Linting 工具，专为你的仓库真正关注的规则而生。它诞生于 [The IDE Reimagined: JetBrains Codex Hackathon](https://cerebralvalley.ai/e/jetbrains-x-openai-hack)， 这是一场在旧金山举办的为期两天的活动，旨在与 JetBrains 和 OpenAI 的工程师共同构建 基于 AI 的开发者工具。 大多数 Linting 工具都内置了固定的规则目录。Lintropy 则完全相反：规则存在于 你的仓库中，一次一个 YAML 文件，描述**你**自己的约定： - API 代码必须放在 `src/api/` 目录下 - feature 模块之间不能直接相互 import - 禁止在测试之外使用 `dbg!`、`println!` 或 `.unwrap()` - migrations 必须包含 rollback 文件 - 只能有一个模块触碰 `process.env` 针对架构、边界、migration 策略以及团队惯例进行 Linting —— 而不仅仅是代码风格。 ## 安装 ### Homebrew (macOS 和 Linux) ``` brew tap Typiqally/lintropy brew install lintropy ``` ### 从源码构建 需要 Stable Rust 1.95 或更高版本。 ``` cargo install --path . ``` 目前尚未发布到 crates.io。 ## 支持的语言 - **Rust**, **Go**, **Python**, **TypeScript**（包含 `.tsx`） — 通过 tree-sitter 实现结构化 `query` 规则 - **任何文本文件** — 正则表达式 `match` 规则 计划支持更多基于 tree-sitter 的语言。可通过 issues 投票或贡献代码。 ## 演示 ``` $ lintropy check . warning[no-unwrap]: avoid .unwrap() on `client`; use .expect("...") or ? --> src/handlers/users.rs:42:18 | 42 | let user = client.unwrap().get(id).await?; | ^^^^^^^^^^^^^^^ help: replace with `client.expect("TODO: handle error")` | = rule defined in: .lintropy/no-unwrap.rule.yaml error[api-only-in-src-api]: API handlers must live under src/api/ --> src/features/users/create_user.rs:1:1 | 1 | pub async fn create_user(...) { ... } | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | = rule defined in: .lintropy/architecture/api-only-in-src-api.rule.yaml Summary: 1 error, 1 warning, 2 files affected. ``` ## 为什么选择 Lintropy 通用的 Linting 工具在处理通用规则方面非常出色。但对于那些仅在特定公司、特定的单个 monorepo 或单个产品内部才有意义的代码库本地规则，它们就显得力不从心了。 Lintropy 填补了这一空白： - 规则存储在仓库中，与它们所约束的代码一起进行版本控制 - 规则易于 review - 规则足够简单，方便 agent 自动生成 - 诊断信息会告诉你触发了哪个规则文件 - tree-sitter 负责处理结构，regex 负责处理纯文本 | | 通用 Linting 工具 | Lintropy | |---|---|---| | 规则来源 | 内置于工具中 | 存在于你的仓库中 | | 编写方式 | 插件代码或复杂的配置 | 小巧的 YAML 文件 | | 适用范围 | 语言层面的通用规范 | 针对项目特定的约束 | | 最佳用途 | 代码风格和正确性 | 架构和边界 | | Agent 支持 | 附带功能 | 一等公民支持 | ## 工作原理 两种规则类型： - `query`：用于结构化模式的 tree-sitter 规则 - `match`：用于文本模式的 regex 规则 典型布局： ``` . ├── lintropy.yaml └── .lintropy/ ├── no-unwrap.rule.yaml ├── no-dbg.rule.yaml └── architecture/ └── api-only-in-src-api.rule.yaml ``` 规则示例： ``` # .lintropy/no-unwrap.rule.yaml severity: warning message: "avoid .unwrap() on `{{recv}}`; use .expect(\"...\") or ?" fix: '{{recv}}.expect("TODO: handle error")' language: rust query: | (call_expression function: (field_expression value: (_) @recv field: (field_identifier) @method) (#eq? @method "unwrap")) @match ``` 最小化的根配置： ``` version: 1 settings: fail_on: error default_severity: error ``` ## 为 Agent 工作流而生 其设计让 Codex、Claude Code 及类似的 agent 能够在无需过多提示开销的情况下编写出有效的规则。 - 一个文件对应一条规则 - 低门槛的 YAML - 确定性的仓库发现机制 - 可解释的诊断信息 - 对 schema 友好的配置 - 由 LSP 驱动的实时反馈，用于编辑后的交互循环 如果 agent 能够编写代码，它们也应该编写并遵守仓库的 guardrails。 ## 快速开始 `examples/rust-demo/` crate 同时也作为参考测试固件。Clone 该 仓库并运行： ``` cd examples/rust-demo lintropy check . ``` 你应该会看到跨越三个文件的四个警告（`no-unwrap`、`no-println`、`user-use-builder`、`no-todo`），以及一个提示，表明有一个可用的 autofix： ``` lintropy check . --fix # apply the no-unwrap autofix in place lintropy check . --fix-dry-run # print the unified diff instead ``` 其他支持的语言也提供了类似的单语言演示： - [`examples/go-demo/`](examples/go-demo) — `no-fmt-println`, `no-todo-comment` - [`examples/python-demo/`](examples/python-demo) — `no-print`, `no-todo-comment` - [`examples/typescript-demo/`](examples/typescript-demo) — `no-console-log`, `no-any-type`, `no-todo-comment`（涵盖 `.ts` 和 `.tsx`） 要在你自己的仓库中初始化 lintropy： ``` lintropy init # writes lintropy.yaml + .lintropy/no-unwrap.rule.yaml lintropy init --with-skill # also installs SKILL.md into detected agent skill dirs ``` 位于 [`skill/SKILL.md`](skill/SKILL.md) 的标准 `SKILL.md` 文件正是 `init --with-skill` 命令安装到 agent 技能目录中的内容。 ## 编辑器与 Agent 支持 Lintropy 内置了一个 LSP 服务器（`lintropy lsp`）以及一个安装命令，可将其接入到所有受支持的目标中： ``` lintropy install vscode # VS Code lintropy install cursor # Cursor lintropy install jetbrains # JetBrains IDEs (LSP4IJ template) lintropy install claude-code # Claude Code plugin + skill lintropy install codex # Codex plugin + skill ``` 每个目标环境都为你提供实时的诊断信息、quickfix、配置重载，以及针对 `query: |` DSL 的 semantic-token 高亮显示。无需单独安装“查询语法”扩展。详细的集成说明请参见 [`docs/integrations/`](docs/integrations/index.md)。 ### VS Code 和 Cursor ``` lintropy install vscode # or: cursor lintropy install cursor --profile Default ``` 将打包的扩展源码构建为 `.vsix`，并通过 `code --install-extension` / `cursor --install-extension` 进行安装。该扩展按以下顺序解析 `lintropy` 二进制文件：显式指定的 `lintropy.path` 设置 → `PATH` → 从匹配的 GitHub release 中由扩展管理的下载版本。 在不安装的情况下打包 `.vsix`（适用于 CI）： ``` lintropy install vscode --package-only -o ./lintropy.vsix ``` 配置解析是按文件进行的，而不是整个工作区统一一个根配置：每个源文件使用距离其最近的祖先 `lintropy.yaml`。新添加的嵌套 `lintropy.yaml` 会为该子树创建一个全新的规则上下文，而对 `.lintropy/` 的更改则会合并到已解析根目录的规则中，并重新为打开的文件发布诊断信息。 有关各设置的详细参考，请参见 [`editors/vscode/lintropy/README.md`](editors/vscode/lintropy/README.md)。 ### JetBrains IDEs ``` lintropy install jetbrains --dir ~/.lintropy ``` 将 [LSP4IJ](https://plugins.jetbrains.com/plugin/23257-lsp4ij) 自定义服务器模板解压到 `~/.lintropy/lsp4ij-template`。在 IDE 中只需一步导入操作： `View → Tool Windows → LSP Console → + → New Language Server → Template → Import from directory…` 选择解压后的目录。所有字段均已预填。包含手动设置回退方案的完整操作指南：[`editors/jetbrains/README.md`](editors/jetbrains/README.md)。 ### Claude Code 有两种方式，请选择与你的环境相匹配的一种。 **Marketplace（推荐）。** 在 Claude Code 内部： ``` /plugin marketplace add Typiqally/lintropy /plugin install lintropy-lsp@lintropy ``` 该 marketplace manifest 位于仓库根目录下，因此它可以在任何干净的 Claude Code 安装环境中生效 —— 无需 `lintropy` CLI。对于本地代码检出，可以使用：`/plugin marketplace add /absolute/path/to/lintropy`。 **CLI。** 当你希望插件 manifest 固定本地 `lintropy` 二进制文件的绝对路径时： ``` lintropy install claude-code ``` CLI 会重新生成插件 manifest（版本与 `lintropy` 同步，extension 映射范围限定为编译进程序的语言，`command` 解析为二进制文件的绝对路径），并将其写入 `./lintropy-claude-code-plugin/` 目录中，同时将 lintropy skill 打包在同一目录下的 `skills/lintropy/SKILL.md`，随后打印出你应该运行的 `claude --plugin-dir ` 命令。该 skill 会随插件一同加载和卸载。使用 `/reload-plugins` 可以在不重启的情况下应用修改。 ### Codex ``` lintropy install codex ``` 通过 `.agents/plugins/marketplace.json`，这个仓库本身就是一个本地的 Codex marketplace，因此你可以将 Codex 指向该检出目录： ``` codex marketplace add /absolute/path/to/lintropy ``` `lintropy install codex` 会将相同结构的内容生成到 `./lintropy-codex-marketplace/` 目录中，以便进行临时本地安装。该 marketplace 包含一个位于 `plugins/lintropy/` 下的镜像插件，其中有 `.codex-plugin/plugin.json` 以及打包好的 lintropy skill，位于 `skills/lintropy/SKILL.md`。这为 Codex 提供了仓库内规则编写和调试循环的原生 lintropy 指导。Codex 插件目前尚未开放用于编辑器端 LSP 注册的接口，因此要获取实时的诊断信息，你仍需安装上述的编辑器集成之一。 ### JSON Schemas 本仓库签入了适用于所有 lintropy YAML 配置文件的 JSON Schemas： - `editors/schemas/lintropy.schema.json` — 仓库根目录的 `lintropy.yaml` - `editors/schemas/lintropy-rule.schema.json` — `.lintropy/**/*.rule.yaml` - `editors/schemas/lintropy-rules.schema.json` — `.lintropy/**/*.rules.yaml` 在 `.vscode/settings.json` 和 `.idea/jsonSchemas.xml` 中的工作区设置会分别将它们接入到 VS Code / Cursor 以及 JetBrains IDEs 中。如果 schema 发生更改，请使用 `./scripts/export-editor-schemas.sh` 进行刷新。 ## 状态 Pre-1.0 阶段。CLI 接口已足够稳定，可以固定 tag；YAML schema 和诊断格式在 1.0 版本之前仍可能发生变化。请在 [GitHub](https://github.com/Typiqally/lintropy/issues) 上追踪进度并提交 issues。 ## 许可证 [MIT](LICENSE)

标签：Apache Flink, Rust, SOC Prime, Tree-sitter, 代码规范检查, 代码质量, 代码静态分析, 开发工具, 网络流量审计, 通知系统