Evaluate clang-format 18 as the linting gateway for git commit hooks

[justinjoy]

Context

wirelog currently mandates clang-format 18 (llvm@18) as the sole formatting/linting gate, enforced manually before each commit (see CLAUDE.md and .clang-format). As we consider adding a git pre-commit hook to automate this, it is worth evaluating whether clang-format 18 is the right tool for the job — or whether alternatives would make the hook simpler and more maintainable.

---

Option A: Keep clang-format 18 as the linting gateway

Pros

1. Already integrated — .clang-format config is mature and tested against representative files (lexer.c, program.c, wirelog.h).
2. Deterministic formatting — clang-format is an opinionated formatter; it produces byte-identical output regardless of who runs it, eliminating style debates.
3. Deep C language awareness — understands C11 syntax, macros, and complex expressions far better than regex-based linters.
4. Widely adopted in C/C++ ecosystems — most contributors will already have it installed or know how to get it.
5. IDE support — virtually every editor has clang-format integration for format-on-save.

Cons

1. Version pinning is fragile — we require exactly v18. Formatting output can change between major versions (e.g., AlwaysBreakAfterReturnType is renamed in v19+). Contributors on rolling-release distros may have v19/v20, leading to spurious diffs.
2. Installation burden — not a single pip install or npm install. On some distros, getting exactly v18 means adding an LLVM apt repo or using Homebrew. This raises the barrier to first contribution.
3. No pre-commit framework integration out of the box — clang-format ships as a standalone binary; wiring it into a git hook requires a custom script or a wrapper like pre-commit with the clang-format mirror repo, which itself pins a version.
4. Formatter only, not a linter — clang-format fixes style but cannot detect logic issues, unused variables, or unsafe patterns. A commit hook based solely on clang-format gives a false sense of "linted".
5. Config option churn — some options we use (e.g., AlwaysBreakAfterReturnType: All) are deprecated/renamed across versions, requiring maintenance when we eventually upgrade.

---

Option B: Adopt the pre-commit framework with clang-format as one hook

Use pre-commit (.pre-commit-config.yaml) to orchestrate multiple hooks, including clang-format.

Pros

1. Declarative, version-pinned config — .pre-commit-config.yaml pins the exact clang-format version via its mirror repo; contributors just run pre-commit install.
2. Composable — easily add more hooks (e.g., clang-tidy, cppcheck, trailing whitespace, SPDX license header check) without writing shell scripts.
3. CI-friendly — pre-commit run --all-files works identically in CI and locally.
4. Isolation — pre-commit manages its own virtualenvs/tool versions, so contributors' system clang-format version doesn't matter.

Cons

1. Python dependency — pre-commit requires Python 3.x, which is an additional runtime dependency for a pure-C project.
2. Extra abstraction layer — adds a tool to learn and debug when hooks misbehave.
3. Mirror repo lag — the clang-format pre-commit mirror may lag behind upstream releases.

---

Option C: Replace clang-format with an alternative formatter/linter

Possible alternatives:

Tool	Type	Hook simplicity	C11 awareness	Notes
clang-tidy	Linter + fixer	Medium (needs compile_commands.json)	Excellent	Catches bugs, not just style. Can auto-fix some issues.
uncrustify	Formatter	Easy (single binary)	Good	Highly configurable, stable config format, fewer cross-version surprises.
astyle	Formatter	Easy (single binary)	Moderate	Simpler config, but less precise for complex C constructs.
indent (GNU)	Formatter	Trivial (coreutils-adjacent)	Basic	Classic UNIX tool, but limited and not actively developed.

Pros of switching

1. uncrustify has a more stable configuration format across versions — less breakage on upgrades.
2. clang-tidy provides actual static analysis (null dereference, use-after-free patterns) on top of style — more value from a single hook.
3. Some alternatives are easier to install on all platforms.

Cons of switching

1. Migration cost — our .clang-format config represents significant tuning effort; recreating equivalent behavior in another tool is non-trivial.
2. clang-tidy requires a compilation database (compile_commands.json) — Meson can generate this, but it adds a build step before linting.
3. Community familiarity — clang-format is the de facto standard for C formatting; switching to a less common tool may confuse contributors.

---

Questions for discussion

1. Version pinning: Should we keep requiring exactly v18, or accept a version range (e.g., 18–19) with a CI check for exact output?
2. pre-commit framework: Is adding a Python dependency acceptable for a C project, given the convenience it provides?
3. Scope of the hook: Should the commit hook only enforce formatting, or should it also run lightweight static analysis (e.g., cppcheck --enable=warning)?
4. Contributor experience: What is the acceptable setup cost for a new contributor? (brew install clang-format@18 vs pip install pre-commit && pre-commit install?)

Looking forward to hearing everyone's thoughts.

[justinjoy]

Option C (clang-tidy) does not solve the version pinning problem — it makes things worse

Option C's clang-tidy adoption exacerbates the core pain points raised in this discussion (version pinning, installation burden) rather than solving them.

1. Version pinning problem remains identical

• clang-tidy is part of the LLVM project, and check lists and behavior change across major versions.
• The same .clang-tidy config can produce different results on v18 vs v19, exactly like clang-format.
• Additionally, compile_commands.json generation depends on the compiler version, introducing a dual version dependency.

2. Standalone installation is practically impossible

Platform	Standalone clang-tidy install	Actual required package
Ubuntu/Debian	apt install clang-tidy-18 (requires LLVM apt repo)	clang-tidy binary + libclang runtime
Arch Linux	Not possible	pacman -S clang (full clang toolchain)
macOS (Homebrew)	Not possible	brew install llvm@18 (full LLVM ~1.5GB)

clang-format can be installed as a relatively lightweight standalone binary, but clang-tidy depends on the libclang runtime for AST parsing, resulting in a much larger installation footprint.

3. Compilation database is mandatory

clang-tidy cannot function properly without compile_commands.json. This means the build system must be configured before linting can run, raising the contributor onboarding barrier compared to a pure formatting hook.

Conclusion

While clang-tidy's static analysis value is acknowledged, it is a strictly heavier choice than clang-format for commit hook purposes across every dimension. If static analysis is desired, a clang-format + cppcheck combination under Option B (pre-commit framework) is more practical — cppcheck can be installed independently without LLVM dependencies and has much better cross-version stability.

[justinjoy]

Decision: Adopt Uncrustify (Option C)

I ported the existing .clang-format config to uncrustify and ran a full comparison test across the entire codebase.

Test Results

• Uncrustify 0.82.0 vs clang-format 18
• Scope: all wirelog .c/.h files (19,270 lines)
• Match rate: 97.4% (493 diff lines / 19,270 total lines)
• wirelog/parser/lexer.c: 100% identical output

Fully Compatible Settings

Setting	Value
Indent	4-space, no tabs
Function return type	GNU-style on separate line (static void\nfunc_name(...))
Braces	K&R (control statements), next line (function body)
else/while cuddle	} else {, } while (...)
Pointer alignment	Right (char *ptr)
Spacing	if (...) / func(...) / (char *)malloc
Include sorting	Disabled (preserve)
Comment reflow	Disabled (preserve)
Case indent	0 relative to switch

Known Limitations (accounting for the 2.6% diff)

1. Function call argument continuation alignment

clang-format uses a penalty-based system that dynamically decides alignment for function call arguments based on the open-paren position:

• Short function names: aligns to paren (check_keyword(a, b,\n c))
• Long names / deep nesting: falls back to flat 4-space continuation indent

Uncrustify lacks this adaptive logic and must choose one strategy. We set indent_func_call_param = true (flat 4-space) to prevent line explosion on deeply-nested calls.

// clang-format (paren-aligned for nested calls):
result = realloc(
                  prog->relations, new_cap * sizeof(info_t));

// uncrustify (flat indent):
result = realloc(
    prog->relations, new_cap * sizeof(info_t));

Both produce equally readable output. The flat indent is arguably more consistent.

2. #define macro continuation body indent

Macro continuation body indent level may differ slightly. In the wirelog codebase, this affects only the WIRELOG_VERSION macro in wirelog.h (1 occurrence).

Conclusion

A 97.4% match rate is excellent for a cross-tool port. The remaining 2.6% stems from uncrustify's architectural limitation (no penalty-based line wrapping), with no practical impact on readability. We are adopting uncrustify as the linting gateway.

Benefits:

• Stable config format across versions (no option rename churn like clang-format v18 -> v19)
• Simple single-binary installation
• Easy pre-commit hook integration
• Ported config ready to commit (uncrustify.cfg)

[justinjoy]

Resolution: Migrated to uncrustify

This discussion evaluated clang-format 18 vs alternatives for the git commit hook. The project has since fully migrated to uncrustify (Option C from the original proposal):

Current state (2026-04-10)

• uncrustify.cfg in project root, active configuration
• Pre-commit hook via scripts/setup_uncrustify_hook.py, wired in meson.build:321-344
• CI lint gate in lint-main.yml and lint-pr.yml — uncrustify checks on all platforms (ubuntu, macOS, Windows)
• clang-tidy 18 runs alongside for static analysis (separate concern)
• .clang-format file still exists but is no longer the active formatting gate

Original questions answered

1. Version pinning: uncrustify has a stable config format across versions, solving the clang-format v18/v19 breakage concern
2. pre-commit framework: not adopted; custom Python hook integrated directly into the Meson build
3. Scope: formatting (uncrustify) + static analysis (clang-tidy 18) as separate CI checks
4. Contributor experience: meson setup build auto-configures the hook; no manual tool installation needed

Cleanup note

The .clang-format file and stale CI comments referencing clang-format (ci-pr.yml:22, lint-main.yml:10) could be removed in a future cleanup commit.

This discussion has served its purpose and can be closed.