Skip to content

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

Ratchet module boundary escape hatches (#82300)

Chris Truterdd9d8d05796b
diff --git a/.clj-kondo/config.edn b/.clj-kondo/config.edn
index 65998f56f9c..6e84284720f 100644
--- a/.clj-kondo/config.edn
+++ b/.clj-kondo/config.edn
@@ -181,7 +181,7 @@
clojure.core.async/take!
clojure.core.async/to-chan!
clojure.core.async/to-chan!!
- ;; only writes .clj-kondo/ratchets.edn, from a :once fixture that finishes before the parallel tests
+ ;; writes the ratchet files from a :once fixture that finishes before the parallel tests
dev.kondo-ratchet/fix!
metabase.ai-tracing.core/record!
metabase.api.macros.defendpoint.tools-manifest/assert-optional-fields-nullable!
@@ -844,7 +844,7 @@
:name test-namespaces}
{:pattern "^(?!.*-test(?:\\..*)?$)(?!.*test-util)(?!^metabase\\.test.*).*$"
:name source-namespaces}
- {:pattern "(?:(?:^metabase\\.cmd.*)|(?:^build.*)|(?:^metabuild-common.*)|(?:^release.*)|(?:^i18n.*)|(?:^lint-migrations-file$))|(?:^mage.*)|(?:^load-namespaces.*)"
+ {:pattern "(?:(?:^metabase\\.cmd.*)|(?:^build.*)|(?:^metabuild-common.*)|(?:^release.*)|(?:^i18n.*)|(?:^lint-migrations-file$))|(?:^mage.*)|(?:^load-namespaces.*)|(?:^dev\\..*)"
:name printable-namespaces}
{:pattern "^metabase\\.(?:(?:lib)|(?:legacy-mbql))\\..*"
:name metabase-lib}
diff --git a/.clj-kondo/config/modules/ratchets.edn b/.clj-kondo/config/modules/ratchets.edn
new file mode 100644
index 00000000000..2f0d5a3a79c
--- /dev/null
+++ b/.clj-kondo/config/modules/ratchets.edn
@@ -0,0 +1,6 @@
+;; Budgets for escape hatches in config.edn. Counts may fall but not exceed these values.
+;; Leave reductions to the post-merge shrink workflow; explain increases in the PR.
+{:api-any 1
+ :friend-edges 28
+ :model-imports-bypass 2
+ :uses-any 4}
diff --git a/.clj-kondo/ratchets.edn b/.clj-kondo/ratchets.edn
index 6605ec7cea3..0a9a6db98df 100644
--- a/.clj-kondo/ratchets.edn
+++ b/.clj-kondo/ratchets.edn
@@ -5,7 +5,7 @@
;; Any ignore outside :comment-exempt needs an explanatory comment directly above or trailing on its line.
;; `./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
+;; Raising or adding a budget (`--seed` for inline ignores, a manual edit otherwise) 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
diff --git a/.github/file-paths.yaml b/.github/file-paths.yaml
index 55827f9d1c6..edcadc31cae 100644
--- a/.github/file-paths.yaml
+++ b/.github/file-paths.yaml
@@ -115,10 +115,10 @@ backend_sources: &backend_sources
- "src/**"
- "modules/drivers/{*,*/{*,!(test)/**}}"
- "resources/**"
- # The ratchets file drives project_ratchet_checks alone, so the automation PR that lowers the budgets
- # runs the Project tests job by itself. Patterns are OR-ed, so a separate "!..." entry would match
+ # Ratchet files drive project_ratchet_checks alone, so automation PRs that lower budgets
+ # run the Project tests job by themselves. Patterns are OR-ed, so a separate "!..." entry would match
# every other path instead of excluding this one.
- - ".clj-kondo/{!(ratchets.edn),*/**}"
+ - ".clj-kondo/**/!(ratchets.edn)"
backend_specs: &backend_specs
- *shared_specs
@@ -169,6 +169,7 @@ project_backend_checks:
# Only the ratchet check reads the budgets, so a diff that touches nothing else runs that suite alone.
project_ratchet_checks:
- ".clj-kondo/ratchets.edn"
+ - ".clj-kondo/config/modules/ratchets.edn"
project_migration_checks:
- *project_tests_infra
diff --git a/.github/scripts/file-paths.unit.spec.ts b/.github/scripts/file-paths.unit.spec.ts
index f7922c92625..5db31531eaf 100644
--- a/.github/scripts/file-paths.unit.spec.ts
+++ b/.github/scripts/file-paths.unit.spec.ts
@@ -29,7 +29,7 @@ describe("file-paths.yaml", () => {
// dorny/paths-filter ORs the patterns in a filter, so a "!..." entry does not subtract from the
// other entries - it matches every path they don't, turning the filter permanently on. Excluding
// a path means writing the exclusion inside one pattern, the way backend_sources keeps
- // ratchets.edn out with ".clj-kondo/{!(ratchets.edn),*/**}".
+ // ratchet files out with ".clj-kondo/**/!(ratchets.edn)".
it("never excludes a path with a standalone negation", () => {
const negated = Object.entries(filters).flatMap(([name, filter]) =>
patterns(filter)
@@ -44,6 +44,9 @@ describe("file-paths.yaml", () => {
"%s skips a ratchets-only change and still follows the rest of .clj-kondo",
(name) => {
expect(matches(name, ".clj-kondo/ratchets.edn")).toBe(false);
+ expect(
+ matches(name, ".clj-kondo/config/modules/ratchets.edn"),
+ ).toBe(false);
expect(matches(name, ".clj-kondo/config.edn")).toBe(true);
expect(matches(name, ".clj-kondo/config/modules/config.edn")).toBe(true);
},
@@ -53,5 +56,11 @@ describe("file-paths.yaml", () => {
expect(matches("project_ratchet_checks", ".clj-kondo/ratchets.edn")).toBe(
true,
);
+ expect(
+ matches(
+ "project_ratchet_checks",
+ ".clj-kondo/config/modules/ratchets.edn",
+ ),
+ ).toBe(true);
});
});
diff --git a/.github/workflows/kondo-ratchets-shrink.yml b/.github/workflows/kondo-ratchets-shrink.yml
index 20a2d6804a1..51e0840e894 100644
--- a/.github/workflows/kondo-ratchets-shrink.yml
+++ b/.github/workflows/kondo-ratchets-shrink.yml
@@ -1,9 +1,9 @@
name: Shrink ratchets
-# Lowers the budgets in .clj-kondo/ratchets.edn to match master and delivers the result through one
+# Lowers the ratchet budgets to match master and delivers the result through one
# automation PR, because the rulesets require a pull request for every change to master. The PR is
# approved by github-actions[bot] and merges itself once the ratchet check passes. A merge of that PR
-# touches only ratchets.edn, which matches `.clj-kondo/**` below, so it triggers one more run that finds
+# touches only ratchet files, which match `.clj-kondo/**` below, so it triggers one more run that finds
# nothing to lower and stops: a single no-op, not a loop.
on:
@@ -32,7 +32,8 @@ concurrency:
env:
AUTOMATION_BRANCH: automation/shrink-ratchets
- RATCHETS_FILE: .clj-kondo/ratchets.edn
+ KONDO_RATCHETS_FILE: .clj-kondo/ratchets.edn
+ MODULE_RATCHETS_FILE: .clj-kondo/config/modules/ratchets.edn
jobs:
shrink:
@@ -56,9 +57,10 @@ jobs:
with:
distribution: temurin
java-version: 25
- - name: Shrink ignore limits
+ - name: Shrink ratchets
run: |
- cp "$RATCHETS_FILE" "$RUNNER_TEMP/ratchets-before.edn"
+ cp "$KONDO_RATCHETS_FILE" "$RUNNER_TEMP/kondo-ratchets-before.edn"
+ cp "$MODULE_RATCHETS_FILE" "$RUNNER_TEMP/module-ratchets-before.edn"
./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
@@ -77,23 +79,23 @@ jobs:
--jq '.[0].number // empty')
echo "pr=$open_pr" >> "$GITHUB_OUTPUT"
- if git diff --quiet -- "$RATCHETS_FILE"; then
+ if git diff --quiet -- "$KONDO_RATCHETS_FILE" "$MODULE_RATCHETS_FILE"; then
echo "Ratchet budgets already match master $(git rev-parse --short HEAD)"
[ -z "$open_pr" ] || echo "The open automation PR #$open_pr is re-approved below"
echo "push=false" >> "$GITHUB_OUTPUT"
exit 0
fi
- # The ratchet file is the whole payload, so an open PR that already carries this result is left
+ # The ratchet files are 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. 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.
+ # shrunk ratchet files produced above, to determine whether the PR would deliver the same result.
#
# 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.
if [ -n "$open_pr" ] \
&& git fetch --quiet --depth=1 origin "refs/heads/$AUTOMATION_BRANCH" 2>/dev/null \
- && git diff --quiet FETCH_HEAD -- "$RATCHETS_FILE" \
+ && git diff --quiet FETCH_HEAD -- "$KONDO_RATCHETS_FILE" "$MODULE_RATCHETS_FILE" \
&& [ "$(gh pr view "$open_pr" --repo "$GITHUB_REPOSITORY" \
--json mergeable --jq .mergeable)" != CONFLICTING ]; then
echo "The automation PR #$open_pr already carries this result"
@@ -102,7 +104,7 @@ jobs:
exit 0
fi
- git diff --stat -- "$RATCHETS_FILE"
+ git diff --stat -- "$KONDO_RATCHETS_FILE" "$MODULE_RATCHETS_FILE"
echo "push=true" >> "$GITHUB_OUTPUT"
- name: Update the automation PR
id: deliver
@@ -116,14 +118,16 @@ jobs:
OPEN_PR: ${{ steps.compare.outputs.pr }}
run: |
./bin/mage -kondo-ratchets-pr-body \
- "$RUNNER_TEMP/ratchets-before.edn" \
- "$RATCHETS_FILE" \
+ "$RUNNER_TEMP/kondo-ratchets-before.edn" \
+ "$KONDO_RATCHETS_FILE" \
+ "$RUNNER_TEMP/module-ratchets-before.edn" \
+ "$MODULE_RATCHETS_FILE" \
"${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}" \
> "$RUNNER_TEMP/ratchets-pr-body.md"
git config user.name github-actions
git config user.email [email protected]
- git add -- "$RATCHETS_FILE"
+ git add -- "$KONDO_RATCHETS_FILE" "$MODULE_RATCHETS_FILE"
git commit --quiet -m "Tighten ratchets"
git push --force --quiet \
"https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" \
diff --git a/CLAUDE.md b/CLAUDE.md
index 169b5b0daa4..fbf1cf8ff41 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -98,70 +98,14 @@ Module names form a tree: `lib.schema` is a child of `lib`. When OSS module `sea
- Each `:module-exports` entry widens a nested module's visibility by one ancestor. Export every link to
make it available everywhere. OSS module `X` exports its `enterprise/X` companion automatically.
-## Kondo Ignore Ratchets
+## 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 a non-negative integer ceiling or
-`:unlimited`, which has no ceiling. This count policy is independent of `:comment-exempt`, described below.
+After changing Clojure suppressions or module-boundary escape hatches, run `./bin/mage kondo-ratchets`.
+Fix the underlying issue when possible; suppressions are a last resort and need a nearby explanation.
-Both ratchet commands are quick Babashka tasks, not JVM test runs:
-
-```bash
-./bin/mage kondo-ratchets # validate the file without changing it
-./bin/mage kondo-ratchets-shrink [--seed :lint] # lower budgets; optionally seed one
-```
-
-`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.
-
-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 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
-removing, puts any still-working ignore back exactly as it was, and stamps it with a `[kondo-keep]`
-comment; marked sites are skipped on later runs. That verification needs a clean starting point, so
-files with pre-existing lint findings are excluded from the sweep and reported. `--fix --audit` rechecks the
-marked sites too, removing any that have become truly redundant along with their stamped marker
-comments (a marker trailing on a code line is left for a hand fix). `[kondo-keep]` can also be added
-by hand to protect an ignore whose exact form matters — it only counts on the line directly above the
-ignore, or trailing on the ignore's own line.
-
-If `.clj-kondo/ratchets.edn` conflicts during a merge, rebase, or restack, run
-`./bin/merge-kondo-ratchets`. A change on one side wins over an unchanged base. When both sides change
-the same policy, the tool chooses the smaller budget, a numeric budget over `:unlimited`, or a removed
-entry over either. A file deleted on one side and changed on the other is left for you to resolve.
+Explain budget increases in the PR. Do not record reductions in feature PRs: post-merge automation opens
+a `Tighten ratchets` PR for them. Use `./bin/mage kondo-ratchets-shrink --seed :linter` only when adding an
+inline-ignore budget. If either ratchet file conflicts, run `./bin/merge-kondo-ratchets`.
## Tool Preferences
diff --git a/bb.edn b/bb.edn
index ac1ee105440..a66bbb61012 100644
--- a/bb.edn
+++ b/bb.edn
@@ -307,13 +307,13 @@
(project-tests/run!)))}
kondo-ratchets
- {:doc "Validate .clj-kondo/ratchets.edn and the source tree's kondo suppressions (Babashka; seconds, not a test run)."
+ {:doc "Validate the kondo and module ratchet files against the source tree (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! (dev.kondo-ratchet/check))}
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."
+ {:doc "Lower kondo and module budgets to match the source tree. This is the only Mage task that writes the ratchet files."
: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)"]]
@@ -426,27 +426,33 @@
;; 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"]]
+ -ratchets-merge
+ {:doc "Internal three-way merge for ratchet files. Called by bin/merge-kondo-ratchets."
:arg-schema [:tuple
+ [:enum {:name "kind"} "kondo" "modules"]
[: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.
+ (let [[kind base-path ours-path theirs-path output-path] (:arguments parsed)
+ modules? (= kind "modules")
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)))
+ (if modules?
+ (binding [dev.kondo-ratchet/*module-ratchets-file* path]
+ (dev.kondo-ratchet/read-module-ratchets))
+ (binding [dev.kondo-ratchet/*ratchets-file* path]
+ (dev.kondo-ratchet/read-ratchets))))
+ [base ours theirs] (map read-stage [base-path ours-path theirs-path])]
+ (if modules?
+ (spit output-path
+ (dev.kondo-ratchet/render-module-ratchets
+ (dev.kondo-ratchet/merge-module-ratchets base ours theirs)))
+ (let [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))))}
-kondo-ratchets-pr-body
@@ -454,15 +460,22 @@
:arg-schema [:tuple
[:string {:name "before" :description "Ratchets file before shrinking"}]
[:string {:name "after" :description "Ratchets file after shrinking"}]
+ [:string {:name "modules-before" :description "Module ratchets before shrinking"}]
+ [:string {:name "modules-after" :description "Module ratchets after shrinking"}]
[:string {:name "workflow-url" :description "URL of the workflow run"}]]
:requires [[dev.kondo-ratchet]]
:task (task!
- (let [[before-path after-path workflow-url] (:arguments parsed)
+ (let [[before-path after-path modules-before-path modules-after-path workflow-url] (:arguments parsed)
read-ratchets (fn [path]
(binding [dev.kondo-ratchet/*ratchets-file* path]
- (dev.kondo-ratchet/read-ratchets)))]
- (print (dev.kondo-ratchet/shrink-pr-body (read-ratchets before-path)
- (read-ratchets after-path)
+ (dev.kondo-ratchet/read-ratchets)))
+ read-modules (fn [path]
+ (binding [dev.kondo-ratchet/*module-ratchets-file* path]
+ (dev.kondo-ratchet/read-module-ratchets)))]
+ (print (dev.kondo-ratchet/shrink-pr-body (assoc (read-ratchets before-path)
+ :module-counts (read-modules modules-before-path))
+ (assoc (read-ratchets after-path)
+ :module-counts (read-modules modules-after-path))
workflow-url))))}
-driver-decisions
diff --git a/bin/merge-kondo-ratchets b/bin/merge-kondo-ratchets
index b185b947e0b..0795f130d3a 100755
--- a/bin/merge-kondo-ratchets
+++ b/bin/merge-kondo-ratchets
@@ -1,7 +1,7 @@
#!/usr/bin/env bash
#
-# Resolve a conflicted .clj-kondo/ratchets.edn and stage the result.
-# This script only reads the index stages; `./bin/mage -kondo-ratchets-merge` merges the policies.
+# Resolve and stage conflicts in either ratchet file.
+# This script only reads index stages; Mage validates and merges the maps.
set -euo pipefail
@@ -9,41 +9,55 @@ set -euo pipefail
bin_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
cd -- "$(git rev-parse --show-toplevel)"
-ratchets_file=.clj-kondo/ratchets.edn
+ratchet_files=(
+ .clj-kondo/ratchets.edn
+ .clj-kondo/config/modules/ratchets.edn
+)
+conflicted_files=()
# One "<mode> <sha> <stage>\t<path>" line per unmerged stage: 1 = base, 2 = ours, 3 = theirs.
-stages=$(git ls-files -u -- "$ratchets_file" | awk '{ print $3 }')
-
-has_stage() {
- grep -qx -- "$1" <<< "$stages"
-}
-
-if [ -z "$stages" ]; then
- echo "$ratchets_file is not conflicted" >&2
- exit 1
-fi
-
-if ! has_stage 2 || ! has_stage 3; then
- echo "$ratchets_file was deleted on one side and changed on the other; resolve it by hand" >&2
+for ratchets_file in "${ratchet_files[@]}"; do
+ stages=$(git ls-files -u -- "$ratchets_file" | awk '{ print $3 }')
+ if [ -n "$stages" ]; then
+ conflicted_files+=("$ratchets_file")
+ if ! grep -qx -- 2 <<< "$stages" || ! grep -qx -- 3 <<< "$stages"; then
+ echo "$ratchets_file was deleted on one side and changed on the other; resolve it by hand" >&2
+ exit 1
+ fi
+ fi
+done
+
+if [ "${#conflicted_files[@]}" -eq 0 ]; then
+ echo "neither ratchet file is conflicted" >&2
exit 1
fi
tmp_dir=$(mktemp -d)
trap 'rm -rf -- "$tmp_dir"' EXIT
-git show ":2:$ratchets_file" > "$tmp_dir/ours"
-git show ":3:$ratchets_file" > "$tmp_dir/theirs"
-if has_stage 1; then
- git show ":1:$ratchets_file" > "$tmp_dir/base"
-else
- # Both sides added the file, so every policy is a one-sided change against an empty base.
- printf '{}\n' > "$tmp_dir/base"
-fi
-
-"$bin_dir/mage" -kondo-ratchets-merge \
- "$tmp_dir/base" \
- "$tmp_dir/ours" \
- "$tmp_dir/theirs" \
- "$PWD/$ratchets_file"
-git add -- "$ratchets_file"
-echo "staged merged $ratchets_file"
+for i in "${!conflicted_files[@]}"; do
+ ratchets_file=${conflicted_files[$i]}
+ stages=$(git ls-files -u -- "$ratchets_file" | awk '{ print $3 }')
+ git show ":2:$ratchets_file" > "$tmp_dir/ours-$i"
+ git show ":3:$ratchets_file" > "$tmp_dir/theirs-$i"
+ if grep -qx -- 1 <<< "$stages"; then
+ git show ":1:$ratchets_file" > "$tmp_dir/base-$i"
+ else
+ # Both sides added the file, so every policy is a one-sided change against an empty base.
+ printf '{}\n' > "$tmp_dir/base-$i"
+ fi
+
+ if [ "$ratchets_file" = .clj-kondo/ratchets.edn ]; then
+ kind=kondo
+ else
+ kind=modules
+ fi
+ "$bin_dir/mage" -ratchets-merge "$kind" \
+ "$tmp_dir/base-$i" \
+ "$tmp_dir/ours-$i" \
+ "$tmp_dir/theirs-$i" \
+ "$PWD/$ratchets_file"
+done
+
+git add -- "${conflicted_files[@]}"
+printf 'staged merged %s\n' "${conflicted_files[@]}"
diff --git a/dev/src/dev/deps_graph.clj b/dev/src/dev/deps_graph.clj
index 13804771aa9..94b70bf8b65 100644
--- a/dev/src/dev/deps_graph.clj
+++ b/dev/src/dev/deps_graph.clj
@@ -930,3 +930,105 @@
(comment
(model-ownership)
(model-boundary-violations (kondo-config)))
+
+;;;; Module boundary analysis
+
+(defn- graph-nodes [graph]
+ (into (set (keys graph)) (mapcat val) graph))
+
+(defn strongly-connected-components
+ "Return the strongly connected components of `graph` as a vector of sets.
+ A node outside every cycle comes back as a singleton set."
+ [graph]
+ ;; Tarjan's algorithm, kept recursive because that reads better than an explicit stack of frames.
+ ;; Each node on the search path costs a level of recursion, so the worst case is one level per node.
+ ;; As of 2026-09-11 the 206-module graph peaks at 40 levels; the default 2 MB thread stack fits about 2,600.
+ (letfn [(pop-component [state root]
+ (loop [state state, component #{}]
+ (let [node (peek (:stack state))
+ state (-> state
+ (update :stack pop)
+ (update :on-stack disj node))
+ component (conj component node)]
+ (if (= node root)
+ (update state :components conj component)
+ (recur state component)))))
+ (visit [state node]
+ (let [node-index (:next-index state)
+ state (-> state
+ (assoc-in [:index node] node-index)
+ (assoc-in [:lowlink node] node-index)
+ (update :next-index inc)
+ (update :stack conj node)
+ (update :on-stack conj node))
+ state (reduce (fn [state successor]
+ (cond
+ (not (contains? (:index state) successor))
+ (let [state (visit state successor)]
+ (update-in state [:lowlink node]
+ min
+ (get-in state [:lowlink successor])))
+
+ (contains? (:on-stack state) successor)
+ (update-in state [:lowlink node]
+ min
+ (get-in state [:index successor]))
+
+ :else
+ state))
+ state
+ (get graph node))]
+ (cond-> state
+ (= (get-in state [:lowlink node]) (get-in state [:index node]))
+ (pop-component node))))]
+ (:components
+ (reduce (fn [state node]
+ (cond-> state
+ (not (contains? (:index state) node)) (visit node)))
+ {:components []
+ :index {}
+ :lowlink {}
+ :next-index 0
+ :on-stack #{}
+ :stack []}
+ (sort (graph-nodes graph))))))
+
+(defn cyclic-components
+ "Non-singleton [[strongly-connected-components]], largest first; ties sort by first member."
+ [graph]
+ (->> (strongly-connected-components graph)
+ (filter #(> (count %) 1))
+ (sort-by (fn [component] [(- (count component)) (str (first (sort component)))]))
+ vec))
+
+(defn- cyclic-component-sizes
+ "Module and namespace counts for each [[cyclic-components]] cluster."
+ [graph node->namespace-count]
+ (mapv (fn [component]
+ {:modules (count component)
+ :namespaces (transduce (map #(get node->namespace-count % 0)) + 0 component)})
+ (cyclic-components graph)))
+
+(defn module-boundary-stats
+ "REPL diagnostics for the module graph:
+
+ - `:api-any-namespaces` namespaces exposed by `:api :any` modules
+ - `:module-count` configured modules
+ - `:scc-module-sizes` modules per cycle, largest first
+ - `:scc-namespace-sizes` namespaces per cycle, in the same order
+
+ These values are not ratcheted because any source change can move them. Use namespace sizes to track
+ cycle reduction: splitting a module can grow a cycle's module count without removing namespaces."
+ ([]
+ (module-boundary-stats (dependencies) (kondo-config)))
+ ([deps config]
+ (let [any-modules (into #{} (keep (fn [[module cfg]] (when (= :any (:api cfg)) module))) config)
+ sizes (cyclic-component-sizes (module-dependencies deps)
+ (frequencies (keep :module deps)))]
+ {:api-any-namespaces (count (filter #(contains? any-modules (:module %)) deps))
+ :module-count (count config)
+ :scc-module-sizes (mapv :modules sizes)
+ :scc-namespace-sizes (mapv :namespaces sizes)})))
+
+(comment
+ (module-boundary-stats))
diff --git a/dev/src/dev/kondo_ratchet.clj b/dev/src/dev/kondo_ratchet.clj
index dc92e90c184..3040f98f126 100644
--- a/dev/src/dev/kondo_ratchet.clj
+++ b/dev/src/dev/kondo_ratchet.clj
@@ -1,11 +1,9 @@
(ns dev.kondo-ratchet
- "Check inline kondo ignores against the per-linter policies in `.clj-kondo/ratchets.edn`.
+ "Enforce budgets for kondo suppressions and module escape hatches.
- 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."
+ Counts may fall but not exceed their budgets. Ignores outside `:comment-exempt` need justification.
+ `./bin/mage kondo-ratchets-shrink` is the only writer; `--seed` adds or raises an ignore budget.
+ This namespace runs under Babashka and the JVM, so keep it dependency-free."
{:clj-kondo/config '{:linters {:discouraged-var {clojure.core/println {:level :off}}}}}
(:require
[clojure.edn :as edn]
@@ -16,36 +14,58 @@
(set! *warn-on-reflection* true)
(def ^:dynamic *ratchets-file*
- "The budgets file, relative to the repo root. Rebind it to read a file elsewhere, such as a merge stage."
+ "Kondo budgets, relative to the repo root. Rebind to read a merge stage or test fixture."
".clj-kondo/ratchets.edn")
+(def ^:dynamic *module-ratchets-file*
+ "Module-boundary budgets, relative to the repo root. Rebind to read a merge stage or test fixture."
+ ".clj-kondo/config/modules/ratchets.edn")
+
+(def ^:private module-config-file
+ ".clj-kondo/config/modules/config.edn")
+
(defn- read-ratchets-form
- "The one EDN map in `file`.
+ "The one EDN map at `path`.
An empty file, a non-map, or a second form is an error rather than an empty policy set, so a damaged
file can never read as \"no budgets\"."
- [^java.io.File file]
- (with-open [reader (java.io.PushbackReader. (io/reader file))]
+ [path]
+ (with-open [reader (java.io.PushbackReader. (io/reader path))]
(let [eof (Object.)
form (edn/read {:eof eof} reader)]
(when (identical? eof form)
- (throw (ex-info (str *ratchets-file* " is empty; expected one map of policies")
- {:file *ratchets-file*})))
+ (throw (ex-info (str path " is empty; expected one map of policies")
+ {:file path})))
(when-not (map? form)
- (throw (ex-info (str *ratchets-file* " must hold a map of policies, not " (pr-str form))
- {:file *ratchets-file*, :form form})))
+ (throw (ex-info (str path " must hold a map of policies, not " (pr-str form))
+ {:file path, :form form})))
(when-not (identical? eof (edn/read {:eof eof} reader))
- (throw (ex-info (str *ratchets-file* " holds more than one form; expected one map of policies")
- {:file *ratchets-file*})))
+ (throw (ex-info (str path " holds more than one form; expected one map of policies")
+ {:file path})))
form)))
(def ^:private empty-policies
{:ignore-counts {}, :config-counts {}, :comment-exempt #{}})
+(defn- validate-budgets!
+ "Throw unless `budgets`, the value of `field`, maps names to non-negative integers."
+ [field budgets]
+ (when-not (map? budgets)
+ (throw (ex-info (str field " must be a map of budgets")
+ {field budgets})))
+ (doseq [[k budget] budgets]
+ (when-not (nat-int? budget)
+ (throw (ex-info (format "%s in %s has invalid budget %s; expected a non-negative integer"
+ k field (pr-str budget))
+ {:field field, :name k, :budget budget})))))
+
(defn validate-policies
- "`ratchets` when each policy field it carries has the right shape: `:ignore-counts` maps linters to a
- non-negative integer or `:unlimited`, `:config-counts` maps linters to a non-negative integer, and
- `:comment-exempt` is a set. Every linter named anywhere must be a keyword.
- Throws otherwise, so a malformed file can never be read as a set of removals."
+ "Validate and return `ratchets`:
+
+ - `:ignore-counts` maps linters to non-negative integers or `:unlimited`
+ - `:config-counts` maps linters to non-negative integers
+ - `:comment-exempt` is a set of linters
+
+ All names must be keywords. Throws on malformed input."
[ratchets]
(let [{:keys [ignore-counts config-counts comment-exempt]} (merge empty-policies ratchets)]
(when-not (map? ignore-counts)
@@ -57,36 +77,47 @@
(throw (ex-info (format "%s has invalid policy %s; expected a non-negative integer or :unlimited"
linter (pr-str policy))
{:linter linter, :policy policy}))))
- (when-not (map? config-counts)
- (throw (ex-info ":config-counts must be a map of linter budgets"
- {:config-counts config-counts})))
- (doseq [[linter budget] config-counts]
- (when-not (and (integer? budget) (not (neg? budget)))
- (throw (ex-info (format "%s has invalid config budget %s; expected a non-negative integer"
- linter (pr-str budget))
- {:linter linter, :budget budget}))))
+ (validate-budgets! :config-counts config-counts)
(when-not (set? comment-exempt)
(throw (ex-info ":comment-exempt must be a set of linters"
{:comment-exempt comment-exempt})))
;; the merge keys on (str linter) and renders the same way, so a non-keyword name would be rewritten
;; as a keyword, collide with one, or produce a file that no longer reads back
- (doseq [linter (concat (keys ignore-counts) (keys config-counts) comment-exempt)]
- (when-not (keyword? linter)
+ (doseq [policy-name (concat (keys ignore-counts) (keys config-counts) comment-exempt)]
+ (when-not (keyword? policy-name)
(throw (ex-info (format "%s is not a linter name; policies and exemptions are keyed by keyword"
- (pr-str linter))
- {:linter linter}))))
+ (pr-str policy-name))
+ {:policy-name policy-name}))))
ratchets))
(defn read-ratchets
- "Parsed contents of [[*ratchets-file*]], with empty defaults for omitted keys.
- Throws when the file is missing or a policy field is malformed (see [[validate-policies]]); only an
- explicit `{:disabled true}` opts out of enforcement."
+ "Read and validate [[*ratchets-file*]], defaulting omitted fields to empty.
+ Only `{:disabled true}` disables enforcement."
[]
(let [file (io/file *ratchets-file*)]
(when-not (.exists file)
(throw (ex-info (str *ratchets-file* " is missing -- only {:disabled true} opts out of enforcement")
{:file *ratchets-file*})))
- (validate-policies (merge empty-policies (read-ratchets-form file)))))
+ (validate-policies (merge empty-policies (read-ratchets-form *ratchets-file*)))))
+
+(defn validate-module-ratchets
+ "Validate and return a map from module metric keywords to non-negative integer budgets."
+ [ratchets]
+ (validate-budgets! :module-ratchets ratchets)
+ (doseq [metric (keys ratchets)]
+ (when-not (keyword? metric)
+ (throw (ex-info (str (pr-str metric) " is not a module metric; metrics are keyed by keyword")
+ {:metric metric}))))
+ ratchets)
+
+(defn read-module-ratchets
+ "Read and validate [[*module-ratchets-file*]]."
+ []
+ (let [file (io/file *module-ratchets-file*)]
+ (when-not (.exists file)
+ (throw (ex-info (str *module-ratchets-file* " is missing")
+ {:file *module-ratchets-file*})))
+ (validate-module-ratchets (read-ratchets-form *module-ratchets-file*))))
(defn disabled?
"Whether `ratchets` (default: [[read-ratchets]]) explicitly disables the ratchets."
@@ -95,6 +126,24 @@
([ratchets]
(true? (:disabled ratchets))))
+(defn module-escape-hatches
+ "Count the module config's escape hatches.
+
+ - `:api-any` modules that expose every namespace
+ - `:friend-edges` individual `:friends` grants
+ - `:model-imports-bypass` modules exempt from model-boundary checks
+ - `:uses-any` modules that may depend on any module"
+ ([]
+ (-> (edn/read-string (slurp module-config-file))
+ :metabase/modules
+ module-escape-hatches))
+ ([config]
+ (let [values (vals config)]
+ {:api-any (count (filter #(= :any (:api %)) values))
+ :friend-edges (transduce (map (comp count :friends)) + 0 values)
+ :model-imports-bypass (count (filter #(= :bypass (:model-imports %)) values))
+ :uses-any (count (filter #(= :any (:uses %)) values))})))
+
(def ^:private deps-file
"deps.edn")
@@ -530,9 +579,8 @@
[_k cfg] (get config scope)]
(counts (:linters cfg)))))))
-(defn config-drift
- "Linters whose config-suppression count differs from its budget (absent = 0, either side).
- Returns `{linter {:recorded _, :actual _}}`."
+(defn count-drift
+ "Differences between `recorded` and `actual`, treating missing values as zero, sorted by name."
[recorded actual]
(sorted-by-str
(for [linter (into (set (keys actual)) (keys recorded))
@@ -541,11 +589,11 @@
:when (not= budget n)]
[linter {:recorded budget, :actual n}])))
-(defn config-over-budget
- "Linters whose config-suppression count exceeds its budget."
+(defn counts-over-budget
+ "Names whose actual count exceeds their budget."
[budgets counts]
(sorted-by-str
- (for [[linter {:keys [recorded actual] :as entry}] (config-drift budgets counts)
+ (for [[linter {:keys [recorded actual] :as entry}] (count-drift budgets counts)
:when (> actual recorded)]
[linter entry])))
@@ -557,10 +605,14 @@
";; Any ignore outside :comment-exempt needs an explanatory comment directly above or trailing on its line.\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"
+ ";; Raising or adding a budget (`--seed` for inline ignores, a manual edit otherwise) 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"))
+(def ^:private module-header
+ (str ";; Budgets for escape hatches in config.edn. Counts may fall but not exceed these values.\n"
+ ";; Leave reductions to the post-merge shrink workflow; explain increases in the PR.\n"))
+
(defn- render-counts
[counts indent]
(if (empty? counts)
@@ -574,8 +626,7 @@
"}"))))
(defn render
- "Text of the ratchets file for the `{:ignore-counts _, :config-counts _, :comment-exempt _}` map.
- Byte-stable: [[fix!]] idempotency and the file-hygiene test depend on it."
+ "Canonical Kondo ratchet-file text."
[{:keys [ignore-counts config-counts comment-exempt]}]
(let [counts-indent (apply str (repeat (count "{:ignore-counts {") \space))
exempt-indent (apply str (repeat (count " :comment-exempt #{") \space))]
@@ -591,6 +642,11 @@
"}"))
"}\n")))
+(defn render-module-ratchets
+ "Canonical module ratchet-file text."
+ [ratchets]
+ (str module-header (render-counts ratchets " ") "\n"))
+
(def ^:private absent
"Stands in for a policy map entry that a stage doesn't have."
::absent)
@@ -637,7 +693,7 @@
(into (set base) (concat ours theirs))))
(def ^:private merge-fields
- #{:ignore-counts :config-counts :comment-exempt})
+ #{:comment-exempt :config-counts :ignore-counts})
(defn- validate-merge-shape
"`ratchets` when it contains only the policy fields and `:disabled`, and each policy field passes
@@ -653,11 +709,9 @@
(validate-policies ratchets))
(defn merge-ratchets
- "Three-way merge ratchets from `base`, the target branch (`ours`), and the incoming branch (`theirs`).
- Every stage is validated first, even when a disabled stage decides the result: a target that
- explicitly disables ratchets stays disabled, and an incoming disabled form leaves `ours` as it is.
- Otherwise `:ignore-counts` and `:config-counts` merge with [[merge-counts]] and `:comment-exempt`
- with [[merge-exemptions]]."
+ "Three-way merge `base`, `ours`, and `theirs`, validating every stage first.
+ A disabled target stays disabled; a disabled incoming stage leaves `ours` unchanged. Otherwise merge
+ count maps with [[merge-counts]] and exemptions with [[merge-exemptions]]."
[base ours theirs]
(let [[base ours theirs] (map validate-merge-shape [base ours theirs])]
(cond
@@ -673,6 +727,11 @@
(:comment-exempt ours #{})
(:comment-exempt theirs #{}))})))
+(defn merge-module-ratchets
+ "Three-way merge module budgets, validating every stage first."
+ [base ours theirs]
+ (apply merge-counts (map validate-module-ratchets [base ours theirs])))
+
(defn lowered-counts
"`recorded` with each bounded budget lowered to its actual count; bounded entries with no ignores go.
An `:unlimited` policy is kept as written, even at zero: it records a decision about the linter, not a count.
@@ -724,7 +783,8 @@
(defn change-report
"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]
+ [{:keys [ignore-counts config-counts comment-exempt]} module-ratchets
+ occurrences config-actual module-actual seeded]
(let [actual (actual-counts occurrences)]
(concat
(for [linter seeded
@@ -748,21 +808,29 @@
(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 kondo-ratchets-shrink --seed %s`"
linter n linter))
- (for [[linter {:keys [recorded actual]}] (config-drift config-counts config-actual)]
+ (for [[linter {:keys [recorded actual]}] (count-drift config-counts config-actual)]
(cond
(zero? actual) (format "dropped config %s (no suppressions left)" linter)
(< 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 [[metric {:keys [recorded actual]}] (count-drift module-ratchets module-actual)]
+ (cond
+ (zero? actual) (format "dropped module %s (no escape hatches left)" metric)
+ (< actual recorded) (format "lowered module %s %d -> %d" metric recorded actual)
+ :else (format (str "WARNING: module %s is over budget (%d recorded, %d actual)"
+ " -- remove one from " module-config-file " or raise the budget by hand")
+ metric recorded actual)))
(some-> (stale-exemptions-warning comment-exempt occurrences) vector))))
(def ^:private count-fields
- [:ignore-counts :config-counts])
+ [:ignore-counts :config-counts :module-counts])
(defn- display-name
[field linter]
- (if (= field :config-counts)
- (str ":config/" (subs (str linter) 1))
+ (case field
+ :config-counts (str ":config/" (subs (str linter) 1))
+ :module-counts (str ":module/" (subs (str linter) 1))
(str linter)))
(defn- shrink-changes
@@ -785,7 +853,7 @@
(defn shrink-summary
"A compact, sorted before/after listing of numeric budgets lowered between two ratchet maps.
- Config-level budgets carry a `:config/` prefix."
+ Config and module budgets carry `:config/` and `:module/` prefixes."
[before after]
(let [changes (shrink-changes before after)]
(if (empty? changes)
@@ -829,7 +897,7 @@
")\n"))
(defn fix!
- "Rewrite [[*ratchets-file*]]: lower budgets and normalize formatting.
+ "Lower budgets and normalize both ratchet files.
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.
@@ -840,53 +908,67 @@
(let [{:keys [ignore-counts config-counts comment-exempt] :as ratchets} (read-ratchets)]
(if (disabled? ratchets)
(println (str *ratchets-file* " is disabled -- nothing to do"))
- (let [known (known-linters)
- _ (validate-linters! ratchets known)
- seeded (if seed [(keyword (str/replace-first seed #"^:" ""))] [])
- _ (validate-seed! seeded known)
- occurrences (scan)
- actual (actual-counts occurrences)
- config-actual (config-suppressions)
- text (render {:ignore-counts (lowered-counts ignore-counts actual seeded)
- :config-counts (lowered-counts config-counts config-actual [])
- :comment-exempt comment-exempt})
- old (slurp *ratchets-file*)]
- (run! println (change-report ratchets occurrences config-actual seeded))
- (if (= old text)
+ (let [module-ratchets (read-module-ratchets)
+ known (known-linters)
+ _ (validate-linters! ratchets known)
+ seeded (if seed [(keyword (str/replace-first seed #"^:" ""))] [])
+ _ (validate-seed! seeded known)
+ occurrences (scan)
+ actual (actual-counts occurrences)
+ config-actual (config-suppressions)
+ module-actual (module-escape-hatches)
+ outputs [[*ratchets-file*
+ (render {:ignore-counts (lowered-counts ignore-counts actual seeded)
+ :config-counts (lowered-counts config-counts config-actual [])
+ :comment-exempt comment-exempt})]
+ [*module-ratchets-file*
+ (render-module-ratchets
+ (lowered-counts module-ratchets module-actual []))]]
+ changed (filterv (fn [[path text]] (not= (slurp path) text)) outputs)]
+ (run! println (change-report ratchets module-ratchets occurrences config-actual module-actual seeded))
+ (if (empty? changed)
(println "unchanged")
- (do (spit *ratchets-file* text)
- (println (str "wrote " *ratchets-file*)))))))))
+ (doseq [[path text] changed]
+ (spit path text)
+ (println (str "wrote " path)))))))))
(defn check-report
- "The lines [[check]] prints when inline ignores or config suppressions (`config-actual`) exceed their
- 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."
+ "Diagnostics for budget violations, unjustified ignores, and noncanonical ratchet text.
+ Lower counts are valid; post-merge automation records them."
[{:keys [ignore-counts config-counts comment-exempt] :or {comment-exempt #{}} :as ratchets}
- occurrences config-actual text]
+ module-ratchets occurrences config-actual module-actual ratchets-text module-ratchets-text]
(let [over (over-budget ignore-counts occurrences)
- config-over (config-over-budget config-counts config-actual)
+ config-over (counts-over-budget config-counts config-actual)
+ module-over (counts-over-budget module-ratchets module-actual)
uncommented (unjustified comment-exempt occurrences)
- linter-line (fn [[linter {:keys [recorded actual]}]]
- (format " %s: %d recorded, %d actual" linter recorded actual))]
+ budget-line (fn [[k {:keys [recorded actual]}]]
+ (format " %s: %d recorded, %d actual" k recorded actual))]
(concat
(when (seq over)
(cons (str "over budget -- remove an ignore, or seed the budget with"
" `./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)))
+ (cons (budget-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 manually and explain the increase in the PR:")
- (map linter-line config-over)))
+ (map budget-line config-over)))
+ (when (seq module-over)
+ (cons (str "module escape hatches over budget -- remove one from " module-config-file
+ ", or raise the budget manually and explain the increase in the PR:")
+ (map budget-line module-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))
+ (when (not= ratchets-text (render ratchets))
[(str *ratchets-file* " is not normalized -- run `./bin/mage kondo-ratchets-shrink`"
+ " to fix the formatting")])
+ (when (not= module-ratchets-text (render-module-ratchets module-ratchets))
+ [(str *module-ratchets-file* " is not normalized -- run `./bin/mage kondo-ratchets-shrink`"
" to fix the formatting")]))))
(defn- exit!
@@ -901,32 +983,30 @@
(exit! message))
(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, an ignore lacks a required justification
- comment, or the file is not normalized.
- Only an explicit `{:disabled true}` opts out of enforcement.
- Unused `:unlimited` policies and stale `:comment-exempt` entries are reported but do not fail the check."
+ "Validate the ratchet files and current counts. Fail on missing or malformed configuration, unknown
+ linters, budget violations, or unjustified ignores. Report stale unlimited policies and exemptions
+ without failing. Only `{:disabled true}` disables enforcement."
[]
- (if-not (.exists (io/file *ratchets-file*))
- (fail! (str *ratchets-file* " is missing -- only {:disabled true} opts out of enforcement"))
- ;; read-ratchets, validate-linters! and scan all throw on malformed input; without this they reach
- ;; the user as a babashka stack dump.
- (try
- (let [ratchets (read-ratchets)]
- (if (disabled? ratchets)
- (println (str *ratchets-file* " is disabled -- nothing to check"))
- (do
- (validate-linters! ratchets (known-linters))
- (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))))
- (do (run! println lines)
- (exit! (str *ratchets-file* " drifted from the source tree"))))))))
- (catch clojure.lang.ExceptionInfo e
- (if (:babashka/exit (ex-data e))
- (throw e)
- (fail! (ex-message e)))))))
+ ;; Turn validation errors into concise Mage output instead of a Babashka stack trace.
+ (try
+ (let [ratchets (read-ratchets)]
+ (if (disabled? ratchets)
+ (println (str *ratchets-file* " is disabled -- nothing to check"))
+ (do
+ (validate-linters! ratchets (known-linters))
+ (let [module-ratchets (read-module-ratchets)
+ occurrences (scan)
+ lines (check-report ratchets module-ratchets occurrences
+ (config-suppressions) (module-escape-hatches)
+ (slurp *ratchets-file*) (slurp *module-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))))
+ (do (run! println lines)
+ (exit! "ratchet files drifted from the source tree")))))))
+ (catch clojure.lang.ExceptionInfo e
+ (if (:babashka/exit (ex-data e))
+ (throw e)
+ (fail! (ex-message e))))))
diff --git a/dev/test/metabase/core/kondo_ratchet_check_test.clj b/dev/test/metabase/core/kondo_ratchet_check_test.clj
index 245f2d4c3fa..96cb29731cb 100644
--- a/dev/test/metabase/core/kondo_ratchet_check_test.clj
+++ b/dev/test/metabase/core/kondo_ratchet_check_test.clj
@@ -4,7 +4,8 @@
[clojure.java.io :as io]
[clojure.string :as str]
[clojure.test :refer :all]
- [dev.kondo-ratchet :as kondo-ratchet]))
+ [dev.kondo-ratchet :as kondo-ratchet]
+ [metabase.test :as mt]))
(set! *warn-on-reflection* true)
@@ -19,10 +20,16 @@
"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))
+ (report-lines ratchets occurrences {} {} text))
([ratchets occurrences config-actual text]
- (vec (kondo-ratchet/check-report (merge {:config-counts {}, :comment-exempt #{}} ratchets)
- occurrences config-actual text))))
+ (report-lines ratchets occurrences config-actual {} text))
+ ([ratchets occurrences config-actual module-actual text]
+ (let [module-ratchets (:module-counts ratchets {})]
+ (vec (kondo-ratchet/check-report (-> {:config-counts {}, :comment-exempt #{}}
+ (merge ratchets)
+ (dissoc :module-counts))
+ module-ratchets occurrences config-actual module-actual text
+ (kondo-ratchet/render-module-ratchets module-ratchets))))))
(deftest ^:parallel clean-test
(let [ratchets {:ignore-counts {:a 2, :b 1}}]
@@ -69,6 +76,18 @@
(report-lines ratchets [] {:a 2, :b 1, :new 1} (kondo-ratchet/render ratchets)))
"a lowered config count passes; growth and new entries are reported")))
+(deftest ^:parallel module-over-budget-test
+ (let [ratchets {:ignore-counts {}, :module-counts {:api-any 1, :friend-edges 3}}]
+ (is (= ["module escape hatches over budget -- remove one from .clj-kondo/config/modules/config.edn, or raise the budget manually and explain the increase in the PR:"
+ " :api-any: 1 recorded, 2 actual"
+ " :uses-any: 0 recorded, 1 actual"]
+ (report-lines ratchets
+ []
+ {}
+ {:api-any 2, :friend-edges 2, :uses-any 1}
+ (kondo-ratchet/render ratchets)))
+ "lower counts pass; growth and new metrics are reported")))
+
(defn- check-with!
"Output lines of [[kondo-ratchet/check]] against `ratchets` written to a temp file, with `occurrences`
standing in for the tree scan; `:thrown?` says whether it failed."
@@ -77,11 +96,16 @@
"kondo-ratchet-check-test"
(make-array java.nio.file.attribute.FileAttribute 0)))
budgets (doto (io/file dir "ratchets.edn")
- (spit (kondo-ratchet/render (merge {:config-counts {}, :comment-exempt #{}} ratchets))))
+ (spit (kondo-ratchet/render (merge {:config-counts {}, :comment-exempt #{}}
+ (dissoc ratchets :module-counts)))))
+ modules (doto (io/file dir "module-ratchets.edn")
+ (spit (kondo-ratchet/render-module-ratchets (:module-counts ratchets {}))))
thrown? (atom false)]
- (binding [kondo-ratchet/*ratchets-file* (.getPath budgets)]
+ (binding [kondo-ratchet/*ratchets-file* (.getPath budgets)
+ kondo-ratchet/*module-ratchets-file* (.getPath modules)]
(with-redefs [kondo-ratchet/known-linters (constantly (set (keys (:ignore-counts ratchets))))
kondo-ratchet/config-suppressions (constantly {})
+ kondo-ratchet/module-escape-hatches (constantly {})
kondo-ratchet/scan (constantly occurrences)]
{:lines (str/split-lines
(with-out-str
@@ -152,8 +176,13 @@
(make-array java.nio.file.attribute.FileAttribute 0)))
budgets (doto (io/file dir "ratchets.edn") (spit "{:disabled true}\n"))]
(binding [kondo-ratchet/*ratchets-file* (.getPath budgets)]
- (is (= (str (.getPath budgets) " is disabled -- nothing to check\n")
- (with-out-str (kondo-ratchet/check)))))))
+ (mt/with-dynamic-fn-redefs
+ [kondo-ratchet/known-linters #(throw (AssertionError. "read the known linters"))
+ kondo-ratchet/scan #(throw (AssertionError. "scanned the source tree"))
+ kondo-ratchet/config-suppressions #(throw (AssertionError. "counted config suppressions"))
+ kondo-ratchet/module-escape-hatches #(throw (AssertionError. "counted module escape hatches"))]
+ (is (= (str (.getPath budgets) " is disabled -- nothing to check\n")
+ (with-out-str (kondo-ratchet/check))))))))
(deftest check-unknown-linter-test
(let [dir (.toFile (java.nio.file.Files/createTempDirectory
diff --git a/dev/test/metabase/core/kondo_ratchet_test.clj b/dev/test/metabase/core/kondo_ratchet_test.clj
index 6156b8563a4..e6954083895 100644
--- a/dev/test/metabase/core/kondo_ratchet_test.clj
+++ b/dev/test/metabase/core/kondo_ratchet_test.clj
@@ -28,8 +28,8 @@
(is (= {:a {:recorded 0, :actual 1, :examples ["f.clj:1"]}}
(kondo-ratchet/over-budget {:b 1} occurrences))))
(testing "config budgets"
- (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}))))))
+ (is (= {} (kondo-ratchet/counts-over-budget {:cfg 3} {:cfg 1})))
+ (is (= {:cfg {:recorded 1, :actual 2}} (kondo-ratchet/counts-over-budget {:cfg 1} {:cfg 2}))))))
;;;; ---------------------------------------------------------------------------
;;;; Scanner unit tests
@@ -170,8 +170,14 @@
;;;; Budget bookkeeping unit tests
;;;; ---------------------------------------------------------------------------
+(deftest ^:parallel module-escape-hatches-test
+ (is (= {:api-any 1, :friend-edges 3, :model-imports-bypass 1, :uses-any 1}
+ (kondo-ratchet/module-escape-hatches
+ {'a {:api :any, :friends #{'b 'c}, :uses #{'b}, :model-imports :bypass}
+ 'b {:api #{'b.api}, :friends #{'a}, :uses :any, :model-imports #{:model/A}}}))))
+
(deftest ^:parallel render-test
- (testing "keys come out sorted, values aligned, and the text round-trips losslessly"
+ (testing "renders stable text with sorted entries"
(let [ratchets {:ignore-counts {:all 1
:discouraged-var 3
:metabase/modules 2
@@ -194,6 +200,13 @@
(is (str/ends-with? (kondo-ratchet/render {:ignore-counts {}, :config-counts {}, :comment-exempt #{}})
"{:ignore-counts {}\n :config-counts {}\n :comment-exempt #{}}\n"))))
+(deftest ^:parallel render-module-ratchets-test
+ (let [ratchets {:uses-any 4, :api-any 1}
+ text (kondo-ratchet/render-module-ratchets ratchets)]
+ (is (str/ends-with? text "{:api-any 1\n :uses-any 4}\n"))
+ (is (= ratchets (edn/read-string text)))
+ (is (= text (kondo-ratchet/render-module-ratchets (edn/read-string text))))))
+
(deftest read-ratchets-policy-values-test
(let [file (doto (java.io.File/createTempFile "kondo-ratchets" ".edn")
(spit (pr-str {:ignore-counts {:bounded 4, :free :unlimited}})))]
@@ -220,7 +233,18 @@
(binding [kondo-ratchet/*ratchets-file* (.getPath file)]
(is (thrown-with-msg? clojure.lang.ExceptionInfo #"expected a non-negative integer"
(kondo-ratchet/read-ratchets))
- (str "a config budget is always a plain count, so " (pr-str value) " is rejected"))))))
+ (str "config budgets are always plain counts, so " (pr-str value) " is rejected"))))))
+
+(deftest read-module-ratchets-test
+ (doseq [[content message] [["{:api-any 1}" nil]
+ ["{:api-any :unlimited}" #"expected a non-negative integer"]
+ ["{\"api-any\" 1}" #"is not a module metric"]]]
+ (let [file (doto (java.io.File/createTempFile "module-ratchets" ".edn") (spit content))]
+ (binding [kondo-ratchet/*module-ratchets-file* (.getPath file)]
+ (if message
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo message
+ (kondo-ratchet/read-module-ratchets)))
+ (is (= {:api-any 1} (kondo-ratchet/read-module-ratchets))))))))
(deftest read-ratchets-validates-field-shapes-test
(doseq [[field message] [[:ignore-counts #":ignore-counts must be a map"]
@@ -301,15 +325,20 @@
"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"
+ (testing "fix! explains that the ratchets are disabled, counts nothing, and leaves the file unchanged"
(let [dir (.toFile (java.nio.file.Files/createTempDirectory
"kondo-ratchet-test"
(make-array java.nio.file.attribute.FileAttribute 0)))
budgets (doto (io/file dir "ratchets.edn") (spit "{:disabled true}\n"))]
(binding [kondo-ratchet/*ratchets-file* (.getPath budgets)]
(is (kondo-ratchet/disabled?))
- (is (= (str (.getPath budgets) " is disabled -- nothing to do\n")
- (with-out-str (kondo-ratchet/fix! {:seed "whatever"}))))
+ (mt/with-dynamic-fn-redefs
+ [kondo-ratchet/known-linters #(throw (AssertionError. "read the known linters"))
+ kondo-ratchet/scan #(throw (AssertionError. "scanned the source tree"))
+ kondo-ratchet/config-suppressions #(throw (AssertionError. "counted config suppressions"))
+ kondo-ratchet/module-escape-hatches #(throw (AssertionError. "counted module escape hatches"))]
+ (is (= (str (.getPath budgets) " is disabled -- nothing to do\n")
+ (with-out-str (kondo-ratchet/fix! {:seed "whatever"})))))
(is (= "{:disabled true}\n" (slurp budgets)))))))
(deftest ^:synchronized seed-unlimited-linter-test
@@ -318,12 +347,16 @@
(make-array java.nio.file.attribute.FileAttribute 0)))
ratchets {:ignore-counts {:free :unlimited}, :config-counts {}, :comment-exempt #{}}
budgets (doto (io/file dir "ratchets.edn") (spit (kondo-ratchet/render ratchets)))
+ modules (doto (io/file dir "module-ratchets.edn")
+ (spit (kondo-ratchet/render-module-ratchets {})))
occurrences [{:file "f.clj", :line 1, :linters [:free]}
{:file "f.clj", :line 2, :linters [:free]}]]
- (binding [kondo-ratchet/*ratchets-file* (.getPath budgets)]
- (with-redefs [kondo-ratchet/known-linters (constantly #{:free})
- kondo-ratchet/scan (constantly occurrences)
- kondo-ratchet/config-suppressions (constantly {})]
+ (binding [kondo-ratchet/*ratchets-file* (.getPath budgets)
+ kondo-ratchet/*module-ratchets-file* (.getPath modules)]
+ (with-redefs [kondo-ratchet/known-linters (constantly #{:free})
+ kondo-ratchet/scan (constantly occurrences)
+ kondo-ratchet/config-suppressions (constantly {})
+ kondo-ratchet/module-escape-hatches (constantly {})]
(is (= ["seeded :free at 2"
(str "wrote " (.getPath budgets))]
(str/split-lines (with-out-str (kondo-ratchet/fix! {:seed "free"}))))))
@@ -337,8 +370,11 @@
"kondo-ratchet-test"
(make-array java.nio.file.attribute.FileAttribute 0)))
text (kondo-ratchet/render {:ignore-counts {:free :unlimited}, :config-counts {}, :comment-exempt #{}})
- budgets (doto (io/file dir "ratchets.edn") (spit text))]
- (binding [kondo-ratchet/*ratchets-file* (.getPath budgets)]
+ budgets (doto (io/file dir "ratchets.edn") (spit text))
+ modules (doto (io/file dir "module-ratchets.edn")
+ (spit (kondo-ratchet/render-module-ratchets {})))]
+ (binding [kondo-ratchet/*ratchets-file* (.getPath budgets)
+ kondo-ratchet/*module-ratchets-file* (.getPath modules)]
(with-redefs [kondo-ratchet/known-linters (constantly #{:free})
kondo-ratchet/scan (fn [] (throw (AssertionError. "scanned before validating the seed")))]
(is (thrown-with-msg? clojure.lang.ExceptionInfo
@@ -355,12 +391,16 @@
:config-counts {}
:comment-exempt #{:empty}}
budgets (doto (io/file dir "ratchets.edn") (spit (kondo-ratchet/render ratchets)))
+ modules (doto (io/file dir "module-ratchets.edn")
+ (spit (kondo-ratchet/render-module-ratchets {})))
occurrences [{:file "f.clj", :line 1, :linters [:free]}]
run! #(str/split-lines (with-out-str (kondo-ratchet/fix!)))]
- (binding [kondo-ratchet/*ratchets-file* (.getPath budgets)]
- (with-redefs [kondo-ratchet/known-linters (constantly #{:free :empty :gone :zero})
- kondo-ratchet/scan (constantly occurrences)
- kondo-ratchet/config-suppressions (constantly {})]
+ (binding [kondo-ratchet/*ratchets-file* (.getPath budgets)
+ kondo-ratchet/*module-ratchets-file* (.getPath modules)]
+ (with-redefs [kondo-ratchet/known-linters (constantly #{:free :empty :gone :zero})
+ kondo-ratchet/scan (constantly occurrences)
+ kondo-ratchet/config-suppressions (constantly {})
+ kondo-ratchet/module-escape-hatches (constantly {})]
(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"
@@ -378,6 +418,29 @@
(run!))
"a second run changes nothing and still reports")))))
+(deftest ^:synchronized fix-lowers-module-counts-test
+ (let [dir (.toFile (java.nio.file.Files/createTempDirectory
+ "kondo-ratchet-test"
+ (make-array java.nio.file.attribute.FileAttribute 0)))
+ ratchets {:ignore-counts {}, :config-counts {}, :comment-exempt #{}}
+ budgets (doto (io/file dir "ratchets.edn") (spit (kondo-ratchet/render ratchets)))
+ modules (doto (io/file dir "module-ratchets.edn")
+ (spit (kondo-ratchet/render-module-ratchets
+ {:api-any 2, :friend-edges 5, :uses-any 1})))]
+ (binding [kondo-ratchet/*ratchets-file* (.getPath budgets)
+ kondo-ratchet/*module-ratchets-file* (.getPath modules)]
+ (with-redefs [kondo-ratchet/known-linters (constantly #{})
+ kondo-ratchet/scan (constantly [])
+ kondo-ratchet/config-suppressions (constantly {})
+ kondo-ratchet/module-escape-hatches (constantly {:api-any 1, :friend-edges 4, :uses-any 0})]
+ (is (= ["lowered module :api-any 2 -> 1"
+ "lowered module :friend-edges 5 -> 4"
+ "dropped module :uses-any (no escape hatches left)"
+ (str "wrote " (.getPath modules))]
+ (str/split-lines (with-out-str (kondo-ratchet/fix!)))))
+ (is (= {:api-any 1, :friend-edges 4}
+ (kondo-ratchet/read-module-ratchets)))))))
+
(deftest read-ratchets-requires-one-map-test
(doseq [[content message] [["" #"is empty; expected one map"]
[" \n;; only a comment\n" #"is empty; expected one map"]
@@ -541,12 +604,12 @@
var), per-var re-allows count at any nesting depth, discouragements and enablements count
nothing; groups, :config-in-comment and :config-in-call sum per linter"))
-(deftest ^:parallel config-drift-test
+(deftest ^:parallel count-drift-test
(is (= {:gone {:recorded 2, :actual 0}
:new {:recorded 0, :actual 1}
:up {:recorded 1, :actual 3}}
- (kondo-ratchet/config-drift {:gone 2, :same 5, :up 1}
- {:same 5, :new 1, :up 3}))))
+ (kondo-ratchet/count-drift {:gone 2, :same 5, :up 1}
+ {:same 5, :new 1, :up 3}))))
(defn- merge-policies
"[[kondo-ratchet/merge-ratchets]] over `:ignore-counts` maps alone, so a test reads as the three stages."
@@ -583,11 +646,19 @@
(deftest ^:parallel merge-ratchets-config-counts-test
(is (= {:config-counts {:lowered 1, :ours-add 2, :theirs-add 3}}
- (select-keys (kondo-ratchet/merge-ratchets {:config-counts {:lowered 4, :dropped 1}}
- {:config-counts {:lowered 2, :ours-add 2}}
- {:config-counts {:lowered 1, :dropped 1, :theirs-add 3}})
+ (select-keys (kondo-ratchet/merge-ratchets
+ {:config-counts {:lowered 4, :dropped 1}}
+ {:config-counts {:lowered 2, :ours-add 2}}
+ {:config-counts {:lowered 1, :dropped 1, :theirs-add 3}})
[:config-counts]))))
+(deftest ^:parallel merge-module-ratchets-test
+ (is (= {:lowered 1, :ours-add 2, :theirs-add 3}
+ (kondo-ratchet/merge-module-ratchets
+ {:lowered 4, :dropped 1}
+ {:lowered 2, :ours-add 2}
+ {:lowered 1, :dropped 1, :theirs-add 3}))))
+
(deftest ^:parallel merge-ratchets-absent-base-test
(testing "with no base stage, each policy is a one-sided addition and shared linters take the stricter"
(is (= {:ignore-counts {:ours 2, :shared 3, :theirs 3}
@@ -695,6 +766,8 @@
"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"
+ "lowered module :api-any 2 -> 1"
+ "WARNING: module :uses-any is over budget (1 recorded, 2 actual) -- remove one from .clj-kondo/config/modules/config.edn or raise the budget by hand"
"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
@@ -709,8 +782,10 @@
:cfg-over 1
:cfg-same 6}
:comment-exempt #{:lower :polite}}
+ {:api-any 2, :uses-any 1}
occurrences
{:cfg-lower 2, :cfg-over 3, :cfg-same 6}
+ {:api-any 1, :uses-any 2}
[:new :void]))
"untouched budgets (:same, :cfg-same), a used unlimited policy (:free), and a still-needed
exemption (:lower) earn no line; a hand-written 0 (:zero) is dropped like any bounded budget with no
@@ -719,13 +794,16 @@
(deftest ^:parallel shrink-summary-test
(is (= (str "{:a 2 => 1\n"
" :config/unused-import 4 => 0\n"
+ " :module/friend-edges 3 => 2\n"
" :z 10 => 3}")
(kondo-ratchet/shrink-summary
{:ignore-counts {:a 2, :same 1, :unlimited :unlimited, :z 10}
:config-counts {:same 2, :unused-import 4}
+ :module-counts {:friend-edges 3}
:comment-exempt #{:a}}
{:ignore-counts {:a 1, :raised 2, :same 1, :unlimited :unlimited, :z 3}
:config-counts {:same 2}
+ :module-counts {:friend-edges 2}
:comment-exempt #{}})))
(is (= "{}" (kondo-ratchet/shrink-summary {:ignore-counts {:a 1}}
{:ignore-counts {:a 2}}))
diff --git a/dev/test/metabase/core/modules_test.clj b/dev/test/metabase/core/modules_test.clj
index 858f7691381..8e24190459d 100644
--- a/dev/test/metabase/core/modules_test.clj
+++ b/dev/test/metabase/core/modules_test.clj
@@ -329,3 +329,34 @@
(testing (format "\n'%s' module :model-imports" module)
(is (= (sort imports)
imports))))))))
+
+;;;; Module boundary analysis
+
+(deftest ^:parallel strongly-connected-components-test
+ (let [graph {:a #{:b}
+ :b #{:a :c}
+ :c #{}
+ :d #{:e}
+ :e #{:f}
+ :f #{:d}
+ :g #{:h}}]
+ (is (= #{#{:a :b} #{:c} #{:d :e :f} #{:g} #{:h}}
+ (set (dev.deps-graph/strongly-connected-components graph))))
+ (is (= [#{:d :e :f} #{:a :b}]
+ (dev.deps-graph/cyclic-components graph)))))
+
+(deftest ^:parallel module-boundary-config-values-have-valid-types-test
+ (testing "Module boundary keys have the shapes the ratchet counts expect"
+ (doseq [[module config] (dev.deps-graph/kondo-config)]
+ (testing (format "\n%s" module)
+ (is (or (nil? (:api config))
+ (set? (:api config))
+ (= :any (:api config)))
+ ":api must be omitted, a set, or :any")
+ (is (or (nil? (:uses config))
+ (set? (:uses config))
+ (= :any (:uses config)))
+ ":uses must be omitted, a set, or :any")
+ (is (or (nil? (:friends config))
+ (set? (:friends config)))
+ ":friends must be a set when present")))))
diff --git a/mage/test/mage/merge_kondo_ratchets_test.clj b/mage/test/mage/merge_kondo_ratchets_test.clj
index 3642aea0984..42fee62e073 100644
--- a/mage/test/mage/merge_kondo_ratchets_test.clj
+++ b/mage/test/mage/merge_kondo_ratchets_test.clj
@@ -18,6 +18,9 @@
(def ^:private ratchets-file
".clj-kondo/ratchets.edn")
+(def ^:private module-ratchets-file
+ ".clj-kondo/config/modules/ratchets.edn")
+
;; Keep the user's git configuration (hooks, merge drivers) out of the temporary repositories.
(def ^:private git-env
{"GIT_CONFIG_GLOBAL" "/dev/null"
@@ -138,6 +141,18 @@
(is (= #{"M .clj-kondo/ratchets.edn" "UU app.txt"}
(status dir)))))
+(deftest resolves-module-ratchets-test
+ (with-conflict [dir {:base {module-ratchets-file "{:api-any 3, :friend-edges 5}\n"}
+ :ours {module-ratchets-file "{:api-any 2, :friend-edges 5}\n"}
+ :theirs {module-ratchets-file "{:api-any 3, :friend-edges 4, :uses-any 1}\n"}}]
+ (let [{:keys [exit out]} (run dir script)]
+ (is (= 0 exit))
+ (is (str/includes? out (str "staged merged " module-ratchets-file))))
+ (is (= {:api-any 2, :friend-edges 4, :uses-any 1}
+ (edn/read-string (slurp (str (fs/path dir module-ratchets-file))))))
+ (is (= #{(str "M " module-ratchets-file) "UU app.txt"}
+ (status dir)))))
+
(deftest keeps-a-disabled-target-verbatim-test
(let [disabled ";; release branch\n{:disabled true}\n"]
(with-conflict [dir {:base {ratchets-file base-ratchets}
@@ -214,4 +229,4 @@
(with-conflict [dir {:base {ratchets-file base-ratchets}}]
(let [{:keys [exit err]} (run dir script)]
(is (= 1 exit))
- (is (str/includes? err "is not conflicted")))))
+ (is (str/includes? err "neither ratchet file is conflicted")))))