clang-tidy only ever sees changed lines: no job lints unchanged first-party code, and the standing bill is 4155 findings

[Yaraslaut]

The gap

ci.yml's clang-tidy-diff is the only job in this repository that runs clang-tidy over the tree, and it is diff-scoped twice over: clang-tidy-diff.py analyses only the files named in the diff, and passes a -line-filter that drops every finding outside the diff's own line ranges.

The consequence is that a finding in a first-party file nobody has touched is reported by no job at all, and never becomes reportable until someone happens to edit that exact line. That is not a bug in the diff job — a whole-file -Werror lint over this tree could not be turned on in one step — but it is a coverage gap that nothing currently records, and it is the gap #664 was pointing at from one directory over. (#664 blamed the root HeaderFilterRegex; measured, that regex has no observable effect on this job at all — see the correction on #664.)

The bill, measured rather than estimated

So the question a whole-file leg has to answer is "how much is standing debt". I measured it while working #664, on 563502ab, clang 22.1.8, Qt 6.11.2, with the clang-tidy job's own configure flags from a cold build directory:

cmake --preset clang-debug -DMORPH_BUILD_NET=ON -DMORPH_BUILD_QT=ON \
  -DMORPH_BUILD_FORMS_QML=ON -DMORPH_BUILD_OFFLINE_SQLITE=ON \
  -DMORPH_BUILD_LOAD_TESTS=ON -DMORPH_BUILD_HMAC_EXAMPLES=ON \
  -DMORPH_BUILD_FUZZERS=ON -DMORPH_BUILD_LADDER=ON \
  -DMORPH_BUILD_BANK_EXAMPLE=ON -DMORPH_BUILD_BANK_GUI=ON

740 database entries, 423 distinct in-workspace translation units, 282 under examples/. clang-tidy was then run over all 423, --header-filter='.*' --extra-arg=-std=c++23 --extra-arg=-Wno-missing-include-dirs, one output file per TU, findings de-duplicated by (file, line, column, check):

distinct findings under --header-filter='.*' : 5577
  of which in a main file (always shown)     : 3010
  of which in an included header             : 2567

  by bucket:
     2930  first-party: examples/
     1422  build tree (_deps, vendored, generated)
      713  first-party: tests/
      488  first-party: include/
       22  first-party: src/
        2  system/toolchain

So a whole-file leg over first-party code, with the vendored trees excluded, starts at roughly 4155 findings (5577 − 1422 vendored), of which 3010 are in .cpp main files and ~657 in first-party headers that today's HeaderFilterRegex also excludes. For scale: #646 was 84 findings and #656 was 97.

Headers only, by root:

      633 findings in  150 header(s)  examples/
      488 findings in   34 header(s)  include/
       21 findings in    6 header(s)  tests/
        1 findings in    1 header(s)  src/

Cost, measured on a 12-core Linux box: 423 TUs at -P 10 took ~20 minutes wall, the heaviest TUs dominated by include/morph/forms/forms.hpp (102 findings alone) and the ORM-bearing bank models. A four-core hosted runner pays more.

What a fix would have to settle, and two facts that constrain it

1. Vendored code must be excluded explicitly, and an inclusive first-party regex will not do it. A header filter is an unanchored search over an absolute path, and (include/morph|src|tests|examples)/ matches 608 headers under build/clang-debug/_deps — 244 glaze, 202 stdexec, 153 Lightweight — because FetchContent lays dependencies out as _deps/<name>-src/src/ and _deps/<name>-src/include/. The polarity that works is HeaderFilterRegex: ".*" with an ExcludeHeaderFilterRegex naming the build tree (/_deps/, /build/, _autogen/, /CMakeFiles/); it also cannot go stale when a rung is added, because it names nothing first-party. Verified behaviourally: on one bank model TU that exclusion takes vendored diagnostic lines from 1300 to 0.
2. A whole-file leg cannot simply be WarningsAsErrors: "*" on day one. 4155 findings is not a backlog anyone clears in a PR, and suppressing to green is the outcome this repository has filed issues about repeatedly. The plausible shapes are a non-blocking reporting leg, a ratchet on the count, or a per-directory opt-in — all of which are design decisions, not implementation ones, which is why this is filed rather than attempted.

Verification status

• Reproduced: every number above, on 563502ab, over 423 of 423 in-workspace TUs — a full sweep, not a sample. The 608-vendored-header figure is a direct os.walk over build/clang-debug/_deps matched against the regex. The 1300→0 exclusion figure is two clang-tidy runs on examples/bank/src/models/account_model.cpp.
• Not verified: the wall-clock cost on a CI runner (measured locally only); whether the 4155 figure is stable across clang minor versions; and whether any of the findings are false positives worth suppressing rather than fixing — I counted them, I did not read them.
• Weak: the "roughly 4155" figure subtracts the vendored bucket from the total, which assumes the exclusion above is what a real leg would use. With a different exclusion the number moves.

What would change the verdict

Close as invalid if a job is added that already lints unchanged first-party code and I missed it — I checked .github/workflows/* and scripts/* for clang-tidy and run-clang-tidy invocations and found only the diff job plus scripts/check_tidy_suppression_scope.sh, which drives a synthetic probe rather than the tree. Close as wontfix if the considered answer is that diff-scoped lint is the intended coverage level — in which case this issue is still worth keeping as the record of what that choice costs, because nothing else in the repository writes it down.

Found while working #664 (PR #676). Filed, not folded.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VptDWG2fKr2vBnLSJcgzgW

[Yaraslaut]

Overlap with #580 — read these together, and consider closing one

Filed before I found #580, which is the same gap measured at a narrower scope: "clang-tidy-diff's changed-lines scope hides 101 findings in include/morph/", from six test TUs, explicitly a lower bound.

This issue is the tree-wide version of that, from a full sweep rather than six TUs: 423 of 423 in-workspace TUs, 5577 distinct findings, ~4155 after excluding vendored code — of which #580's include/morph/ slice measures 488 findings in 34 headers here, against its own lower bound of 101 in 17.

They are one defect, not two. My suggestion is to keep #580 as the ticket (it is older and already triaged valid, and its eight comments carry discussion this does not) and close this one as a duplicate after moving the tree-wide numbers onto it — or the reverse, if the wider scope is the more useful frame. Either way one of the two should go; I am not closing #580's sibling unilaterally when a maintainer may prefer the other direction.

The one thing here that is genuinely not in #580 is the polarity finding for any whole-file leg's header filter: an inclusive (include/morph|src|tests|examples)/ matches 608 headers under build/clang-debug/_deps, because a header filter is an unanchored search over an absolute path and FetchContent lays dependencies out as _deps/<name>-src/src/. That should survive whichever ticket is kept.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VptDWG2fKr2vBnLSJcgzgW

[Yaraslaut]

Triage: valid — and it supersedes #580, which I am closing into it

Premises verified structurally on 5fc5e788:

• clang-tidy-diff.py is the only clang-tidy invocation in any workflow — every other clang-tidy hit in .github/workflows/*.yml is an apt cache key or an error string. scripts/check_tidy_suppression_scope.sh drives a synthetic probe, not the tree.
• The job is diff-driven, so a finding in a file nobody touched is reported by nothing.

The measurements are the filer's — 423 of 423 TUs, ~20 minutes wall on 12 cores — and I have not reproduced them. What makes them usable anyway is that the issue separates them honestly: the sweep is reproduced, the CI wall-clock is not, and the "roughly 4155" is explicitly labelled weak because it subtracts a vendored bucket whose boundary depends on the exclusion a real leg would choose.

triage: valid, enhancement, area: ci.

Consolidating #580 into this

#580 is the same defect at a narrower scope — "clang-tidy-diff's changed-lines scope hides 101 findings in include/morph/". Same fix site, same mechanism, different measurement. Two open issues for one gap means whoever fixes it has to reconcile two numbers, and the older one is stale in a way nobody has re-measured.

This issue keeps the ticket because its evidence is strictly better: a full sweep with the method written down, versus a figure whose provenance I flagged as un-re-measured twice today when deciding not to dispatch against it. #580's own subject survives here as 488 findings in 34 header(s) include/ in the by-root table.

Closing #580 as superseded, not resolved, with the standard condition: re-open it if this issue is closed without acting on the include/morph/ part.

The two constraints are the valuable part

1. An inclusive first-party regex does not work. (include/morph|src|tests|examples)/ matches 608 headers under _deps, because a header filter is an unanchored search over an absolute path and FetchContent lays dependencies out as _deps/<name>-src/include/. The working polarity is HeaderFilterRegex: ".*" plus an ExcludeHeaderFilterRegex naming the build tree — which also cannot go stale when a rung is added, because it names nothing first-party. That is a design fact somebody would otherwise rediscover expensively.
2. WarningsAsErrors: "*" on day one is not available. 4155 is not a PR-sized backlog, and suppressing to green is the outcome this repository has filed issues about repeatedly.

Why this is filed rather than dispatched

The remaining choice — non-blocking reporting leg, ratchet on the count, or per-directory opt-in — is a decision about what coverage level this project wants, not an implementation. Dispatching a lane to pick one would be a lane making a policy call. This needs a human decision before it needs an engineer, and the issue is right to say so.

My own read, offered rather than imposed: a ratchet fits this repository's habits best — it is the only one of the three that cannot silently regress, and this codebase has repeatedly chosen "a gate that fails when the thing it measures gets worse" over "a gate that reports". A per-directory opt-in becomes a stale list; a reporting leg becomes noise nobody reads.

Invariant 7 applies to the fix, not the issue

"Would this still pass if the feature did nothing?" Whatever leg lands here must answer it: a whole-file lint reporting zero because it analysed zero TUs is the precise failure this repository keeps finding, and the 423-of-423 denominator in this issue is the shape its success output should take.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VptDWG2fKr2vBnLSJcgzgW

[Yaraslaut]

Closed — out of scope under the CI reduction

This issue proposes adding or tightening CI enforcement. morph#755 moved in the opposite direction deliberately: the check surface had reached 57 checks per PR across 51 jobs and 31 checker scripts, while more than half the open backlog was CI maintaining itself. The meta-gates — the checks policing other checks — were removed.

The finding itself is not disputed and the analysis stands; what has changed is the appetite for enforcing it in CI. Closed as not planned, not as invalid.

No compile, test, sanitizer, coverage or platform coverage was removed — every build, sanitizer, Valgrind, coverage and platform leg still runs. The trade is that pins, citations and conventions of this kind are now conventions rather than gates.

Re-open if the cost/benefit changes — the evidence recorded here would not need re-gathering.