diff --git a/AGENTS.md b/AGENTS.md index 8ce0d8d388..1d30644dcd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -204,7 +204,11 @@ PR"): it runs the same gates the PR lanes run (fmt, clippy, cargo-deny, the test suite, doctests; plus `just test-ignored` on Linux), dispatched for your OS, and then `clippy-strict`, which applies a stricter lint set to the lines your branch changed. Run `just clippy-strict` alone to see just -those. Platform notes for agents: +those. That gate is local only: no CI lane runs it, so its hits never turn +a PR red, and in a revise or conflict round the directive bounds the +change, so report its hits in `notes` rather than fix them. `just fix` +does not run it, so nothing in the edit loop asks you to. Platform notes +for agents: - **macOS**: the workspace does not build natively (see [Platform matrix](#platform-matrix)); `just ci` runs the darwin-capable @@ -213,7 +217,7 @@ those. Platform notes for agents: is unverified until `just test-cross` has run. - **VM/daemon-path changes**: also run `just e2e` (the session proof) and/or `just test-vm` (the VM integration harnesses). -- **Tight iteration loops**: `just fix` (fmt → `clippy --fix` → fmt, then the - strict clippy gate, with `--allow-dirty` so it runs mid-edit) then - `just test`. Both carry this host's scope; neither needs a hand-written - `cargo` line. +- **Tight iteration loops**: `just fix` (fmt → `clippy --fix` → fmt, with + `--allow-dirty` so it runs mid-edit) then `just test`. Both carry this + host's scope; neither needs a hand-written `cargo` line. Everything that + loop prints is something to fix; the strict gate is not in it. diff --git a/justfile b/justfile index 60ea601590..4610374079 100644 --- a/justfile +++ b/justfile @@ -271,18 +271,21 @@ fmt: # clean-worktree check — the usual case here is running mid-edit with # staged/unstaged work. # -# Autofix pass: fmt, clippy --fix, fmt again, then the strict clippy gate (runnable mid-edit). +# The strict clippy gate is not part of this loop. It ran here once, and +# three agent rounds on the NET walk then rewrote lines their task never +# named to clear it, two in conflict rounds whose only directive was the +# merge (#1737, #1730, #1727): everything else this recipe prints is +# something to fix, so a strict hit printed beside it reads the same way, +# whatever a doc says. There is no autofix for that set either — `clippy +# --fix` cannot be scoped to changed lines and would sweep legacy sites — so +# the gate lives in `just clippy-strict` and `just ci`, which is the round +# that owns the judgement. +# +# Autofix pass: fmt, clippy --fix, fmt again (runnable mid-edit). fix: cargo fmt --all cargo clippy {{scope}} --all-targets --fix --allow-dirty -- -D warnings cargo fmt --all - # No autofix for the strict set, and a hit fails this recipe. `clippy --fix` - # rewrites every hit in the selected crates and cannot be scoped to changed - # lines, so autofixing it would sweep legacy sites in every crate it - # touches. Most of the set has no machine-applicable suggestion anyway (6% - # of current hits, none of the four largest lints), so these are judgement - # calls, not rewrites. - scripts/clippy-strict.sh "" {{strict-scope}} # CI: ci.yml `fmt`. # @@ -301,9 +304,13 @@ clippy: # The lints below are the ones the tree is not yet clean for: CI's clippy job # runs `-D warnings`, so they live here rather than in Cargo.toml and only the # lines you changed are reported. Run it once your change is ready, fix what it -# reports in the files you touched, and promote each lint into +# reports on the lines your change introduced, and promote each lint into # [workspace.lints.clippy] as its count reaches zero. # +# This recipe and `just ci` are the only callers; `just fix` does not run it. A +# hit on a line the round's directive did not name is a note, not a licence to +# edit it. +# # Strict Clippy on the lines this branch changed, scoped to the crates you touched. clippy-strict BASE="": scripts/clippy-strict.sh "{{BASE}}" {{strict-scope}} diff --git a/scripts/clippy-strict.sh b/scripts/clippy-strict.sh index c4510292b7..7f38b335a4 100755 --- a/scripts/clippy-strict.sh +++ b/scripts/clippy-strict.sh @@ -19,7 +19,17 @@ # # Usage: scripts/clippy-strict.sh [BASE] [CARGO_SCOPE...] # -# BASE defaults to the merge-base with the main branch; only diagnostics whose +# Callers: `just clippy-strict` and, through it, `just ci`. Not `just fix`: that +# is the mid-edit loop, and everything it prints is something to fix, so a hit +# printed there reads as work whatever a doc says — the round's directive bounds +# what a change may touch, and a hit outside it belongs in the round's notes. +# +# Exit codes: 0 clean, 2 hits on changed lines, anything else a failure to run +# (cargo's own status, 127 with no python3, 1 for a crash in the filter). A gate +# that exits 0 because it could not run is worse than no gate, so none of those +# is ever read as clean. +# +# BASE defaults to the merge-base with `origin/main`; only diagnostics whose # primary span falls on a line added or changed since BASE are reported. Edits # that are not committed yet count, as do untracked files. Any further arguments # are passed to `cargo clippy` as the crate scope, overriding the derived one @@ -58,7 +68,24 @@ if [ "$#" -gt 0 ]; then shift fi if [ -z "$base" ]; then - base="$(git merge-base main HEAD 2>/dev/null || git merge-base origin/main HEAD)" + # `origin/main`, not the local `main`. A branch that merges `origin/main` + # leaves the local ref where it was — agent sandboxes and worktrees never + # check main out at all — and the merge-base against a ref that stale + # predates the main commits the branch merged in, so every line of those + # commits reads as a line this branch changed. The gate then reports + # diagnostics on other people's code, under a heading saying they are + # yours. That is what it looked like: on the branch adding this comment, + # a local `main` ten commits behind turned a change touching no Rust at + # all into 14 changed Rust files across `minimald`, `sessions` and + # `switch`. + # + # The remote ref is the safe one by construction: `origin/main` cannot be + # behind anything the branch merged, because merging it required fetching + # it first, and a fetch only moves it forward. Stale means the base is + # merely older than the newest main, never older than this branch's own + # first commit. The local ref is kept as a fallback for a clone with no + # remote. + base="$(git merge-base origin/main HEAD 2>/dev/null || git merge-base main HEAD)" fi explicit_scope=("$@") @@ -154,12 +181,18 @@ if [ "$status" -ne 0 ]; then exit "$status" fi -python3 - "$out_file" "$diff_file" "$untracked_file" "${lints[@]}" <<'PY' +# HITS_EXIT, and only HITS_EXIT, is the filter saying it found something. Any +# other non-zero is the filter itself failing — no python3 on PATH, a crash in +# it — and is said as such rather than read as clean. +HITS_EXIT=2 +hits_status=0 +python3 - "$HITS_EXIT" "$out_file" "$diff_file" "$untracked_file" "${lints[@]}" <<'PY' || hits_status=$? import json import sys -out_path, diff_path, untracked_path = sys.argv[1], sys.argv[2], sys.argv[3] -strict = set(sys.argv[4:]) +hits_exit = int(sys.argv[1]) +out_path, diff_path, untracked_path = sys.argv[2], sys.argv[3], sys.argv[4] +strict = set(sys.argv[5:]) # path -> [(start, end)] of lines added or changed in the new revision. changed = {} @@ -251,7 +284,15 @@ if hits: f'with #[expect(, reason = "...")]. Re-run: just clippy-strict', file=sys.stderr, ) - sys.exit(1) + # Distinct from the 1 an unhandled exception here would exit with, so the + # caller can demote hits without demoting a broken filter. + sys.exit(hits_exit) print("clippy-strict: clean") PY + +if [ "$hits_status" -ne 0 ] && [ "$hits_status" -ne "$HITS_EXIT" ]; then + echo "clippy-strict: the diagnostic filter failed (exit ${hits_status});" \ + "nothing was checked" >&2 +fi +exit "$hits_status"