Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Refine kondo ratchet commands and prompts (#81776)

Chris Truter30f9f25ba959
diff --git a/.claude/skills/_shared/clojure-style-guide.md b/.claude/skills/_shared/clojure-style-guide.md
index fd6e302a674..afd97a05b56 100644
--- a/.claude/skills/_shared/clojure-style-guide.md
+++ b/.claude/skills/_shared/clojure-style-guide.md
@@ -304,12 +304,13 @@ Tag response Malli `:map` schemas with `{:closed true}` so the generated OpenAPI
**Linter Suppressions:**
-The right shape is a **reader-discard map** placed directly above the form being silenced, listing the rule keywords explicitly:
+The right shape is a **reader-discard map** placed directly above the form being silenced, listing the
+rule keywords explicitly and including the required explanation:
```clojure
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-route-uses-kebab-case
- :metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :post "/api_key" ...)
+;; Loaded by name from the plugin registry.
+#_{:clj-kondo/ignore [:clojure-lsp/unused-public-var]}
+(defn plugin-entrypoint ...)
```
For a single require entry, hang it as metadata on that entry:
@@ -320,7 +321,12 @@ For a single require entry, hang it as metadata on that entry:
[metabase.query-processor.store :as qp.store])
```
-Common Metabase-specific rules you'll see: `:metabase/modules`, `:metabase/validate-defendpoint-route-uses-kebab-case`, `:metabase/validate-defendpoint-has-response-schema`, `:metabase/prefer-with-dynamic-fn-redefs`, `:deprecated-namespace`, `:discouraged-namespace`. Don't use the keyword form (`#_:clj-kondo/ignore`); always the map form so it's grep-able by which rule(s) are suppressed.
+Use the map form, not the keyword form (`#_:clj-kondo/ignore`), so searches can identify the suppressed
+rules. Keep `:clj-kondo/ignore` as the map's first key; the ratchet scanner rejects other orderings.
+
+Fix the warning when possible. Adding a suppression is a last resort and requires approval. If one is
+necessary, add an explanatory `;;` comment directly above it or at the end of the same line. CI enforces
+these requirements with `./bin/mage kondo-ratchets`.
**Configurable Options:**
diff --git a/.claude/skills/clojure-review/SKILL.md b/.claude/skills/clojure-review/SKILL.md
index 805450e67e0..541fab8f0d5 100644
--- a/.claude/skills/clojure-review/SKILL.md
+++ b/.claude/skills/clojure-review/SKILL.md
@@ -111,7 +111,12 @@ liability it usually is.
### Miscellaneous
- [ ] Example data is bird-themed when possible
-- [ ] Kondo linter suppressions use proper format (not `#_:clj-kondo/ignore` keyword form)
+- [ ] Kondo suppressions use a reader-discard map, not `#_:clj-kondo/ignore`, with
+ `:clj-kondo/ignore` as the first key
+- [ ] Each new suppression is approved and has a `;;` comment explaining why the warning cannot be fixed
+- [ ] Any ratchet budget increase is explained in the PR
+- [ ] PRs that remove ignores leave ratchet budgets unchanged; the shrink workflow records reductions on
+ `master`
## Pattern matching table
diff --git a/.claude/skills/clojure-write/SKILL.md b/.claude/skills/clojure-write/SKILL.md
index 69bb6b4bc9d..adaa1edb0e6 100644
--- a/.claude/skills/clojure-write/SKILL.md
+++ b/.claude/skills/clojure-write/SKILL.md
@@ -125,6 +125,10 @@ breakage keeps happening, *that* is the signal a comment was warranted.
or `:model/X` reference, or a new module), run `./bin/mage fix-modules-config` to regenerate
`.clj-kondo/config/modules/config.edn`, then run `./bin/mage project-tests modules`. The fixer is a no-op when
nothing drifted; see "Module Boundaries" in the project `CLAUDE.md`.
+- Fix kondo warnings instead of suppressing them. Add a suppression only as a last resort, with approval
+ and a `;;` comment explaining why it is necessary.
+- Do not lower budgets in `.clj-kondo/ratchets.edn` after removing ignores. The shrink workflow records
+ reductions on `master`.
- If `.clj-kondo/ratchets.edn` conflicts during a merge, rebase, or restack, run
`./bin/merge-kondo-ratchets`. It preserves one-sided changes, chooses the policy that allows fewer
suppressions when both sides change the same entry, and stops when the conflict needs a human decision.
diff --git a/.clj-kondo/ratchets.edn b/.clj-kondo/ratchets.edn
index dc11a4b82f3..cdf4037006a 100644
--- a/.clj-kondo/ratchets.edn
+++ b/.clj-kondo/ratchets.edn
@@ -1,14 +1,15 @@
-;; Budgets for kondo suppressions: inline `:clj-kondo/ignore` forms per linter (:ignore-counts),
-;; and config-level waivers in .clj-kondo/config.edn (:config-counts -- :off switches and :exclude
-;; entries). Each :ignore-counts value is a non-negative integer budget, or :unlimited for no ceiling.
-;; CI rejects counts above a numeric budget; local tests require those counts to match exactly.
+;; Budgets for kondo suppressions: inline `:clj-kondo/ignore` forms per linter (:ignore-counts), and
+;; config-level waivers in .clj-kondo/config.edn (:config-counts -- :off switches and :exclude entries).
+;; Each :ignore-counts value is a non-negative integer budget, or :unlimited for no ceiling.
+;; Checks fail when a count exceeds its numeric budget; unused budget is allowed.
;; Any ignore outside :comment-exempt needs an explanatory comment directly above or trailing on its line.
-;; `./bin/mage fix-kondo-ratchets` lowers budgets and drops stale exemptions; local test runs do it
-;; automatically. Raising a budget, adding one (`--seed` for inline, by hand for config), or
-;; widening the exemptions is a hand edit to defend in your PR.
+;; `./bin/mage kondo-ratchets-shrink` lowers budgets unless `--seed` explicitly adds or raises one.
+;; The workflow runs it on master, so feature branches do not need to record reductions.
+;; Raising or adding a budget (`--seed` for inline ignores, a manual edit for config) or widening the
+;; exemptions must be explained in the PR.
;; :all is the vector-less ignore form, which suppresses every linter on the next form.
{:ignore-counts {:aliased-namespace-symbol 3
- :case-symbol-test 1
+ :case-symbol-test 2
:clojure-lsp/unused-public-var 9
:consistent-alias 2
:def-fn 1
diff --git a/.github/workflows/backend.yml b/.github/workflows/backend.yml
index 9b0590e33a1..b4499cb43bf 100644
--- a/.github/workflows/backend.yml
+++ b/.github/workflows/backend.yml
@@ -19,7 +19,7 @@ on:
type: boolean
default: false
run-project-ratchet-checks:
- description: Run the ratchet check on its own, when the backend checks (which include it) do not run.
+ description: Run the ratchet check for a diff that touches nothing but the ratchets file.
type: boolean
default: false
@@ -81,10 +81,11 @@ jobs:
- name: Run migration checks
if: ${{ inputs.force-run || inputs.run-project-migration-checks }}
run: ./bin/mage project-tests migrations
- # The backend checks already run this suite, so it only runs when they do not.
+ # Babashka, not a JVM test run, so it is cheap enough to run alongside the backend checks.
+ # It still needs the JDK prepare-backend installs, to resolve clj-kondo on a cold cache.
- name: Run ratchet checks
- if: ${{ inputs.run-project-ratchet-checks && !inputs.force-run && !inputs.run-project-backend-checks }}
- run: ./bin/mage project-tests ratchets
+ if: ${{ inputs.force-run || inputs.run-project-backend-checks || inputs.run-project-ratchet-checks }}
+ run: ./bin/mage kondo-ratchets
project-tests:
name: Project tests
diff --git a/.github/workflows/kondo-ratchets-shrink.yml b/.github/workflows/kondo-ratchets-shrink.yml
index dfc2bd2b2c8..b9a269d445a 100644
--- a/.github/workflows/kondo-ratchets-shrink.yml
+++ b/.github/workflows/kondo-ratchets-shrink.yml
@@ -57,7 +57,7 @@ jobs:
distribution: temurin
java-version: 25
- name: Shrink ignore limits
- run: ./bin/mage fix-kondo-ratchets
+ run: ./bin/mage kondo-ratchets-shrink
# Two independent outputs: `push` says the branch needs a new commit, `pr` names the open automation
# PR if there is one. Approval and auto-merge key on `pr` alone, so a run that failed after opening
# the PR is repaired by the next run instead of leaving the PR stranded.
@@ -84,8 +84,8 @@ jobs:
# The ratchet file is the whole payload, so an open PR that already carries this result is left
# alone. Rebasing it onto every master push would restart its CI and churn the diff without
- # changing what it delivers. The diff is against the working tree, holding what
- # fix-kondo-ratchets produced above, and so asks whether the PR would deliver the same file.
+ # changing what it delivers. Compare the open PR with the working tree, which contains the
+ # shrunk ratchets file produced above, to determine whether the PR would deliver the same file.
#
# A conflicted PR is the exception: only a fresh commit clears it. Mergeability is computed
# lazily, so a pending UNKNOWN reads as not conflicted and the next run settles it.
@@ -133,7 +133,7 @@ jobs:
--head "$AUTOMATION_BRANCH" \
--title "Tighten ratchets" \
--label "no-backport" \
- --body "\`./bin/mage fix-kondo-ratchets\` lowered \`$RATCHETS_FILE\` to match master.
+ --body "\`./bin/mage kondo-ratchets-shrink\` lowered \`$RATCHETS_FILE\` to match master.
The shrink workflow force-updates this branch from master whenever the result changes, so the
diff is always one commit on top of a recent master. It approves and merges itself once the
ratchet check passes; nothing is raised.")
diff --git a/CLAUDE.md b/CLAUDE.md
index 2c269be7bed..742c9f14a18 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -77,51 +77,62 @@ It piggybacks on a running dev nREPL (~5s) and auto-spawns a JVM if none is runn
the four generated keys; structural changes it can't safely make (a new module needs a human `:team`, or
modules need reordering) are printed as `WARNING:` lines for you to resolve by hand.
-Run the repository-level module, ratchet, and migration checks with:
+Run all repository-level checks, or one named suite:
```bash
./bin/mage project-tests
+./bin/mage project-tests <backend|migrations|modules|ratchets>
```
## Kondo Ignore Ratchets
`.clj-kondo/ratchets.edn` records, per linter, how many inline `:clj-kondo/ignore` forms the backend source
tree may contain, and how many config-level suppressions (`:off` switches and `:exclude` entries in
-`.clj-kondo/config.edn`) exist. Each `:ignore-counts` value is either an exact integer budget or `:unlimited`,
-which has no count ceiling. This count policy is independent of `:comment-exempt`, described below.
-Development enforces the file exactly, while CI rejects only over-budget suppressions and leaves reductions
-and stale exemptions for the shrink workflow to record.
-Prefer fixing the underlying warning over adding an ignore. Every policy key must name a linter: one of the
-pinned clj-kondo version's built-ins, a linter configured under `.clj-kondo/`, or an external diagnostic
-such as `:clojure-lsp/unused-public-var`.
-The test and the fixer refuse unknown names rather than dropping them.
-
-The ratchets apply only to `master`. When a release branch is cut, `.clj-kondo/ratchets.edn` is replaced
-with `{:disabled true}`. The test and fixer recognize this explicit opt-out, while a missing file still
-causes an error on `master`.
-
-Budget too high (you removed ignores): once the change lands on `master`, the shrink workflow lowers the
-budgets in the `Tighten ratchets` automation PR, which approves and merges itself once the ratchet check
-passes. A bounded budget that reaches zero is dropped; an `:unlimited` entry stays even with no ignores
-left, and the check and fixer print one warning naming such entries so you can delete them by hand. To
-tighten by hand (babashka, no JVM; a no-op prints `unchanged`):
+`.clj-kondo/config.edn`) exist. Each `:ignore-counts` value is either a non-negative integer ceiling or
+`:unlimited`, which has no ceiling. This count policy is independent of `:comment-exempt`, described below.
+
+Both ratchet commands are quick Babashka tasks, not JVM test runs:
```bash
-./bin/mage fix-kondo-ratchets
+./bin/mage kondo-ratchets # validate the file without changing it
+./bin/mage kondo-ratchets-shrink [--seed :lint] # lower budgets; optionally seed one
```
-Budget too low (you added an ignore): the task only raises an `:ignore-counts` budget when told to. If the
-ignore is genuinely required, run `./bin/mage fix-kondo-ratchets --seed :the-linter` and defend the increase
-in the PR. Set a linter's `:ignore-counts` value to `:unlimited` only when increasing its ignore count should
-not require a budget change.
+`kondo-ratchets` is the command CI runs. It rejects suppression counts above their budgets, ignores without
+required justification comments, unknown linter names, and a missing or incorrectly formatted ratchets
+file. It allows budgets above the current counts.
+
+`kondo-ratchets-shrink` lowers budgets to the current counts and normalizes the file. It is the only Mage
+command that writes the file. With `--seed`, it can also add or raise an inline-ignore budget.
+
+Every policy key must name a linter: one of the pinned clj-kondo version's built-ins, a linter configured
+under `.clj-kondo/`, or an external diagnostic such as `:clojure-lsp/unused-public-var`. Both commands
+reject unknown names rather than dropping them.
+
+Release branches disable ratchet enforcement by replacing `.clj-kondo/ratchets.edn` with
+`{:disabled true}`. Both commands recognize this explicit opt-out; a missing file remains an error.
+
+When you remove ignores, leave the higher budget unchanged on the feature branch. After the change lands,
+the shrink workflow opens a `Tighten ratchets` PR to record the reduction. Avoiding ratchet-file changes in
+feature PRs also prevents unrelated PRs from conflicting over the file. The shrinker removes a bounded
+budget when its count reaches zero. It preserves an unused `:unlimited` entry and prints a warning so that
+the entry can be reviewed and removed manually on `master`.
+
+When you add a necessary ignore, run `./bin/mage kondo-ratchets-shrink --seed :the-linter` and explain the
+budget increase in the PR. Use `:unlimited` only when future ignores for that linter should not require
+budget changes.
-The ignore must be the first key in its map; noncanonical forms fail the ratchet instead of being guessed
-at. Ignores of linters outside the file's `:comment-exempt` set need an explanatory `;;` comment directly
-above (or trailing on the same line). The set only shrinks: once a linter's last uncommented ignore gains
-a comment, the fixer drops its exemption.
+Fix the underlying warning when possible. Adding a suppression is a last resort and requires approval.
+In every suppression map, `:clj-kondo/ignore` must be the first key. Unless every suppressed linter is in
+`:comment-exempt`, add a `;;` comment directly above the suppression or at the end of the same line to
+explain why it is necessary. The check reports missing comments.
+When a linter's last uncommented ignore is commented or removed, the check warns that its exemption is
+stale. Remove the entry by hand; nothing does so automatically. Like `:unlimited`, an exemption records a
+decision rather than a count.
Introducing a new linter: `./bin/mage kondo-insert-ignores :the-linter` inserts an ignore at every site it
-flags, then `./bin/mage fix-kondo-ratchets --seed :the-linter` records the budget — no big-bang cleanup.
+flags, then `./bin/mage kondo-ratchets-shrink --seed :the-linter` records the budget. This lets the linter
+land without fixing all its existing findings at once.
To burn debt down, `./bin/mage kondo-redundant-ignores` lists ignores that are no longer needed (slow:
full kondo run). Kondo's redundancy report can't see hook-linter warnings, so `--fix` re-lints after
diff --git a/bb.edn b/bb.edn
index 638c710a102..cf668d7f988 100644
--- a/bb.edn
+++ b/bb.edn
@@ -277,12 +277,12 @@
:task (task! (mage.modules/cli-fix-config (cli/parse! (current-task))))}
project-tests
- {:doc "Run project-level backend and migration checks."
- :examples [["./bin/mage project-tests" "Run backend and migration checks"]
+ {:doc "Run project-level checks."
+ :examples [["./bin/mage project-tests" "Run every suite"]
["./bin/mage project-tests backend" "Run backend checks"]
["./bin/mage project-tests migrations" "Run migration checks"]
["./bin/mage project-tests modules" "Run module checks"]
- ["./bin/mage project-tests ratchets" "Run ratchet checks"]]
+ ["./bin/mage project-tests ratchets" "Check the repository's kondo suppression ratchets"]]
:arg-schema [:or
[:tuple]
[:tuple [:enum {:name "suite"}
@@ -295,42 +295,19 @@
(project-tests/run! suite)
(project-tests/run!)))}
- fix-kondo-ratchets
- {:doc "Lower the per-linter ignore budgets in .clj-kondo/ratchets.edn to match the source tree."
- :examples [["./bin/mage fix-kondo-ratchets" "Ratchet budgets down (never raises one; over-budget linters are only warned about)"]
- ["./bin/mage fix-kondo-ratchets --seed :some-linter" "Also set :some-linter's budget to its actual count, for landing a new linter"]]
- :options [["-s" "--seed LINTER" "Set LINTER's budget to the actual count (may add or raise it)"]]
- :requires [[dev.kondo-ratchet]]
- :task (task! (dev.kondo-ratchet/fix! (:options parsed)))}
-
- merge-kondo-ratchets
- {:doc "Three-way merge conflicting .clj-kondo/ratchets.edn files."
- :examples [["./bin/mage merge-kondo-ratchets BASE OURS THEIRS OUTPUT"
- "Merge three ratchet-file stages into OUTPUT"]]
- :arg-schema [:tuple
- [:string {:name "base" :description "Merge base's ratchets file"}]
- [:string {:name "ours" :description "Git stage 2: the branch being merged or rebased onto"}]
- [:string {:name "theirs" :description "Git stage 3: the commits being applied to it"}]
- [:string {:name "output" :description "Path to write the merged ratchets file"}]]
+ kondo-ratchets
+ {:doc "Validate .clj-kondo/ratchets.edn and the source tree's kondo suppressions (Babashka; seconds, not a test run)."
+ :examples [["./bin/mage kondo-ratchets" "Fail on an invalid ratchets file, an over-budget suppression, or a missing justification comment"]]
:requires [[dev.kondo-ratchet]]
- :task (task!
- (let [[base-path ours-path theirs-path output-path] (:arguments parsed)
- ;; Every stage goes through the reader that validates the checked-in file.
- read-stage (fn [path]
- (binding [dev.kondo-ratchet/*ratchets-file* path]
- (dev.kondo-ratchet/read-ratchets)))
- [base ours theirs] (map read-stage [base-path ours-path theirs-path])
- merged (dev.kondo-ratchet/merge-ratchets base ours theirs)]
- (spit output-path (if (dev.kondo-ratchet/disabled? merged)
- (slurp ours-path)
- (dev.kondo-ratchet/render merged)))
- (println (str "merged ratchets into " output-path))))}
+ :task (task! (dev.kondo-ratchet/check))}
- check-kondo-ratchets
- {:doc "Fail when suppressions exceed a bounded budget or the ratchets file isn't normalized (babashka only, no JVM)."
- :examples [["./bin/mage check-kondo-ratchets" "Exit 1 when a policy is exceeded, the file is missing, or its formatting is not normalized"]]
+ kondo-ratchets-shrink
+ {:doc "Lower the budgets in .clj-kondo/ratchets.edn to match the source tree. This is the only Mage task that writes the file."
+ :examples [["./bin/mage kondo-ratchets-shrink" "Lower budgets to current counts without raising over-budget entries"]
+ ["./bin/mage kondo-ratchets-shrink --seed :some-linter" "Set :some-linter's budget to its current count when introducing the linter"]]
+ :options [["-s" "--seed LINTER" "Set LINTER's budget to the actual count (may add or raise it)"]]
:requires [[dev.kondo-ratchet]]
- :task (task! (dev.kondo-ratchet/check))}
+ :task (task! (dev.kondo-ratchet/fix! (:options parsed)))}
kondo-redundant-ignores
{:doc "Report inline kondo ignores that are no longer necessary (slow: full kondo run)."
@@ -438,6 +415,29 @@
;; These tasks are more for internal tooling, e.g. for use from git hooks etc.
;; - hidden from `./bin/mage` listing and `bb tasks`, these all - start with a `-`
+ -kondo-ratchets-merge
+ {:doc "Internal three-way merge for conflicting .clj-kondo/ratchets.edn files. Called by bin/merge-kondo-ratchets."
+ :examples [["./bin/mage -kondo-ratchets-merge BASE OURS THEIRS OUTPUT"
+ "Merge three ratchet-file stages into OUTPUT"]]
+ :arg-schema [:tuple
+ [:string {:name "base" :description "Ratchets file from the merge base"}]
+ [:string {:name "ours" :description "Git stage 2: ratchets file from the branch receiving the changes"}]
+ [:string {:name "theirs" :description "Git stage 3: ratchets file from the commits being applied"}]
+ [:string {:name "output" :description "Path to write the merged ratchets file"}]]
+ :requires [[dev.kondo-ratchet]]
+ :task (task!
+ (let [[base-path ours-path theirs-path output-path] (:arguments parsed)
+ ;; Every stage goes through the reader that validates the checked-in file.
+ read-stage (fn [path]
+ (binding [dev.kondo-ratchet/*ratchets-file* path]
+ (dev.kondo-ratchet/read-ratchets)))
+ [base ours theirs] (map read-stage [base-path ours-path theirs-path])
+ merged (dev.kondo-ratchet/merge-ratchets base ours theirs)]
+ (spit output-path (if (dev.kondo-ratchet/disabled? merged)
+ (slurp ours-path)
+ (dev.kondo-ratchet/render merged)))
+ (println (str "merged ratchets into " output-path))))}
+
-driver-decisions
{:doc "Determine which driver tests should run based on PR context. Outputs decisions for all drivers."
:examples [["./bin/mage -driver-decisions --git-ref=master --force-run=false --pr-labels= --skip=false" "Determine driver decisions for a PR"]
diff --git a/bin/merge-kondo-ratchets b/bin/merge-kondo-ratchets
index cb261e4c4e9..b185b947e0b 100755
--- a/bin/merge-kondo-ratchets
+++ b/bin/merge-kondo-ratchets
@@ -1,10 +1,11 @@
#!/usr/bin/env bash
#
# Resolve a conflicted .clj-kondo/ratchets.edn and stage the result.
-# This script only reads the index stages; `./bin/mage merge-kondo-ratchets` merges the policies.
+# This script only reads the index stages; `./bin/mage -kondo-ratchets-merge` merges the policies.
set -euo pipefail
+# Find mage through this script's path: the cd below can land in a different repository.
bin_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
cd -- "$(git rev-parse --show-toplevel)"
@@ -39,7 +40,7 @@ else
printf '{}\n' > "$tmp_dir/base"
fi
-"$bin_dir/mage" merge-kondo-ratchets \
+"$bin_dir/mage" -kondo-ratchets-merge \
"$tmp_dir/base" \
"$tmp_dir/ours" \
"$tmp_dir/theirs" \
diff --git a/dev/src/dev/kondo_ratchet.clj b/dev/src/dev/kondo_ratchet.clj
index f124382ac4c..1ebf0d884f8 100644
--- a/dev/src/dev/kondo_ratchet.clj
+++ b/dev/src/dev/kondo_ratchet.clj
@@ -1,9 +1,10 @@
(ns dev.kondo-ratchet
- "Ratchet on inline kondo ignore forms.
+ "Check inline kondo ignores against the per-linter policies in `.clj-kondo/ratchets.edn`.
- Per-linter policies live in `.clj-kondo/ratchets.edn`, with the linters whose ignores need no comment.
- Local tests require an exact match; CI rejects only increases and lets the shrink workflow record the rest.
- `./bin/mage fix-kondo-ratchets` lowers budgets and drops stale exemptions, never the reverse.
+ The policies include suppression budgets and linters exempt from justification comments.
+ Checks fail when a suppression count exceeds its budget, but allow budgets above current counts.
+ `./bin/mage kondo-ratchets-shrink` lowers budgets unless `--seed` explicitly adds or raises one; it is
+ the only Mage command that writes the file.
Loaded by both the bb task and the JVM test, so keep it dependency-free."
{:clj-kondo/config '{:linters {:discouraged-var {clojure.core/println {:level :off}}}}}
(:require
@@ -549,14 +550,15 @@
[linter entry])))
(def ^:private header
- (str ";; Budgets for kondo suppressions: inline `" ignore-marker "` forms per linter (:ignore-counts),\n"
- ";; and config-level waivers in .clj-kondo/config.edn (:config-counts -- :off switches and :exclude\n"
- ";; entries). Each :ignore-counts value is a non-negative integer budget, or :unlimited for no ceiling.\n"
- ";; CI rejects counts above a numeric budget; local tests require those counts to match exactly.\n"
+ (str ";; Budgets for kondo suppressions: inline `" ignore-marker "` forms per linter (:ignore-counts), and\n"
+ ";; config-level waivers in .clj-kondo/config.edn (:config-counts -- :off switches and :exclude entries).\n"
+ ";; Each :ignore-counts value is a non-negative integer budget, or :unlimited for no ceiling.\n"
+ ";; Checks fail when a count exceeds its numeric budget; unused budget is allowed.\n"
";; Any ignore outside :comment-exempt needs an explanatory comment directly above or trailing on its line.\n"
- ";; `./bin/mage fix-kondo-ratchets` lowers budgets and drops stale exemptions; local test runs do it\n"
- ";; automatically. Raising a budget, adding one (`--seed` for inline, by hand for config), or\n"
- ";; widening the exemptions is a hand edit to defend in your PR.\n"
+ ";; `./bin/mage kondo-ratchets-shrink` lowers budgets unless `--seed` explicitly adds or raises one.\n"
+ ";; The workflow runs it on master, so feature branches do not need to record reductions.\n"
+ ";; Raising or adding a budget (`--seed` for inline ignores, a manual edit for config) or widening the\n"
+ ";; exemptions must be explained in the PR.\n"
";; :all is the vector-less ignore form, which suppresses every linter on the next form.\n"))
(defn- render-counts
@@ -710,9 +712,18 @@
(str "WARNING: :unlimited policies with no ignores left: " (str/join ", " linters)
" -- delete an entry by hand once its linter no longer needs one"))))
+(defn stale-exemptions-warning
+ "An informational warning naming linters whose `:comment-exempt` entries are stale, or nil when there
+ are none. Does not modify the exemptions."
+ [exempt occurrences]
+ (let [linters (stale-exemptions exempt occurrences)]
+ (when (seq linters)
+ (str "WARNING: :comment-exempt is no longer needed for these linters: " (str/join ", " linters)
+ " -- delete the stale entries by hand"))))
+
(defn change-report
- "The lines [[fix!]] prints: lowered/dropped/seeded budgets, dropped exemptions, plus warnings for
- anything over budget and for `:unlimited` policies nothing uses any more."
+ "The lines [[fix!]] prints for budget changes, budget violations, unused `:unlimited` policies, and
+ stale comment exemptions."
[{:keys [ignore-counts config-counts comment-exempt]} occurrences config-actual seeded]
(let [actual (actual-counts occurrences)]
(concat
@@ -735,7 +746,7 @@
linter budget n linter)))
(some-> (unexercised-unlimited-warning (apply dissoc ignore-counts seeded) actual) vector)
(for [[linter n] (sort-by (comp str first) (apply dissoc actual (concat seeded (keys ignore-counts))))]
- (format "WARNING: %s has %d ignores but no budget entry -- seed one with `./bin/mage fix-kondo-ratchets --seed %s`"
+ (format "WARNING: %s has %d ignores but no budget entry -- seed one with `./bin/mage kondo-ratchets-shrink --seed %s`"
linter n linter))
(for [[linter {:keys [recorded actual]}] (config-drift config-counts config-actual)]
(cond
@@ -743,12 +754,11 @@
(< actual recorded) (format "lowered config %s %d -> %d" linter recorded actual)
:else (format "WARNING: config suppressions for %s are over budget (%d recorded, %d actual) -- remove one from .clj-kondo/config.edn or raise the budget by hand"
linter recorded actual)))
- (for [linter (stale-exemptions comment-exempt occurrences)]
- (format "unexempted %s (all its ignores are justified now)" linter)))))
+ (some-> (stale-exemptions-warning comment-exempt occurrences) vector))))
(defn fix!
- "Rewrite [[*ratchets-file*]]: lower budgets, drop stale comment exemptions, normalize formatting.
- Refuses to touch a file naming an unknown linter, whether seeded or recorded, and never removes one.
+ "Rewrite [[*ratchets-file*]]: lower budgets and normalize formatting.
+ Refuses to touch a file containing an unknown linter or to seed one, rather than silently dropping it.
`--seed LINTER` (`{:seed \"...\"}` here) sets that budget to the actual count and bounds an unlimited one.
Prints the [[change-report]], or `unchanged` on a no-op.
Does nothing, including seeding, when the file sets `:disabled` to `true`."
@@ -767,7 +777,7 @@
config-actual (config-suppressions)
text (render {:ignore-counts (lowered-counts ignore-counts actual seeded)
:config-counts (lowered-counts config-counts config-actual [])
- :comment-exempt (reduce disj comment-exempt (stale-exemptions comment-exempt occurrences))})
+ :comment-exempt comment-exempt})
old (slurp *ratchets-file*)]
(run! println (change-report ratchets occurrences config-actual seeded))
(if (= old text)
@@ -777,26 +787,34 @@
(defn check-report
"The lines [[check]] prints when inline ignores or config suppressions (`config-actual`) exceed their
- budgets, or `text` is not normalized.
+ budgets, an ignore lacks a required justification comment, or `text` is not normalized.
Lower counts are allowed because the shrink workflow records them after the change lands."
- [{:keys [ignore-counts config-counts] :as ratchets} occurrences config-actual text]
+ [{:keys [ignore-counts config-counts comment-exempt] :or {comment-exempt #{}} :as ratchets}
+ occurrences config-actual text]
(let [over (over-budget ignore-counts occurrences)
config-over (config-over-budget config-counts config-actual)
+ uncommented (unjustified comment-exempt occurrences)
linter-line (fn [[linter {:keys [recorded actual]}]]
(format " %s: %d recorded, %d actual" linter recorded actual))]
(concat
(when (seq over)
(cons (str "over budget -- remove an ignore, or seed the budget with"
- " `./bin/mage fix-kondo-ratchets --seed <linter>` and defend it in the PR:")
+ " `./bin/mage kondo-ratchets-shrink --seed <linter>` and explain the increase in the PR:")
(mapcat (fn [[_ {:keys [examples]} :as entry]]
(cons (linter-line entry) (map #(str " " %) examples)))
over)))
(when (seq config-over)
(cons (str "config suppressions over budget -- remove the entry from " kondo-config-file
- ", or raise the budget by hand and defend it in the PR:")
+ ", or raise the budget manually and explain the increase in the PR:")
(map linter-line config-over)))
+ (when (seq uncommented)
+ (cons (str "ignores without required comments -- add a `;;` comment above the form or at the end"
+ " of the same line, explaining why the suppression is necessary:")
+ (map (fn [{:keys [file line linters]}]
+ (format " %s:%d %s" file line (vec linters)))
+ uncommented)))
(when (not= text (render ratchets))
- [(str *ratchets-file* " is not normalized -- run `./bin/mage fix-kondo-ratchets`"
+ [(str *ratchets-file* " is not normalized -- run `./bin/mage kondo-ratchets-shrink`"
" to fix the formatting")]))))
(defn- exit!
@@ -812,9 +830,10 @@
(defn check
"Fail the babashka task when the ratchets file is missing, a policy names an unknown linter, inline
- ignores or config suppressions exceed a bounded budget, or the file is not normalized.
+ ignores or config suppressions exceed a bounded budget, an ignore lacks a required justification
+ comment, or the file is not normalized.
Only an explicit `{:disabled true}` opts out of enforcement.
- An unused `:unlimited` policy is reported but does not fail the check."
+ Unused `:unlimited` policies and stale `:comment-exempt` entries are reported but do not fail the check."
[]
(if-not (.exists (io/file *ratchets-file*))
(fail! (str *ratchets-file* " is missing -- only {:disabled true} opts out of enforcement"))
@@ -829,6 +848,7 @@
(let [occurrences (scan)
lines (check-report ratchets occurrences (config-suppressions) (slurp *ratchets-file*))]
(some-> (unexercised-unlimited-warning (:ignore-counts ratchets) (actual-counts occurrences)) println)
+ (some-> (stale-exemptions-warning (:comment-exempt ratchets) occurrences) println)
(if (empty? lines)
(println (format "ok -- %d ignore forms within %d policies"
(count occurrences) (count (:ignore-counts ratchets))))
diff --git a/dev/test/metabase/core/kondo_ratchet_check_test.clj b/dev/test/metabase/core/kondo_ratchet_check_test.clj
index 697d3092920..245f2d4c3fa 100644
--- a/dev/test/metabase/core/kondo_ratchet_check_test.clj
+++ b/dev/test/metabase/core/kondo_ratchet_check_test.clj
@@ -9,17 +9,20 @@
(set! *warn-on-reflection* true)
(defn- occurrences
- "One single-linter ignore form per unit in `linter->count`, all in `f.clj` on successive lines."
+ "Create the specified number of justified, single-linter ignores for each linter in `linter->count`."
[linter->count]
(for [[linter n] linter->count
i (range n)]
- {:file "f.clj", :line (inc i), :linters [linter]}))
+ {:file "f.clj", :line (inc i), :linters [linter], :justified? true}))
(defn- report-lines
+ "Return [[kondo-ratchet/check-report]] output for `ratchets`. Supply the defaults that
+ [[kondo-ratchet/read-ratchets]] adds to a partial file."
([ratchets occurrences text]
(report-lines ratchets occurrences {} text))
([ratchets occurrences config-actual text]
- (vec (kondo-ratchet/check-report ratchets occurrences config-actual text))))
+ (vec (kondo-ratchet/check-report (merge {:config-counts {}, :comment-exempt #{}} ratchets)
+ occurrences config-actual text))))
(deftest ^:parallel clean-test
(let [ratchets {:ignore-counts {:a 2, :b 1}}]
@@ -28,7 +31,7 @@
(deftest ^:parallel over-budget-test
(let [ratchets {:ignore-counts {:a 1}}]
- (is (= ["over budget -- remove an ignore, or seed the budget with `./bin/mage fix-kondo-ratchets --seed <linter>` and defend it in the PR:"
+ (is (= ["over budget -- remove an ignore, or seed the budget with `./bin/mage kondo-ratchets-shrink --seed <linter>` and explain the increase in the PR:"
" :a: 1 recorded, 3 actual"
" f.clj:1"
" f.clj:2"
@@ -46,9 +49,21 @@
(kondo-ratchet/render ratchets)))
"unlimited linters do not fail the CI report, even when their actual count reaches zero")))
+(deftest ^:parallel unjustified-test
+ (let [ratchets {:ignore-counts {:a 3, :b 1, :grandfathered 1}, :comment-exempt #{:grandfathered}}
+ occurrences [{:file "f.clj", :line 7, :linters [:a], :justified? false}
+ {:file "g.clj", :line 12, :linters [:a :b], :justified? false}
+ {:file "g.clj", :line 20, :linters [:a], :justified? true}
+ {:file "h.clj", :line 3, :linters [:grandfathered], :justified? false}]]
+ (is (= ["ignores without required comments -- add a `;;` comment above the form or at the end of the same line, explaining why the suppression is necessary:"
+ " f.clj:7 [:a]"
+ " g.clj:12 [:a :b]"]
+ (report-lines ratchets occurrences (kondo-ratchet/render ratchets)))
+ "a commented ignore passes, and so does an uncommented one whose every linter is exempt")))
+
(deftest ^:parallel config-over-budget-test
(let [ratchets {:ignore-counts {}, :config-counts {:a 1, :b 2}}]
- (is (= ["config suppressions over budget -- remove the entry from .clj-kondo/config.edn, or raise the budget by hand and defend it in the PR:"
+ (is (= ["config suppressions over budget -- remove the entry from .clj-kondo/config.edn, or raise the budget manually and explain the increase in the PR:"
" :a: 1 recorded, 2 actual"
" :new: 0 recorded, 1 actual"]
(report-lines ratchets [] {:a 2, :b 1, :new 1} (kondo-ratchet/render ratchets)))
@@ -84,7 +99,7 @@
(check-with! ratchets (occurrences {:free 1, :over 1})))
"the warning comes first, sorted, and does not fail the check")
(is (= {:lines ["WARNING: :unlimited policies with no ignores left: :a-empty, :z-empty -- delete an entry by hand once its linter no longer needs one"
- "over budget -- remove an ignore, or seed the budget with `./bin/mage fix-kondo-ratchets --seed <linter>` and defend it in the PR:"
+ "over budget -- remove an ignore, or seed the budget with `./bin/mage kondo-ratchets-shrink --seed <linter>` and explain the increase in the PR:"
" :over: 1 recorded, 2 actual"
" f.clj:1"
" f.clj:2"]
@@ -96,6 +111,17 @@
(check-with! ratchets (occurrences {:z-empty 1, :a-empty 1, :free 1, :over 1})))
"no warning when every unlimited policy is in use")))
+(deftest check-reports-stale-exemptions-test
+ (let [ratchets {:ignore-counts {:grandfathered 1, :none-left 1, :still-needed 1}
+ :comment-exempt #{:grandfathered :none-left :still-needed}}
+ occurrences [{:file "f.clj", :line 1, :linters [:grandfathered], :justified? true}
+ {:file "g.clj", :line 1, :linters [:still-needed], :justified? false}]]
+ (is (= {:lines ["WARNING: :comment-exempt is no longer needed for these linters: :grandfathered, :none-left -- delete the stale entries by hand"
+ "ok -- 2 ignore forms within 3 policies"]
+ :thrown? false}
+ (check-with! ratchets occurrences))
+ "exemptions with only commented ignores or no ignores are named, and do not fail the check")))
+
(deftest ^:parallel stale-test
(let [ratchets {:ignore-counts {:a 5, :gone 2}}]
(is (= []
@@ -104,7 +130,7 @@
(deftest ^:parallel not-normalized-test
(let [ratchets {:ignore-counts {:a 1}}
text (kondo-ratchet/render ratchets)]
- (is (= [(str kondo-ratchet/*ratchets-file* " is not normalized -- run `./bin/mage fix-kondo-ratchets`"
+ (is (= [(str kondo-ratchet/*ratchets-file* " is not normalized -- run `./bin/mage kondo-ratchets-shrink`"
" to fix the formatting")]
(report-lines ratchets (occurrences {:a 1}) (str/replace text "{:a 1}" "{:a 1}")))
"same data, different whitespace")))
@@ -112,11 +138,11 @@
(deftest ^:parallel combined-test
(testing "over-budget and formatting problems are reported together"
(let [ratchets {:ignore-counts {:over 1, :stale 2}}]
- (is (= ["over budget -- remove an ignore, or seed the budget with `./bin/mage fix-kondo-ratchets --seed <linter>` and defend it in the PR:"
+ (is (= ["over budget -- remove an ignore, or seed the budget with `./bin/mage kondo-ratchets-shrink --seed <linter>` and explain the increase in the PR:"
" :over: 1 recorded, 2 actual"
" f.clj:1"
" f.clj:2"
- (str kondo-ratchet/*ratchets-file* " is not normalized -- run `./bin/mage fix-kondo-ratchets`"
+ (str kondo-ratchet/*ratchets-file* " is not normalized -- run `./bin/mage kondo-ratchets-shrink`"
" to fix the formatting")]
(report-lines ratchets (occurrences {:over 2, :stale 1}) "{:ignore-counts {}}\n"))))))
diff --git a/dev/test/metabase/core/kondo_ratchet_test.clj b/dev/test/metabase/core/kondo_ratchet_test.clj
index 33c77787f8e..12ad56b3f09 100644
--- a/dev/test/metabase/core/kondo_ratchet_test.clj
+++ b/dev/test/metabase/core/kondo_ratchet_test.clj
@@ -1,5 +1,6 @@
(ns metabase.core.kondo-ratchet-test
- "Ratchet on inline kondo ignore forms: budgets live in `.clj-kondo/ratchets.edn` and only move down.
+ "Unit tests for [[dev.kondo-ratchet]]: scanning, policy reading, rendering, merging, and shrinking.
+ [[metabase.core.kondo-ratchet-check-test]] tests the command that checks the source tree.
The ignore forms in this file are string fixtures — the scanner masks string literals, so they don't
count as suppressions."
(:require
@@ -12,131 +13,22 @@
(set! *warn-on-reflection* true)
-;; Scanning walks the whole tree, so the ratchet tests share one pass per run. The cache only exists
-;; while the :once fixture is live; a directly-run test var (no fixture) always scans fresh, so a
-;; long-lived REPL never compares fresh ratchet-file contents with stale counts.
-(def ^:private tree-scan-cache
- (atom nil))
-
-(defn- tree-scan []
- (if-let [scan @tree-scan-cache]
- @scan
- (kondo-ratchet/scan)))
-
-(defn- ratchets-enabled? []
- (not (kondo-ratchet/disabled?)))
-
-;; Local tooling sets CI=false and CI=, and both are truthy when tested for presence.
-(defn- ci? []
- (= "true" (System/getenv "CI")))
-
-(defn- budget-drift
- [ci? policies occurrences]
- (if ci?
- (kondo-ratchet/over-budget policies occurrences)
- (kondo-ratchet/drift policies occurrences)))
-
-(defn- config-budget-drift
- [ci? budgets counts]
- (if ci?
- (kondo-ratchet/config-over-budget budgets counts)
- (kondo-ratchet/config-drift budgets counts)))
-
-;; Stale exemptions fail local runs only; the shrink workflow drops them, so CI must not fail when
-;; another PR has already justified the last ignore.
-(defn- stale-exemptions
- [ci? exempt occurrences]
- (if ci?
- #{}
- (kondo-ratchet/stale-exemptions exempt occurrences)))
-
-;; Outside CI, tighten the ratchets before asserting — the fix rides along in your next commit.
-;; The shrink workflow performs the same update on master.
-(use-fixtures :once (fn [thunk]
- (when-not (ci?)
- (kondo-ratchet/fix!))
- (reset! tree-scan-cache (delay (kondo-ratchet/scan)))
- (try
- (thunk)
- (finally
- (reset! tree-scan-cache nil)))))
-
;;;; ---------------------------------------------------------------------------
-;;;; The ratchets themselves
+;;;; Budget semantics
;;;; ---------------------------------------------------------------------------
-(deftest ^:parallel budgets-match-actual-counts-test
- (when (ratchets-enabled?)
- (testing (str "\nBudgets in " kondo-ratchet/*ratchets-file* " must match the actual inline ignore counts in development.\n"
- "Budget too low: remove an ignore, or seed the budget with\n"
- "`./bin/mage fix-kondo-ratchets --seed <linter>` and defend it in the PR.\n"
- "Budget too high: run `./bin/mage fix-kondo-ratchets`; the shrink workflow records\n"
- "lower counts after the change lands. Too high in a local run means\n"
- "`fix!` itself is broken, since the test fixture just ran it.")
- (let [{:keys [ignore-counts]} (kondo-ratchet/read-ratchets)]
- (is (= {}
- (budget-drift (ci?) ignore-counts (tree-scan))))))))
-
-(deftest ^:parallel ignores-are-justified-test
- (when (ratchets-enabled?)
- (testing (str "\nInline ignores of these linters need an explanatory `;;` comment on the line above\n"
- "(or trailing on the same line) saying why the suppression is warranted.\n"
- "Linters in :comment-exempt in " kondo-ratchet/*ratchets-file* " are grandfathered;\n"
- "widening that set is a hand edit to defend in the PR.")
- (let [exempt (:comment-exempt (kondo-ratchet/read-ratchets))]
- (is (= []
- (map #(dissoc % :justified?)
- (kondo-ratchet/unjustified exempt (tree-scan)))))))))
-
-(deftest ^:parallel no-stale-exemptions-test
- (when (ratchets-enabled?)
- (testing (str "\nEvery linter in :comment-exempt still has at least one unjustified ignore; once the last\n"
- "one gains a comment, the exemption goes. Run `./bin/mage fix-kondo-ratchets`.")
- (let [{:keys [comment-exempt]} (kondo-ratchet/read-ratchets)]
- (is (= #{}
- (stale-exemptions (ci?) comment-exempt (tree-scan))))))))
-
-(deftest ^:parallel config-budgets-match-actual-test
- (when (ratchets-enabled?)
- (testing (str "\nConfig-level suppression budgets in " kondo-ratchet/*ratchets-file* " must match\n"
- ".clj-kondo/config.edn (:off switches and :exclude entries, per linter).\n"
- "Budget too low: remove the new config suppression, or raise the budget by hand and\n"
- "defend it in the PR. Budget too high: run `./bin/mage fix-kondo-ratchets`.")
- (is (= {}
- (config-budget-drift (ci?)
- (:config-counts (kondo-ratchet/read-ratchets))
- (kondo-ratchet/config-suppressions)))))))
-
-(deftest ^:parallel ci-tolerates-reductions-test
+;; Feature branches may leave budgets above current counts and comment exemptions that are no longer
+;; needed. The shrink workflow lowers budgets after merge; stale exemptions must be removed by hand.
+(deftest ^:parallel reductions-are-tolerated-test
(let [occurrences [{:file "f.clj", :line 1, :linters [:a], :justified? false}
{:file "g.clj", :line 1, :linters [:b], :justified? true}]]
(testing "inline budgets"
- (is (= {} (budget-drift true {:a 3, :b 1} occurrences)))
- (is (= {:a {:recorded 3, :actual 1}} (budget-drift false {:a 3, :b 1} occurrences)))
- (is (= {:a {:recorded 0, :actual 1, :examples ["f.clj:1"]}} (budget-drift true {:b 1} occurrences))))
+ (is (= {} (kondo-ratchet/over-budget {:a 3, :b 1} occurrences)))
+ (is (= {:a {:recorded 0, :actual 1, :examples ["f.clj:1"]}}
+ (kondo-ratchet/over-budget {:b 1} occurrences))))
(testing "config budgets"
- (is (= {} (config-budget-drift true {:cfg 3} {:cfg 1})))
- (is (= {:cfg {:recorded 3, :actual 1}} (config-budget-drift false {:cfg 3} {:cfg 1})))
- (is (= {:cfg {:recorded 1, :actual 2}} (config-budget-drift true {:cfg 1} {:cfg 2}))))
- (testing "stale exemptions"
- (is (= #{} (stale-exemptions true #{:a :b} occurrences)))
- (is (= #{:b} (stale-exemptions false #{:a :b} occurrences))))))
-
-(deftest ^:parallel ratchets-file-normalized-test
- (when (ratchets-enabled?)
- (testing (str "\n" kondo-ratchet/*ratchets-file* " should be sorted and aligned exactly as the generator"
- " writes it.\nAfter a hand edit, run `./bin/mage fix-kondo-ratchets` to normalize the"
- " formatting.")
- (is (= (kondo-ratchet/render (kondo-ratchet/read-ratchets))
- (slurp kondo-ratchet/*ratchets-file*))))))
-
-(deftest ^:parallel policies-name-known-linters-test
- (when (ratchets-enabled?)
- (testing (str "\nEvery policy key in " kondo-ratchet/*ratchets-file* " must name a linter: a clj-kondo built-in\n"
- "in the pinned version, a linter configured under .clj-kondo/, or an external diagnostic\n"
- "such as :clojure-lsp/unused-public-var. Unknown names are never removed automatically.")
- (is (= #{}
- (kondo-ratchet/unknown-linters (kondo-ratchet/read-ratchets) (kondo-ratchet/known-linters)))))))
+ (is (= {} (kondo-ratchet/config-over-budget {:cfg 3} {:cfg 1})))
+ (is (= {:cfg {:recorded 1, :actual 2}} (kondo-ratchet/config-over-budget {:cfg 1} {:cfg 2}))))))
;;;; ---------------------------------------------------------------------------
;;;; Scanner unit tests
@@ -400,15 +292,12 @@
{:file "f.clj", :line line, :linters [:a]})]
(is (= 5 (count (:examples (:a (kondo-ratchet/drift {} occurrences)))))))))
-(deftest ^:parallel budget-drift-test
+(deftest ^:parallel over-budget-unlimited-test
(let [policies {:bounded 2, :free :unlimited, :empty :unlimited}
occurrences [{:file "f.clj", :line 1, :linters [:bounded :free]}]]
- (is (= {:bounded {:recorded 2, :actual 1}}
- (budget-drift nil policies occurrences))
- "local checks require bounded counts to match exactly, but ignore unlimited linters")
(is (= {}
- (budget-drift "true" policies occurrences))
- "CI allows bounded improvements and unlimited policies, including stale ones")))
+ (kondo-ratchet/over-budget policies occurrences))
+ "unused numeric budgets and unlimited policies do not fail the check")))
(deftest ^:synchronized fix-when-disabled-test
(testing "fix! explains that the ratchets are disabled and leaves the file unchanged"
@@ -457,13 +346,13 @@
(is (= text (slurp budgets))
"nothing is written")))))
-(deftest ^:synchronized fix-keeps-empty-unlimited-linter-test
+(deftest ^:synchronized fix-keeps-decision-policies-test
(let [dir (.toFile (java.nio.file.Files/createTempDirectory
"kondo-ratchet-test"
(make-array java.nio.file.attribute.FileAttribute 0)))
ratchets {:ignore-counts {:free :unlimited, :empty :unlimited, :gone 2, :zero 0}
:config-counts {}
- :comment-exempt #{}}
+ :comment-exempt #{:empty}}
budgets (doto (io/file dir "ratchets.edn") (spit (kondo-ratchet/render ratchets)))
occurrences [{:file "f.clj", :line 1, :linters [:free]}]
run! #(str/split-lines (with-out-str (kondo-ratchet/fix!)))]
@@ -474,14 +363,16 @@
(is (= ["dropped :gone (no ignores left)"
"dropped :zero (no ignores left)"
"WARNING: :unlimited policies with no ignores left: :empty -- delete an entry by hand once its linter no longer needs one"
+ "WARNING: :comment-exempt is no longer needed for these linters: :empty -- delete the stale entries by hand"
(str "wrote " (.getPath budgets))]
(run!))
- "the bounded zeros go, a hand-written 0 included; the unlimited zero stays and is reported")
+ "bounded zeros go; decision policies stay and are reported when no longer needed")
(is (= {:ignore-counts {:free :unlimited, :empty :unlimited}
:config-counts {}
- :comment-exempt #{}}
+ :comment-exempt #{:empty}}
(kondo-ratchet/read-ratchets)))
(is (= ["WARNING: :unlimited policies with no ignores left: :empty -- delete an entry by hand once its linter no longer needs one"
+ "WARNING: :comment-exempt is no longer needed for these linters: :empty -- delete the stale entries by hand"
"unchanged"]
(run!))
"a second run changes nothing and still reports")))))
@@ -803,7 +694,7 @@
"dropped config :cfg-gone (no suppressions left)"
"lowered config :cfg-lower 4 -> 2"
"WARNING: config suppressions for :cfg-over are over budget (1 recorded, 3 actual) -- remove one from .clj-kondo/config.edn or raise the budget by hand"
- "unexempted :polite (all its ignores are justified now)"]
+ "WARNING: :comment-exempt is no longer needed for these linters: :polite -- delete the stale entries by hand"]
(kondo-ratchet/change-report {:ignore-counts {:empty :unlimited
:free :unlimited
:gone 5
diff --git a/mage/src/mage/kondo_ratchet.clj b/mage/src/mage/kondo_ratchet.clj
index 0ec1a0eedf0..3778786ebde 100644
--- a/mage/src/mage/kondo_ratchet.clj
+++ b/mage/src/mage/kondo_ratchet.clj
@@ -416,7 +416,8 @@
(count covered)
(str/join ", " (sort (distinct (map :type covered))))
keep-marker)))
- (println "Now run `./bin/mage fix-kondo-ratchets` to update the budgets, and `./bin/mage kondo` for the final word.")
+ (println (str "Now run `./bin/mage kondo-ratchets` to check the suppressions, "
+ "then `./bin/mage kondo` to run the final lint."))
(when (or (seq exposed) (seq mismatched))
(throw (ex-info "the removals left warnings in the tree; fix or re-ignore them by hand and re-run"
{:exit-code 1}))))
@@ -484,14 +485,13 @@
(println)
(if (empty? by-file)
(println "No findings; nothing inserted.")
- (do (println (format "Inserted %d ignores across %d files. Now seed the budget:\n ./bin/mage fix-kondo-ratchets --seed %s"
+ (do (println (format "Inserted %d ignores across %d files. Now seed the budget:\n ./bin/mage kondo-ratchets-shrink --seed %s"
(count (distinct (map (juxt :filename :row) findings)))
(count by-file)
linter))
- ;; Inserted ignores carry no justification comment of their own, so the justification ratchet
- ;; fails unless the linter is grandfathered -- but an insert lands under whatever comment was
- ;; already above the flagged form, which justifies it. Advising an exemption none of the sites
- ;; need would just fail no-stale-exemptions-test instead, so ask the scanner first.
+ ;; An existing comment above the flagged form may justify the inserted ignore. Suggest an
+ ;; exemption only when the scanner still finds uncommented ignores; otherwise it is unnecessary
+ ;; and the ratchet check reports it as stale.
(when-not (contains? (:comment-exempt (kondo-ratchet/read-ratchets)) linter)
(when (seq (kondo-ratchet/unjustified #{} (filter #(some #{linter} (:linters %))
(kondo-ratchet/scan roots))))
diff --git a/mage/src/mage/project_tests.clj b/mage/src/mage/project_tests.clj
index 9087bd4819a..e2c98ba8661 100644
--- a/mage/src/mage/project_tests.clj
+++ b/mage/src/mage/project_tests.clj
@@ -11,16 +11,17 @@
'[dev.modules-config-test
metabase.core.modules-test])
-(def ^:private ratchet-check-namespaces
+(def ^:private ratchet-test-namespaces
+ ;; These test the tooling itself. `./bin/mage kondo-ratchets` checks the source tree.
'[metabase.core.kondo-ratchet-test
metabase.core.kondo-ratchet-check-test])
(def ^:private backend-check-namespaces
- (vec (concat module-check-namespaces ratchet-check-namespaces)))
+ (vec (concat module-check-namespaces ratchet-test-namespaces)))
(def ^:private default-suites
"Suites the bare `project-tests` command runs, in order."
- ["migrations" "backend"])
+ ["migrations" "backend" "ratchets"])
;; `sh` is a [[mage.shell/sh*]]-compatible function so unit tests can inspect commands without running them.
;; .github/scripts/check-preresolve-aliases.sh reads the alias strings out of these two functions.
@@ -35,6 +36,10 @@
":only"
(pr-str namespaces)))
+(defn- run-ratchet-checks! [sh]
+ (sh {:dir u/project-root-directory}
+ "./bin/mage" "kondo-ratchets"))
+
(def ^:private suite-labels
{"backend" "backend checks"
"migrations" "migration checks"
@@ -51,7 +56,7 @@
"backend" (run-clojure-checks! sh backend-check-namespaces)
"migrations" (run-migration-checks! sh)
"modules" (run-clojure-checks! sh module-check-namespaces)
- "ratchets" (run-clojure-checks! sh ratchet-check-namespaces)))
+ "ratchets" (run-ratchet-checks! sh)))
(catch Exception e
(println "Could not run" (suite-labels suite) "--" (ex-message e))
1)))
diff --git a/mage/test/mage/project_tests_test.clj b/mage/test/mage/project_tests_test.clj
index 5c872656c3f..9b04a41f6d7 100644
--- a/mage/test/mage/project_tests_test.clj
+++ b/mage/test/mage/project_tests_test.clj
@@ -2,7 +2,8 @@
(:require
[clojure.string :as str]
[clojure.test :refer [deftest is testing]]
- [mage.project-tests :as project-tests]))
+ [mage.project-tests :as project-tests]
+ [mage.shell :as shell]))
;; Referenced by core_test.clj to ensure namespace is loaded
(def keep-me :loaded)
@@ -76,11 +77,18 @@
(is (= [] failed))
(is (not (str/includes? out "Failed:")))))
+(deftest default-suites-include-ratchet-check-test
+ (let [calls (atom [])]
+ (with-redefs [shell/sh* (fake-sh calls [])]
+ (project-tests/run!))
+ (is (= 3 (count @calls)))
+ (is (= ["./bin/mage" "kondo-ratchets"] (last @calls)))))
+
(deftest targeted-suites-test
- (testing "modules and ratchets run only their own namespaces"
+ (testing "modules runs only its own namespaces"
(is (= [["clojure" "-X:dev:dev/test:ee:ee-dev:drivers:drivers-dev:test:ci" ":only"
"[dev.modules-config-test metabase.core.modules-test]"]]
- (:calls (run-suites! [] ["modules"]))))
- (is (= [["clojure" "-X:dev:dev/test:ee:ee-dev:drivers:drivers-dev:test:ci" ":only"
- "[metabase.core.kondo-ratchet-test metabase.core.kondo-ratchet-check-test]"]]
+ (:calls (run-suites! [] ["modules"])))))
+ (testing "ratchets checks the repository's policy file"
+ (is (= [["./bin/mage" "kondo-ratchets"]]
(:calls (run-suites! [] ["ratchets"]))))))