Add some pre-commit hooks

.gitattributes

@@ -1 +1 @@
-* text=auto
+* text=auto eol=lf

.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/pipeline-ci.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-pages.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

.pre-commit-config.yaml

@@ -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)$'

CMakeLists.txt

@@ -24,24 +24,29 @@ if(PROJECT_IS_TOP_LEVEL)
   )
 endif()
 
-target_sources(msft_proxy4
+target_sources(
+  msft_proxy4
   INTERFACE
     FILE_SET public_headers
-    TYPE HEADERS 
-    BASE_DIRS include
-    FILES
-      include/proxy/proxy.h
-      include/proxy/proxy_macros.h
-      include/proxy/proxy_fmt.h
-      include/proxy/v4/proxy.ixx
-      include/proxy/v4/proxy.h
-      include/proxy/v4/proxy_macros.h
-      include/proxy/v4/proxy_fmt.h
+      TYPE HEADERS
+      BASE_DIRS include
+      FILES
+        include/proxy/proxy.h
+        include/proxy/proxy_macros.h
+        include/proxy/proxy_fmt.h
+        include/proxy/v4/proxy.ixx
+        include/proxy/v4/proxy.h
+        include/proxy/v4/proxy_macros.h
+        include/proxy/v4/proxy_fmt.h
 )
 
 target_compile_features(msft_proxy4 INTERFACE cxx_std_20)
-target_include_directories(msft_proxy4 INTERFACE $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
-                                                $<INSTALL_INTERFACE:include>)
+target_include_directories(
+  msft_proxy4
+  INTERFACE
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+    $<INSTALL_INTERFACE:include>
+)
 
 # Do not set the module target if proxy is consumed as a subdirectory.
 if(PROJECT_IS_TOP_LEVEL)
@@ -58,9 +63,10 @@ endif()
 
 include(GNUInstallDirs)
 
-install(TARGETS msft_proxy4
-        EXPORT msft_proxy4Targets
-        FILE_SET public_headers DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+install(
+  TARGETS msft_proxy4
+  EXPORT msft_proxy4Targets
+  FILE_SET public_headers DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
 )
 
 install(
@@ -83,19 +89,21 @@ configure_package_config_file(
 )
 
 include(CMakePackageConfigHelpers)
-write_basic_package_version_file(cmake/msft_proxy4ConfigVersion.cmake
-                                 COMPATIBILITY SameMajorVersion
-                                 ARCH_INDEPENDENT)
+write_basic_package_version_file(
+  cmake/msft_proxy4ConfigVersion.cmake
+  COMPATIBILITY SameMajorVersion
+  ARCH_INDEPENDENT
+)
 
 install(
-  FILES 
+  FILES
     ${CMAKE_CURRENT_BINARY_DIR}/cmake/msft_proxy4Config.cmake
     ${CMAKE_CURRENT_BINARY_DIR}/cmake/msft_proxy4ConfigVersion.cmake
   DESTINATION ${CMAKE_INSTALL_DATADIR}/msft_proxy4
 )
 
 # build tests if BUILD_TESTING is ON
-if (BUILD_TESTING)
+if(BUILD_TESTING)
   include(CTest)
 
   include(FetchContent)
@@ -108,7 +116,8 @@ if (BUILD_TESTING)
   FetchContent_Declare(
     fmt
     URL https://github.com/fmtlib/fmt/archive/refs/tags/12.1.0.tar.gz
-    URL_HASH SHA256=ea7de4299689e12b6dddd392f9896f08fb0777ac7168897a244a6d6085043fea
+    URL_HASH
+      SHA256=ea7de4299689e12b6dddd392f9896f08fb0777ac7168897a244a6d6085043fea
     SYSTEM
   )
   FetchContent_MakeAvailable(fmt)
@@ -117,7 +126,13 @@ if (BUILD_TESTING)
     set(PROXY_BUILD_FLAGS /utf-8 /W4)
     set(PROXY_STRICT_WARNING_FLAGS ${PROXY_BUILD_FLAGS} /WX)
   else()
-    set(PROXY_BUILD_FLAGS -Wall -Wextra -Wpedantic $<$<CXX_COMPILER_ID:Clang>:-Wno-c++2b-extensions>)
+    set(
+      PROXY_BUILD_FLAGS
+      -Wall
+      -Wextra
+      -Wpedantic
+      $<$<CXX_COMPILER_ID:Clang>:-Wno-c++2b-extensions>
+    )
     set(PROXY_STRICT_WARNING_FLAGS ${PROXY_BUILD_FLAGS} -Werror)
   endif()
 

CONTRIBUTING.md

@@ -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.

MODULE.bazel

@@ -6,13 +6,17 @@ module(
 bazel_dep(name = "platforms", version = "1.1.0")
 bazel_dep(name = "rules_cc", version = "0.2.18")
 bazel_dep(name = "bazel_skylib", version = "1.8.2")
+
 bazel_dep(name = "googletest", version = "1.17.0.bcr.2", dev_dependency = True)
 bazel_dep(name = "google_benchmark", version = "1.9.5", dev_dependency = True)
 bazel_dep(name = "fmt", version = "12.1.0", dev_dependency = True)
 bazel_dep(name = "rules_python", version = "2.0.2", dev_dependency = True)
 
 python = use_extension("@rules_python//python/extensions:python.bzl", "python", dev_dependency = True)
-python.toolchain(python_version = "3.12", is_default = True)
+python.toolchain(
+    is_default = True,
+    python_version = "3.12",
+)
 use_repo(python, bootstrap_python = "python_3_12_host")
 
 use_repo_rule("//tools:doc_examples.bzl", "doc_examples")(name = "doc_examples")