Skip to content

chore(lint)!: make cargo clippy -- -D warnings pass, document build prerequisites, pin the gate in CI - #6

Merged
nusendra merged 5 commits into
mainfrom
chore/clippy-deny-warnings
Oct 28, 2026
Merged

nusendra merged 5 commits into
mainfrom
chore/clippy-deny-warnings

Conversation

@nusendra

@nusendra nusendra commented Oct 28, 2026 •

Copy link
Copy Markdown
Owner

Makes cargo clippy --workspace --all-targets -- -D warnings exit 0, documents the two build prerequisites that cost ~20 minutes to rediscover, and adds a CI job so the gate cannot rot again.

None of these findings are new — all of them reproduce on a pristine main.

CI found a 24th finding that my local toolchain cannot see. See A toolchain-dependent gate below — it changed the shape of the CI job, and it is the most important thing in this PR.

The real finding set was 23 on Rust 1.94, 24 on Rust 1.99

The follow-up card listed 13. That was a lower bound, because the ployer-core / ployer-git / ployer-server findings abort compilation under -D warnings, so clippy never reached the crates behind them. Measured instead without -D warnings and parsed from --message-format=json (46 raw diagnostics → 23 unique, after de-duplicating the lib / lib-test / bin passes over the same line):

crate findings
ployer-core 9
ployer-db 5 — all previously hidden
ployer-api 3 — all previously hidden
ployer-git 3
ployer-templates 2
ployer-server 1

By lint: should_implement_trait 8, too_many_arguments 6, new_without_default 2, unnecessary_map_or 2, and one each of derivable_impls, redundant_pattern_matching, single_match, collapsible_if, needless_borrows_for_generic_args.

Plus unnecessary_sort_by in ployer-api/src/routes/system.rs:104, which only exists on Rust 1.99 — see below.

A toolchain-dependent gate

The first CI run on this PR failed, which is worth reading as a result rather than an accident.

My local toolchain is 1.94; CI's stable is 1.99. Clippy 1.99 flags unnecessary_sort_by at system.rs:104, which 1.94 does not. So "the full set is 23" was never a property of the repo — it was a property of the toolchain I happened to measure with. The card asked for the true full finding set; the honest answer is that there isn't one without pinning a version.

Two consequences, both in c4ffb58:

1. Fixed the finding. Used sort_by_cached_key rather than clippy's suggested sort_by_key: version_key allocates a Vec<(u32, String)> per call and the old comparator recomputed it twice per comparison, so caching takes it from O(n log n) key computations to O(n). Order is unchanged — Reverse(key) ascending equals the old descending comparator, and both sorts are stable, so ties keep input order either way.

2. Pinned the lint toolchain. -D warnings on a floating stable means every six-week Rust release can red-light every open PR over a new lint unrelated to the change under review — the same rot this card exists to fix, pointing the other way. CI is now two jobs:

  • lint — toolchain pinned to 1.99.1, runs the clippy gate. Deterministic, so a clippy upgrade becomes its own reviewable PR that bumps the pin and fixes the new findings together. Upgrade procedure is in a comment at the top of the workflow.
  • test — floating stable, runs the suite. Genuine compiler and runtime regressions still surface, which is the breakage actually worth interrupting a PR for.

⚠️ Breaking change (commit 0f1f6fc)

Eight inherent constructors in ployer-core are renamed:

before after
BuildStrategy::from_str BuildStrategy::from_db_str
AppStatus::from_str AppStatus::from_db_str
DeploymentStatus::from_str DeploymentStatus::from_db_str
HealthCheckStatus::from_str HealthCheckStatus::from_db_str
ServerStatus::from_str ServerStatus::from_db_str
UserRole::from_str UserRole::from_db_str
WebhookProvider::from_str WebhookProvider::from_db_str
WebhookDeliveryStatus::from_str WebhookDeliveryStatus::from_db_str

Signatures (&str -> Self) and match arms are untouched, so behaviour is identical. All 32 call sites are updated in the same commit. Blast radius is this workspace only: every ployer-* crate is a path dependency of the ployer binary, nothing is published to crates.io, so no external consumer can break.

Why rename rather than implement FromStr

The card offered three options. Each of these functions is total, infallible, and lossy — an unrecognised value silently becomes a default variant:

WebhookProvider::from_str("bitbucket")  // => GitHub
UserRole::from_str("superadmin")        // => User

FromStr would need type Err = Infallible, which makes that fallback unobservable: s.parse()? would read like a successful parse and quietly hand back the wrong variant — on UserRole, a privilege decision. Implementing the trait and keeping the inherent method as a wrapper does not even silence the lint, since it fires on the method name. And naming a method from_str without implementing the trait is the same trap wearing the trait's clothes, which is exactly what should_implement_trait is pointing at.

from_db_str names what these actually are: readers for one specific database column, where tolerating an unknown value is deliberate — a row written by a newer schema must not render existing rows unreadable. Each now carries a doc comment stating its fallback variant and why FromStr was declined. UserRole's notes that it fails closed.

The six #[allow]s, and why

too_many_arguments is allowed on six functions rather than fixed, each with a comment at the site:

  • Five ployer-db writers (application::create 11, application::update 11, webhook::create_delivery 13, container_stats::record 8, server::update 8) — every argument is one SQL column. A params struct would duplicate the column list in a second place where it can drift from the statement without the compiler noticing, which is strictly worse than a long signature next to the SQL.
  • ployer-api::execute_deployment (10) — spawned as a detached task, so nothing can be borrowed from AppState; everything must be passed by value. Bundling it is a refactor of the deployment hot path, which does not belong in a lint fix.

Deliberately out of scope

  • cargo fmt. Measured: cargo +1.99.1 fmt --all -- --check reports ~325 unformatted hunks across nearly every file. A blanket reformat would bury git blame repo-wide; the card said to decide that separately rather than fold it in. CI runs it as continue-on-error: true — log-only visibility, not a gate. Note GitHub renders such a step green regardless of result, so do not read that check as "the tree is formatted".
  • MSRV. #[allow(lint, reason = "..")] is tidier than a comment but needs Rust 1.81, and DOCUMENTATION.md declares 1.75. Raising a documented MSRV is not a lint cleanup's call, so the allows use a plain attribute plus a // comment.
  • Switching reqwest to rustls-tls. That changes the shipped binary's TLS stack. Documented libssl-dev instead, as the card directed.
  • Refactoring the ployer-db repository signatures into params structs, and the execute_deployment argument list. Both are real refactors with their own risk; they belong in their own PR, not behind a lint fix.

Build prerequisites, now documented

Both were already encoded in release.yml but nowhere a human would look.

  • libssl-dev — reqwest's default native-tls feature pulls in openssl-sys, which fails on the first dependency, long before any Ployer code compiles. Documented per distro, with the verbatim error so it is searchable.
  • SQLX_OFFLINE=true — without it, .cargo/config.toml points DATABASE_URL at sqlite://ployer.db?mode=rwc, and mode=rwc creates an empty database in the cwd. Every sqlx::query! then fails with no such table, which misleads you toward running migrations when the fix is offline mode. The committed .sqlx/ metadata is correct and current.

Verification

Against the pinned toolchain, in an isolated CARGO_TARGET_DIR:

cargo +1.99.1 clippy --workspace --all-targets -- -D warnings   # exit 0
SQLX_OFFLINE=true cargo +1.99.1 test --workspace                # 137 passed, 0 failed

Authoritative result: CI on this branch is green — Clippy (pinned 1.99.1) and Tests (stable) both pass. That is the verification that counts, since it is the only one running on a clean machine.

Two caveats on my local numbers, for whoever reviews this:

  • An earlier round of local runs shared a CARGO_TARGET_DIR with another worktree on a different branch and produced one bogus failure (no field 'icon' on type IndexEntry) from a stale cross-branch rlib. Everything reported here was re-run in an isolated target dir. If you verify locally, do not point CARGO_TARGET_DIR at a tree you are also building elsewhere.
  • Clippy was re-run after cargo clean -p on all eight workspace crates, so the lint result is from-scratch rather than a warm-cache artifact.

Because this PR adds a gate that will run against the other open PRs, both were test-merged against this branch and checked:

merged with clippy tests
#3 fix/app-slug-placeholder exit 0 141 passed, 0 failed
#4 chore/drop-dead-template-icon-field exit 0 137 passed, 0 failed

Both merge without conflict in either order. The two ployer-templates fixes here are byte-for-byte the same edits as #3, which is why that overlap resolves cleanly. Those two runs predate the 1.99.1 pin, so once this lands, expect #3 and #4 to need the same one-line sort_by_cached_key fix only if they touch system.rs — neither does.

Five commits, reviewable in order: 15 non-breaking fixes → the rename → docs and CI → the pinned toolchain and its 24th finding → a docs correction. No deploy.

Mechanical fixes only; no behaviour change, no signature change.

ployer-core
  - BuildStrategy: derive Default with #[default] instead of a manual impl
    (derivable_impls).

ployer-git
  - GitService: derive Default (new_without_default).
  - Two Option::map_or(false, ..) -> Option::is_some_and (unnecessary_map_or).

ployer-server
  - ServerManager: add Default forwarding to new(), which logs, so it cannot
    be derived (new_without_default).

ployer-templates
  - compose.rs: drop a needless borrow on Mapping::remove.
  - render.rs: collapse a nested if.
  These two are the same edits as #3, byte for byte, so the
  branches merge without conflict in either order.

ployer-api
  - domains.rs: `if let Some(_) = ..` -> bind, then `.is_some()`.
  - deployment.rs: single-arm match -> `if let`/`.is_ok()`.
  - deployment.rs: execute_deployment keeps its 10 arguments behind an
    #[allow(.., reason = ..)]; it is spawned detached so nothing can be
    borrowed from AppState, and bundling the arguments is a refactor of the
    deployment path, not a lint fix.

ployer-db
  - Five repository writers keep their argument lists behind
    #[allow(.., reason = ..)]: each argument is one SQL column, and a params
    struct would duplicate the column list where it can drift from the
    statement without the compiler noticing.

Verified: SQLX_OFFLINE=true cargo test --workspace -> 137 passed, 0 failed.
Remaining after this commit: 8x should_implement_trait in ployer-core.
…_str`

BREAKING CHANGE: eight inherent constructors in ployer-core are renamed.

  BuildStrategy::from_str          -> BuildStrategy::from_db_str
  AppStatus::from_str              -> AppStatus::from_db_str
  DeploymentStatus::from_str       -> DeploymentStatus::from_db_str
  HealthCheckStatus::from_str      -> HealthCheckStatus::from_db_str
  ServerStatus::from_str           -> ServerStatus::from_db_str
  UserRole::from_str               -> UserRole::from_db_str
  WebhookProvider::from_str        -> WebhookProvider::from_db_str
  WebhookDeliveryStatus::from_str  -> WebhookDeliveryStatus::from_db_str

Signatures are otherwise unchanged (`&str -> Self`) and the match arms are
untouched, so behaviour is identical. All 32 call sites in this workspace are
updated in the same commit; there is no external consumer, since every
ployer-* crate is a path dependency of the `ployer` binary.

Why rename instead of implementing `FromStr`:

Each of these is a total, infallible, *lossy* function — an unrecognised value
silently becomes a default variant (`"bitbucket"` -> `WebhookProvider::GitHub`,
`"superadmin"` -> `UserRole::User`). `FromStr` would have to use
`Err = Infallible`, which makes that fallback unobservable: `s.parse()?` would
read like a successful parse and quietly hand back the wrong variant. Naming
the method `from_str` without implementing the trait is the same trap wearing
the trait's clothes, which is precisely what clippy::should_implement_trait
objects to.

`from_db_str` says what these are: readers for one specific database column,
where tolerating an unknown value is the point — a row written by a newer
schema must not make existing rows unreadable. Each now carries a doc comment
stating the fallback variant and why `FromStr` was declined.

This clears the last 8 of the 23 clippy findings on this branch.
`cargo clippy --workspace --all-targets -- -D warnings` now exits 0, and
SQLX_OFFLINE=true cargo test --workspace passes 137/137.
Both prerequisites were already encoded in release.yml but nowhere a human
would look, which is why they cost ~20 minutes to rediscover.

DOCUMENTATION.md
  - Prerequisites gains OpenSSL headers, with the package name per distro,
    the reason (reqwest's default native-tls feature pulls in openssl-sys),
    and the verbatim error so it is searchable.
  - A new subsection on SQLX_OFFLINE=true: what breaks without it, why the
    error says "no such table" rather than "no database", and that the fix
    is offline mode and not running migrations.
  - A new "Development Checks" section with the two gate commands and the
    house rule for lint exceptions: narrowly scoped #[allow] on the item with
    a comment, never a wider gate.

README.md
  - One line under Requirements pointing source builders at the above; the
    existing list is about running a release binary, not building one.

.github/workflows/ci.yml (new)
  - Runs `cargo clippy --workspace --all-targets -- -D warnings` and
    `cargo test --workspace` on pushes to main and on every PR, so the gate
    cannot rot again. Mirrors release.yml: same stable toolchain action, same
    libssl-dev/pkg-config step, same Swatinem/rust-cache, SQLX_OFFLINE in the
    workflow env.
  - `cargo fmt --check` is included as continue-on-error only. The tree is not
    rustfmt-clean on main; making it blocking would either fail on arrival or
    force a tree-wide reformat that buries git blame. Advisory keeps the
    backlog visible without pretending it is decided.

Lint attributes use a plain #[allow] plus a comment rather than the tidier
`reason = ".."` form: `reason` needs Rust 1.81 and DOCUMENTATION.md declares an
MSRV of 1.75. Raising the MSRV is not a lint cleanup's call to make.
The first CI run on this PR failed, which is the gate doing its job and also
exposing a design flaw in how I had set it up.

1. A 24th finding, invisible locally

   crates/ployer-api/src/routes/system.rs:104 trips unnecessary_sort_by on
   Rust 1.99 (CI) but not on 1.94 (the toolchain I measured the other 23 with),
   so the "full set" of 23 was itself relative to a toolchain version.

   Fixed with sort_by_cached_key rather than clippy's suggested sort_by_key:
   version_key allocates a Vec<(u32, String)> on every call, and the old
   comparator recomputed it twice per comparison. Caching drops that to one key
   per element. Order is unchanged -- Reverse(key) ascending is the same as the
   old descending comparator, and both sorts are stable, so ties keep input
   order either way.

2. The gate was pinned to a moving target

   `-D warnings` on a floating `stable` toolchain means every six-week Rust
   release can red-light every open PR over a new lint unrelated to the change
   under review. That is the same rot this card set out to fix, just pointing
   the other way.

   CI is now two jobs:
     - lint: toolchain pinned to 1.99.1, runs the clippy gate. Deterministic,
       so a clippy upgrade is its own reviewable PR that bumps the pin and
       fixes the new findings together. The upgrade procedure is in a comment
       at the top of the workflow.
     - test: floating stable, runs the suite. Genuine compiler and runtime
       regressions still surface, which is the kind of breakage worth
       interrupting a PR for.

Verified against the pinned toolchain, in an isolated CARGO_TARGET_DIR:
  cargo +1.99.1 clippy --workspace --all-targets -- -D warnings  -> exit 0
  SQLX_OFFLINE=true cargo +1.99.1 test --workspace               -> 137 passed
Measured: cargo +1.99.1 fmt --all -- --check reports ~325 unformatted hunks
across nearly every file, so the 'not rustfmt-clean' premise holds. But the
previous wording said fmt was 'not in CI yet' when the workflow does run it;
it is non-blocking, which is a different claim. Also notes that GitHub reports
a continue-on-error step as green whatever it returns, so a reader does not
mistake the green check for a clean tree.
@nusendra
nusendra merged commit f314846 into main Oct 28, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant