Add some pre-commit hooks

Author: mingxwa

.github/workflows/bvt-clang.yml

@@ -17,7 +17,7 @@ jobs:
     - name: Install clang
       run: |
         curl https://apt.llvm.org/llvm.sh | sudo bash -s -- "$CLANG_VERSION"
-        sudo apt install -y "clang-$CLANG_VERSION" "libc++-$CLANG_VERSION-dev" "clang-format-$CLANG_VERSION"
+        sudo apt install -y "clang-$CLANG_VERSION" "libc++-$CLANG_VERSION-dev"
         {
           echo "CC=clang-$CLANG_VERSION"
           echo "CXX=clang++-$CLANG_VERSION"
@@ -27,7 +27,6 @@ jobs:
     - name: Check toolchain versions
       run: |
         "$CXX" --version
-        "clang-format-$CLANG_VERSION" --version
         cmake --version
         ninja --version
         meson --version
@@ -36,9 +35,6 @@ jobs:
     - name: Build and run test with clang ${{ env.CLANG_VERSION }} on cmake
       run: |
         cmake -B build-cmake -GNinja -DCMAKE_CXX_STANDARD=23 -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=TRUE
-        mapfile -t FILES < <(find include tests benchmarks build-cmake/examples_from_docs tools -type f \( -name '*.h' -o -name '*.ixx' -o -name '*.cpp' \))
-        echo "Running clang-format on ${#FILES[@]} files: ${FILES[*]}"
-        "clang-format-$CLANG_VERSION" --dry-run --Werror "${FILES[@]}"
         cmake --build build-cmake -j
         ctest --test-dir build-cmake -j
         mkdir build-cmake/drop

.github/workflows/bvt-compatibility.yml

@@ -34,10 +34,11 @@ jobs:
     - name: Install clang
       if: ${{ matrix.compiler.family == 'clang' }}
       run: |
-        if [ '${{ matrix.compiler.version }}' -ge 21 ]; then
-          curl https://apt.llvm.org/llvm.sh | sudo bash -s -- '${{ matrix.compiler.version }}'
+        version='${{ matrix.compiler.version }}'
+        if [ "$version" -ge 21 ]; then
+          curl https://apt.llvm.org/llvm.sh | sudo bash -s -- "$version"
         fi
-        sudo apt install -y 'clang-${{ matrix.compiler.version }}' 'clang-tools-${{ matrix.compiler.version }}' 'libc++-${{ matrix.compiler.version }}-dev' 'libc++abi-${{ matrix.compiler.version }}-dev'
+        sudo apt install -y "clang-$version" "clang-tools-$version" "libc++-$version-dev" "libc++abi-$version-dev"
         cat <<'EOF' >> "$GITHUB_ENV"
         CC=clang-${{ matrix.compiler.version }}
         CXX=clang++-${{ matrix.compiler.version }}

.github/workflows/bvt-lint.yml

@@ -0,0 +1,32 @@
+on:
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  bvt-lint:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Setup Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.13"
+
+    - name: Cache pre-commit envs
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/pre-commit
+        key: pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
+
+    - name: Install pre-commit
+      run: python3 -m pip install --upgrade pip pre-commit
+
+    - name: Run pre-commit hooks
+      run: pre-commit run --all-files --show-diff-on-failure --color always
+
+    - name: Install mkdocs
+      run: python3 -m pip install -r mkdocs/requirements.txt
+
+    - name: Build docs (mkdocs --strict)
+      run: mkdocs build --strict

.github/workflows/mkdocs.yml

@@ -8,6 +8,10 @@ on:
   workflow_dispatch:
 
 jobs:
+  run-bvt-lint:
+    uses: ./.github/workflows/bvt-lint.yml
+    name: Run BVT for lint
+
   run-bvt-gcc:
     uses: ./.github/workflows/bvt-gcc.yml
     name: Run BVT with GCC
@@ -40,7 +44,3 @@ jobs:
     uses: ./.github/workflows/bvt-report.yml
     name: Generate report
     needs: [run-bvt-gcc, run-bvt-clang, run-bvt-msvc, run-bvt-appleclang, run-bvt-nvhpc, run-bvt-oneapi]
-
-  mkdocs:
-    uses: ./.github/workflows/mkdocs.yml
-    name: Build mkdocs

.github/workflows/pipeline-ci.yml

@@ -7,9 +7,29 @@ on:
 
 jobs:
   build:
-    uses: ./.github/workflows/mkdocs.yml
-    with:
-      upload-artifacts: true
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          python3 -m pip install -r mkdocs/requirements.txt
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - name: Upload site artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: ./site
 
   deploy:
     needs: build

.github/workflows/pipeline-pages.yml

@@ -0,0 +1,56 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: mixed-line-ending
+        args: ["--fix=lf"]
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+        args: ["--markdown-linebreak-ext=md"]
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: check-illegal-windows-names
+      - id: check-added-large-files
+        args: ["--maxkb=1024"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.15
+    hooks:
+      - id: ruff-format
+
+  - repo: https://github.com/BlankSpruce/gersemi-pre-commit
+    rev: 0.27.7
+    hooks:
+      - id: gersemi
+        args: ["--indent", "2"]
+        exclude: '^(subprojects|build|bazel-.*)/'
+
+  - repo: https://github.com/keith/pre-commit-buildifier
+    rev: 8.2.1
+    hooks:
+      - id: buildifier
+        exclude: '^(subprojects|build|bazel-.*)/'
+
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.8
+    hooks:
+      - id: actionlint
+
+  - repo: local
+    hooks:
+      - id: meson-format
+        name: meson format
+        language: python
+        additional_dependencies: ["meson==1.10.1"]
+        entry: meson
+        args: ["format", "--check-only", "--recursive", "meson.build"]
+        pass_filenames: false
+        files: '(^|/)(meson\.build|meson\.options|meson_options\.txt)$'
+
+      - id: clang-format
+        name: clang-format
+        language: python
+        additional_dependencies: ["clang-format==22.1.5"]
+        entry: python3 tools/format_cpp.py
+        pass_filenames: false
+        files: '\.(h|ixx|cpp|md)$'

.pre-commit-config.yaml

@@ -0,0 +1,39 @@
+# Contributing
+
+Thanks for contributing! This document covers the local lint setup so your changes match what CI enforces.
+
+## Lint matrix
+
+CI runs the `bvt-lint` job on every PR. The workflow installs `pre-commit`, runs `pre-commit run --all-files`, and then builds the docs with `mkdocs build --strict`. The full check set, file scopes, and pinned tool versions all live in [`.pre-commit-config.yaml`](.pre-commit-config.yaml). That file is the single source of truth.
+
+| Hook                  | What it checks |
+|-----------------------|----------------|
+| `pre-commit-hooks`    | Basic hygiene. Line endings, trailing whitespace, final newline, merge-conflict markers, case-conflicting paths, Windows-illegal names, files over 1024 KB. |
+| `ruff-format`         | Python scripts (`*.py`). |
+| `clang-format`        | Every tracked C++ source file (`*.h`, `*.cpp`, `*.ixx`) and the `## Example` cpp blocks inside any Markdown file. |
+| `gersemi`             | CMake build files (`CMakeLists.txt` and `*.cmake`) outside `subprojects/`. |
+| `meson-format`        | Meson build files (`meson.build`, `meson.options`, `meson_options.txt`). |
+| `buildifier`          | Bazel build files (`BUILD.bazel`, `MODULE.bazel`, `WORKSPACE.bazel`, `*.bzl`). |
+| `actionlint`          | GitHub Actions workflows (`.github/workflows/*.yml`). |
+
+These hooks run both locally and in CI. On top of them, CI also builds the docs with `mkdocs build --strict` to confirm `docs/` builds cleanly.
+
+The `clang-format` hook is backed by [`tools/format_cpp.py`](tools/format_cpp.py), which you can also run directly.
+
+```sh
+python3 tools/format_cpp.py             # apply fixes in place
+python3 tools/format_cpp.py --check     # exits non-zero if any file would change
+```
+
+## Running lint locally
+
+Install [`pre-commit`](https://pre-commit.com/), then run `pre-commit install` so the hooks run on every `git commit`. The framework manages each formatter at its pinned version for you. See the [pre-commit docs](https://pre-commit.com/) for everyday usage such as running a single hook or all files.
+
+## Upgrading a formatter
+
+All versions are pinned in [`.pre-commit-config.yaml`](.pre-commit-config.yaml), which is the only file you change to upgrade a formatter:
+
+- For most hooks, bump the `rev:` field.
+- For local hooks, bump the version pin in `additional_dependencies:` (for example `meson==X.Y.Z` or `clang-format==X.Y.Z`).
+
+CI reinstalls from the new pin on the next run.

CONTRIBUTING.md

@@ -11,29 +11,36 @@
 from pathlib import Path
 from typing import Optional
 
+_EXAMPLE_PATTERN = re.compile(
+    r"(?P<prefix>## Example\r?\n\r?\n```cpp\r?\n)"
+    r"(?P<code>.*?)"
+    r"(?P<suffix>\r?\n```)",
+    re.DOTALL,
+)
 
-def try_extract_example_code(md_path: Path) -> Optional[str]:
-    """Return the generated C++ source for *md_path*, or None if it has no example."""
-    example_pattern = re.compile(
-        r"## Example\r?\n\r?\n```cpp\r?\n(.*?)\r?\n```", re.DOTALL
-    )
-    with open(md_path, "r", encoding="utf-8") as f:
-        content = f.read()
 
-    blocks: list[str] = re.findall(example_pattern, content)
-    if len(blocks) == 0:
-        return None
-    if len(blocks) > 1:
-        raise ValueError(f"'{md_path}' has more than one '## Example' C++ block.")
+def try_extract_example_code(content: str) -> Optional["re.Match[str]"]:
+    """Return the sole ## Example cpp block match in *content*, or None.
 
-    code = blocks[0]
-    return f"// This file was auto-generated from:\n// {md_path}\n\n{code}"
+    Raises ValueError if more than one such block exists.
+    """
+    matches = list(_EXAMPLE_PATTERN.finditer(content))
+    if len(matches) > 1:
+        raise ValueError("more than one '## Example' C++ block")
+    return matches[0] if matches else None
 
 
 if __name__ == "__main__":
     if len(sys.argv) != 3:
         print(f"Usage: {sys.argv[0]} INPUT.md OUTPUT.cpp", file=sys.stderr)
         sys.exit(1)
-    code = try_extract_example_code(Path(sys.argv[1]))
-    if code is not None:
+    md_path = Path(sys.argv[1])
+    try:
+        m = try_extract_example_code(md_path.read_text(encoding="utf-8"))
+    except ValueError as e:
+        raise ValueError(f"'{md_path}': {e}") from None
+    if m is not None:
+        code = (
+            f"// This file was auto-generated from:\n// {md_path}\n\n{m.group('code')}"
+        )
         Path(sys.argv[2]).write_text(code, encoding="utf-8")