reduce-header-includes

name	reduce-header-includes
description	Use when the user wants to remove unused
user-invocable	true
allowed-tools	Bash, Read, Edit, Write, Agent

1. One-time setup

brew install llvm                         # → /opt/homebrew/opt/llvm/bin/clang-include-cleaner
BUILD=WebKitBuild/cmake-mac/Debug         # mac-dev-debug preset's binaryDir
cmake --preset mac-dev-debug              # emits $BUILD/compile_commands.json
cmake --build --preset mac-dev-debug      # generated/forwarding headers + .ninja_deps must exist before analysis

1a. Dump ninja dependency data (once per session, after a clean build)

ninja -C $BUILD -t deps > /tmp/ninja-deps.txt

This is the authoritative "which TUs read which headers" map for ranking and cascade prediction. It is reliable only immediately after a successful build — see §5a for staleness rules. Match headers by basename (grep '/Foo\.h$'), not full path: WTF deps appear via WebKitBuild/.../Headers/wtf/ symlinks and JSC via PrivateHeaders/JavaScriptCore/ copies, so the same header shows under multiple paths.

2. Prepare a filtered compile_commands.json

Homebrew clang can't read Apple-specific flags or Apple-built PCH, and the CMake textual prefix (cmake_pch.hxx) breaks standalone-header analysis. Build a filtered CDB once per session:

RES=$(xcrun clang -print-resource-dir)
mkdir -p /tmp/cdb-optimize
python3 - "$RES" <<'PY'
import json, re, sys
res = sys.argv[1]
src = json.load(open("WebKitBuild/cmake-mac/Debug/compile_commands.json"))
DROP = re.compile(r"-fcas-\S+|-fno-odr-hash-protocols|-clang-vendor-feature=\S+|"
                  r"-Wno-error=allocator-wrappers|-mllvm|-cas-friendly-debug-info|-Winvalid-pch")
out = []
for e in src:
    a, i = e["command"].split(), 0; keep = []
    while i < len(a):
        t = a[i]
        if t == "-Xclang" and i+1 < len(a) and (a[i+1] in ("-include-pch", "-include")
                or a[i+1].endswith((".pch", ".hxx")) or a[i+1].startswith("-fno-builtin-")):
            i += 2; continue
        if t == "--serialize-diagnostics": i += 2; continue
        if DROP.fullmatch(t): i += 1; continue
        keep.append(t); i += 1
    keep.append(f"-resource-dir={res}")
    e["command"] = " ".join(keep); out.append(e)
json.dump(out, open("/tmp/cdb-optimize/compile_commands.json", "w"))
PY

Why strip -Xclang -include -Xclang cmake_pch.hxx: the textual prefix transitively includes most project headers. When analyzing Foo.h as the main file, #pragma once doesn't guard the main file itself, so the prefix pulls in Foo.h once and then clang parses it again as the TU body → "redefinition" errors. Stripping the prefix is safe for .cpp files because they all #include "config.h" on line 1 anyway.

Why inject -resource-dir: without it, homebrew clang can't find Availability.h, so every PLATFORM(...)/ENABLE(...) macro resolves wrong and the suggestions are garbage.

3. Rank targets by impact (ninja deps)

Process headers highest-fan-out first — removing one include from a header read by 500 TUs is worth 500× one read by 3 TUs:

for h in <candidate headers>; do
  printf '%6d  %s\n' "$(grep -c "/$(basename "$h")\$" /tmp/ninja-deps.txt)" "$h"
done | sort -rn | head -40

Deps records opened, not used — it ranks reach, it cannot tell you what's removable. That's Pass A's job.

Basename collision: matching by basename merges same-named headers across projects (bmalloc/Vector.h + wtf/Vector.h reported as 405 when bmalloc's true reach is 4). When a count looks suspiciously high for the project, re-check with a parent-dir prefix: grep -c "bmalloc/$(basename "$h")\$".

4. Pass A — Remove unused includes (.h .cpp .c .mm .m)

/opt/homebrew/opt/llvm/bin/clang-include-cleaner \
    --print=changes --disable-insert \
    --ignore-headers='config\.h,.*SoftLinking\.h,.*SPI\.h' \
    -p /tmp/cdb-optimize <file>

Output: - "Header.h" @Line:N per removable include.

Headers (.h) have no CDB entry; clang-include-cleaner interpolates flags from a sibling .cpp. Force the language and pre-include config.h (headers don't include it themselves):

/opt/homebrew/opt/llvm/bin/clang-include-cleaner \
    --print=changes --disable-insert \
    --ignore-headers='config\.h,.*SoftLinking\.h,.*SPI\.h' \
    --extra-arg-before=-xobjective-c++ \
    --extra-arg-before=-std=c++2b \
    --extra-arg=-includeconfig.h \
    -p /tmp/cdb-optimize <header.h>

The -includeconfig.h flag is per-project — bmalloc/libpas have no config.h (their headers self-include BPlatform.h/pas_config.h), so drop that flag there. Keep it for WTF/JSC/WebCore/WebKit.

If a header still won't parse standalone (heavy template/macro context, or it is one of the few headers config.h itself pulls in), skip it and note it — don't fight the tool.

Never remove (all file types), even if the tool says so:

• config.h
• *SoftLinking.h (symbols via SOFT_LINK_* macros)
• The file's own header (Foo.h in Foo.cpp) — often only used via DEFINE_ALLOCATOR/WTF_MAKE_*
• NeverDestroyed.h when a *_ALLOCATOR / LazyNeverDestroyed macro/use is present
• SIMDUTF.h
• *SPI.h
• <TargetConditionals.h>, <AvailabilityMacros.h>, <Availability.h> — define TARGET_OS_*/__MAC_* macros that #if tests
• <Foundation/Foundation.h> and other ObjC framework umbrellas in .mm/.m — provide NSString/NSBundle/etc. via macros the tool can't trace
• Project macro-only foundations: bmalloc BPlatform.h/BCompiler.h/BExport.h/BInline.h; WTF Platform.h/Compiler.h/ExportMacros.h
• The flagged #include is the file's entire body for this platform — pure forwarding/portability shims (e.g., pas_thread.h is just #include <pthread.h> on non-Windows). The tool sees no local symbol use because re-export is the point.
• Any #include in a file that pulls __has_include(<WebKitAdditions/...>) — the additions header is internal-SDK-only and invisible to open-source tooling, so includes that exist to satisfy it (e.g., AllocationCounts.h's <atomic>/BExport.h) read as unused.

Never remove from .h files (OK to remove from .c/.cpp/.m/.mm): these guard against transitive breakage in downstream TUs/platforms, which can't happen from a leaf file — there the file's own compile is the full verification.

• <mach/*.h> inside #if BOS(DARWIN)/#if OS(DARWIN) — needed on embedded even when macOS gets it transitively
• Any #include inside an #if PLATFORM(...)/#if ENABLE(...) block whose condition can differ on non-mac
• Any top-level #include whose only use is inside an #if/#else arm that's compiled out on mac (e.g., BAssert.h's Logging.h — only referenced under #if !BUSE(OS_LOG)). The tool only sees the active config.
• Any #include whose only use is inside a #define macro body (e.g., GigacageConfig.h's <bit> — std::bit_cast appears only in #define g_gigacageConfig). The tool doesn't analyze macro definitions, only expansions; if no expansion lands in the analyzed TU, it reports unused.
• *Inlines.h — template/inline bodies in the target header may need them at instantiation time in a downstream TU; the tool only sees instantiations in the analyzed TU.
• JSC split-inlines without the suffix: JSCJSValueCell.h, JSCJSValueStructure.h, JSCJSValueBigInt.h, JSCellButterfly.h. Same failure mode as *Inlines.h (out-of-class inline method definitions, not declarations) — removal links fine in the edited header but drops JSValue::inherits()/structureOrNull() defs from downstream TUs → undefined-symbol at link. Filter regex: Inlines.*\.h|JSCJSValue(Cell|Structure|BigInt)\.h|JSCellButterfly\.h.
• wtf/text/StringHash.h / *Hash.h when the target header defines a type used as a HashMap/HashSet key. The trait specialization (DefaultHash<K>) is needed at container instantiation in a downstream TU, not in the key header itself, so the tool reports it unused. (Observed: RegExpKey.h → PackedRefPtr<StringImpl> static_assert + GenericHashTraits undefined.)

Verify by exported symbol, not header basename. Before applying a removal of Foo.h, grep the target file for the names Foo.h declares, not just the string "Foo" — header name and type name often differ (ArgList.h → MarkedArgumentBuffer, HashSet.h → UncheckedKeyHashSet). Quick extractor:

grep -hoE '^\s*(class|struct|enum class|using|typedef|#define)\s+\w+' <Foo.h> | awk '{print $NF}' | sort -u

Then grep -v '#include' <target> | grep -wF -f - for each. If any hit, it's a FP.

Apply removals with the Edit tool (one line per removal). Do not use --edit — the never-remove filter must be applied manually.

4c. Leaf-file sweep (.cpp .c .mm .m, unranked)

After the §3-ranked header pass, sweep all implementation files in the target directory. Leaf TUs have fan-out 0 so they never surface via §3, but every TP is a free win with zero cascade risk — only the file's own compile needs to pass. PR #62576 found 38 removals in libpas .c files this way that the header-ranked pass missed entirely.

macOS xargs -I{} truncates long command lines, so write a helper once and pass filenames as $1:

cat > /tmp/run-cleaner-cpp.sh <<'EOF'
#!/bin/sh
out=$(/opt/homebrew/opt/llvm/bin/clang-include-cleaner --print=changes --disable-insert \
  --ignore-headers='config\.h,.*SoftLinking\.h,.*SPI\.h' \
  -p /tmp/cdb-optimize "$1" 2>/dev/null)
[ -n "$out" ] && printf '=== %s ===\n%s\n' "$1" "$out"
EOF
chmod +x /tmp/run-cleaner-cpp.sh

find Source/<dir> \( -name '*.c' -o -name '*.cpp' -o -name '*.m' -o -name '*.mm' \) -print0 \
  | xargs -0 -n1 -P8 /tmp/run-cleaner-cpp.sh > /tmp/leaf-results.txt
grep '^- ' /tmp/leaf-results.txt | sort | uniq -c | sort -rn | head

(For headers, copy to /tmp/run-cleaner-header.sh and add the §4 --extra-arg-before=-xobjective-c++ --extra-arg-before=-std=c++2b --extra-arg=-includeconfig.h flags.)

Apply only the "all file types" never-remove list above — the "headers only" filters don't apply here. Then -k 0 build; any failure is a per-file revert, not a cascade.

5. Pass B — Add missing direct includes (.cpp .c .mm .m only)

Pass B is ~4× noisier than Pass A (bmalloc dry-run: ~20% precision vs ~70%). Default to running it only as the repair tool inside the §6 fix-loop, not as a blanket pre-pass. If you do run it broadly, apply the never-insert filter and path normalization aggressively.

/opt/homebrew/opt/llvm/bin/clang-include-cleaner \
    --print=changes --disable-remove \
    -p /tmp/cdb-optimize <file>

Output: + "Header.h" / + <wtf/Header.h> per missing direct include.

Never run Pass B on .h files — adding includes to headers bloats the transitive graph, which is what we're fighting.

Normalize paths before inserting. The tool emits -I-relative paths; WebKit uses quoted basenames. Strip leading bmalloc/, libpas/src/libpas/, JavaScriptCore/, WebCore/, wtf/ (when inside WTF) so + "libpas/src/libpas/pas_lock.h" becomes #include "pas_lock.h".

Never insert:

• wtf/Forward.h, wtf/Platform.h, wtf/Compiler.h, wtf/Assertions.h, wtf/ExportMacros.h — provided by config.h
• bmalloc BPlatform.h/BCompiler.h/BExport.h/BInline.h/BAssert.h — bmalloc's config.h-equivalents
• Underscore-prefixed system internals (<_strings.h>, <_stdio.h>, …) — use the public header instead
• <sys/qos.h>, <sys/_types/*.h> — implementation details; use <dispatch/dispatch.h> / <cstddef> etc.
• cmake_pch.hxx or any prefix/PCH header
• A header that's already included via the file's own .h

Insertion point: after #include "config.h" and the file's own header, alphabetically within the existing group. In .mm/.m, use #import for ObjC framework headers (<Foundation/...>, <WebKit/...>), #include for everything else.

5a. Predict the cascade before rebuilding (optional shortcut)

After removing #include "X.h" from header H, the candidate-casualty set is:

awk -v H="/$(basename H)" -v X="/$(basename X.h)" '
  /: #deps /        { tu=$1; hasH=0; hasX=0 }
  $1 ~ H"$"         { hasH=1 }
  $1 ~ X"$"         { hasX=1 }
  hasH && hasX && tu { print tu; tu="" }
' /tmp/ninja-deps.txt | head

This over-predicts (flat list, no include-tree — can't tell "via H" from "via some other path") but never under-predicts for this platform/config. Run Pass B on those TUs first instead of waiting 10–15 min for -k 0 to find them. If the set is ≳10 TUs, that's the §6 escape-hatch signal up front.

Staleness: /tmp/ninja-deps.txt reflects the last successful compile per TU. After edits it's stale-but-conservative (removed includes still listed → over-predicts, which is safe). Re-dump only after a clean -k 0 build; don't re-dump mid-loop.

6. Build-and-fix loop

cmake --build --preset mac-dev-debug -- -k 0 2>&1 | tee /tmp/build.log

Run with dangerouslyDisableSandbox: true, run_in_background: true. Monitor:

grep -E "error:" /tmp/build.log | head -40

If -k 0 reports exactly 1 FAILED: and it's LLInt{Settings,Offsets}Extractor.cpp.o, that target generates headers the rest of JSC depends on, so ninja can't continue past it. Fix that one error and re-run; the next round will surface the real cascade.

For each use of undeclared identifier 'X' / unknown type name 'X' / incomplete type 'X' / no member named 'X':

1. Identify the real TU. If the error is in UnifiedSourceN.cpp/.mm, open the unified wrapper and find which constituent .cpp owns the failing line.
2. Expect casualties in files you didn't edit. Removing an include from a header, or from an earlier sibling in a unified bundle, breaks downstream files that were leaning on it transitively. This is normal — do not revert.
3. Find the providing header. git grep -nE "^(class|struct|enum class|using) X\b" -- 'Source/**/*.h' | head. Prefer the header with the definition, not a forward declaration.
4. Add #include "Provider.h" to the failing real .cpp — never to the unified wrapper. If the failing line is in a .h (the type appears in a signature/member), add the include to that .h — this is the IWYU fix; the header was leaning on a transitive path you just cut.
5. Re-build with -k 0. Repeat until clean.

Escape hatch: if one removed header line causes an unbounded cascade (≳10 TUs all needing the same add), that header was a de-facto umbrella — restore that single removal and move on. Known JSC umbrellas (skip removals here outright): JSCInlines.h, JSCellInlines.h, JSCJSValueInlines.h, Lookup.h, ObjectAllocationProfile.h — each fans out to all WebCore JS bindings.

7. Cross-platform fallout (after PR)

Local CMake only builds macOS. EWS-only breaks from removed includes that other platforms need directly:

• <mach/mach.h> — embedded Darwin (ios/tv/watch/vision) for mach_task_self/kern_return_t; macOS gets it transitively via frameworks
• <mach/task_info.h> — task_vm_info_data_t/TASK_VM_INFO_COUNT (does not provide mach_task_self — need <mach/mach.h> too)
• <sys/file.h> — Linux (WPE/GTK) for flock()/LOCK_*
• <wtf/NeverDestroyed.h> — LazyNeverDestroyed<T>; forward decl insufficient
• <wtf/Function.h> — WTF::Function<> on Linux; not pulled in transitively there

EWS-only breaks: re-add the include in the failing TU, guarded by the same #if the failing platform uses.