Backend coverage

poly resolves every file through a tiered model:

1. Curated Rust backends for high-fidelity lint and format support.
2. Native-toolchain backends for canonical first-party formatters — plus shellcheck — when configured or present on PATH.
3. Tree-sitter generic formatting for identified languages without a dedicated backend.
4. Optional catalog tools from the embedded registry.

The curated Rust backends ship as engine components (web, python, sql, php, biome, ruby, nix, astgrep, misc, typos). A bundled build links them all in; a core build downloads the ones a run needs. Either way they are configured the same way, as [engines.<id>]. See Components and offline use; poly components list names the engines in each component.

Language table

Language or files	Backend	Lint	Format
JavaScript / TypeScript / JSX / TSX	oxc	yes	yes
JSON / JSONC	oxc parse diagnostics + formatter	yes	yes
Python	ruff internals	yes	yes
Python (type checking)	opt-in ty project check ([engines.python-types] backend = "ty"; imports resolve through the detected virtualenv’s site-packages)	opt-in	no
TOML	taplo (lint) + oxc_formatter_toml (format; taplo’s formatter when a taplo layout key is set)	yes	yes
Markdown	rumdl (lint) + oxc_formatter_markdown (format; rumdl’s fixer when a rumdl rule key is set)	yes	yes
Markdown ADRs (NNNN-*.md)	adrlint (opt-in MADR structural rules)	opt-in	no
SQL	sqruff	yes	yes
YAML	serde_yaml (libyaml, the grammar PyYAML implements) + oxc_formatter_yaml	yes	yes
CSS / SCSS	oxc_formatter_css (format; malva when a malva key is set) + biome (lint)	yes	yes
Less	oxc_formatter_css (malva when a malva key is set)	no	yes
HTML / Vue / Svelte / Astro / Angular / templates / XML	markup_fmt	no	yes
GraphQL	graphql-parser + pretty_graphql (parse-error lint + format) + biome (rule lint)	yes	yes
HCL / Terraform	hcl-edit (lint) + a port of hclwrite.Format (the layout terraform fmt and terragrunt hclfmt produce)	yes	yes
Dockerfile (Dockerfile, Dockerfile.*, Dockerfile-*, *.dockerfile, Containerfile, …)	vendored dockerfile-parser, hadolint-style rules	yes	no
.env files (.env, .env.*, *.env)	dotenv-analyzer	yes	no
INI and compatible (.ini, .cfg, .desktop, .npmrc, .editorconfig, .pylintrc, .coveragerc, .flake8, …)	rust-ini	yes	no
Nix	alejandra	no	yes
Ruby (*.rb, Gemfile, Rakefile, *.gemspec, *.rake, *.ru, Podfile, …)	rubyfmt	no	yes
PHP	mago	yes	yes
R	opt-in styler (via Rscript), tree-sitter fallback otherwise	no	yes
Go	gofmt when present (default-on), imports grouped as goimports does; tree-sitter fallback otherwise	no	yes
Rust	rustfmt when present (default-on), tree-sitter fallback otherwise	no	yes
Zig	opt-in zig fmt, tree-sitter fallback otherwise	no	yes
Java	opt-in google-java-format, tree-sitter fallback otherwise	no	yes
Kotlin	opt-in ktfmt, tree-sitter fallback otherwise	no	yes
Swift	opt-in swift-format, tree-sitter fallback otherwise	no	yes
Dart	opt-in dart format, tree-sitter fallback otherwise	no	yes
Gleam	opt-in gleam format, tree-sitter fallback otherwise	no	yes
Shell	shellcheck and shfmt when present (both default-on), tree-sitter fallback otherwise	optional	yes
Starlark / Bazel (BUILD, *.bzl, WORKSPACE, Tiltfile, …)	opt-in buildifier recipe tool, tree-sitter fallback otherwise	opt-in	yes
All text files	opt-in typos spell-check ([engines.typos] enabled = true)	opt-in	no
Any recognized language	opt-in uncomment comment removal	opt-in	no
Other identified grammars	tree-sitter generic tier	no	best effort

Unsupported or unknown file types are skipped unless tree-sitter-language-pack can identify them. Some whitespace-sensitive data, template or patch grammars intentionally no-op rather than risk a destructive rewrite. Lock files (Cargo.lock, pnpm-lock.yaml, yarn.lock, …) are never linted or formatted.

Enablement is a universal key, not a per-backend property

“opt-in” and “default-on” above describe each backend’s own default. Every engine table also accepts an explicit enabled, which always wins over that default — [engines.zigfmt] enabled = true turns on an opt-in formatter, and [engines.ruff] enabled = false turns off a default-on one. See Turning one engine off.

Batching native tools

A native tool runs once per file by default. batch = true in its table hands it many files per invocation instead — [engines.<tool>] for gofmt, shfmt, zigfmt, ktfmt, google-java-format, dartfmt, gleamfmt and shellcheck. Output is identical to the per-file path; whether it is faster depends on file sizes and machine load, which is why it is opt-in. rustfmt, swift-format and styler cannot be batched.

Shell indentation

shfmt takes its indentation from the file’s .editorconfig (indent_style, indent_size) as shfmt itself would, falling back to poly’s two spaces. [engines.shfmt] indent_width = N or use_tabs = true overrides it; indent_width cannot be 0 (shfmt’s “indent with tabs”), so use use_tabs for that.

The two cross-cutting lint tiers

Beyond the dedicated backends above, two lint tiers run on every language:

• The native quality metric engine — file and function length, type length, parameter count, nesting depth, cyclomatic complexity, lazy ignore markers, and test files the runner will not collect. See code quality metrics.
• A built-in ast-grep rule pack of 26 rules across C#, Elixir, Go, Java, Kotlin, Python, Ruby, Rust and Swift. 13 are on by default; the other 13 author their own severity: off and are one extend_select away.

A pack rule whose findings are concentrated in generated or test code declares those paths in its own YAML, with the standard ast-grep ignores: key — placeholder-implementation excludes **/*_generated.rs, force-cast excludes **/RustBridge/**, not-null-assertion excludes Kotlin test source sets, and unwrap-used excludes test and generated paths. Those are defaults: a [per_file_ignores] entry naming the rule replaces them, and every finding they drop is listed in the run’s suppressed array. See per-file ignores.

Both run in-process alongside the backends in the table, at warning severity — so neither fails an unconfigured CI on its own.

Coverage is claimed, never assumed

Both tiers answer “did anything lint this file?” from the same lookup their linting performs, not from “the engine is switched on”. A language the quality tier can parse but cannot model still reports no lint rules for <language> rather than being counted as linted.

Backend notes

Architecture decision records

Numbered ADR files (NNNN-*.md) can additionally be checked against the MADR template by the opt-in adrlint backend. It is separate from rumdl on purpose: rumdl judges the Markdown, adrlint judges the decision record’s section structure, front-matter metadata, list style and document-local link anchors. Enable it with [engines.adrlint] enabled = true.

It runs the document rules only. Directory numbering and file names (MADR41–MADR44), the immutability lock (ADR50/ADR51), link-target existence (MADR12a/MADR12c) and external links (MADR11) depend on the rest of the tree or the network, which a per-file, content-hash-cached engine cannot model honestly; the adrlint CLI remains the tool for those. See architecture decision records.

Reaching an oxlint plugin

oxlint compiles in whole plugins that its default set (unicorn, typescript, oxc) leaves switched off — vitest, jest, jsx-a11y, promise, import, node, vue and others. Rule selection cannot turn one on: a filter resolves only against the rules of plugins that are already enabled, so extend_select = ["vitest/expect-expect"] on its own does nothing at all. Name the plugin instead:

[engines.oxc]
plugins = ["vitest"]

The plugin’s correctness rules come on with it, and poly’s own categories are layered on top, so the rules then behave like any other. An unrecognised plugin name fails the run rather than being ignored — a dropped name would leave you believing a rule set is live over a run that checks nothing of the kind.

dotenv

.env files autofix with poly lint --fix, and inline # dotenv-linter:off <Check> / # dotenv-linter:on <Check> comments suppress a check for the lines between them — the same directive syntax the standalone dotenv-linter CLI understands.

Rules: DuplicatedKey, EndingBlankLine, ExtraBlankLine, IncorrectDelimiter, KeyWithoutValue, LeadingCharacter, LowercaseKey, QuoteCharacter, SpaceCharacter, SubstitutionKey, TrailingWhitespace, UnorderedKey, ValueWithoutQuotes, SchemaViolation.

INI is lint-only, by design

rust-ini’s parser discards comments while parsing, so writing its model back out would silently delete every comment in the file. poly never does that — INI formatting stays with the tree-sitter generic tier instead, which preserves comments structurally.

Rules: parse-error (a real syntax error, with the parser’s own line and column), duplicate-key, duplicate-section, key-without-value, inconsistent-separator, trailing-whitespace.

Detection is deliberately narrow. These are never treated as INI:

• *.conf — most are not INI; nginx, httpd and friends use their own syntax.
• *.properties — Java’s key=value syntax, not INI’s.
• .gitconfig — quoted subsections rust-ini cannot parse.
• systemd units — duplicate keys are legal there.

The tree-sitter generic tier

The generic tier identifies and best-effort formats hundreds of grammars, including first-class detection for C, C++, Elixir, Protobuf and the long tail covered by tree-sitter-language-pack. Java and Kotlin reach it only as the fallback when their opt-in native formatter is absent; both, along with C, C++, C# and Ruby, are languages the cross-cutting code-quality tier lints in full.

The optional tool catalog

For everything else, opt into tools from the embedded mdsf catalog. Entries are PATH-probed and skipped when absent, so enabling one never breaks a run:

[tools.prettier]
enabled = true
files = "**/*.{js,ts}"

A fix command is never run as a linter

A tool whose lint command rewrites files (sqruff fix, rubocop --autocorrect, pyupgrade) is not run by poly lint — a fix command would overwrite your source and still exit 0. Enabling one for linting logs a warning naming the tool and the command it refused. poly fmt still runs it as a formatter.

Tool catalogAll 348 catalog tools across 175 languages, with the type and languages each one covers.