HeaderFilterRegex excludes every examples/** header from clang-tidy: 49 findings from five of 737 TUs

[Yaraslaut]

What

The repository-root .clang-tidy carries

HeaderFilterRegex: "include/morph/.*"

clang-tidy reports diagnostics in the main file plus any header whose path
matches that regex, and discards the rest. So no finding in any header under
examples/** is ever reported, by any job, no matter which translation unit
reaches it.

This is the same shape as #481, #650, #651 and #656 -- a gate that reads code
and is believed to cover examples/, covering only part of it -- one level
down: those were about which translation units the job analyses, this is
about which headers it reports on once it has them.

It is not a small remainder. The ladder keeps model logic, DTOs and inline
presenter helpers in headers by design: examples/bank/include/bank/models/*
and examples/<rung>/include/<rung>/** are where a rung's code actually
lives, and every one of those files is silent today.

Measurement

Reproduced, on 7ab4c7a9 plus this branch's #656 commit (so the eleven
bank-GUI sources are already clean), clang-tidy 22.1.8, against the
clang-tidy job's own configure and its own -extra-arg pair. Five of the
eleven bank-GUI TUs, re-run with --header-filter='examples/.*' in place of
the configured include/morph/.*:

distinct findings in examples/**.hpp, from 5 of the 11 TUs: 49
--- per header ---
      8 examples/bank/include/bank/models/card_model.hpp
      6 examples/bank/include/bank/models/payment_model.hpp
      6 examples/bank/include/bank/models/loan_model.hpp
      5 examples/bank/include/bank/models/transaction_model.hpp
      5 examples/bank/include/bank/models/auth_model.hpp
      4 examples/bank/include/bank/models/payee_model.hpp
      4 examples/bank/include/bank/dto/payee_dto.hpp
      3 examples/bank/include/bank/models/customer_model.hpp
      3 examples/bank/include/bank/core/types.hpp
      3 examples/bank/gui/controllers/Format.hpp
      1 examples/bank/gui/controllers/../BankClient.hpp
      1 examples/bank/gui/BankClient.hpp
--- per check ---
     37 cert-dcl59-cpp,misc-anonymous-namespace-in-header
      4 readability-identifier-length
      2 cppcoreguidelines-special-member-functions
      2 cppcoreguidelines-pro-bounds-avoid-unchecked-container-access
      1 readability-use-anyofallof
      1 readability-math-missing-parentheses
      1 misc-const-correctness
      1 bugprone-incorrect-roundings

Real output, the first six:

examples/bank/gui/BankClient.hpp:20:7: error: class 'BankClient' defines a copy constructor and a copy assignment operator but does not define a destructor, a move constructor or a move assignment operator [cppcoreguidelines-special-member-functions,-warnings-as-errors]
examples/bank/gui/controllers/../BankClient.hpp:20:7: error: class 'BankClient' defines a copy constructor and a copy assignment operator but does not define a destructor, a move constructor or a move assignment operator [cppcoreguidelines-special-member-functions,-warnings-as-errors]
examples/bank/gui/controllers/Format.hpp:69:10: error: variable name 'ok' is too short, expected at least 3 characters [readability-identifier-length,-warnings-as-errors]
examples/bank/gui/controllers/Format.hpp:76:38: error: casting (double + 0.5) to integer leads to incorrect rounding; consider using lround (#include <cmath>) instead [bugprone-incorrect-roundings,-warnings-as-errors]
examples/bank/gui/controllers/Format.hpp:76:38: error: '*' has higher precedence than '+'; add parentheses to explicitly specify the order of operations [readability-math-missing-parentheses,-warnings-as-errors]
examples/bank/include/bank/core/types.hpp:27:55: error: parameter name 'c' is too short, expected at least 3 characters [readability-identifier-length,-warnings-as-errors]

Two things the numbers do and do not say

• 49 is a lower bound, and a small one. It comes from five bank TUs. The
  job's database holds 737 entries spanning thirteen example directories;
  every rung's own headers are in the same position and none of them was
  measured here.
• The same-header-two-paths duplicate is real. BankClient.hpp appears
  twice, once as examples/bank/gui/BankClient.hpp and once as
  examples/bank/gui/controllers/../BankClient.hpp, because a header filter
  matches the spelling of the include path rather than the resolved file.
  That is a property of any wider regex too, worth knowing before one is
  written.
• One of the findings looks like a real defect, not style. Filed
  separately as bank GUI: parseMinor casts an unbounded double to int64_t; 1e30 in any amount field is UB #663 (bugprone-incorrect-roundings on
  Format.hpp:76, and the unbounded double -> int64_t cast on the same
  line, which is reproduced UB). It has sat unreported for as long as this
  filter has been in place, which is the argument for the filter being the
  issue and not the one finding.

Verification status

• Reproduced: the 49, the per-header and per-check split, on the revision
  and toolchain named above.
• Reproduced: that widening the filter is what surfaces them -- the same
  five TUs under the configured include/morph/.* report zero findings in
  any examples/** header.
• Inferred, not measured: the repository-wide total. Only five of 737
  database entries were re-run.
• Not attempted: any fix. Nothing has been changed.

Why it is not simply "widen the regex"

Widening it to (include/morph|examples)/.* would make the clang-tidy job
report all of the above on the first PR that touches a changed line in one of
those headers, which is #656's situation repeated at a larger scale, and 37
of the 49 are one check (misc-anonymous-namespace-in-header) that wants a
decision about the ladder's header idiom rather than 37 edits. The sequencing
#646/#656 established applies: widen the filter in one change, clear what it
exposes in another, and do not gate the first on the second.

tests/.clang-tidy's reach note (#632, scripts/check_tidy_suppression_scope.sh)
is also in scope for whoever takes this: once examples/** headers are
reported, the per-rung examples/*/tests/.clang-tidy suppressions start
applying to them from every test TU, exactly as tests/.clang-tidy does for
include/morph/**.

What would change the verdict

Close when the filter reports on the ladder's own headers and the findings it
exposes are either fixed or recorded -- verified by re-running the command
above and pasting the output, not by a green CI run, since a green
clang-tidy-diff leg proves only that those lines were not touched.

Close as invalid if the narrow filter turns out to be a deliberate,
recorded decision somewhere this search missed; nothing in .clang-tidy,
tests/.clang-tidy or ci.yml argues for it.

Context

Found while clearing #656. HeaderFilterRegex is repository-wide, so this is
not a bank-GUI issue and was not folded into that change.

[Yaraslaut]

Triage: valid — structurally confirmed, and this is the widest of the cluster

I checked the mechanism on 7ab4c7a9 rather than relying on the reproduction:

$ grep -n HeaderFilterRegex .clang-tidy
23:HeaderFilterRegex: "include/morph/.*"

$ for f in $(git ls-files '*.clang-tidy'); do printf '%-52s ' "$f"; grep -c HeaderFilterRegex "$f"; done
.clang-tidy                                          1
examples/bank/tests/.clang-tidy                      0
examples/bookmarks/tests/.clang-tidy                 0
examples/common/testkit/.clang-tidy                  0
examples/crm/tests/.clang-tidy                       0
examples/kanban/tests/.clang-tidy                    0
examples/ledger/tests/.clang-tidy                    0
examples/lims/tests/.clang-tidy                      0
examples/pastebin/tests/.clang-tidy                  0
examples/polls/tests/.clang-tidy                     0
tests/.clang-tidy                                    0

One config sets the key, ten do not, and clang-tidy inherits HeaderFilterRegex rather than merging it — a nearer .clang-tidy without the key does not widen it. So findings in every header under examples/** are discarded, from every job, and have been for as long as the regex has existed.

triage: valid, bug, area: ci.

The 49 findings across 12 headers is the filer's measurement, not mine — it needs the Qt configure. Note the filer labels it a lower bound: it came from five of the eleven bank TUs against a 737-entry database, so the real figure over the whole tree is larger, probably by a lot.

Why this is the widest instance of a cluster this repository keeps finding

#481, #650, #651, #656 and this are the same defect at five scales: a gate that looks tree-wide and is not. What makes this one the worst is that it is invisible from inside the reports — #651 could be found by diffing two jobs' configure flags, and #656 by noticing a file had never been analysed, but a discarded header finding leaves no trace anywhere. The only way to see it is to read the regex and know clang-tidy's inheritance rule.

And it already cost something concrete. #663 — an unbounded double → int64_t cast on every bank GUI amount, reproduced under UBSan — lives in a header under examples/. It has been unreportable this whole time. That is the argument for fixing this before the cluster's other members: the others hide style debt, this one hid a defect.

For whoever takes it

• Expect a large first bill. Widening the regex surfaces every finding in every examples/** header at once, across the ladder. 84 clang-tidy findings become reachable in the two AUTOMOC self-including TUs once #624's fix lands #646 (84 findings) and 97 unreported clang-tidy findings in the eleven bank-GUI sources morph#651 brings into reach #656 (97) are the precedents for how that is handled: measure first, fix the mechanical bulk, file the residual, do not suppress.
• Widening it to .* is probably wrong — that pulls in _deps/, the vendored Lightweight ORM and anything else under the build tree. The regex needs to name first-party roots explicitly, and whatever it names should be derived from or checked against the tree rather than hand-listed, or it becomes the next stale list.
• The tests/ half is already handled by scripts/check_tidy_suppression_scope.sh (tests/.clang-tidy's suppressions also silence include/morph headers, so a header gate driven by test TUs under-reports #632); do not duplicate it.

What would change the verdict

Close as invalid if clang-tidy turns out to merge HeaderFilterRegex across nested configs rather than inherit the nearest — that would make the ten empty configs irrelevant and the finding wrong. I read the inheritance rule as "nearest wins" and did not test it; that test is one fixture and worth doing first.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VptDWG2fKr2vBnLSJcgzgW

[Yaraslaut]

Handing this back as mis-framed — the mechanism is real, the consequence is not

Dispatched to fix this alongside #663 (PR #676, which lands #663 only). I built the widened regex, a derived-polarity exclusion and a behavioural gate for it, got the whole thing green, and then ran the check that should have come first. It says the premise does not hold, so I reverted all of it rather than ship a no-op with a gate attached.

Everything below is measured on 563502ab, clang 22.1.8 (CI pins CLANG_VERSION: "22"), Qt 6.11.2, this job's own configure flags, cold build directory.

The mechanism is exactly as triaged

One config sets the key, ten do not, HeaderFilterRegex is inherited rather than merged, and nothing else in the tree references it (grep -rn HeaderFilterRegex .github scripts docs tests examples .clang-tidy → one hit). No dispute there.

But no job in this repository is affected by it

ci.yml's clang-tidy-diff is the only job that runs clang-tidy over the tree. Its own filter step already states the fact that decides this:

A changed header is never dropped -- a header is never a translation unit [...]

A changed header therefore reaches clang-tidy-diff.py, which names it on the command line, and clang tooling analyses a header named on the command line as that translation unit's main file. Main-file diagnostics bypass HeaderFilterRegex entirely.

With the unmodified config, and a diff containing nothing but one line of an examples/** header:

$ grep '^HeaderFilterRegex' .clang-tidy
HeaderFilterRegex: "include/morph/.*"

$ python3 clang-tidy-diff.py -path build/clang-debug -clang-tidy-binary clang-tidy \
      -p1 -extra-arg=-std=c++23 -extra-arg=-Wno-missing-include-dirs -quiet < hdr_only.diff
Running clang-tidy in 1 threads...
/.../examples/bank/gui/controllers/Format.hpp:100:10: error: variable name 'ok' is too short, expected at least 3 characters [readability-identifier-length,-warnings-as-errors]
  100 |     bool ok = false;
      |          ^
exit=1

Reported — under the regex this issue says discards it.

The mirror case, also unmodified: a diff changing only a .cpp whose TU includes examples/bank/include/bank/models/transaction_model.hpp (5 findings when reached as an include) reports nothing, because clang-tidy-diff.py's -line-filter drops every finding in a file that is not in the diff. Widening the regex does not change that either — I ran that case both ways.

So, in the only job that runs clang-tidy:

	today	with the regex widened
a changed first-party header	linted, as a main file	linted, as a main file
an unchanged header	dropped by -line-filter	dropped by -line-filter

Which also disproves "this is why #663 sat unreported"

Analysing the pre-fix Format.hpp as its own TU under the unmodified narrow regex — exactly what CI does for a changed header:

Format.hpp:69:10: error: variable name 'ok' is too short, expected at least 3 characters [readability-identifier-length,-warnings-as-errors]
Format.hpp:76:38: error: '*' has higher precedence than '+'; add parentheses to explicitly specify the order of operations [readability-math-missing-parentheses,-warnings-as-errors]
Format.hpp:76:38: error: casting (double + 0.5) to integer leads to incorrect rounding; consider using lround (#include <cmath>) instead [bugprone-incorrect-roundings,-warnings-as-errors]

Three findings, one of them on line 76, the line #663 is about, all reportable today. Widening the regex adds only the three findings in the included bank/core/types.hpp, which the line filter discards anyway. #663 went unreported because nobody put that line in a diff — and no clang-tidy check reports the out-of-range conversion itself under either regex, so this gate would not have found #663 in any configuration.

The measurement, since it is worth keeping regardless

I ran clang-tidy over all 423 in-workspace TUs of this job's database (740 entries, 282 under examples/) with --header-filter='.*', de-duplicating by (header, 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

admitted by today's  HeaderFilterRegex 'include/morph/.*'      : 488
admitted by '.*' + exclude '/(build|_deps|vcpkg_installed)/'   : 1145

NEWLY ADMITTED : 657 findings in 159 headers
     633 findings in  150 header(s)  examples/
      21 findings in    6 header(s)  tests/
       1 findings in    1 header(s)  src/
       2 in system headers

So the filer's "49 across 12 headers" lower bound is 633 across 150 headers tree-wide, about 13×. Leading checks: cert-dcl59-cpp 226, readability-identifier-length 80, readability-identifier-naming 73, readability-convert-member-functions-to-static 34, readability-redundant-member-init 33, bugprone-unchecked-optional-access 28.

Two of the triage's design points are confirmed with numbers:

• .* alone admits 1422 further findings in 62 vendored headers, 1174 of them the Lightweight ORM. On one bank model TU the exclusion takes it from 1300 vendored diagnostic lines to 0.
• an inclusive alternation would be wrong on arrival, not merely stale: 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 workable polarity is HeaderFilterRegex: ".*" plus an ExcludeHeaderFilterRegex naming the build tree — which also cannot go stale when a rung is added, since it names nothing first-party.

Verification status

• Reproduced: everything above, on 563502ab, with the commands and output shown. The whole-tree sweep is 423 of 423 in-workspace TUs, not a sample.
• Inferred, not reproduced: nothing load-bearing. The -line-filter behaviour is stated from its observed effect, not from reading clang-tidy's source.
• Not verified: whether any future job would be affected — obviously not measurable. Nor did I check non-CI consumers beyond the grep above; a developer running whole-file clang-tidy locally does see the narrow regex hide examples/** header findings, which is a real if minor cost.

What would change the verdict

Re-open as valid if a job is added that runs clang-tidy whole-file rather than diff-scoped — at that point the regex governs real coverage and the 657-finding bill above is what widening costs. Also re-open if clang-tidy-diff.py is replaced by something that does not analyse changed headers as main files, or if the filter-unbuilt-sources.py step starts dropping headers from the diff (its comment currently promises the opposite).

The gap that is real, and that this issue is pointing at from one directory over, is filed separately: a finding in an unchanged first-party header is reported by no job at all, and the regex is not what closes it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VptDWG2fKr2vBnLSJcgzgW

[Yaraslaut]

Runner: correcting my own triage — invalid, and I had already verified the fact that refutes it

I triaged this valid, called it "the widest member of the cluster", and attached a causal story: that it was why #663 sat unreported. All three were wrong, and the lane that went to implement it built the fix, then ran the check that should have come first, and reverted everything.

The mechanism, from ci.yml's own filter step (:2527):

"A changed header is never dropped — a header is never a translation unit, so -only-check-in-db's literal membership test would silently discard all of include/morph/**…"

A changed header is handed to clang-tidy as that invocation's main file, and main-file diagnostics bypass HeaderFilterRegex. Measured by the lane on the unmodified config:

$ grep '^HeaderFilterRegex' .clang-tidy
HeaderFilterRegex: "include/morph/.*"
$ clang-tidy-diff.py ... < hdr_only.diff
examples/bank/gui/controllers/Format.hpp:100:10: error: variable name 'ok' is too short …
exit=1

Reported, under the regex this issue says discards it. And the mirror case — a .cpp-only diff whose TU includes a header with findings — reports nothing before or after widening, because -line-filter drops it. The regex is a no-op in CI in both directions.

The causal story is also disproved. Pre-fix Format.hpp, analysed as its own TU under the narrow regex, reports bugprone-incorrect-roundings on line 76 — the #663 line. #664 did not hide #663; nothing was hiding it, because nothing was analysing unchanged files at all.

What I should have caught, and had in hand

Two sweeps ago I verified PR #649's filter myself and wrote, in my own verification comment:

"Source in DB → kept. Source not in DB → dropped, with a named warning. Header not in DB → kept … the property that separates this from -only-check-in-db."

That is the same fact. I measured it, wrote it down, and then triaged this issue valid without connecting the two. The check that would have caught it was one grep over a file I had already read.

This is the second of my triages overturned today — #667 was the other, also a specific-sounding mechanism I accepted without running the cheap test. The common shape: a premise phrased as a concrete causal chain ("X lacks feature Y, therefore Z") reads as verified and usually is not, and I have been more sceptical of lane reports than of issue bodies. That asymmetry is backwards — a lane report arrives with its measurements attached; an issue body arrives with its reasoning attached.

Where the real problem lives

Not nowhere. The lane's tree-wide measurement found 657 findings in 159 headers newly admitted by a widened regex (633 in 150 examples/ headers, 13× the 49-in-12 lower bound this issue cited) — but CI would report none of them, because no job lints unchanged code. That is #677, filed today, and it is the same defect as the pre-existing #580 at a wider scope.

So the successor already exists. Closing this as invalid rather than rescoping it, because #677 and #580 between them hold the real finding and a third ticket would fragment it. The question of which of #677/#580 survives is theirs to settle.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VptDWG2fKr2vBnLSJcgzgW