refactor(Tactic/Linter/Header): make the header linter stateful

[marcelolynch]

This PR rewrites the header linter as a stateful linter (leanprover/lean4#14357). The rewrite builds on the new implementation of the linter from #40347. Linter behavior does not change. The four pre-existing header linter test files pass without changes.

The linter state removes the last per-command cost of the linter. The current implementation runs a fast parse of the imports on every command of every file, to detect whether the current command is the first one. #40347 notes this residual cost and points to the new linting framework for the fix. The state now records a verdict for the module: the header checks ran, or the module is exempt. The linter reaches the verdict on the first command, and every later command returns after one read of a state field, with no parse.

The state also replaces the Std.Mutex that cached the library-root check. The check now runs at most once per module, so it needs no cache.

The state also stores the parsed module header, and the header linter becomes a producer. The minImports and longLine linters read the parsed header from the state for their end-of-file checks, instead of a re-parse of the file. When the header checks did not run, both linters fall back to the previous re-parse. Two tests pin the payload path and the fallback path of the minImports report.

• depends on: refactor(Tactic/Linter/MinImports): make the minImports linter stateful #42186

🤖 Generated with Claude Code

[github-actions]

PR summary 48540ad78d

Import changes for modified files

Dependency changes

File	Base Count	Head Count	Change
Mathlib.Tactic.Linter.Header	4	3	-1 (-25.00%)

Import changes for all files

Files	Import difference
../mathlib-ci/scripts/pr_summary/import_trans_difference.sh all
There are 8414 files with changed transitive imports taking up over 367408 characters: this is too many to display!
You can run this locally from your mathlib4 directory:

git clone https://github.com/leanprover-community/mathlib-ci.git ../mathlib-ci

---

Declarations diff (regex)

+ HeaderState
+ async_uses_norm_num
+ headerPost
+ longLinePost
+ minImportsPost
- headerLinter
- longLineLinter
- minImportsLinter

You can run this locally as follows

## from your `mathlib4` directory:
git clone https://github.com/leanprover-community/mathlib-ci.git ../mathlib-ci

## summary with just the declaration names:
../mathlib-ci/scripts/pr_summary/declarations_diff.sh <optional_commit>

## more verbose report:
../mathlib-ci/scripts/pr_summary/declarations_diff.sh long <optional_commit>

The doc-module for scripts/pr_summary/declarations_diff.sh in the mathlib-ci repository contains some details about this script.

Declarations diff (Lean)

✅ Lean-aware diff — post-build, computed from the Lean environment (commit 48540ad).

• +36 new declarations
• −1 removed declarations

+Mathlib.Linter.HeaderState
+Mathlib.Linter.HeaderState.casesOn
+Mathlib.Linter.HeaderState.ctorIdx
+Mathlib.Linter.HeaderState.headerSyntax
+Mathlib.Linter.HeaderState.mk
+Mathlib.Linter.HeaderState.mk.inj
+Mathlib.Linter.HeaderState.mk.injEq
+Mathlib.Linter.HeaderState.mk.noConfusion
+Mathlib.Linter.HeaderState.mk.sizeOf_spec
+Mathlib.Linter.HeaderState.noConfusion
+Mathlib.Linter.HeaderState.noConfusionType
+Mathlib.Linter.HeaderState.rec
+Mathlib.Linter.HeaderState.recOn
+Mathlib.Linter.HeaderState.settled
+Mathlib.Linter.ImportState
+Mathlib.Linter.ImportState.casesOn
+Mathlib.Linter.ImportState.ctorIdx
+Mathlib.Linter.ImportState.importSize
+Mathlib.Linter.ImportState.minImports
+Mathlib.Linter.ImportState.mk
+Mathlib.Linter.ImportState.mk.inj
+Mathlib.Linter.ImportState.mk.injEq
+Mathlib.Linter.ImportState.mk.noConfusion
+Mathlib.Linter.ImportState.mk.sizeOf_spec
+Mathlib.Linter.ImportState.noConfusion
+Mathlib.Linter.ImportState.noConfusionType
+Mathlib.Linter.ImportState.rec
+Mathlib.Linter.ImportState.recOn
+Mathlib.Linter.ImportState.transClosure
+Mathlib.Linter.MinImports.minImportsLinter
+Mathlib.Linter.Style.Header.headerLinter
+Mathlib.Linter.Style.longLine.longLineLinter
+Mathlib.Linter.instInhabitedHeaderState
+Mathlib.Linter.instInhabitedHeaderState.default
+Mathlib.Linter.instInhabitedImportState
+Mathlib.Linter.resetMinImports
-Mathlib.Linter.«command#reset_min_imports»

---

No changes to strong technical debt.
No changes to weak technical debt.

Current commit 48540ad78d
Reference commit 37252fbc4b

This script lives in the mathlib-ci repository. To run it locally, from your mathlib4 directory:

git clone https://github.com/leanprover-community/mathlib-ci.git ../mathlib-ci
../mathlib-ci/scripts/reporting/technical-debt-metrics.py pr_summary

• The relative value is the weighted sum of the differences with weight given by the inverse of the current value of the statistic.
• The absolute value is the relative value divided by the total sum of the inverses of the current values (i.e. the weighted average of the differences).

[mathlib-dependent-issues]

This PR/issue depends on:

• refactor(Tactic/Linter/MinImports): make the minImports linter stateful #42186
  By Dependent Issues (🤖). Happy coding!

[mathlib-merge-conflicts]

This pull request has conflicts, please merge master and resolve them.

[mathlib-merge-conflicts]

This pull request has conflicts, please merge master and resolve them.

[mathlib-merge-conflicts]

This pull request has conflicts, please merge master and resolve them.