poly-overview

<!-- AI-RULEZ :: GENERATED FILE — DO NOT EDIT Content-Hash: blake3:273b80b1cc5f091780eac739023a29774686024091327f99c639532e042d2ff6 Source-Hash: blake3:840c919261146454e2836095406355dd3ba8664fc068055c202682015400e43f Schema-Version: v1 --> # poly Overview poly is a single pure-Rust binary that lints and formats a whole repository across languages. It wraps best-in-class tools as in-process crate backends and falls back to a tree-sitter generic tier for everything else, so it runs the same on any machine and in CI. No system tool is ever *required*; the one scoped exception is the native-toolchain tier below, which uses a language's canonical CLI when it happens to be installed. ## Per-language coverage tiers - **Tier 1 — native in-process backends.** Highest fidelity, compiled straight into the binary and registered per language in `registry.rs`: `ruff` (Python), `oxc` (JS/TS/JSX/TSX/JSON/JSONC), `taplo` (TOML), `rumdl` (Markdown/MDX), `sqruff` (SQL), YAML, `malva` (CSS/SCSS/LESS) + `biome` (CSS/SCSS), `markup_fmt` (HTML/Vue/Svelte/Astro/Angular/Jinja/ Vento/Mustache/XML), `mago` (PHP), `rubyfmt` (Ruby), `graphql` + `biome` (GraphQL), `nixfmt` (Nix), `hcl`, Dockerfile, dotenv, and INI. - **Tier 2 — tree-sitter generic tier.** The catch-all for the long tail (Elixir, C/C++, C#, protobuf, and the rest of 300+ grammars). CST-driven structural reindent for brace-family grammars, whitespace normalization otherwise, and a `LEAVE_UNTOUCHED` list for grammars where whitespace is significant. Best-effort, pure Rust, grammars loaded on demand — never gofmt/rustfmt parity, by design. - **Native-toolchain tier (scoped exception).** A language's canonical first-party CLI run per file over stdin/stdout when installed: `rustfmt`, `gofmt` and `shellcheck` are **on by default when found on PATH**; `zig fmt`, `shfmt`, `google-java-format`, `ktfmt`, `styler` (R), `swift-format`, `dart format`, and `gleam format` are opt-in via `[fmt.<lang>.<tool>] enabled = true` / `[lint.<lang>.<tool>] enabled = true`. When the tool is absent, formatting falls through to tier 2 with an info-level notice, so the zero-dependency guarantee always holds. ## Cross-cutting engines (every language) Four engines are appended to every language regardless of tier: - **`typos`** — spelling in identifiers, comments, and strings. - **`quality`** — structural code-quality metrics off the tree-sitter parse: file/function/ type length, nesting depth, cyclomatic complexity, parameter count, and `lazy-ignore`. Warning severity, on by default. The structural rules need a verified node-kind table and run for Python, Rust, Go, JavaScript, TypeScript, TSX, Java, Kotlin, C, C++, C#, and Ruby; `magic-number` and `law-of-demeter` are opt-in. Configure under `[lint.quality]`. - **`astgrep`** — ast-grep pattern rules. poly embeds a **built-in rule pack** of 26 rules across 9 languages (C#, Elixir, Go, Java, Kotlin, Python, Ruby, Rust, Swift), on by default; 13 of them ship `severity: off`. User rules under `[rules] dirs` (default `.poly/rules`) layer on top and replace a pack rule sharing its `id`. Disable the pack wholesale with `[rules] builtin = false`. - **`uncomment`** — opt-in comment removal, off unless `[lint.uncomment] enabled = true`. ## When to use it Reach for poly as the single lint/format gate for any repo: local dev, git hooks, and CI. It replaces invoking ruff / oxlint / rustfmt / prettier individually — one binary, one `poly.toml`, one report. A language with no native backend still gets tier-2 formatting plus the cross-cutting engines, so poly covers the whole tree rather than only the languages you wired up by hand.