Problem Statement

The codebase currently has no static analysis enforcing modern C++ idioms and best practices. Without a tool like clang-tidy, it is easy for outdated patterns (raw pointers, C-style casts, missing override, etc.) to slip in unnoticed, increasing technical debt over time.

Proposed Solution

Integrate clang-tidy into the build system (xmake) and CI pipeline to statically analyse the codebase and enforce modern C++ usage. A .clang-tidy configuration file should be added at the root of the repository, enabling a curated set of checks, for example:

• modernize-* — replace old C++ patterns with C++17/20 equivalents (e.g. modernize-use-nullptr, modernize-use-override, modernize-use-default-member-init).
• cppcoreguidelines-* — enforce C++ Core Guidelines.
• readability-* — improve code clarity and reduce ambiguity.
• performance-* — catch common performance pitfalls.
• bugprone-* — detect patterns likely to cause bugs.

Checks that are not applicable to the project (e.g. those conflicting with chosen third-party libraries) should be explicitly disabled with a comment explaining the rationale.

Alternative Solutions

• Use clang-tidy only in CI as a warning step (non-blocking) — lower friction to adopt but does not prevent new violations from being merged.
• Use cppcheck instead — lighter tool but less powerful than clang-tidy for enforcing modern C++ idioms.
• Combine both clang-tidy and cppcheck for broader coverage.

Use Cases

• Use case 1: A contributor submitting a PR that uses a C-style cast gets a CI failure with a clear message pointing to the offending line.
• Use case 2: A reviewer can rely on clang-tidy to catch common idiom violations automatically, allowing them to focus on logic and design.
• Use case 3: New contributors have a concrete, machine-enforced reference for what modern C++ code looks like in this project.

Impact

• CI build time will increase slightly due to static analysis.
• Some existing code may need to be refactored to pass the new checks — this can be done progressively (see #548).
• No changes to runtime behaviour or public API.
• No breaking changes.

Implementation Details (optional)

• Add a .clang-tidy file at the repository root with a well-commented configuration.
• Configure xmake to run clang-tidy alongside compilation (e.g. via set_policy("build.c_cxx.clang_tidy", true) or a custom rule).
• Add a dedicated CI step (GitHub Actions) that runs clang-tidy on all modified files in a PR, or on the full codebase on main.
• Consider using run-clang-tidy or clang-tidy-diff.py for incremental analysis on PRs to keep CI fast.
• Fixes can be applied progressively per plugin/module, similar to the approach described in #548.

Additional Context

clang-tidy is the standard static analysis tool for C++ projects using Clang/LLVM and integrates well with xmake and GitHub Actions. Enforcing it early will make the codebase easier to maintain and onboard new contributors onto modern C++ practices.

Related Issues

• #548 ([REFACTOR] Progressively clean up code using -Weverything)