[build] Add misc-include-cleaner clang-tidy check for headers

[fhanau]

Reduces transitive include bloat by enforcing that no unused headers are being added.

This only covers header files for now and does not include KJ includes, otherwise the PR would need to be much larger and people would get linter errors more frequently.

Deployment plan: This will require some downstream changes to land, a PR for that will follow soon. I plan to only enable this check for workerd for now and see how things go with that, if people find that it is too much of an annoyance to sometimes be told that they have superfluous headers we can disable it again. But I hope that the check makes sense to developers for the most part and that we can benefit from having includes that make sense and slightly faster compile times (fewer includes means less time spent parsing headers).
If feedback is mostly positive a couple weeks in, we may want to extend this to the downstream repo and to capnproto.

[ask-bonk]

Model not found: cloudflare-ai-gateway/anthropic/claude-opus-4-6. Did you mean: anthropic/claude-opus-4.5, anthropic/claude-opus-4.6, anthropic/claude-opus-4.7?

github run

[ask-bonk]

@fhanau Bonk workflow failed. Check the logs for details.

View workflow run · To retry, trigger Bonk again.

[github-actions]

The generated output of @cloudflare/workers-types matches the snapshot in types/generated-snapshot 🎉

[fhanau]

Note to self: Improve documentation of HEADER_ONLY_CHECKS before landing this

[fhanau]

Why am I fixing clang-tidy checks other than misc-include-cleaner in these files? Previously the jsg-core target was not being covered by clang-tidy as some of its headers can't compile on their own due to header interdependencies that I have not been able to resolve. But with the new no-clang-tidy-headers tag, we can apply clang-tidy to the source files only and get proper coverage for them.

[codspeed-hq]

Merging this PR will improve performance by 9.18%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 1 improved benchmark
✅ 71 untouched benchmarks
⏩ 129 skipped benchmarks¹

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚡	simpleStringBody[Response]	24.8 µs	22.7 µs	+9.18%

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing felix/080726-include-enforcement (1667a06) with main (84284d8)}

Footnotes

1. 129 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[npaun]

We're still disabling the check in a number of places. Do you plan to cut down on these in a later PR?

[fhanau]

We're still disabling the check in a number of places. Do you plan to cut down on these in a later PR?

I cleaned up all that I could without significant extra effort:

• //src/rust/jsg has no-clang-tidy since it has C++ headers that fail to compile on their own due to missing headers for reasons I didn't fully understand (the way wd_rust_crate uses globs for headers is a mess I tried to clean up while working on this, but it also lead to unexpected compile errors). At this point, I'm content with at least not making the existing situation worse
• //src/workerd/tests:bench-tools needs to have clang-tidy disabled since it pulls in headers from clang-19, which are incompatible with how clang-tidy-22 works (different LLVM versions aren't supposed to be mixed like that I guess). We can only fix this once we update the CI compiler version (might be a good idea anyway, but there's no rush so far). Unfortunately, this might get worse as we try to adopt clang-tidy-23 (which is incompatible with some clang 22 headers), we'll have to see.
• no-clang-tidy-headers is used for JSG headers as explained in [build] Add misc-include-cleaner clang-tidy check for headers #7054 (comment)
• This check only runs on headers and does not warn about superfluous includes of KJ headers for reasons I've covered in a comment (avoid needing to make humongous changes). I think this will give us much of the savings in terms of lower compile times while not causing lint checks to fail every time someone has kj/debug.h somewhere it's not needed.