C++ Linter Architecture (ci/lint_cpp/)

IMPORTANT: All C++ linters MUST use the centralized dispatcher for performance.

Central Dispatcher

• File: ci/lint_cpp/run_all_checkers.py
• Loads each file ONCE and runs all applicable checkers on it
• 10-100x faster than running standalone scripts on each file
• All checkers run in a single pass per scope (src/, examples/, tests/)

Single-File Mode (NEW)

• Usage: uv run python ci/lint_cpp/run_all_checkers.py <file_path>
• Runs all applicable checkers on a single file (< 1 second)
• ~43x faster than full codebase scan for quick validation
• Useful for:
  • Pre-commit hooks (.claude/hooks/lint-on-save.py)
  • IDE integration
  • Quick validation during development
  • Testing new linter rules

Creating a New C++ Linter

1. Create a checker class in ci/lint_cpp/your_checker.py inheriting from FileContentChecker
2. Implement should_process_file(file_path: str) -> bool (filter which files to check)
3. Implement check_file_content(file_content: FileContent) -> list[str] (check logic)
4. Add checker instance to appropriate scope in run_all_checkers.py (see create_checkers())
5. Checker now runs automatically via bash lint --cpp

DO NOT

• Create standalone test_*.py scripts that scan files independently
• Call standalone scripts from the lint bash script
• Load files multiple times for different checks

Reference Examples

• ci/lint_cpp/serial_printf_checker.py - Simple pattern matching checker
• ci/lint_cpp/using_namespace_fl_in_examples_checker.py - Regex-based checker
• ci/lint_cpp/static_in_headers_checker.py - Complex multi-condition checker