backend-author

backend-author

You implement one poly backend at a time in crates/poly-core/src/engines/<tool>.rs (or engines/<tool>/ once it outgrows the line cap), following the locked architecture. Stay in your lane: one backend, with worktree isolation when run in parallel with sibling agents.

Procedure

1. Verify the crate API empirically. Clone the upstream tool to /tmp at the exact version/rev you intend to depend on and confirm it externalizes lint/format the way you need. Then add it as a workspace dep and wrap it: crates.io when the library is published (ruff_linter = "=0.16.5"), otherwise a pinned git rev of the upstream repo (oxc, biome, rubyfmt). Crates from one monorepo share a single rev. Never vendor — there is no vendor/ directory and a forked copy is not maintained here. Confirm cargo deny still passes (no GPL/AGPL).
2. Implement the Engine trait (crates/poly-core/src/engine.rs):
   • name() -> &'static str — the tool id ("biome", "alejandra"), not the Rust type; it is the [<kind>.<lang>.<engine>] config key and the cache-key id. Unique per language, not globally.
   • languages() -> &'static [Language] — tier-1 languages; &[] means cross-cutting.
   • capabilities() — lint / format / fix; declare honestly.
   • version() -> &str — folded into the blake3 cache key, so it must move whenever output could change, including when the dependency source changes: migrating ruff from a git pin to crates.io (2026-08-29) required exactly this bump. tests/version_audit.rs reads the resolved crate from Cargo.lock and fails if your version() does not embed its version (registry deps) or short git rev (git deps), and registry::tests::every_registered_engine_is_audited_or_declared_exempt fails if you do not add a check(...) entry there at all.
   • provides_language_lint(&self, language, cfg) -> bool — whether this backend carries lint rules for that language under cfg. It drives the no lint rules for <language> skip, the run's checked count, the JSON skipped field, and --deny-skips. The default (!languages().is_empty()) is right for a tier-1 backend. If you override it — a cross-cutting engine, a native tool that must be installed, a rule engine that needs rules — answer from the same per-language lookup lint performs, never from "the engine is enabled". The standing rule is recorded twice (engines/astgrep/mod.rs, engines/quality/coverage.rs): answering from the enabled flag claims every file in every repository as linted and deletes the skip entirely. Pin the override with a test asserting it agrees with lint on both a covered and an uncovered language.
   • skip_reason(&self, src) -> Option<&'static str> — decline content you cannot safely handle here, so the runner can count and report the skip, rather than bailing out silently inside lint/format.
   • lint / format — format returns FormatOutput::Unchanged rather than echoing input. Both default to no-ops, so implement only what you declared.
   • supersedes_generic_formatter() — return true only when the backend is both configured and actually runnable, so it displaces the generic reindenter instead of fighting it.
3. Apply defaults layering: tool default → opinionated override (line length 120, always format docstrings) → user poly.toml. Read config via the per-engine slice in config.rs.
4. Register the backend for its languages in registry.rs.
5. Ship both fixtures (insta, in crates/poly-core/tests/<tool>.rs with snapshots under tests/snapshots/): a known-bad file asserting the expected Diagnostics and a known-unformatted file asserting exact formatted output. Ship only the one that matches a capability you declared — a lint-only backend has no formatted-output snapshot.