Code Quality Tooling (clang-format, clang-tidy, cmake-format)

The commands, the scoping rules, the two clang-tidy traps and the cadence are generic and live upstream: ANTfrastructure / code-quality-tooling.md. Read that first; this page carries only what is specific to this repo.

The configs (.clang-format, .clang-tidy, gcovr.cfg) are ANTfrastructure’s too, copied in; .antfrastructure-shared.manifest lists the nine assets this repo takes. Edit them upstream in shared/config/, then run Sync-SharedConfig.ps1 -RepoRoot . -Write. .cmake-format.yaml also lives at this repo’s root. The drift gate, bash third_party/ANTfrastructure/shared/config/sync-shared-config.sh --repo-root . --check, is one of the six gates of the hub’s lint aggregator, which .github/workflows/lint-gates.yml runs on every push, docs-only ones included (it has no paths-ignore). Its Pester mirror in the Windows lane: scripts/windows/tests/SharedConfig.Drift.Tests.ps1.

This repo’s paths

This dev box has no host LLVM any more (checked 2026-09-25: no C:\Program Files\LLVM; it held LLVM 22.1.8 when these commands were verified on 2026-07-19): install one before pointing upstream’s $CT at its clang-tidy.exe. Upstream trap 1, the container build database rewrite, is for the checkout at C:\GitHub\BeschleunigerBallett:

$db = "$env:TEMP\tidydb"; New-Item -ItemType Directory -Force $db | Out-Null
(Get-Content build-clangcl-debug\compile_commands.json -Raw) `
  -replace 'C:/ws', 'C:/GitHub/BeschleunigerBallett' |
  Set-Content "$db\compile_commands.json" -NoNewline
& $CT -p $db --quiet Src/GraphicsEngineVulkan/Main.cpp

Upstream trap 2’s module skip is in third_party/ANTfrastructure/windows/scripts/modules/WindowsClang.Common.psm1. Linux equivalent: scripts/linux/run-static-analysis-format.sh.

Running them as part of a build

Build-Windows.ps1 runs both unless told otherwise:

# format + tidy included (slower)
.\scripts\windows\Build-Windows.ps1 -Configurations 'clangcl-debug'

# the fast loop, skipping them
.\scripts\windows\Build-Windows.ps1 -Configurations 'clangcl-debug' -SkipFormat -SkipTidy

Containerized builds always run clang-format, and clang-tidy again since 2026-10-01: neither scripts/windows/Build-Windows-Container.ps1 nor the Windows x64 lane’s Invoke-WindowsLane.ps1 passes -SkipFormat, nor -SkipTidy any more, because the image’s clang-tidy (LLVM 23.1.1 when hub CON10 proved it) reads a clang-cl C++23 BMI. It covers only the TUs that import no kataglyphis module (the hub’s Invoke-ClangTidyFixStep skips the rest, upstream trap 2), and .clang-tidy sets no WarningsAsErrors: a finding is logged, never fatal; only a TU tidy cannot parse fails the step.

The clang-format check is a failing gate since 2026-10-06, after the sweep below. Both lanes run clang-format --dry-run -Werror, fail on one deviating file, and refuse a clang-format of another release than the pinned LLVM’s (in third_party/ANTfrastructure/linux/scripts/01-core/versions.env): the fleet formats with the pinned LLVM (owner decision, 2026-10-06). Since 2026-10-19 the hub picks and checks the binary on both lanes.

• Windows: Build-Windows.ps1’s clang-format check step, which the x64 lane’s Invoke-WindowsLane.ps1 runs since it stopped passing -SkipFormat (the arm64 cross lane still skips it: formatting does not depend on the target). The hub’s Invoke-ClangFormatCheck requires LLVM_WINDOWS_VERSION of the PATH clang-format, the image’s C:\llvm-patched\bin\clang-format.exe.

• Linux: the static-analysis job’s first step, run-static-analysis-format.sh --only-format-check, over Src, Test and scripts/riscv64, the 217 files Get-ProjectCppFiles gives Windows. The hub’s code_quality_require_pinned_clang_format takes the first LLVM_RELEASE clang-format of /usr/local/llvm-target/bin and PATH, so a distro one (21.1.8 flagged 41 of the swept files) never grades.

Rewrite locally with Build-Windows.ps1 -ApplyFormat or the pinned binary’s -i (run-static-analysis-format.sh uses it too).

cmake-format is a failing gate too (since 2026-10-12), in the same --only-format-check step: the hub’s pinned cmake-format checks every CMake file outside build*/, .venv/ and third_party/ against .cmake-format.yaml. Before, only the full mode ran it, in place, so it rewrote the CI checkout and never failed; 11 of 18 files had drifted. The sweep that fixed them is in .git-blame-ignore-revs.

Known state (2026-10-06)

0 of 216 own sources under Src/ and Test/ differ from .clang-format (0 of 217 with scripts/riscv64/fp16_helpers.c), after the sweep in commit fb246fbcdae20e0d513c3133455c180f2faecd40. It ran clang-format 23.1.1 (LLVM commit 6dfe1677ab8dffbc6ec13d53a1e0215d75147689, /usr/local/llvm-target/bin in :latest, the version :winamd64 ships as C:\llvm-patched) over the 217 files Get-ProjectCppFiles lists, read from the git index so a CRLF checkout cannot count, and reformatted 146 of them. It reflowed 37 comments past the 120-column limit onto two lines, which the one-line comment rule forbids, so each was rewritten as one shorter line. The commit is in .git-blame-ignore-revs; run git config blame.ignoreRevsFile .git-blame-ignore-revs once per clone so git blame skips it.

Before the sweep the check only reported, so drift only grew: 72 of 125 on 2026-07-19, 142 of 216 on 2026-08-05 (Windows), 134 of 217 on 2026-09-29 and 136 of 216 on 2026-10-06 (Linux, distro 21.1.8), 146 of 217 by the pinned 23.1.1.

The hub pin of 2026-10-10 moved the gate to 23.1.3, which reads the same: 0 of 217 in :winamd64 and :latest. Since hub a5443e2c (2026-10-12) .clang-format sets ReflowComments: Never, so clang-format leaves comments as written and a long one stays one line. It also stopped aligning a // line under the trailing comment above it, so the three such pairs in VulkanDevice.cpp and VulkanInstance.cpp became one line each. 0 of 217 deviate in :latest.