Typiqally/lintropy

Lintropy is a linter for rules your repo actually cares about. It started at [The IDE Reimagined: JetBrains Codex Hackathon](https://cerebralvalley.ai/e/jetbrains-x-openai-hack), a two-day San Francisco event focused on building AI-powered developer tools alongside JetBrains and OpenAI engineers. Most linters ship a fixed catalog. Lintropy does the opposite: rules live in your repo, one YAML file at a time, describing **your** conventions: - API code must live in `src/api/` - feature modules cannot import each other directly - `dbg!`, `println!`, or `.unwrap()` are banned outside tests - migrations require rollback files - only one module can touch `process.env` Linting for architecture, boundaries, migration policies, and team ceremony — not just style. ## 安装 ### Homebrew（macOS 和 Linux） ``` brew tap Typiqally/lintropy brew install lintropy ``` ### 从源代码安装 Stable Rust 1.95 or newer required. ``` cargo install --path . ``` Not yet on crates.io. ## 支持的语言 - **Rust**, **Go**, **Python**, **TypeScript** (incl. `.tsx`) — structural `query` rules via tree-sitter - **Any text file** — regex `match` rules More tree-sitter languages planned. Vote or contribute via 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 Generic linters are great at universal rules. They are weak at codebase-local rules that only make sense inside one company, one monorepo, or one product. Lintropy fills that gap: - rules stored in the repo, versioned alongside the code they govern - rules easy to review - rules simple enough for agents to generate - diagnostics tell you which rule file fired - tree-sitter handles structure, regex handles plain text | | Generic linters | Lintropy | |---|---|---| | Rule source | Built into the tool | Lives in your repo | | Authoring | Plugin code or complex config | Small YAML files | | Scope | Language-wide conventions | Project-specific constraints | | Best use | Style and correctness | Architecture and boundaries | | Agent support | Incidental | First-class | ## 工作原理 Two rule types: - `query`: tree-sitter rules for structural patterns - `match`: regex rules for text patterns Typical layout: ``` . ├── lintropy.yaml └── .lintropy/ ├── no-unwrap.rule.yaml ├── no-dbg.rule.yaml └── architecture/ └── api-only-in-src-api.rule.yaml ``` Example rule: ``` # .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 ``` Minimal root config: ``` version: 1 settings: fail_on: error default_severity: error ``` ## 为代理工作流而构建 Designed so Codex, Claude Code, and similar agents can write valid rules without much prompting overhead. - one rule per file - low-ceremony YAML - deterministic repo discovery - explainable diagnostics - schema-friendly config - hook-based workflows for post-edit feedback If agents write code, they should write and respect the repo's guardrails too. ## 快速入门 The `examples/rust-demo/` crate doubles as the reference fixture. Clone this repo and run: ``` cd examples/rust-demo lintropy check . ``` You should see four warnings (`no-unwrap`, `no-println`, `user-use-builder`, `no-todo`) across three files, plus a hint that one autofix is available: ``` lintropy check . --fix # apply the no-unwrap autofix in place lintropy check . --fix-dry-run # print the unified diff instead ``` Analogous single-language demos ship for the other supported languages: - [`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` (covers `.ts` and `.tsx`) To scaffold lintropy inside your own repo: ``` lintropy init # writes lintropy.yaml + .lintropy/no-unwrap.rule.yaml lintropy init --with-skill # also installs SKILL.md + wires the Claude Code hook ``` The canonical `SKILL.md` at [`skill/SKILL.md`](skill/SKILL.md) is what `init --with-skill` installs into agent skill directories. ## 编辑器支持 This repo checks in JSON Schemas for all lintropy YAML surfaces: - `editors/schemas/lintropy.schema.json` for repo-root `lintropy.yaml` - `editors/schemas/lintropy-rule.schema.json` for `.lintropy/**/*.rule.yaml` - `editors/schemas/lintropy-rules.schema.json` for `.lintropy/**/*.rules.yaml` Refresh them after schema changes with: ``` ./scripts/export-editor-schemas.sh ``` ### 一条命令，任意编辑器 ``` lintropy install-editor vscode # or: cursor lintropy install-editor jetbrains --dir ~/.lintropy ``` For VS Code / Cursor this installs a single extension: an LSP client that delivers diagnostics, quickfixes, config-reload, **and** semantic-token highlighting for the `query:` DSL — all over LSP, no separate grammar extension. For JetBrains this unpacks the LSP4IJ template (which in turn delivers diagnostics + `query:` highlighting from the same server). Still needs one IDE-side import step — see [JetBrains IDEs](#jetbrains-ides) below. The rest of this section covers the per-editor details, JSON schema mappings for editor-side YAML completion, and the underlying building-block commands. ### VS Code / Cursor Workspace settings in `.vscode/settings.json` associate those schemas with the matching files, and `.vscode/extensions.json` recommends `redhat.vscode-yaml`. Cursor uses the same workspace settings, so completions, hover docs, and validation work there as well. #### 扩展安装 ``` lintropy install-editor vscode # or: cursor ``` Under the hood this calls `lintropy install-lsp-extension vscode`, which downloads the matching `.vsix` from the GitHub release and hands it to `code --install-extension`. The extension registers `.rs` files plus `lintropy.yaml` / `.lintropy/**/*.yaml` as LSP documents; live diagnostics flow for the Rust files and semantic-token highlighting flows for the `query: |` DSL inside the YAML rule files. No separate "query syntax" extension to install. Once installed, the extension resolves the `lintropy` binary in this order: explicit `lintropy.path` setting → PATH lookup → automatic download from the matching GitHub release into the extension's global storage (controlled by `lintropy.binarySource`). So `install-editor vscode` followed by opening a Rust file is sufficient even on a machine where `lintropy` is not on PATH. Other settings: `lintropy.enable`, `lintropy.trace.server`, `lintropy.binarySource` (see [`editors/vscode/lintropy/README.md`](editors/vscode/lintropy/README.md)). Contributors with a checkout can build + install the local `.vsix` directly: ``` cd editors/vscode/lintropy npm install && npm run compile npx vsce package -o lintropy.vsix code --install-extension lintropy.vsix ``` ### JetBrains IDEs Shared mappings live in `.idea/jsonSchemas.xml`, pointing JetBrains IDEs at the same checked-in schema files for: - `lintropy.yaml` - `.lintropy/**/*.rule.yaml` - `.lintropy/**/*.rules.yaml` If your IDE ignores shared `.idea` files, add the same three mappings manually under `Languages & Frameworks | Schemas and DTDs | JSON Schema Mappings`. #### LSPIJ 安装 ``` lintropy install-editor jetbrains --dir ~/.lintropy ``` This unpacks the LSP4IJ custom server template to `--dir/lsp4ij-template/`. Still needs one import step in the IDE (JetBrains has no equivalent of `code --install-extension`). ##### LSP4IJ 服务器导入 JetBrains IDEs plug into `lintropy lsp` through the [LSP4IJ](https://plugins.jetbrains.com/plugin/23257-lsp4ij) community plugin. Works on all JetBrains IDEs including free Community editions. After `install-editor jetbrains --dir ~/.lintropy`, in your IDE: `View → Tool Windows → LSP Console → + → New Language Server → Template → Import from directory...` and pick `~/.lintropy/lsp4ij-template`. All fields (name, command, `*.rs → rust` mapping) are pre-filled. Full walkthrough including manual-setup fallback and troubleshooting: [`editors/jetbrains/README.md`](editors/jetbrains/README.md). ## 状态 Pre-1.0. CLI surface stable enough to pin a tag; YAML schema and diagnostic format may change before 1.0. Track progress and file issues on [GitHub](https://github.com/Typiqally/lintropy/issues). ## 许可证 [MIT](LICENSE)

标签：AST解析, Go, Linter, pptx, Python, Repo级规则, Ruby工具, Rust, SEO: architecture lint, SEO: boundary rules, SEO: repo-native linting, SEO: tree-sitter linter, SEO: YAML lint, TypeScript, YAML配置, 云安全监控, 代码约定, 代码规范, 可视化界面, 团队约定, 多语言支持, 安全插件, 安全测试框架, 无后门, 架构约束, 树形解析, 树状扫描, 网络流量审计, 自定义规则, 边界规则, 通知系统, 静态分析