Code Quality Tools

Purpose and Scope

This page documents AReaL's code quality infrastructure, including pre-commit hooks, linting, formatting, and automated validation. These tools ensure consistent code style, catch common errors before commit, and enforce quality standards across Python, C/C++/CUDA, Markdown, and configuration files.

Pre-commit Framework

AReaL uses the pre-commit framework to automatically run code quality checks before each commit. The configuration is defined in .pre-commit-config.yaml1-144 The system triggers hooks for both the pre-commit and commit-msg stages .pre-commit-config.yaml1-3

Pre-commit Execution Flow

The pipeline consists of multiple stages, including formatting, linting, and specialized validation hooks.

Pre-commit Execution Flow

Sources: .pre-commit-config.yaml1-144

Python Code Quality: Ruff

AReaL uses Ruff (version 0.14.9) for both linting and formatting Python code. Ruff is configured to automatically fix issues when possible .pre-commit-config.yaml47-58

• Ruff Linting: The ruff hook checks for code quality issues, unused imports, and style violations in .py, .pyi, and .ipynb files .pre-commit-config.yaml51-54
• Ruff Formatting: The ruff-format hook ensures consistent code style across the codebase .pre-commit-config.yaml55-58

Sources: .pre-commit-config.yaml47-58

C/C++/CUDA Formatting: clang-format

AReaL uses clang-format (version 19.1.7) to format C, C++, and CUDA code consistently using a file-based style with a Google fallback .pre-commit-config.yaml6-14

Extension	Language
.c, .h	C
.cc, .cpp, .cxx, .hpp, .hxx	C++
.cu, .cuh	CUDA

Sources: .pre-commit-config.yaml9-13

Documentation and Notebooks

Markdown Formatting: mdformat

AReaL uses mdformat (version 0.7.17) with a wrap width of 88 characters .pre-commit-config.yaml35-40 It includes plugins for GitHub Flavored Markdown (mdformat-gfm), tables, and frontmatter .pre-commit-config.yaml41-44 Specific algorithm and performance documentation are excluded to maintain precise technical layouts .pre-commit-config.yaml45

Jupyter Notebooks: nbstripout

The nbstripout hook (version 0.7.1) automatically strips output cells and metadata from Jupyter notebooks before committing to keep the repository clean and reduce diff noise .pre-commit-config.yaml60-66

Sources: .pre-commit-config.yaml35-45 .pre-commit-config.yaml60-66

Validation and Hygiene Hooks

File Validation

• YAML/JSON: Hooks validate the syntax of configuration files .pre-commit-config.yaml18-19 .pre-commit-config.yaml29-30
• Large Files: Prevents committing files larger than 1000KB, excluding uv.lock .pre-commit-config.yaml25-28
• Private Keys: Detects accidentally staged private keys .pre-commit-config.yaml32-33

File Hygiene

• End-of-File Fixer: Ensures files end with a newline .pre-commit-config.yaml21-22
• Trailing Whitespace: Removes trailing spaces from line endings .pre-commit-config.yaml23-24

Sources: .pre-commit-config.yaml15-33

Custom Local Hooks

AReaL implements several repository-specific hooks to maintain consistency across its complex multi-backend and distributed infrastructure.

License Header Validation

The check-license-header hook (implemented in areal/tools/check_license_header.py) ensures all Python source files in the areal/ directory contain the SPDX Apache-2.0 license header areal/tools/check_license_header.py1-17 It respects shebangs by inserting the header on the second line if a shebang is present areal/tools/check_license_header.py35-38

CODEOWNERS Formatting

The format-codeowners hook (implemented in areal/tools/format_codeowners.py) enforces strict standards on .github/CODEOWNERS areal/tools/format_codeowners.py4-21:

• Alignment: Re-aligns the owners column based on the longest path areal/tools/format_codeowners.py8-9
• Redundancy: Errors on duplicate path patterns areal/tools/format_codeowners.py14
• Governance: Warns if a rule has fewer than two owners, as the project governance policy expects redundancy to avoid single points of failure areal/tools/format_codeowners.py15-17 GOVERNANCE.md59-61

Build System Consistency

• Pyproject Consistency: The check-pyproject-consistency hook ensures that pyproject.toml and pyproject.vllm.toml remain synchronized .pre-commit-config.yaml70-74
• UV Lockfile: The uv-lock hook automatically runs scripts/uv_lock.sh to regenerate lockfiles whenever pyproject.toml variants change .pre-commit-config.yaml82-86

CLI Documentation Flow

Sources: .pre-commit-config.yaml68-124 areal/tools/check_license_header.py1-69 areal/tools/format_codeowners.py1-133

Conventional Commits

AReaL enforces the Conventional Commits specification for commit messages using conventional-pre-commit .pre-commit-config.yaml126-144

Allowed Types

The following types are permitted in commit subjects .pre-commit-config.yaml132-143:

• feat: New features
• fix: Bug fixes
• docs: Documentation changes
• gov: Governance/policy changes
• style: Formatting/style changes
• refactor: Code restructuring
• perf: Performance improvements
• test: Adding or correcting tests
• build: Build system changes
• ci: CI configuration changes
• chore: Maintenance tasks
• revert: Reverting previous commits

Sources: .pre-commit-config.yaml126-144

Governance and Access Control

Code quality is mechanically enforced via GitHub Branch Protection rules defined in .github/ruleset.json .github/ruleset.json1-43

Merge Requirements

• Reviewers: All pull requests require approval from at least two maintainers .github/ruleset.json25 GOVERNANCE.md59
• Ownership: At least one approval must come from a code owner of the modified paths as defined in .github/CODEOWNERS GOVERNANCE.md60-61
• Status Checks: The pre-commit status check must pass before merging .github/ruleset.json37-38

Code Entity to Tool Mapping

Sources: .github/ruleset.json1-43 GOVERNANCE.md1-85 .github/CODEOWNERS1-35