Clarify folding pipeline and options handling

## Summary

- **`[[rules]]`**: TOML array-of-tables config for per-file compilation
flag rules with glob pattern matching (`append`/`remove`). Patterns are
pre-compiled at config load time. Rules whose patterns all fail to
compile are dropped entirely (no silent no-op entries), and rules now
apply uniformly to every compilation — including the header-context
fallback path used when editing a header without its own CDB entry.
- **CDB auto-scan**: Default search scans workspace root + all immediate
subdirectories for `compile_commands.json`, replacing the hardcoded
directory list.
- **LSP `initializationOptions`**: Clients can pass config as JSON via
the LSP initialize request; priority is `initializationOptions >
clice.toml > defaults`.
- **XDG cache paths**: Default cache/index/logging paths prefer
`$XDG_CACHE_HOME/clice/<workspace-hash>/`; fall back to
`$HOME/.cache/clice/<hash>/`, then `<workspace>/.clice/`.
- **`${workspace}` substitution**: supported in `cache_dir`,
`index_dir`, `logging_dir`, and every `compile_commands_paths` entry.
No-op when `workspace_root` is empty.
- **Partial config support**: All TOML/JSON fields are optional via
`kota::meta::defaulted<T>`, so minimal config files work correctly.
- **Detailed diagnostics**: malformed `clice.toml` now logs line, column
and parser description (via toml++ direct parse); a malformed workspace
config surfaces a clear fallback warning instead of silently reverting
to defaults.

## Test plan

- [x] 28 unit tests for config (full suite 545 unit tests pass, Debug)
- [x] 119 integration tests pass
- [x] 2 smoke tests pass

🤖 Generated with [Claude Code](https://claude.com/claude-code)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* XDG-based, workspace-scoped project cache (PCH/PCM and header caches
moved under project cache) with workspace fallback
* Initialization options JSON can override config (takes precedence over
file/defaults)
* Per-file pattern rules to append/remove compile flags; expanded
discovery of compilation databases (multiple paths)

* **Refactor**
* Configuration fields reorganized under a project scope; runtime
behavior now respects project-scoped values

* **Tests**
* New unit and integration tests for config parsing, rule matching, and
persistent cache behavior

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

.github/actions/setup-pixi/action.yml

@@ -13,7 +13,7 @@ runs:
     - name: Setup Pixi
       uses: prefix-dev/setup-pixi@v0.9.3
       with:
-        pixi-version: v0.62.0
+        pixi-version: v0.67.0
         environments: ${{ inputs.environments }}
         activate-environment: true
         cache: true

.github/workflows/benchmark.yml

@@ -21,7 +21,7 @@ jobs:
 
       - name: Build scan_benchmark
         run: |
-          pixi run cmake-config RelWithDebInfo ON "-DCLICE_ENABLE_BENCHMARK=ON"
+          pixi run cmake-config RelWithDebInfo ON -- -DCLICE_ENABLE_BENCHMARK=ON
           cmake --build build/RelWithDebInfo --target scan_benchmark
 
       - name: Clone LLVM

.github/workflows/build-llvm.yml

@@ -1,6 +1,22 @@
 name: build llvm
 
 on:
+  workflow_dispatch:
+    inputs:
+      llvm_version:
+        description: "LLVM version to build (e.g., 21.1.8)"
+        required: true
+        type: string
+      skip_upload:
+        description: "Skip upload and PR creation (build-only mode)"
+        required: false
+        type: boolean
+        default: false
+      skip_pr:
+        description: "Skip PR creation (upload only, no PR)"
+        required: false
+        type: boolean
+        default: false
   pull_request:
     # if you want to run this workflow, change the branch name to main,
     # if you want to turn off it, change it to non existent branch.
@@ -12,9 +28,7 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - os: windows-2025
-            llvm_mode: Debug
-            lto: OFF
+          # Native builds
           - os: windows-2025
             llvm_mode: RelWithDebInfo
             lto: OFF
@@ -39,6 +53,42 @@ jobs:
           - os: macos-15
             llvm_mode: RelWithDebInfo
             lto: ON
+
+          # Cross-compilation builds
+          # macOS x64 (from arm64 macos-15)
+          - os: macos-15
+            llvm_mode: RelWithDebInfo
+            lto: OFF
+            target_triple: x86_64-apple-darwin
+          - os: macos-15
+            llvm_mode: RelWithDebInfo
+            lto: ON
+            target_triple: x86_64-apple-darwin
+
+          # Linux aarch64 (from x64 ubuntu-24.04)
+          - os: ubuntu-24.04
+            llvm_mode: RelWithDebInfo
+            lto: OFF
+            target_triple: aarch64-linux-gnu
+            pixi_env: cross-linux-aarch64
+          - os: ubuntu-24.04
+            llvm_mode: RelWithDebInfo
+            lto: ON
+            target_triple: aarch64-linux-gnu
+            pixi_env: cross-linux-aarch64
+
+          # Windows arm64 (from x64 windows-2025)
+          - os: windows-2025
+            llvm_mode: RelWithDebInfo
+            lto: OFF
+            target_triple: aarch64-pc-windows-msvc
+            pixi_env: cross-windows-arm64
+          - os: windows-2025
+            llvm_mode: RelWithDebInfo
+            lto: ON
+            target_triple: aarch64-pc-windows-msvc
+            pixi_env: cross-windows-arm64
+
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout repository
@@ -67,49 +117,91 @@ jobs:
           free -h
           df -h
 
-      - name: Setup Pixi
-        uses: prefix-dev/setup-pixi@v0.9.3
+      - uses: ./.github/actions/setup-pixi
         with:
-          pixi-version: v0.59.0
-          environments: package
-          activate-environment: true
-          cache: true
-          locked: true
+          environments: ${{ matrix.pixi_env || 'package' }}
 
-      - name: Clone llvm-project (21.1.4)
+      - name: Clone llvm-project
         shell: bash
         run: |
-          git clone --branch llvmorg-21.1.4 --depth 1 https://github.com/llvm/llvm-project.git .llvm
+          VERSION="${{ inputs.llvm_version || '21.1.8' }}"
+          echo "Cloning LLVM ${VERSION}..."
+          git clone --branch "llvmorg-${VERSION}" --depth 1 https://github.com/llvm/llvm-project.git .llvm
+
+      - name: Validate distribution components
+        shell: bash
+        run: |
+          python3 scripts/validate-llvm-components.py \
+            --llvm-src=.llvm \
+            --components-file=scripts/llvm-components.json
 
       - name: Build LLVM (install-distribution)
         shell: bash
         run: |
-          pixi run build-llvm --llvm-src=.llvm --mode="${{ matrix.llvm_mode }}" --lto="${{ matrix.lto }}" --build-dir=build
+          ENV="${{ matrix.pixi_env || 'package' }}"
+          EXTRA_ARGS=""
+          if [[ -n "${{ matrix.target_triple }}" ]]; then
+            EXTRA_ARGS="--target-triple=${{ matrix.target_triple }}"
+          fi
+          pixi run -e "$ENV" build-llvm \
+            --llvm-src=.llvm \
+            --mode="${{ matrix.llvm_mode }}" \
+            --lto="${{ matrix.lto }}" \
+            --build-dir=build \
+            ${EXTRA_ARGS}
 
       - name: Build clice using installed LLVM
+        if: ${{ !matrix.target_triple }}
         shell: bash
         run: |
-          cmake -B build -G Ninja \
-            -DCMAKE_BUILD_TYPE=${{ matrix.llvm_mode }} \
-            -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain.cmake \
-            -DCLICE_ENABLE_TEST=ON \
-            -DCLICE_CI_ENVIRONMENT=ON \
-            -DCLICE_ENABLE_LTO=${{ matrix.lto }} \
-            -DLLVM_INSTALL_PATH=".llvm/build-install"
-          cmake --build build
+          pixi run cmake-config ${{ matrix.llvm_mode }} ON -- \
+            "-DCLICE_ENABLE_LTO=${{ matrix.lto }}" \
+            "-DLLVM_INSTALL_PATH=.llvm/build-install"
+          pixi run cmake-build ${{ matrix.llvm_mode }}
+
+      - name: Build clice using installed LLVM (cross-compile)
+        if: ${{ matrix.target_triple }}
+        shell: bash
+        run: |
+          ENV="${{ matrix.pixi_env || 'package' }}"
+          pixi run -e "$ENV" cmake-config ${{ matrix.llvm_mode }} ON -- \
+            "-DCLICE_ENABLE_LTO=${{ matrix.lto }}" \
+            "-DCLICE_TARGET_TRIPLE=${{ matrix.target_triple }}" \
+            "-DLLVM_INSTALL_PATH=.llvm/build-install"
+          pixi run -e "$ENV" cmake-build ${{ matrix.llvm_mode }}
+
+      - name: Verify cross-compiled binary architecture
+        if: ${{ matrix.target_triple && runner.os != 'Windows' }}
+        shell: bash
+        run: |
+          BINARY="build/${{ matrix.llvm_mode }}/bin/clice"
+          echo "Binary info:"
+          file "$BINARY"
+          case "${{ matrix.target_triple }}" in
+            aarch64-linux-gnu)   file "$BINARY" | grep -q "aarch64" ;;
+            x86_64-apple-darwin) file "$BINARY" | grep -q "x86_64" ;;
+          esac
+
+      - name: Upload cross-compiled clice for functional test
+        if: ${{ matrix.target_triple && matrix.lto == 'OFF' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: cross-clice-${{ matrix.target_triple }}-${{ matrix.llvm_mode }}
+          path: |
+            build/${{ matrix.llvm_mode }}/bin/
+            build/${{ matrix.llvm_mode }}/lib/
+          if-no-files-found: error
+          retention-days: 1
 
       - name: Run tests
+        if: ${{ !matrix.target_triple }}
         shell: bash
-        run: |
-          EXE_EXT=""
-          if [[ "${{ runner.os }}" == "Windows" ]]; then
-            EXE_EXT=".exe"
-          fi
-          ./build/bin/unit_tests${EXE_EXT} --test-dir="./tests/data"
-          uv run --project tests pytest -s --log-cli-level=INFO tests/integration --executable=./build/bin/clice${EXE_EXT}
+        run: pixi run test ${{ matrix.llvm_mode }}
 
+      # Prune is only supported for native builds (requires linking clice to test).
+      # Cross-compiled targets reuse the native prune manifest of the same OS.
       - name: Prune LLVM static libraries (Debug/RelWithDebInfo no LTO)
-        if: matrix.llvm_mode == 'Debug' || (matrix.llvm_mode == 'RelWithDebInfo' && matrix.lto == 'OFF')
+        if: (!matrix.target_triple) && (matrix.llvm_mode == 'Debug' || (matrix.llvm_mode == 'RelWithDebInfo' && matrix.lto == 'OFF'))
         shell: bash
         run: |
           MANIFEST="pruned-libs-${{ matrix.os }}.json"
@@ -117,13 +209,13 @@ jobs:
           python3 scripts/prune-llvm-bin.py \
             --action discover \
             --install-dir ".llvm/build-install/lib" \
-            --build-dir "build" \
+            --build-dir "build/${{ matrix.llvm_mode }}" \
             --max-attempts 60 \
             --sleep-seconds 60 \
             --manifest "${MANIFEST}"
 
       - name: Upload pruned-libs manifest
-        if: matrix.llvm_mode == 'RelWithDebInfo' && matrix.lto == 'OFF'
+        if: (!matrix.target_triple) && matrix.llvm_mode == 'RelWithDebInfo' && matrix.lto == 'OFF'
         uses: actions/upload-artifact@v4
         with:
           name: llvm-pruned-libs-${{ matrix.os }}
@@ -131,8 +223,8 @@ jobs:
           if-no-files-found: error
           compression-level: 0
 
-      - name: Apply pruned-libs manifest (RelWithDebInfo + LTO)
-        if: matrix.llvm_mode == 'RelWithDebInfo' && matrix.lto == 'ON'
+      - name: Apply pruned-libs manifest (RelWithDebInfo + LTO, native only)
+        if: (!matrix.target_triple) && matrix.llvm_mode == 'RelWithDebInfo' && matrix.lto == 'ON'
         shell: bash
         env:
           GH_TOKEN: ${{ github.token }}
@@ -142,7 +234,27 @@ jobs:
             --action apply \
             --manifest "${MANIFEST}" \
             --install-dir ".llvm/build-install/lib" \
-            --build-dir "build" \
+            --build-dir "build/${{ matrix.llvm_mode }}" \
+            --gh-run-id "${{ github.run_id }}" \
+            --gh-artifact "llvm-pruned-libs-${{ matrix.os }}" \
+            --gh-download-dir "artifacts" \
+            --max-attempts 60 \
+            --sleep-seconds 60
+
+      # For cross-compiled LTO builds, apply the native prune manifest.
+      # The unused library set is arch-independent (same API surface).
+      - name: Apply pruned-libs manifest (cross-compile + LTO)
+        if: matrix.target_triple && matrix.lto == 'ON'
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          MANIFEST="pruned-libs-${{ matrix.os }}.json"
+          python3 scripts/prune-llvm-bin.py \
+            --action apply \
+            --manifest "${MANIFEST}" \
+            --install-dir ".llvm/build-install/lib" \
+            --build-dir "build/${{ matrix.llvm_mode }}" \
             --gh-run-id "${{ github.run_id }}" \
             --gh-artifact "llvm-pruned-libs-${{ matrix.os }}" \
             --gh-download-dir "artifacts" \
@@ -157,23 +269,35 @@ jobs:
             MODE_TAG="debug"
           fi
 
-          ARCH="x64"
-          PLATFORM="linux"
-          TOOLCHAIN="gnu"
-          if [[ "${{ matrix.os }}" == windows-* ]]; then
-            PLATFORM="windows"
-            TOOLCHAIN="msvc"
-          elif [[ "${{ matrix.os }}" == macos-* ]]; then
-            ARCH="arm64"
-            PLATFORM="macos"
-            TOOLCHAIN="clang"
+          # Determine arch/platform/toolchain from target triple or runner OS
+          if [[ -n "${{ matrix.target_triple }}" ]]; then
+            case "${{ matrix.target_triple }}" in
+              x86_64-apple-darwin)
+                ARCH="x64"; PLATFORM="macos"; TOOLCHAIN="clang" ;;
+              aarch64-linux-gnu)
+                ARCH="aarch64"; PLATFORM="linux"; TOOLCHAIN="gnu" ;;
+              aarch64-pc-windows-msvc)
+                ARCH="aarch64"; PLATFORM="windows"; TOOLCHAIN="msvc" ;;
+            esac
+          else
+            ARCH="x64"
+            PLATFORM="linux"
+            TOOLCHAIN="gnu"
+            if [[ "${{ matrix.os }}" == windows-* ]]; then
+              PLATFORM="windows"
+              TOOLCHAIN="msvc"
+            elif [[ "${{ matrix.os }}" == macos-* ]]; then
+              ARCH="arm64"
+              PLATFORM="macos"
+              TOOLCHAIN="clang"
+            fi
           fi
 
           SUFFIX=""
           if [[ "${{ matrix.lto }}" == "ON" ]]; then
             SUFFIX="-lto"
           fi
-          if [[ "${{ matrix.llvm_mode }}" == "Debug" ]]; then
+          if [[ "${{ matrix.llvm_mode }}" == "Debug" && "${{ matrix.os }}" != windows-* ]]; then
             SUFFIX="${SUFFIX}-asan"
           fi
 
@@ -189,3 +313,134 @@ jobs:
           name: ${{ env.LLVM_INSTALL_ARCHIVE }}
           path: ${{ env.LLVM_INSTALL_ARCHIVE }}
           if-no-files-found: error
+
+  test-cross:
+    needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-15-intel
+            llvm_mode: RelWithDebInfo
+            target_triple: x86_64-apple-darwin
+          - os: ubuntu-24.04-arm
+            llvm_mode: RelWithDebInfo
+            target_triple: aarch64-linux-gnu
+          - os: windows-11-arm
+            llvm_mode: RelWithDebInfo
+            target_triple: aarch64-pc-windows-msvc
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - uses: ./.github/actions/setup-pixi
+        with:
+          environments: test-run
+
+      - name: Download cross-compiled clice
+        uses: actions/download-artifact@v4
+        with:
+          name: cross-clice-${{ matrix.target_triple }}-${{ matrix.llvm_mode }}
+          path: build/${{ matrix.llvm_mode }}/
+
+      - name: Make binaries executable
+        if: runner.os != 'Windows'
+        run: chmod +x build/${{ matrix.llvm_mode }}/bin/*
+
+      - name: Run tests
+        run: pixi run -e test-run test ${{ matrix.llvm_mode }}
+
+  upload:
+    needs: build
+    if: ${{ !cancelled() && inputs.llvm_version && !inputs.skip_upload }}
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download all build artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: scripts/download-llvm.sh "${{ github.run_id }}"
+
+      - name: Upload to clice-llvm
+        env:
+          GH_TOKEN: ${{ secrets.UPLOAD_LLVM }}
+          TARGET_REPO: clice-io/clice-llvm
+        run: python3 scripts/upload-llvm.py "${{ inputs.llvm_version }}" "${TARGET_REPO}" "${{ github.run_id }}"
+
+      - name: Save manifest for update-clice job
+        uses: actions/upload-artifact@v4
+        with:
+          name: llvm-manifest-final
+          path: artifacts/llvm-manifest.json
+          if-no-files-found: error
+          compression-level: 0
+
+  update-clice:
+    needs: upload
+    if: ${{ !inputs.skip_pr }}
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download manifest
+        uses: actions/download-artifact@v4
+        with:
+          name: llvm-manifest-final
+          path: .
+
+      - name: Update manifest and version
+        run: |
+          python3 scripts/update-llvm-version.py \
+            --version "${{ inputs.llvm_version }}" \
+            --manifest-src llvm-manifest.json \
+            --manifest-dest config/llvm-manifest.json \
+            --package-cmake cmake/package.cmake
+
+      - name: Create or update PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          VERSION="${{ inputs.llvm_version }}"
+          BRANCH="chore/update-llvm-${VERSION}"
+          RUN_URL="https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          RELEASE_URL="https://github.com/clice-io/clice-llvm/releases/tag/${VERSION}"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b "${BRANCH}"
+          git add config/llvm-manifest.json cmake/package.cmake
+          git commit -m "chore: update LLVM to ${VERSION}"
+          git push --force-with-lease origin "${BRANCH}"
+
+          # Check if PR already exists for this branch
+          EXISTING_PR=$(gh pr list --head "${BRANCH}" --json number --jq '.[0].number // empty')
+
+          BODY="$(cat <<EOF
+          ## Summary
+          - Update LLVM prebuilt binaries to version ${VERSION}
+          - Updated \`config/llvm-manifest.json\` with new SHA256 hashes
+          - Updated \`cmake/package.cmake\` version string
+
+          **Artifacts:** [clice-llvm release](${RELEASE_URL})
+          **Build:** [workflow run](${RUN_URL})
+
+          > Auto-generated by build-llvm workflow
+          EOF
+          )"
+
+          if [[ -n "${EXISTING_PR}" ]]; then
+            echo "Updating existing PR #${EXISTING_PR}"
+            gh pr edit "${EXISTING_PR}" --body "${BODY}"
+          else
+            gh pr create \
+              --title "chore: update LLVM to ${VERSION}" \
+              --body "${BODY}" \
+              --base main
+          fi

.github/workflows/check-format.yml

@@ -14,6 +14,12 @@ jobs:
         with:
           environments: format
 
+      - name: Validate update-llvm-version.py can still patch package.cmake
+        run: |
+          python3 scripts/update-llvm-version.py --check \
+            --manifest-dest config/llvm-manifest.json \
+            --package-cmake cmake/package.cmake
+
       - name: Run formatter
         run: pixi run format
         continue-on-error: true

.github/workflows/publish-clice.yml

@@ -9,6 +9,7 @@ jobs:
       fail-fast: false
       matrix:
         include:
+          # Native builds
           - os: windows-2025
             artifact_name: clice.zip
             asset_name: clice-x64-windows-msvc.zip
@@ -27,6 +28,31 @@ jobs:
             symbol_artifact_name: clice-symbol.tar.gz
             symbol_asset_name: clice-arm64-macos-darwin-symbol.tar.gz
 
+          # Cross-compilation builds
+          - os: macos-15
+            target_triple: x86_64-apple-darwin
+            pixi_env: cross-macos-x64
+            artifact_name: clice.tar.gz
+            asset_name: clice-x86_64-macos-darwin.tar.gz
+            symbol_artifact_name: clice-symbol.tar.gz
+            symbol_asset_name: clice-x86_64-macos-darwin-symbol.tar.gz
+
+          - os: ubuntu-24.04
+            target_triple: aarch64-linux-gnu
+            pixi_env: cross-linux-aarch64
+            artifact_name: clice.tar.gz
+            asset_name: clice-aarch64-linux-gnu.tar.gz
+            symbol_artifact_name: clice-symbol.tar.gz
+            symbol_asset_name: clice-aarch64-linux-gnu-symbol.tar.gz
+
+          - os: windows-2025
+            target_triple: aarch64-pc-windows-msvc
+            pixi_env: cross-windows-arm64
+            artifact_name: clice.zip
+            asset_name: clice-aarch64-windows-msvc.zip
+            symbol_artifact_name: clice-symbol.zip
+            symbol_asset_name: clice-aarch64-windows-msvc-symbol.zip
+
     runs-on: ${{ matrix.os }}
 
     defaults:
@@ -39,11 +65,20 @@ jobs:
 
       - uses: ./.github/actions/setup-pixi
         with:
-          environments: package
+          environments: ${{ matrix.pixi_env || 'package' }}
 
-      - name: Package
+      - name: Package (native)
+        if: ${{ !matrix.target_triple }}
         run: pixi run package
 
+      - name: Package (cross-compile)
+        if: ${{ matrix.target_triple }}
+        run: |
+          ENV="${{ matrix.pixi_env }}"
+          pixi run -e "$ENV" package-config -- \
+            "-DCLICE_TARGET_TRIPLE=${{ matrix.target_triple }}"
+          pixi run -e "$ENV" cmake-build
+
       - name: Upload Main Package to Release
         if: startsWith(github.ref, 'refs/tags/v')
         uses: svenstaro/upload-release-action@v2

.github/workflows/test-cmake.yml

@@ -17,53 +17,134 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [windows-2025, ubuntu-24.04, macos-15]
-        build_type: [Debug, RelWithDebInfo]
+        include:
+          # Native builds
+          - os: windows-2025
+            build_type: RelWithDebInfo
+          - os: ubuntu-24.04
+            build_type: Debug
+          - os: ubuntu-24.04
+            build_type: RelWithDebInfo
+          - os: macos-15
+            build_type: Debug
+          - os: macos-15
+            build_type: RelWithDebInfo
+          # Cross-compile (build only; tests run on native runners)
+          - os: macos-15
+            build_type: RelWithDebInfo
+            target_triple: x86_64-apple-darwin
+            build_only: true
+          - os: ubuntu-24.04
+            build_type: RelWithDebInfo
+            target_triple: aarch64-linux-gnu
+            build_only: true
+            pixi_env: cross-linux-aarch64
+          - os: windows-2025
+            build_type: RelWithDebInfo
+            target_triple: aarch64-pc-windows-msvc
+            build_only: true
+            pixi_env: cross-windows-arm64
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
       - uses: ./.github/actions/setup-pixi
+        with:
+          environments: ${{ matrix.pixi_env || 'default' }}
 
       - name: Restore compiler cache
         uses: actions/cache@v4
         with:
           path: ${{ runner.os == 'Windows' && '.cache/sccache' || '.cache/ccache' }}
-          key: ${{ runner.os }}-${{ matrix.build_type }}-ccache-${{ github.sha }}
+          key: ${{ runner.os }}-${{ matrix.build_type }}-${{ matrix.target_triple || 'native' }}-ccache-${{ github.sha }}
           restore-keys: |
-            ${{ runner.os }}-${{ matrix.build_type }}-ccache-
+            ${{ runner.os }}-${{ matrix.build_type }}-${{ matrix.target_triple || 'native' }}-ccache-
 
       - name: Zero cache stats
         run: |
+          ENV="${{ matrix.pixi_env || 'default' }}"
           if [ "$RUNNER_OS" = "Windows" ]; then
-            pixi run -- sccache --stop-server || true
-            pixi run -- sccache --zero-stats || true
+            pixi run -e "$ENV" -- sccache --stop-server || true
+            pixi run -e "$ENV" -- sccache --zero-stats || true
           else
-            pixi run -- ccache --zero-stats || true
+            pixi run -e "$ENV" -- ccache --zero-stats || true
           fi
         shell: bash
 
-      - name: Build
+      - name: Build (native)
+        if: ${{ !matrix.target_triple }}
         run: pixi run build ${{ matrix.build_type }} ON
 
-      - name: Unit Test
-        run: pixi run unit-test ${{ matrix.build_type }}
+      - name: Build (cross-compile)
+        if: ${{ matrix.target_triple }}
+        shell: bash
+        run: |
+          ENV="${{ matrix.pixi_env || 'default' }}"
+          pixi run -e "$ENV" cmake-config ${{ matrix.build_type }} OFF -- \
+            "-DCLICE_TARGET_TRIPLE=${{ matrix.target_triple }}"
+          pixi run -e "$ENV" cmake-build ${{ matrix.build_type }}
 
-      - name: Integration Test
-        run: pixi run integration-test ${{ matrix.build_type }}
+      - name: Upload cross-compiled binaries
+        if: ${{ matrix.build_only }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: cross-build-${{ matrix.target_triple }}
+          path: |
+            build/${{ matrix.build_type }}/bin/
+            build/${{ matrix.build_type }}/lib/
+          if-no-files-found: error
+          retention-days: 1
 
-      - name: Smoke Test
-        if: success() || failure()
-        run: pixi run smoke-test ${{ matrix.build_type }}
+      - name: Run tests
+        if: ${{ !matrix.build_only }}
+        run: pixi run test ${{ matrix.build_type }}
 
       - name: Print cache stats and stop server
         if: always()
         run: |
+          ENV="${{ matrix.pixi_env || 'default' }}"
           if [ "$RUNNER_OS" = "Windows" ]; then
-            pixi run -- sccache --show-stats
-            pixi run -- sccache --stop-server || true
+            pixi run -e "$ENV" -- sccache --show-stats
+            pixi run -e "$ENV" -- sccache --stop-server || true
           else
-            pixi run -- ccache --show-stats
+            pixi run -e "$ENV" -- ccache --show-stats
           fi
         shell: bash
+
+  test-cross:
+    needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-15-intel
+            build_type: RelWithDebInfo
+            target_triple: x86_64-apple-darwin
+          - os: ubuntu-24.04-arm
+            build_type: RelWithDebInfo
+            target_triple: aarch64-linux-gnu
+          - os: windows-11-arm
+            build_type: RelWithDebInfo
+            target_triple: aarch64-pc-windows-msvc
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - uses: ./.github/actions/setup-pixi
+        with:
+          environments: test-run
+
+      - name: Download cross-compiled binaries
+        uses: actions/download-artifact@v4
+        with:
+          name: cross-build-${{ matrix.target_triple }}
+          path: build/${{ matrix.build_type }}/
+
+      - name: Make binaries executable
+        if: runner.os != 'Windows'
+        run: chmod +x build/${{ matrix.build_type }}/bin/*
+
+      - name: Run tests
+        run: pixi run -e test-run test ${{ matrix.build_type }}

.gitignore

@@ -72,4 +72,3 @@ tests/unit/Local/
 .claude/*
 !.claude/CLAUDE.md
 !.claude/commands/
-openspec/

CMakeLists.txt

@@ -127,9 +127,16 @@ endif()
 set(FBS_SCHEMA_FILE "${PROJECT_SOURCE_DIR}/src/index/schema.fbs")
 set(GENERATED_HEADER "${PROJECT_BINARY_DIR}/generated/schema_generated.h")
 
+if(CMAKE_CROSSCOMPILING)
+    find_program(FLATC_EXECUTABLE flatc REQUIRED)
+    set(FLATC_CMD "${FLATC_EXECUTABLE}")
+else()
+    set(FLATC_CMD "$<TARGET_FILE:flatc>")
+endif()
+
 add_custom_command(
     OUTPUT "${GENERATED_HEADER}"
-    COMMAND $<TARGET_FILE:flatc> --cpp -o "${PROJECT_BINARY_DIR}/generated" "${FBS_SCHEMA_FILE}"
+    COMMAND ${FLATC_CMD} --cpp -o "${PROJECT_BINARY_DIR}/generated" "${FBS_SCHEMA_FILE}"
     DEPENDS "${FBS_SCHEMA_FILE}"
     COMMENT "Generating C++ header from ${FBS_SCHEMA_FILE}"
 )
@@ -200,14 +207,6 @@ if(CLICE_ENABLE_BENCHMARK)
         "${PROJECT_SOURCE_DIR}/src"
     )
     target_link_libraries(scan_benchmark PRIVATE clice::core kota::deco)
-
-    add_executable(pch_chain_benchmark
-        "${PROJECT_SOURCE_DIR}/benchmarks/pch_chain/pch_chain_benchmark.cpp"
-    )
-    target_include_directories(pch_chain_benchmark PRIVATE
-        "${PROJECT_SOURCE_DIR}/src"
-    )
-    target_link_libraries(pch_chain_benchmark PRIVATE clice::core)
 endif()
 
 if(CLICE_RELEASE)

cmake/llvm.cmake

@@ -25,6 +25,22 @@ function(setup_llvm LLVM_VERSION)
         list(APPEND LLVM_SETUP_ARGS "--offline")
     endif()
 
+    if(DEFINED CLICE_TARGET_TRIPLE)
+        if(CLICE_TARGET_TRIPLE MATCHES "linux")
+            list(APPEND LLVM_SETUP_ARGS "--target-platform" "Linux")
+        elseif(CLICE_TARGET_TRIPLE MATCHES "darwin")
+            list(APPEND LLVM_SETUP_ARGS "--target-platform" "macosx")
+        elseif(CLICE_TARGET_TRIPLE MATCHES "windows")
+            list(APPEND LLVM_SETUP_ARGS "--target-platform" "Windows")
+        endif()
+
+        if(CLICE_TARGET_TRIPLE MATCHES "^aarch64")
+            list(APPEND LLVM_SETUP_ARGS "--target-arch" "arm64")
+        elseif(CLICE_TARGET_TRIPLE MATCHES "^x86_64")
+            list(APPEND LLVM_SETUP_ARGS "--target-arch" "x64")
+        endif()
+    endif()
+
     execute_process(
         COMMAND "${Python3_EXECUTABLE}" "${LLVM_SETUP_SCRIPT}" ${LLVM_SETUP_ARGS}
         RESULT_VARIABLE LLVM_SETUP_RESULT

cmake/package.cmake

@@ -1,7 +1,7 @@
 include_guard()
 
 include(${CMAKE_CURRENT_LIST_DIR}/llvm.cmake)
-setup_llvm("21.1.4+r1")
+setup_llvm("21.1.8")
 
 # install dependencies
 include(FetchContent)

cmake/toolchain.cmake

@@ -1,5 +1,29 @@
 cmake_minimum_required(VERSION 3.30)
 
+# Cross-compilation support via CLICE_TARGET_TRIPLE.
+# Examples:
+#   -DCLICE_TARGET_TRIPLE=x86_64-apple-darwin      (macOS x64 from arm64)
+#   -DCLICE_TARGET_TRIPLE=aarch64-linux-gnu         (Linux arm64 from x64)
+#   -DCLICE_TARGET_TRIPLE=aarch64-pc-windows-msvc   (Windows arm64 from x64)
+if(DEFINED CLICE_TARGET_TRIPLE)
+    if(CLICE_TARGET_TRIPLE MATCHES "^x86_64-apple-darwin")
+        set(CMAKE_OSX_ARCHITECTURES "x86_64" CACHE STRING "")
+    elseif(CLICE_TARGET_TRIPLE MATCHES "^aarch64-.*linux")
+        set(CMAKE_SYSTEM_NAME Linux)
+        set(CMAKE_SYSTEM_PROCESSOR aarch64)
+        set(CMAKE_C_COMPILER_TARGET "aarch64-linux-gnu" CACHE STRING "")
+        set(CMAKE_CXX_COMPILER_TARGET "aarch64-linux-gnu" CACHE STRING "")
+        if(DEFINED ENV{CONDA_PREFIX} AND NOT DEFINED CMAKE_SYSROOT)
+            set(CMAKE_SYSROOT "$ENV{CONDA_PREFIX}/aarch64-conda-linux-gnu/sysroot" CACHE PATH "")
+        endif()
+    elseif(CLICE_TARGET_TRIPLE MATCHES "^aarch64-.*-windows")
+        set(CMAKE_SYSTEM_NAME Windows)
+        set(CMAKE_SYSTEM_PROCESSOR ARM64)
+        set(CMAKE_C_COMPILER_TARGET "aarch64-pc-windows-msvc" CACHE STRING "")
+        set(CMAKE_CXX_COMPILER_TARGET "aarch64-pc-windows-msvc" CACHE STRING "")
+    endif()
+endif()
+
 set(CMAKE_C_COMPILER clang CACHE STRING "")
 set(CMAKE_CXX_COMPILER clang++ CACHE STRING "")
 

config/llvm-manifest.json

@@ -1,83 +1,142 @@
 [
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
+    "filename": "aarch64-linux-gnu-releasedbg-lto.tar.xz",
+    "sha256": "f3444ee840b50933c23656cbee7c4d010e752ac55ca66095b97f7c0e997b13b5",
+    "lto": true,
+    "asan": false,
+    "platform": "linux",
+    "arch": "arm64",
+    "build_type": "RelWithDebInfo"
+  },
+  {
+    "version": "21.1.8",
+    "filename": "aarch64-linux-gnu-releasedbg.tar.xz",
+    "sha256": "b9012bf059e4d8673fb564b5780e5fc78c6a2e47f5cc6a39f444d1879b42dd2a",
+    "lto": false,
+    "asan": false,
+    "platform": "linux",
+    "arch": "arm64",
+    "build_type": "RelWithDebInfo"
+  },
+  {
+    "version": "21.1.8",
+    "filename": "aarch64-windows-msvc-releasedbg-lto.tar.xz",
+    "sha256": "8870d16141ba7f9ea12f5147b8d91329abbbaa4376cd4576667dd323d896dd08",
+    "lto": true,
+    "asan": false,
+    "platform": "windows",
+    "arch": "arm64",
+    "build_type": "RelWithDebInfo"
+  },
+  {
+    "version": "21.1.8",
+    "filename": "aarch64-windows-msvc-releasedbg.tar.xz",
+    "sha256": "ad394e79ec85dd40f942671bb0342ffe54a103eb2baabacb773999d57d80134b",
+    "lto": false,
+    "asan": false,
+    "platform": "windows",
+    "arch": "arm64",
+    "build_type": "RelWithDebInfo"
+  },
+  {
+    "version": "21.1.8",
     "filename": "arm64-macos-clang-debug-asan.tar.xz",
-    "sha256": "7da4b7d63edefecaf11773e7e701c575140d1a07329bbbb038673b6ee4516ff5",
+    "sha256": "b02d20e4f7294ee33f49a09dfdd765b3b44135e003ef50e3a760aeee39e3f993",
     "lto": false,
     "asan": true,
     "platform": "macosx",
+    "arch": "arm64",
     "build_type": "Debug"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
     "filename": "arm64-macos-clang-releasedbg-lto.tar.xz",
-    "sha256": "300455b169448f9f01ae95e3bc269f489558a4ca3955e3032171cc75feca0e30",
+    "sha256": "e40c21eb0d0b91d9d4ab31212a5cb01ea46707f5c29839414567857e4147604d",
     "lto": true,
     "asan": false,
     "platform": "macosx",
+    "arch": "arm64",
     "build_type": "RelWithDebInfo"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
     "filename": "arm64-macos-clang-releasedbg.tar.xz",
-    "sha256": "9abfc6cd65b957d734ffb97610a634fb4a66d3fbe0fcfb5a1c9124ef693c1495",
+    "sha256": "e1b01de34f0edfd41c118e4981a93afb35556ae369597e864f4a393db623b926",
     "lto": false,
     "asan": false,
     "platform": "macosx",
+    "arch": "arm64",
     "build_type": "RelWithDebInfo"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
     "filename": "x64-linux-gnu-debug-asan.tar.xz",
-    "sha256": "c1ad3ec476911596a842ac67dd9c9c9475ce9f0a77b81101d3c801840292e7bc",
+    "sha256": "76bb82d822b5377fb5e0fac8abcfba125142e6a0acc02bb36d1fa1532a268646",
     "lto": false,
     "asan": true,
     "platform": "linux",
+    "arch": "x64",
     "build_type": "Debug"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
     "filename": "x64-linux-gnu-releasedbg-lto.tar.xz",
-    "sha256": "8a869c2184d139dbba704e2d712e7a68336458ad2d70622b3eb906c3e3511e54",
+    "sha256": "32f5edddec1e689124f045b586fb402ae30febc05203af7391b088bc8494cd53",
     "lto": true,
     "asan": false,
     "platform": "linux",
+    "arch": "x64",
     "build_type": "RelWithDebInfo"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
     "filename": "x64-linux-gnu-releasedbg.tar.xz",
-    "sha256": "552bab86f715d4f2c027f07eaaf5b3d6b8e430af0b74b470142f3f00da4feec6",
+    "sha256": "8ba3c84f23a2a81a86c54780754a61adf99048aa2ac0dc9b9708d0f842d553de",
     "lto": false,
     "asan": false,
     "platform": "linux",
+    "arch": "x64",
     "build_type": "RelWithDebInfo"
   },
   {
-    "version": "21.1.4+r1",
-    "filename": "x64-windows-msvc-debug-asan.tar.xz",
-    "sha256": "093667a493d336c22ff3c604c5f1fea2a7d2c927c1179cec44e9a03726906ac1",
-    "lto": false,
-    "asan": true,
-    "platform": "windows",
-    "build_type": "Debug"
+    "version": "21.1.8",
+    "filename": "x64-macos-clang-releasedbg-lto.tar.xz",
+    "sha256": "97e81d6296896d7237f118f728d05291707b9e4e5791e07ce4be8aee0517505d",
+    "lto": true,
+    "asan": false,
+    "platform": "macosx",
+    "arch": "x64",
+    "build_type": "RelWithDebInfo"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
+    "filename": "x64-macos-clang-releasedbg.tar.xz",
+    "sha256": "53c13f8e1082fa2fe2f9c05303de48cb3133bf5f24271f4b3062f1dec578159c",
+    "lto": false,
+    "asan": false,
+    "platform": "macosx",
+    "arch": "x64",
+    "build_type": "RelWithDebInfo"
+  },
+  {
+    "version": "21.1.8",
     "filename": "x64-windows-msvc-releasedbg-lto.tar.xz",
-    "sha256": "010539e85621dc3c6ecf359d899feb4075aeca5d0bba6625cdbec0e570e79129",
+    "sha256": "16bcf0e4cbc3d2b1204edd619a3837004dacea28eeff0a101c8d0212f936427d",
     "lto": true,
     "asan": false,
     "platform": "windows",
+    "arch": "x64",
     "build_type": "RelWithDebInfo"
   },
   {
-    "version": "21.1.4+r1",
+    "version": "21.1.8",
     "filename": "x64-windows-msvc-releasedbg.tar.xz",
-    "sha256": "f473c09fbea10053fac00be409d75dc228d4a38bcbc5e4aeb58b56a4b0dde78e",
+    "sha256": "81d31fad05e200726c8178314b0b2045c947483dddd8cb974f4c376ae5f441fa",
     "lto": false,
     "asan": false,
     "platform": "windows",
+    "arch": "x64",
     "build_type": "RelWithDebInfo"
   }
 ]

openspec/changes/explore-improve-folding-range-support/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-22

openspec/changes/explore-improve-folding-range-support/comparison.md

@@ -0,0 +1,113 @@
+## Downloaded Upstream Reference
+
+Downloaded from GitHub tag `llvmorg-21.1.8` into `openspec/changes/explore-improve-folding-range-support/reference/clangd/llvmorg-21.1.8/` using `curl`.
+
+Files downloaded:
+
+- `clang-tools-extra/clangd/SemanticSelection.cpp`
+- `clang-tools-extra/clangd/SemanticSelection.h`
+- `clang-tools-extra/clangd/ClangdServer.cpp`
+- `clang-tools-extra/clangd/ClangdServer.h`
+- `clang-tools-extra/clangd/ClangdLSPServer.cpp`
+- `clang-tools-extra/clangd/Protocol.h`
+- `clang-tools-extra/clangd/Protocol.cpp`
+- `clang-tools-extra/clangd/test/folding-range.test`
+- `clang-tools-extra/clangd/unittests/SemanticSelectionTests.cpp`
+
+Raw GitHub URLs used:
+
+- `https://raw.githubusercontent.com/llvm/llvm-project/llvmorg-21.1.8/clang-tools-extra/clangd/SemanticSelection.cpp`
+- `https://raw.githubusercontent.com/llvm/llvm-project/llvmorg-21.1.8/clang-tools-extra/clangd/SemanticSelection.h`
+- `https://raw.githubusercontent.com/llvm/llvm-project/llvmorg-21.1.8/clang-tools-extra/clangd/ClangdServer.cpp`
+- `https://raw.githubusercontent.com/llvm/llvm-project/llvmorg-21.1.8/clang-tools-extra/clangd/ClangdServer.h`
+- `https://raw.githubusercontent.com/llvm/llvm-project/llvmorg-21.1.8/clang-tools-extra/clangd/ClangdLSPServer.cpp`
+- `https://raw.githubusercontent.com/llvm/llvm-project/llvmorg-21.1.8/clang-tools-extra/clangd/Protocol.h`
+- `https://raw.githubusercontent.com/llvm/llvm-project/llvmorg-21.1.8/clang-tools-extra/clangd/Protocol.cpp`
+- `https://raw.githubusercontent.com/llvm/llvm-project/llvmorg-21.1.8/clang-tools-extra/clangd/test/folding-range.test`
+- `https://raw.githubusercontent.com/llvm/llvm-project/llvmorg-21.1.8/clang-tools-extra/clangd/unittests/SemanticSelectionTests.cpp`
+
+## Clice Reference Files
+
+Current branch files compared against:
+
+- `src/feature/folding_ranges.cpp`
+- `src/server/master_server.cpp`
+- `tests/unit/feature/folding_range_tests.cpp`
+
+## Confirmed Comparison Findings
+
+### 1. clangd already has dedicated comment folding and line-only rendering
+
+clangd's pseudo-parser folding path in `SemanticSelection.cpp` explicitly handles:
+
+- bracket folds with line-only adjustment at `SemanticSelection.cpp:223-235`
+- multiline block and contiguous comment-group folds at `SemanticSelection.cpp:238-269`
+
+The request path wires `LineFoldingOnly` from client capabilities in:
+
+- `ClangdLSPServer.cpp:545`
+- `ClangdServer.cpp:967-980`
+
+Regression coverage exists in:
+
+- `test/folding-range.test:6-20`
+- `unittests/SemanticSelectionTests.cpp:269-455`
+
+Current clice does not have any comment collector in `src/feature/folding_ranges.cpp`, and the server request path in `src/server/master_server.cpp:517-525` forwards folding requests without any folding-specific options.
+
+### 2. clice already folds more AST structure than clangd
+
+clangd's AST-oriented `getFoldingRanges(ParsedAST &AST)` is intentionally narrow and only walks syntax-tree compound statements in `SemanticSelection.cpp:170-175`.
+
+Current clice already folds:
+
+- namespaces at `src/feature/folding_ranges.cpp:66-80`
+- records and access-specifier regions at `src/feature/folding_ranges.cpp:82-121`
+- function parameter lists and bodies at `src/feature/folding_ranges.cpp:123-144`, `246-269`
+- lambda captures at `src/feature/folding_ranges.cpp:134-143`
+- call argument lists at `src/feature/folding_ranges.cpp:146-179`
+- initializer lists at `src/feature/folding_ranges.cpp:181-185`
+- compound statements at `src/feature/folding_ranges.cpp:271-284`
+
+That is materially broader than clangd's current AST folding baseline.
+
+### 3. clice still exposes richer but less compatible output
+
+Current clice maps many internal categories directly to custom kind strings in `src/feature/folding_ranges.cpp:35-54`, and carries `collapsed_text` through `src/feature/folding_ranges.cpp:56-60` and `src/feature/folding_ranges.cpp:363-376`.
+
+clangd's downloaded protocol reference exposes only folding kinds in `Protocol.h:1970-1981` and serializes them in `Protocol.cpp:1680-1692`. The downloaded clangd protocol does not expose `collapsedText`, so `collapsedText` is a clice-specific protocol improvement rather than a clangd parity requirement.
+
+### 4. clice still has an incomplete `#endif` branch closure bug
+
+Current clice closes a prior conditional branch only when `#else` is seen at `src/feature/folding_ranges.cpp:302-311`. On `#endif`, it only pops the stack at `src/feature/folding_ranges.cpp:314-317` and emits no range for the final branch body.
+
+clangd does not solve this either. Upstream `SemanticSelection.cpp:178-190` still leaves PP conditional regions and disabled regions as FIXME items. This means `#if` branch folding remains a clice extension opportunity, not a direct clangd parity target.
+
+### 5. clice lacks client-capability plumbing for folding
+
+Current clice only advertises `caps.folding_range_provider = true` in `src/server/master_server.cpp:244`, and the request handler in `src/server/master_server.cpp:517-525` forwards no `lineFoldingOnly`, `rangeLimit`, or `collapsedText` support signals into the feature layer.
+
+clangd at least threads `LineFoldingOnly` from the client into folding generation via `ClangdLSPServer.cpp:545` and `ClangdServer.cpp:974-976`.
+
+### 6. clice test coverage is still weaker in the most important gap areas
+
+Current clice has structural tests, but the directive and pragma-region cases remain placeholder-only in `tests/unit/feature/folding_range_tests.cpp:398-430`. The tests also do not assert folding kinds.
+
+clangd's downloaded tests cover:
+
+- AST folding
+- comment folding
+- line-folding-only behavior
+- macro-related exclusion cases
+
+Those are visible in `unittests/SemanticSelectionTests.cpp:269-455`.
+
+## Planning Implications
+
+The downloaded source narrows the real parity target:
+
+- confirmed clangd parity gaps for clice: comment folding, `lineFoldingOnly`, standard public kind behavior, stronger tests
+- confirmed clice advantages over clangd: namespaces, access-specifier regions, lambda captures, function parameter folds, function-call folds, initializer folds, pragma regions, collapsed text
+- confirmed clice-specific extension space beyond clangd: inactive-branch folding, complete `#if/#elif/#else/#endif` folding, macro-definition folding, include/import grouping
+
+The earlier `third_party` vendor plan was the wrong storage model for this branch. The correct model is a change-local downloaded reference under `openspec/changes/explore-improve-folding-range-support/reference/`.

openspec/changes/explore-improve-folding-range-support/design.md

@@ -0,0 +1,279 @@
+## Context
+
+`clice` currently implements folding ranges in `src/feature/folding_ranges.cpp`. The implementation is primarily an AST visitor with extra handling for conditional compilation and `#pragma region` data from `CompilationUnitRef::directives()`. It already covers many structural folds that clangd does not currently expose, such as namespaces, records, function parameter lists, lambda captures, call argument lists, access-specifier sections, and initializer lists.
+
+The request path is currently split across:
+
+- `src/feature/folding_ranges.cpp` for collection and rendering
+- `src/server/master_server.cpp` for request plumbing and capability advertisement
+- generated `kota` LSP protocol types for request/response shapes
+- `tests/unit/feature/folding_range_tests.cpp` for unit coverage
+
+That split reveals three immediate shortcomings:
+
+- the current collector has no comment path at all
+- folding-specific client capabilities such as `lineFoldingOnly`, `rangeLimit`, and `collapsedText` are not threaded through the request path
+- directive-related tests are mostly placeholders and do not assert important behavior
+
+The comparison target for this exploration change should be fixed and versioned. At tag `llvmorg-21.1.8`, clangd's folding behavior is centered on `clang-tools-extra/clangd/SemanticSelection.cpp`, with request plumbing in `ClangdServer.cpp` and `ClangdLSPServer.cpp`, protocol types in `Protocol.h` and `Protocol.cpp`, and regression coverage in `test/folding-range.test` plus `unittests/SemanticSelectionTests.cpp`. Those files have been downloaded into `openspec/changes/explore-improve-folding-range-support/reference/clangd/llvmorg-21.1.8/`, and the side-by-side analysis lives in `comparison.md`.
+
+Compared with that clangd baseline, the current gap is clear:
+
+- clangd already has behavior that `clice` still lacks:
+  - multiline comment folding
+  - contiguous `//` comment-group folding
+  - `lineFoldingOnly` rendering behavior wired from client capabilities into folding generation
+  - consistent use of standard public folding kinds
+  - a more complete and assertion-backed folding-range test matrix
+- `clice` already has behavior that clangd does not:
+  - richer AST-structure folding
+  - `#pragma region` and some conditional-compilation folding
+  - `collapsedText`
+- `clice` still has obvious opportunities that are not fully implemented yet:
+  - fully closing the last `#if/#elif/#else` branch at `#endif`
+  - folding inactive branches
+  - folding multiline macro definitions
+  - grouping contiguous `#include` / `import` blocks
+  - capability-aware `kind` and `collapsedText` rendering
+
+In addition, the downloaded clangd source confirms that clangd still does not implement PP conditional regions, include grouping, or access-specifier folding in `SemanticSelection.cpp`; those are explicitly left as FIXME items upstream. The real parity target is therefore narrower than "match everything clangd does": comments, line-only rendering, standard kinds, and test discipline are the confirmed baseline gaps. Everything around directive groups, inactive branches, and richer structural categories remains a clice-specific extension opportunity.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Download a focused clangd reference set from `llvmorg-21.1.8` into this change directory and use it as the explicit comparison baseline for this branch.
+- Preserve `clice`'s current advantage in AST-structure folding instead of regressing to clangd's much narrower block-only baseline.
+- Fill the high-value baseline gaps that clangd already covers, especially multiline comments and `lineFoldingOnly`.
+- Turn preprocessor metadata into a differentiating `clice` capability covering conditional branches, macro definitions, and include/import grouping.
+- Make folding-range output respect client capabilities with predictable fallback behavior.
+- Lock behavior down with unit and integration tests across AST, comments, preprocessor handling, and protocol negotiation.
+
+**Non-Goals:**
+
+- Import clangd implementation code directly into `clice` production paths or make the build depend on the downloaded reference files.
+- Achieve byte-for-byte or range-for-range parity with clangd in this change.
+- Add fine-grained folding for every C++ syntax detail such as template parameter lists, requires-clauses, or attribute arguments before their value is proven.
+- Introduce editor-specific behavior that only exists to satisfy one frontend.
+- Add cross-file or index-backed folding behavior.
+
+## Decisions
+
+### 1. Download a focused clangd reference set into the change directory before implementation work
+
+The branch should first download a small, reviewable set of clangd's folding-related sources from tag `llvmorg-21.1.8` into `openspec/changes/explore-improve-folding-range-support/reference/clangd/llvmorg-21.1.8/`. The downloaded set should include the implementation, request plumbing, protocol types, and relevant tests that explain folding behavior, rather than the whole LLVM tree.
+
+Why:
+
+- it creates a stable review artifact for this exploration branch
+- later implementation work can point at local upstream code instead of external URLs
+- it keeps the eventual runtime change honest about what is parity work and what is a clice-specific extension
+- it avoids adding a repo-level vendor location for a one-branch study artifact
+
+Alternative considered:
+
+- Put the files under `third_party/`. Rejected because this is an exploration artifact, not a production dependency.
+
+### 2. Split the folding-range pipeline into collection, normalization, and rendering
+
+The current implementation mixes "how a range is discovered" with "how it is emitted as LSP". The new design separates this into three layers:
+
+- collection: produce internal `RawFoldingRange` entries from AST, comment scanning, and preprocessor metadata
+- normalization: sort, deduplicate, validate, and reconcile nested or overlapping ranges
+- rendering: decide line/column boundaries, `kind`, and `collapsedText` based on client capabilities
+
+Why:
+
+- `lineFoldingOnly`, `collapsedText`, and standards-compatible kind downgrading are rendering concerns and should not pollute collection logic
+- comments, macros, and include/import groups do not naturally belong inside the AST visitor
+- future range limiting or prioritization should also live in normalization/rendering instead of collector code
+
+Follow-up discussion narrows this design point: the existing `RawFoldingRange` model is finished for the current pipeline work and should not be redesigned here. The missing part is an explicit options object, passed as `Opts`/`FoldingRangeOptions`, that lets callers configure renderer behavior such as `line_folding_only`.
+
+Alternative considered:
+
+- Keep generating final LSP ranges directly inside the visitor. Rejected because capability negotiation and multi-source collection will keep making the function larger and harder to test.
+
+### 3. Keep rich internal categories, but only promise standard-compatible public kinds
+
+Internally, the implementation may still distinguish namespace, class, function body, macro definition, conditional branch, and similar categories so tests, prioritization, and `collapsedText` selection remain precise. However, public LSP output should default to standard kinds only:
+
+- comment folds -> `comment`
+- contiguous include/import groups -> `imports`
+- all other structural and preprocessor folds -> `region`
+
+If some client later proves it needs clice-specific kinds, that can be evaluated separately. This change does not make non-standard kind strings part of the compatibility contract.
+
+Why:
+
+- many current custom strings will not be understood by clients and do not produce stable UI semantics
+- the real differentiator is what `clice` can fold, not the literal `kind` label
+- once public kinds are standardized, `collapsedText` and range boundaries become the primary user-visible expression
+
+Alternative considered:
+
+- Continue exposing all custom kinds directly. Rejected because that leaves client compatibility up to luck rather than protocol design.
+
+### 4. Use the downloaded clangd files as a behavior reference, not as a direct implementation template
+
+clangd's folding logic is text- and token-oriented rather than AST-oriented. `clice` should study the upstream behavior to match the useful parts, but it should not force its own collector architecture to look like clangd's when `CompilationUnitRef::directives()` and the existing AST visitor provide better raw data.
+
+Why:
+
+- parity should be measured at the behavior boundary, not by mirroring file structure
+- `clice` already has data sources that clangd does not, especially for directive metadata
+- this keeps the change focused on correctness and value, not on source-level imitation
+
+Alternative considered:
+
+- Rewrite `clice` folding collection to resemble clangd's text parser closely. Rejected because that would discard existing strengths without a clear benefit.
+
+### 5. Implement comment folding through lexical/source scanning, not AST
+
+Multiline comments are handled independently in clangd's pseudo-parser path, and `clice` should do the same. The design adds a comment collector that scans the main-file source or token stream directly:
+
+- fold multiline `/* ... */` block comments
+- fold contiguous `//` comment groups
+- do not fold single-line comments
+- preserve source spans that let the renderer adjust closing boundaries for `lineFoldingOnly` mode
+
+Why:
+
+- comments are not AST structure, so trying to derive them from AST produces fragile behavior
+- lexical scanning naturally handles adjacent-comment grouping and block-comment boundaries
+
+Alternative considered:
+
+- Only support block comments. Rejected because clangd already demonstrates that contiguous `//` comment groups are a useful folding case.
+
+### 6. Rework preprocessor folding around complete branch blocks instead of the current half-open stack
+
+Today `collect_condition_directives()` only closes the previous branch when it sees `#else`, but when it sees `#endif` it only pops the stack and does not emit a folding range for the final `#if/#elif/#else` branch. As a result, `#if` folding is incomplete.
+
+The new design treats conditional compilation as an explicit branch-group model:
+
+- maintain the ordered branch chain for each `#if` group
+- allow every branch to close at the next `#elif`, `#else`, or `#endif`
+- distinguish active and inactive branches
+- allow inactive branches to produce region folds, optionally with distinct `collapsedText`
+
+Why:
+
+- this is the minimum sound model needed to fix the current logical gap
+- `Condition::ConditionValue` already records true/false/skipped state and can drive inactive-branch folding directly
+
+Alternative considered:
+
+- Patch only the `#endif` closing case. Rejected because nested conditions, inactive branches, and range ordering would remain structurally weak.
+
+### 7. Add dedicated directive-based collectors for macros and include/import groups
+
+`clice` already collects:
+
+- `directive.macros`
+- `directive.includes`
+- `directive.imports`
+
+The new design therefore adds directive-based folding collectors for:
+
+- multiline `#define` macro definitions, using continuation backslashes or stable definition ranges
+- contiguous `#include` blocks, merged into a single `imports` folding range
+- contiguous `import Foo;` / `import Foo:Bar;` module-import blocks, also emitted as `imports`
+
+Why:
+
+- the necessary data already exists in preprocessing metadata and does not require new AST modeling
+- this is one of the easiest places for `clice` to provide value beyond clangd
+
+Alternative considered:
+
+- Leave include/import grouping for a later change. Rejected because the metadata already exists, the implementation cost is relatively low, and the editor-facing value is immediate.
+
+### 8. Separate clangd parity capabilities from clice-only protocol improvements
+
+This change should treat comment folding, `lineFoldingOnly`, and standard public kinds as clangd parity work. `collapsedText` gating and deterministic `rangeLimit` trimming remain clice-side protocol improvements. The downloaded clangd `Protocol.h` / `Protocol.cpp` reference does not expose `collapsedText`, so the design and tests should not imply that clangd already provides that capability.
+
+Why:
+
+- it keeps the comparison honest
+- it allows reviewer discussion to separate "must match upstream baseline" from "valuable extra behavior"
+- it keeps spec language compatible with LSP without overstating clangd
+
+Alternative considered:
+
+- Treat all capability work as a clangd parity gap. Rejected because clangd's known folding path does not establish that broader claim.
+
+### 9. Folding-range output must be explicitly bound to client capabilities
+
+The master server currently only advertises `foldingRangeProvider = true`, but it does not read or propagate folding-specific client capabilities. The new design requires the session to track at least:
+
+- `lineFoldingOnly`
+- whether `collapsedText` is supported
+- optional `rangeLimit`
+
+Capability state should be translated into a feature-layer options object before rendering. The initial option needed by the current discussion is:
+
+```cpp
+struct FoldingRangeOptions {
+    bool line_folding_only = false;
+};
+```
+
+The feature API should accept that options object separately from the source collector inputs, for example as `folding_ranges(unit, opts, encoding)`. Later protocol work can extend the same object for collapsed-text gating or range limiting without changing collectors.
+
+Rendering rules:
+
+- when `opts.line_folding_only = true`, only emit ranges that remain meaningful as line-based folds, adjusting end lines where necessary
+- when the client does not support `collapsedText`, omit it
+- when a `rangeLimit` is declared, trim results deterministically rather than arbitrarily
+
+Alternative considered:
+
+- Continue always returning exact columns and `collapsedText`. Rejected because that relies on client tolerance instead of following the protocol contract.
+- Thread capability state into collectors directly. Rejected because it would reopen the raw model and collection contract even though line-only behavior is a renderer policy.
+
+### 10. Organize tests by source category and protocol behavior
+
+Tests will be split into two dimensions:
+
+- source-category unit tests: AST structure, comments, conditional compilation, multiline macros, `#pragma region`, and include/import groups
+- protocol-behavior tests: `lineFoldingOnly`, `collapsedText` support, public kind mapping, and range limiting
+
+In particular, the current `tests/unit/feature/folding_range_tests.cpp` contains `Directive` and `PragmaRegion` cases that do not actually assert results. This change upgrades them into strong assertion-based tests.
+
+Alternative considered:
+
+- Rely mostly on manual editor validation. Rejected because folding details regress easily, especially for preprocessor handling and line-only rendering.
+
+## Risks / Trade-offs
+
+- [The downloaded clangd reference set could sprawl or become noisy in review] -> Mitigation: keep only the small folding-related file set needed for comparison under the change directory and record the exact URLs in `comparison.md`.
+- [Client capabilities must flow from initialize state into request-time rendering] -> Mitigation: introduce a dedicated folding-options structure so session details do not leak broadly into the feature layer.
+- [Inactive-branch and macro-definition ranges can be unstable around expansion locations] -> Mitigation: prefer spelling/main-file ranges and explicitly filter or special-case macro-expansion ranges when necessary.
+- [Adding comments, macros, and include/import groups can increase the number of ranges quickly] -> Mitigation: implement stable sorting and `rangeLimit` trimming in the normalization layer.
+- [Mapping public kinds back to standard values changes current metadata output] -> Mitigation: the folds themselves remain; the user-visible change is mostly in optional metadata, and tests plus change notes will make that explicit.
+- [Multiple collectors may produce overlapping or duplicate ranges] -> Mitigation: normalize by source category and boundary rules so collectors do not amplify noise.
+
+## Migration Plan
+
+1. Download the focused clangd `llvmorg-21.1.8` folding reference files into `openspec/changes/explore-improve-folding-range-support/reference/clangd/llvmorg-21.1.8/`.
+2. Record the confirmed clangd-vs-clice comparison in this change, including exact URLs, which behaviors are parity gaps, and which are clice-specific extensions.
+3. Keep the existing `RawFoldingRange` data flow, add `FoldingRangeOptions` for `line_folding_only`, and add standard kind mapping.
+4. Add the comment collector and assertion-backed tests for multiline comment folding.
+5. Rewrite conditional-directive and `#pragma region` collection so `#if` branches close correctly through `#endif`.
+6. Add multiline macro folding and grouped include/import collectors.
+7. Wire folding client capabilities through initialize/request handling and add integration coverage.
+8. Add `rangeLimit` trimming and regression cleanup after the new collectors are in place.
+
+Rollback strategy:
+
+- If the downloaded reference set becomes more distracting than useful, keep only the documented comparison notes and delete the change-local downloads before merging.
+- If protocol negotiation proves unstable, keep the new collectors but temporarily disable outward behavior changes tied to `collapsedText` or `rangeLimit`.
+- If a particular new fold category proves noisy, roll it back collector-by-collector instead of reverting the entire folding-range refactor.
+
+## Open Questions
+
+- Are `test/folding-range.test` and `unittests/SemanticSelectionTests.cpp` enough for ongoing comparison, or will later implementation work need more upstream folding-related tests?
+- Should multiline macro folding cover only the macro body, or the full `#define NAME(...)` line plus body as one fold region?
+- Should `rangeLimit` prioritize outer structure, top-of-file regions, or longer ranges when trimming results?
+- For structural AST folds originating from macro expansion, should `clice` preserve current behavior or restrict itself to cases with stable spelling ranges only?

openspec/changes/explore-improve-folding-range-support/proposal.md

@@ -0,0 +1,36 @@
+## Why
+
+`clice` already goes beyond clangd in several structural folding cases: it can fold namespaces, records, function parameter lists and bodies, lambda captures, call argument lists, access-specifier sections, and some preprocessor regions. However, the current implementation in `src/feature/folding_ranges.cpp` still misses several baseline behaviors that clangd already exposes well, especially multiline comment folding, line-only folding rendering, standard public folding kinds, and a stronger regression test matrix. Its preprocessor branch folding is also not yet fully closed.
+
+This exploration branch needs a fixed upstream reference instead of relying on memory. At tag `llvmorg-21.1.8`, clangd's folding implementation is centered around `clang-tools-extra/clangd/SemanticSelection.cpp`, with request plumbing in `ClangdServer.cpp` and `ClangdLSPServer.cpp`, protocol types in `Protocol.h` and `Protocol.cpp`, and folding coverage in `test/folding-range.test` plus `unittests/SemanticSelectionTests.cpp`. Downloading those files into this change directory with `curl` gives the branch a stable, reviewable baseline for side-by-side comparison without introducing a repository-level vendor tree.
+
+More importantly, `clice` already has preprocessor metadata that clangd does not fully exploit, such as `directive.macros`, `directive.includes`, `directive.imports`, and evaluated conditional-branch state. That means `clice` should not stop at matching clangd: after filling the real parity gaps, folding ranges can become a more useful C/C++ feature by covering macro definitions, `#if` branches, and include/import groups that clangd does not currently handle well.
+
+Follow-up discussion clarified the split with `split-folding-range-pipeline`: the existing `RawFoldingRange` model is finished for the current architecture work. The missing capability path is explicit folding options, passed as `Opts`/`FoldingRangeOptions`, so `line_folding_only` can be requested by server capability plumbing and consumed by the renderer.
+
+## What Changes
+
+- Download the clangd folding-range reference files for tag `llvmorg-21.1.8` into `openspec/changes/explore-improve-folding-range-support/reference/clangd/llvmorg-21.1.8/` using `curl` from GitHub raw URLs.
+- Record a concrete clangd-vs-clice comparison in `comparison.md`, including the upstream files consulted, exact download URLs, confirmed parity gaps, clice-only capabilities, and known implementation bugs.
+- Fill the remaining folding-range baseline gaps between `clice` and clangd, especially multiline comment folding, line-only folding rendering, and standard public kind mapping.
+- Complete preprocessor-related folding so full `#if/#elif/#else/#endif` branch regions, nested `#pragma region` blocks, and inactive branches have well-defined behavior.
+- Add folding features that take advantage of `clice`'s existing preprocessor metadata, including multiline macro definitions and grouped `#include` / `import` blocks.
+- Normalize `FoldingRange.kind` output so standard kinds remain compatible while clice-specific fold categories degrade predictably.
+- Make folding range responses honor client capabilities such as `lineFoldingOnly`, optional `collapsedText` support, and range limiting, using folding options rather than collector-specific state.
+- Expand unit and integration coverage for AST folds, comments, preprocessor regions, macros, include/import groups, and protocol negotiation behavior.
+
+## Capabilities
+
+### New Capabilities
+- `folding-ranges`: Provide LSP-compatible, C/C++-focused folding regions that cover AST structure, comments, preprocessor branches, macro definitions, and include/import groups.
+
+### Modified Capabilities
+- None.
+
+## Impact
+
+- A change-local upstream reference set has been downloaded under `openspec/changes/explore-improve-folding-range-support/reference/clangd/llvmorg-21.1.8/`, limited to the folding-range implementation, protocol, and tests needed for analysis.
+- The side-by-side analysis is recorded in `openspec/changes/explore-improve-folding-range-support/comparison.md`.
+- Primary runtime impact is in `src/feature/folding_ranges.cpp`, the compile-unit/preprocessor metadata access paths, request handling in `src/server/master_server.cpp`, and the folding options object used to carry capability-derived rendering choices.
+- Tests need expansion in `tests/unit/feature/folding_range_tests.cpp`, server/integration coverage, and any required fixtures for preprocessor and module scenarios.
+- User-visible behavior will be folding results that are closer to clangd where clangd already has coverage, while also adding high-value C/C++ folds that clangd does not currently provide well, especially macro-definition and conditional-compilation folding.

openspec/changes/explore-improve-folding-range-support/reference/clangd/llvmorg-21.1.8/clang-tools-extra/clangd/ClangdServer.h

@@ -0,0 +1,531 @@
+//===--- ClangdServer.h - Main clangd server code ----------------*- C++-*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_CLANGDSERVER_H
+#define LLVM_CLANG_TOOLS_EXTRA_CLANGD_CLANGDSERVER_H
+
+#include "CodeComplete.h"
+#include "ConfigProvider.h"
+#include "Diagnostics.h"
+#include "DraftStore.h"
+#include "FeatureModule.h"
+#include "GlobalCompilationDatabase.h"
+#include "Hover.h"
+#include "ModulesBuilder.h"
+#include "Protocol.h"
+#include "SemanticHighlighting.h"
+#include "TUScheduler.h"
+#include "XRefs.h"
+#include "index/Background.h"
+#include "index/FileIndex.h"
+#include "index/Index.h"
+#include "refactor/Rename.h"
+#include "refactor/Tweak.h"
+#include "support/Function.h"
+#include "support/MemoryTree.h"
+#include "support/Path.h"
+#include "support/ThreadsafeFS.h"
+#include "clang/Tooling/Core/Replacement.h"
+#include "llvm/ADT/ArrayRef.h"
+#include "llvm/ADT/FunctionExtras.h"
+#include "llvm/ADT/StringRef.h"
+#include <functional>
+#include <memory>
+#include <optional>
+#include <string>
+#include <tuple>
+#include <vector>
+
+namespace clang {
+namespace clangd {
+/// Manages a collection of source files and derived data (ASTs, indexes),
+/// and provides language-aware features such as code completion.
+///
+/// The primary client is ClangdLSPServer which exposes these features via
+/// the Language Server protocol. ClangdServer may also be embedded directly,
+/// though its API is not stable over time.
+///
+/// ClangdServer should be used from a single thread. Many potentially-slow
+/// operations have asynchronous APIs and deliver their results on another
+/// thread.
+/// Such operations support cancellation: if the caller sets up a cancelable
+/// context, many operations will notice cancellation and fail early.
+/// (ClangdLSPServer uses this to implement $/cancelRequest).
+class ClangdServer {
+public:
+  /// Interface with hooks for users of ClangdServer to be notified of events.
+  class Callbacks {
+  public:
+    virtual ~Callbacks() = default;
+
+    /// Called by ClangdServer when \p Diagnostics for \p File are ready.
+    /// These pushed diagnostics might correspond to an older version of the
+    /// file, they do not interfere with "pull-based" ClangdServer::diagnostics.
+    /// May be called concurrently for separate files, not for a single file.
+    virtual void onDiagnosticsReady(PathRef File, llvm::StringRef Version,
+                                    llvm::ArrayRef<Diag> Diagnostics) {}
+    /// Called whenever the file status is updated.
+    /// May be called concurrently for separate files, not for a single file.
+    virtual void onFileUpdated(PathRef File, const TUStatus &Status) {}
+
+    /// Called when background indexing tasks are enqueued/started/completed.
+    /// Not called concurrently.
+    virtual void
+    onBackgroundIndexProgress(const BackgroundQueue::Stats &Stats) {}
+
+    /// Called when the meaning of a source code may have changed without an
+    /// edit. Usually clients assume that responses to requests are valid until
+    /// they next edit the file. If they're invalidated at other times, we
+    /// should tell the client. In particular, when an asynchronous preamble
+    /// build finishes, we can provide more accurate semantic tokens, so we
+    /// should tell the client to refresh.
+    virtual void onSemanticsMaybeChanged(PathRef File) {}
+
+    /// Called by ClangdServer when some \p InactiveRegions for \p File are
+    /// ready.
+    virtual void onInactiveRegionsReady(PathRef File,
+                                        std::vector<Range> InactiveRegions) {}
+  };
+  /// Creates a context provider that loads and installs config.
+  /// Errors in loading config are reported as diagnostics via Callbacks.
+  /// (This is typically used as ClangdServer::Options::ContextProvider).
+  static std::function<Context(PathRef)>
+  createConfiguredContextProvider(const config::Provider *Provider,
+                                  ClangdServer::Callbacks *);
+
+  struct Options {
+    /// To process requests asynchronously, ClangdServer spawns worker threads.
+    /// If this is zero, no threads are spawned. All work is done on the calling
+    /// thread, and callbacks are invoked before "async" functions return.
+    unsigned AsyncThreadsCount = getDefaultAsyncThreadsCount();
+
+    /// AST caching policy. The default is to keep up to 3 ASTs in memory.
+    ASTRetentionPolicy RetentionPolicy;
+
+    /// Cached preambles are potentially large. If false, store them on disk.
+    bool StorePreamblesInMemory = true;
+
+    /// Call hierarchy's outgoing calls feature requires additional index
+    /// serving structures which increase memory usage. If false, these are
+    /// not created and the feature is not enabled.
+    bool EnableOutgoingCalls = true;
+
+    /// This throttler controls which preambles may be built at a given time.
+    clangd::PreambleThrottler *PreambleThrottler = nullptr;
+
+    /// Manages to build module files.
+    ModulesBuilder *ModulesManager = nullptr;
+
+    /// If true, ClangdServer builds a dynamic in-memory index for symbols in
+    /// opened files and uses the index to augment code completion results.
+    bool BuildDynamicSymbolIndex = false;
+    /// If true, ClangdServer automatically indexes files in the current project
+    /// on background threads. The index is stored in the project root.
+    bool BackgroundIndex = false;
+    llvm::ThreadPriority BackgroundIndexPriority = llvm::ThreadPriority::Low;
+
+    /// If set, use this index to augment code completion results.
+    SymbolIndex *StaticIndex = nullptr;
+
+    /// If set, queried to derive a processing context for some work.
+    /// Usually used to inject Config (see createConfiguredContextProvider).
+    ///
+    /// When the provider is called, the active context will be that inherited
+    /// from the request (e.g. addDocument()), or from the ClangdServer
+    /// constructor if there is no such request (e.g. background indexing).
+    ///
+    /// The path is an absolute path of the file being processed.
+    /// If there is no particular file (e.g. project loading) then it is empty.
+    std::function<Context(PathRef)> ContextProvider;
+
+    /// The Options provider to use when running clang-tidy. If null, clang-tidy
+    /// checks will be disabled.
+    TidyProviderRef ClangTidyProvider;
+
+    /// Clangd's workspace root. Relevant for "workspace" operations not bound
+    /// to a particular file.
+    /// FIXME: If not set, should use the current working directory.
+    std::optional<std::string> WorkspaceRoot;
+
+    /// The resource directory is used to find internal headers, overriding
+    /// defaults and -resource-dir compiler flag).
+    /// If std::nullopt, ClangdServer calls
+    /// CompilerInvocation::GetResourcePath() to obtain the standard resource
+    /// directory.
+    std::optional<std::string> ResourceDir;
+
+    /// Time to wait after a new file version before computing diagnostics.
+    DebouncePolicy UpdateDebounce = DebouncePolicy{
+        /*Min=*/std::chrono::milliseconds(50),
+        /*Max=*/std::chrono::milliseconds(500),
+        /*RebuildRatio=*/1,
+    };
+
+    /// Cancel certain requests if the file changes before they begin running.
+    /// This is useful for "transient" actions like enumerateTweaks that were
+    /// likely implicitly generated, and avoids redundant work if clients forget
+    /// to cancel. Clients that always cancel stale requests should clear this.
+    bool ImplicitCancellation = true;
+
+    /// Clangd will execute compiler drivers matching one of these globs to
+    /// fetch system include path.
+    std::vector<std::string> QueryDriverGlobs;
+
+    // Whether the client supports folding only complete lines.
+    bool LineFoldingOnly = false;
+
+    FeatureModuleSet *FeatureModules = nullptr;
+    /// If true, use the dirty buffer contents when building Preambles.
+    bool UseDirtyHeaders = false;
+
+    // If true, parse emplace-like functions in the preamble.
+    bool PreambleParseForwardingFunctions = true;
+
+    /// Whether include fixer insertions for Objective-C code should use #import
+    /// instead of #include.
+    bool ImportInsertions = false;
+
+    /// Whether to collect and publish information about inactive preprocessor
+    /// regions in the document.
+    bool PublishInactiveRegions = false;
+
+    explicit operator TUScheduler::Options() const;
+  };
+  // Sensible default options for use in tests.
+  // Features like indexing must be enabled if desired.
+  static Options optsForTest();
+
+  /// Creates a new ClangdServer instance.
+  ///
+  /// ClangdServer uses \p CDB to obtain compilation arguments for parsing. Note
+  /// that ClangdServer only obtains compilation arguments once for each newly
+  /// added file (i.e., when processing a first call to addDocument) and reuses
+  /// those arguments for subsequent reparses. However, ClangdServer will check
+  /// if compilation arguments changed on calls to forceReparse().
+  ClangdServer(const GlobalCompilationDatabase &CDB, const ThreadsafeFS &TFS,
+               const Options &Opts, Callbacks *Callbacks = nullptr);
+  ~ClangdServer();
+
+  /// Gets the installed feature module of a given type, if any.
+  /// This exposes access the public interface of feature modules that have one.
+  template <typename Mod> Mod *featureModule() {
+    return FeatureModules ? FeatureModules->get<Mod>() : nullptr;
+  }
+  template <typename Mod> const Mod *featureModule() const {
+    return FeatureModules ? FeatureModules->get<Mod>() : nullptr;
+  }
+
+  /// Add a \p File to the list of tracked C++ files or update the contents if
+  /// \p File is already tracked. Also schedules parsing of the AST for it on a
+  /// separate thread. When the parsing is complete, DiagConsumer passed in
+  /// constructor will receive onDiagnosticsReady callback.
+  /// Version identifies this snapshot and is propagated to ASTs, preambles,
+  /// diagnostics etc built from it. If empty, a version number is generated.
+  void addDocument(PathRef File, StringRef Contents,
+                   llvm::StringRef Version = "null",
+                   WantDiagnostics WD = WantDiagnostics::Auto,
+                   bool ForceRebuild = false);
+
+  /// Remove \p File from list of tracked files, schedule a request to free
+  /// resources associated with it. Pending diagnostics for closed files may not
+  /// be delivered, even if requested with WantDiags::Auto or WantDiags::Yes.
+  /// An empty set of diagnostics will be delivered, with Version = "".
+  void removeDocument(PathRef File);
+
+  /// Requests a reparse of currently opened files using their latest source.
+  /// This will typically only rebuild if something other than the source has
+  /// changed (e.g. the CDB yields different flags, or files included in the
+  /// preamble have been modified).
+  void reparseOpenFilesIfNeeded(
+      llvm::function_ref<bool(llvm::StringRef File)> Filter);
+
+  /// Run code completion for \p File at \p Pos.
+  ///
+  /// This method should only be called for currently tracked files.
+  void codeComplete(PathRef File, Position Pos,
+                    const clangd::CodeCompleteOptions &Opts,
+                    Callback<CodeCompleteResult> CB);
+
+  /// Provide signature help for \p File at \p Pos.  This method should only be
+  /// called for tracked files.
+  void signatureHelp(PathRef File, Position Pos, MarkupKind DocumentationFormat,
+                     Callback<SignatureHelp> CB);
+
+  /// Find declaration/definition locations of symbol at a specified position.
+  void locateSymbolAt(PathRef File, Position Pos,
+                      Callback<std::vector<LocatedSymbol>> CB);
+
+  /// Switch to a corresponding source file when given a header file, and vice
+  /// versa.
+  void switchSourceHeader(PathRef Path,
+                          Callback<std::optional<clangd::Path>> CB);
+
+  /// Get document highlights for a given position.
+  void findDocumentHighlights(PathRef File, Position Pos,
+                              Callback<std::vector<DocumentHighlight>> CB);
+
+  /// Get code hover for a given position.
+  void findHover(PathRef File, Position Pos,
+                 Callback<std::optional<HoverInfo>> CB);
+
+  /// Get information about type hierarchy for a given position.
+  void typeHierarchy(PathRef File, Position Pos, int Resolve,
+                     TypeHierarchyDirection Direction,
+                     Callback<std::vector<TypeHierarchyItem>> CB);
+  /// Get direct parents of a type hierarchy item.
+  void superTypes(const TypeHierarchyItem &Item,
+                  Callback<std::optional<std::vector<TypeHierarchyItem>>> CB);
+  /// Get direct children of a type hierarchy item.
+  void subTypes(const TypeHierarchyItem &Item,
+                Callback<std::vector<TypeHierarchyItem>> CB);
+
+  /// Resolve type hierarchy item in the given direction.
+  void resolveTypeHierarchy(TypeHierarchyItem Item, int Resolve,
+                            TypeHierarchyDirection Direction,
+                            Callback<std::optional<TypeHierarchyItem>> CB);
+
+  /// Get information about call hierarchy for a given position.
+  void prepareCallHierarchy(PathRef File, Position Pos,
+                            Callback<std::vector<CallHierarchyItem>> CB);
+
+  /// Resolve incoming calls for a given call hierarchy item.
+  void incomingCalls(const CallHierarchyItem &Item,
+                     Callback<std::vector<CallHierarchyIncomingCall>>);
+
+  /// Resolve outgoing calls for a given call hierarchy item.
+  void outgoingCalls(const CallHierarchyItem &Item,
+                     Callback<std::vector<CallHierarchyOutgoingCall>>);
+
+  /// Resolve inlay hints for a given document.
+  void inlayHints(PathRef File, std::optional<Range> RestrictRange,
+                  Callback<std::vector<InlayHint>>);
+
+  /// Retrieve the top symbols from the workspace matching a query.
+  void workspaceSymbols(StringRef Query, int Limit,
+                        Callback<std::vector<SymbolInformation>> CB);
+
+  /// Retrieve the symbols within the specified file.
+  void documentSymbols(StringRef File,
+                       Callback<std::vector<DocumentSymbol>> CB);
+
+  /// Retrieve ranges that can be used to fold code within the specified file.
+  void foldingRanges(StringRef File, Callback<std::vector<FoldingRange>> CB);
+
+  /// Retrieve implementations for virtual method.
+  void findImplementations(PathRef File, Position Pos,
+                           Callback<std::vector<LocatedSymbol>> CB);
+
+  /// Retrieve symbols for types referenced at \p Pos.
+  void findType(PathRef File, Position Pos,
+                Callback<std::vector<LocatedSymbol>> CB);
+
+  /// Retrieve locations for symbol references.
+  void findReferences(PathRef File, Position Pos, uint32_t Limit,
+                      bool AddContainer, Callback<ReferencesResult> CB);
+
+  /// Run formatting for the \p File with content \p Code.
+  /// If \p Rng is non-empty, formats only those regions.
+  void formatFile(PathRef File, const std::vector<Range> &Rngs,
+                  Callback<tooling::Replacements> CB);
+
+  /// Run formatting after \p TriggerText was typed at \p Pos in \p File with
+  /// content \p Code.
+  void formatOnType(PathRef File, Position Pos, StringRef TriggerText,
+                    Callback<std::vector<TextEdit>> CB);
+
+  /// Test the validity of a rename operation.
+  ///
+  /// If NewName is provided, it performs a name validation.
+  void prepareRename(PathRef File, Position Pos,
+                     std::optional<std::string> NewName,
+                     const RenameOptions &RenameOpts,
+                     Callback<RenameResult> CB);
+
+  /// Rename all occurrences of the symbol at the \p Pos in \p File to
+  /// \p NewName.
+  /// If WantFormat is false, the final TextEdit will be not formatted,
+  /// embedders could use this method to get all occurrences of the symbol (e.g.
+  /// highlighting them in prepare stage).
+  void rename(PathRef File, Position Pos, llvm::StringRef NewName,
+              const RenameOptions &Opts, Callback<RenameResult> CB);
+
+  struct TweakRef {
+    std::string ID;    /// ID to pass for applyTweak.
+    std::string Title; /// A single-line message to show in the UI.
+    llvm::StringLiteral Kind;
+  };
+
+  // Ref to the clangd::Diag.
+  struct DiagRef {
+    clangd::Range Range;
+    std::string Message;
+    bool operator==(const DiagRef &Other) const {
+      return std::tie(Range, Message) == std::tie(Other.Range, Other.Message);
+    }
+    bool operator<(const DiagRef &Other) const {
+      return std::tie(Range, Message) < std::tie(Other.Range, Other.Message);
+    }
+  };
+
+  struct CodeActionInputs {
+    std::string File;
+    Range Selection;
+
+    /// Requested kind of actions to return.
+    std::vector<std::string> RequestedActionKinds;
+
+    /// Diagnostics attached to the code action request.
+    std::vector<DiagRef> Diagnostics;
+
+    /// Tweaks where Filter returns false will not be checked or included.
+    std::function<bool(const Tweak &)> TweakFilter;
+  };
+  struct CodeActionResult {
+    std::string Version;
+    struct QuickFix {
+      DiagRef Diag;
+      Fix F;
+    };
+    std::vector<QuickFix> QuickFixes;
+    std::vector<TweakRef> TweakRefs;
+    struct Rename {
+      DiagRef Diag;
+      std::string FixMessage;
+      std::string NewName;
+    };
+    std::vector<Rename> Renames;
+  };
+  /// Surface code actions (quick-fixes for diagnostics, or available code
+  /// tweaks) for a given range in a file.
+  void codeAction(const CodeActionInputs &Inputs,
+                  Callback<CodeActionResult> CB);
+
+  /// Apply the code tweak with a specified \p ID.
+  void applyTweak(PathRef File, Range Sel, StringRef ID,
+                  Callback<Tweak::Effect> CB);
+
+  /// Called when an event occurs for a watched file in the workspace.
+  void onFileEvent(const DidChangeWatchedFilesParams &Params);
+
+  /// Get symbol info for given position.
+  /// Clangd extension - not part of official LSP.
+  void symbolInfo(PathRef File, Position Pos,
+                  Callback<std::vector<SymbolDetails>> CB);
+
+  /// Get semantic ranges around a specified position in a file.
+  void semanticRanges(PathRef File, const std::vector<Position> &Pos,
+                      Callback<std::vector<SelectionRange>> CB);
+
+  /// Get all document links in a file.
+  void documentLinks(PathRef File, Callback<std::vector<DocumentLink>> CB);
+
+  void semanticHighlights(PathRef File,
+                          Callback<std::vector<HighlightingToken>>);
+
+  /// Describe the AST subtree for a piece of code.
+  void getAST(PathRef File, std::optional<Range> R,
+              Callback<std::optional<ASTNode>> CB);
+
+  /// Runs an arbitrary action that has access to the AST of the specified file.
+  /// The action will execute on one of ClangdServer's internal threads.
+  /// The AST is only valid for the duration of the callback.
+  /// As with other actions, the file must have been opened.
+  void customAction(PathRef File, llvm::StringRef Name,
+                    Callback<InputsAndAST> Action);
+
+  /// Fetches diagnostics for current version of the \p File. This might fail if
+  /// server is busy (building a preamble) and would require a long time to
+  /// prepare diagnostics. If it fails, clients should wait for
+  /// onSemanticsMaybeChanged and then retry.
+  /// These 'pulled' diagnostics do not interfere with the diagnostics 'pushed'
+  /// to Callbacks::onDiagnosticsReady, and clients may use either or both.
+  void diagnostics(PathRef File, Callback<std::vector<Diag>> CB);
+
+  /// Returns estimated memory usage and other statistics for each of the
+  /// currently open files.
+  /// Overall memory usage of clangd may be significantly more than reported
+  /// here, as this metric does not account (at least) for:
+  ///   - memory occupied by static and dynamic index,
+  ///   - memory required for in-flight requests,
+  /// FIXME: those metrics might be useful too, we should add them.
+  llvm::StringMap<TUScheduler::FileStats> fileStats() const;
+
+  /// Gets the contents of a currently tracked file. Returns nullptr if the file
+  /// isn't being tracked.
+  std::shared_ptr<const std::string> getDraft(PathRef File) const;
+
+  // Blocks the main thread until the server is idle. Only for use in tests.
+  // Returns false if the timeout expires.
+  // FIXME: various subcomponents each get the full timeout, so it's more of
+  // an order of magnitude than a hard deadline.
+  [[nodiscard]] bool
+  blockUntilIdleForTest(std::optional<double> TimeoutSeconds = 10);
+
+  /// Builds a nested representation of memory used by components.
+  void profile(MemoryTree &MT) const;
+
+private:
+  FeatureModuleSet *FeatureModules;
+  const GlobalCompilationDatabase &CDB;
+  const ThreadsafeFS &getHeaderFS() const {
+    return UseDirtyHeaders ? *DirtyFS : TFS;
+  }
+  const ThreadsafeFS &TFS;
+
+  Path ResourceDir;
+  // The index used to look up symbols. This could be:
+  //   - null (all index functionality is optional)
+  //   - the dynamic index owned by ClangdServer (DynamicIdx)
+  //   - the static index passed to the constructor
+  //   - a merged view of a static and dynamic index (MergedIndex)
+  const SymbolIndex *Index = nullptr;
+  // If present, an index of symbols in open files. Read via *Index.
+  std::unique_ptr<FileIndex> DynamicIdx;
+  // If present, the new "auto-index" maintained in background threads.
+  std::unique_ptr<BackgroundIndex> BackgroundIdx;
+  // Storage for merged views of the various indexes.
+  std::vector<std::unique_ptr<SymbolIndex>> MergedIdx;
+  // Manage module files.
+  ModulesBuilder *ModulesManager = nullptr;
+
+  // When set, provides clang-tidy options for a specific file.
+  TidyProviderRef ClangTidyProvider;
+
+  bool UseDirtyHeaders = false;
+
+  // Whether the client supports folding only complete lines.
+  bool LineFoldingOnly = false;
+
+  bool PreambleParseForwardingFunctions = true;
+
+  bool ImportInsertions = false;
+
+  bool PublishInactiveRegions = false;
+
+  // GUARDED_BY(CachedCompletionFuzzyFindRequestMutex)
+  llvm::StringMap<std::optional<FuzzyFindRequest>>
+      CachedCompletionFuzzyFindRequestByFile;
+  mutable std::mutex CachedCompletionFuzzyFindRequestMutex;
+
+  std::optional<std::string> WorkspaceRoot;
+  std::optional<AsyncTaskRunner> IndexTasks; // for stdlib indexing.
+  std::optional<TUScheduler> WorkScheduler;
+  // Invalidation policy used for actions that we assume are "transient".
+  TUScheduler::ASTActionInvalidation Transient;
+
+  // Store of the current versions of the open documents.
+  // Only written from the main thread (despite being threadsafe).
+  DraftStore DraftMgr;
+
+  std::unique_ptr<ThreadsafeFS> DirtyFS;
+};
+
+} // namespace clangd
+} // namespace clang
+
+#endif

openspec/changes/explore-improve-folding-range-support/reference/clangd/llvmorg-21.1.8/clang-tools-extra/clangd/SemanticSelection.cpp

@@ -0,0 +1,274 @@
+//===--- SemanticSelection.cpp -----------------------------------*- C++-*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "SemanticSelection.h"
+#include "ParsedAST.h"
+#include "Protocol.h"
+#include "Selection.h"
+#include "SourceCode.h"
+#include "clang/AST/DeclBase.h"
+#include "clang/Basic/SourceLocation.h"
+#include "clang/Basic/SourceManager.h"
+#include "clang/Tooling/Syntax/BuildTree.h"
+#include "clang/Tooling/Syntax/Nodes.h"
+#include "clang/Tooling/Syntax/TokenBufferTokenManager.h"
+#include "clang/Tooling/Syntax/Tree.h"
+#include "llvm/ADT/ArrayRef.h"
+#include "llvm/ADT/StringRef.h"
+#include "llvm/Support/Casting.h"
+#include "llvm/Support/Error.h"
+#include "support/Bracket.h"
+#include "support/DirectiveTree.h"
+#include "support/Token.h"
+#include <optional>
+#include <queue>
+#include <vector>
+
+namespace clang {
+namespace clangd {
+namespace {
+
+// Adds Range \p R to the Result if it is distinct from the last added Range.
+// Assumes that only consecutive ranges can coincide.
+void addIfDistinct(const Range &R, std::vector<Range> &Result) {
+  if (Result.empty() || Result.back() != R) {
+    Result.push_back(R);
+  }
+}
+
+std::optional<FoldingRange> toFoldingRange(SourceRange SR,
+                                           const SourceManager &SM) {
+  const auto Begin = SM.getDecomposedLoc(SR.getBegin()),
+             End = SM.getDecomposedLoc(SR.getEnd());
+  // Do not produce folding ranges if either range ends is not within the main
+  // file. Macros have their own FileID so this also checks if locations are not
+  // within the macros.
+  if ((Begin.first != SM.getMainFileID()) || (End.first != SM.getMainFileID()))
+    return std::nullopt;
+  FoldingRange Range;
+  Range.startCharacter = SM.getColumnNumber(Begin.first, Begin.second) - 1;
+  Range.startLine = SM.getLineNumber(Begin.first, Begin.second) - 1;
+  Range.endCharacter = SM.getColumnNumber(End.first, End.second) - 1;
+  Range.endLine = SM.getLineNumber(End.first, End.second) - 1;
+  return Range;
+}
+
+std::optional<FoldingRange>
+extractFoldingRange(const syntax::Node *Node,
+                    const syntax::TokenBufferTokenManager &TM) {
+  if (const auto *Stmt = dyn_cast<syntax::CompoundStatement>(Node)) {
+    const auto *LBrace = cast_or_null<syntax::Leaf>(
+        Stmt->findChild(syntax::NodeRole::OpenParen));
+    // FIXME(kirillbobyrev): This should find the last child. Compound
+    // statements have only one pair of braces so this is valid but for other
+    // node kinds it might not be correct.
+    const auto *RBrace = cast_or_null<syntax::Leaf>(
+        Stmt->findChild(syntax::NodeRole::CloseParen));
+    if (!LBrace || !RBrace)
+      return std::nullopt;
+    // Fold the entire range within braces, including whitespace.
+    const SourceLocation LBraceLocInfo =
+                             TM.getToken(LBrace->getTokenKey())->endLocation(),
+                         RBraceLocInfo =
+                             TM.getToken(RBrace->getTokenKey())->location();
+    auto Range = toFoldingRange(SourceRange(LBraceLocInfo, RBraceLocInfo),
+                                TM.sourceManager());
+    // Do not generate folding range for compound statements without any
+    // nodes and newlines.
+    if (Range && Range->startLine != Range->endLine)
+      return Range;
+  }
+  return std::nullopt;
+}
+
+// Traverse the tree and collect folding ranges along the way.
+std::vector<FoldingRange>
+collectFoldingRanges(const syntax::Node *Root,
+                     const syntax::TokenBufferTokenManager &TM) {
+  std::queue<const syntax::Node *> Nodes;
+  Nodes.push(Root);
+  std::vector<FoldingRange> Result;
+  while (!Nodes.empty()) {
+    const syntax::Node *Node = Nodes.front();
+    Nodes.pop();
+    const auto Range = extractFoldingRange(Node, TM);
+    if (Range)
+      Result.push_back(*Range);
+    if (const auto *T = dyn_cast<syntax::Tree>(Node))
+      for (const auto *NextNode = T->getFirstChild(); NextNode;
+           NextNode = NextNode->getNextSibling())
+        Nodes.push(NextNode);
+  }
+  return Result;
+}
+
+} // namespace
+
+llvm::Expected<SelectionRange> getSemanticRanges(ParsedAST &AST, Position Pos) {
+  std::vector<Range> Ranges;
+  const auto &SM = AST.getSourceManager();
+  const auto &LangOpts = AST.getLangOpts();
+
+  auto FID = SM.getMainFileID();
+  auto Offset = positionToOffset(SM.getBufferData(FID), Pos);
+  if (!Offset) {
+    return Offset.takeError();
+  }
+
+  // Get node under the cursor.
+  SelectionTree ST = SelectionTree::createRight(
+      AST.getASTContext(), AST.getTokens(), *Offset, *Offset);
+  for (const auto *Node = ST.commonAncestor(); Node != nullptr;
+       Node = Node->Parent) {
+    if (const Decl *D = Node->ASTNode.get<Decl>()) {
+      if (llvm::isa<TranslationUnitDecl>(D)) {
+        break;
+      }
+    }
+
+    auto SR = toHalfOpenFileRange(SM, LangOpts, Node->ASTNode.getSourceRange());
+    if (!SR || SM.getFileID(SR->getBegin()) != SM.getMainFileID()) {
+      continue;
+    }
+    Range R;
+    R.start = sourceLocToPosition(SM, SR->getBegin());
+    R.end = sourceLocToPosition(SM, SR->getEnd());
+    addIfDistinct(R, Ranges);
+  }
+
+  if (Ranges.empty()) {
+    // LSP provides no way to signal "the point is not within a semantic range".
+    // Return an empty range at the point.
+    SelectionRange Empty;
+    Empty.range.start = Empty.range.end = Pos;
+    return std::move(Empty);
+  }
+
+  // Convert to the LSP linked-list representation.
+  SelectionRange Head;
+  Head.range = std::move(Ranges.front());
+  SelectionRange *Tail = &Head;
+  for (auto &Range :
+       llvm::MutableArrayRef(Ranges.data(), Ranges.size()).drop_front()) {
+    Tail->parent = std::make_unique<SelectionRange>();
+    Tail = Tail->parent.get();
+    Tail->range = std::move(Range);
+  }
+
+  return std::move(Head);
+}
+
+// FIXME(kirillbobyrev): Collect comments, PP conditional regions, includes and
+// other code regions (e.g. public/private/protected sections of classes,
+// control flow statement bodies).
+// Related issue: https://github.com/clangd/clangd/issues/310
+llvm::Expected<std::vector<FoldingRange>> getFoldingRanges(ParsedAST &AST) {
+  syntax::Arena A;
+  syntax::TokenBufferTokenManager TM(AST.getTokens(), AST.getLangOpts(),
+                                     AST.getSourceManager());
+  const auto *SyntaxTree = syntax::buildSyntaxTree(A, TM, AST.getASTContext());
+  return collectFoldingRanges(SyntaxTree, TM);
+}
+
+// FIXME( usaxena95): Collect PP conditional regions, includes and other code
+// regions (e.g. public/private/protected sections of classes, control flow
+// statement bodies).
+// Related issue: https://github.com/clangd/clangd/issues/310
+llvm::Expected<std::vector<FoldingRange>>
+getFoldingRanges(const std::string &Code, bool LineFoldingOnly) {
+  auto OrigStream = lex(Code, genericLangOpts());
+
+  auto DirectiveStructure = DirectiveTree::parse(OrigStream);
+  chooseConditionalBranches(DirectiveStructure, OrigStream);
+
+  // FIXME: Provide ranges in the disabled-PP regions as well.
+  auto Preprocessed = DirectiveStructure.stripDirectives(OrigStream);
+
+  auto ParseableStream = cook(Preprocessed, genericLangOpts());
+  pairBrackets(ParseableStream);
+
+  std::vector<FoldingRange> Result;
+  auto AddFoldingRange = [&](Position Start, Position End,
+                             llvm::StringLiteral Kind) {
+    if (Start.line >= End.line)
+      return;
+    FoldingRange FR;
+    FR.startLine = Start.line;
+    FR.startCharacter = Start.character;
+    FR.endLine = End.line;
+    FR.endCharacter = End.character;
+    FR.kind = Kind.str();
+    Result.push_back(FR);
+  };
+  auto OriginalToken = [&](const Token &T) {
+    return OrigStream.tokens()[T.OriginalIndex];
+  };
+  auto StartOffset = [&](const Token &T) {
+    return OriginalToken(T).text().data() - Code.data();
+  };
+  auto StartPosition = [&](const Token &T) {
+    return offsetToPosition(Code, StartOffset(T));
+  };
+  auto EndOffset = [&](const Token &T) {
+    return StartOffset(T) + OriginalToken(T).Length;
+  };
+  auto EndPosition = [&](const Token &T) {
+    return offsetToPosition(Code, EndOffset(T));
+  };
+  auto Tokens = ParseableStream.tokens();
+  // Brackets.
+  for (const auto &Tok : Tokens) {
+    if (auto *Paired = Tok.pair()) {
+      // Process only token at the start of the range. Avoid ranges on a single
+      // line.
+      if (Tok.Line < Paired->Line) {
+        Position Start = offsetToPosition(Code, 1 + StartOffset(Tok));
+        Position End = StartPosition(*Paired);
+        if (LineFoldingOnly)
+          End.line--;
+        AddFoldingRange(Start, End, FoldingRange::REGION_KIND);
+      }
+    }
+  }
+  auto IsBlockComment = [&](const Token &T) {
+    assert(T.Kind == tok::comment);
+    return OriginalToken(T).Length >= 2 &&
+           Code.substr(StartOffset(T), 2) == "/*";
+  };
+  // Multi-line comments.
+  for (auto *T = Tokens.begin(); T != Tokens.end();) {
+    if (T->Kind != tok::comment) {
+      T++;
+      continue;
+    }
+    Token *FirstComment = T;
+    // Show starting sentinals (// and /*) of the comment.
+    Position Start = offsetToPosition(Code, 2 + StartOffset(*FirstComment));
+    Token *LastComment = T;
+    Position End = EndPosition(*T);
+    while (T != Tokens.end() && T->Kind == tok::comment &&
+           StartPosition(*T).line <= End.line + 1) {
+      End = EndPosition(*T);
+      LastComment = T;
+      T++;
+    }
+    if (IsBlockComment(*FirstComment)) {
+      if (LineFoldingOnly)
+        // Show last line of a block comment.
+        End.line--;
+      if (IsBlockComment(*LastComment))
+        // Show ending sentinal "*/" of the block comment.
+        End.character -= 2;
+    }
+    AddFoldingRange(Start, End, FoldingRange::COMMENT_KIND);
+  }
+  return Result;
+}
+
+} // namespace clangd
+} // namespace clang

openspec/changes/explore-improve-folding-range-support/reference/clangd/llvmorg-21.1.8/clang-tools-extra/clangd/SemanticSelection.h

@@ -0,0 +1,41 @@
+//===--- SemanticSelection.h -------------------------------------*- C++-*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// Features for giving interesting semantic ranges around the cursor.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_SEMANTICSELECTION_H
+#define LLVM_CLANG_TOOLS_EXTRA_CLANGD_SEMANTICSELECTION_H
+#include "ParsedAST.h"
+#include "Protocol.h"
+#include "llvm/Support/Error.h"
+#include <string>
+#include <vector>
+namespace clang {
+namespace clangd {
+
+/// Returns the list of all interesting ranges around the Position \p Pos.
+/// The interesting ranges corresponds to the AST nodes in the SelectionTree
+/// containing \p Pos.
+/// If pos is not in any interesting range, return [Pos, Pos).
+llvm::Expected<SelectionRange> getSemanticRanges(ParsedAST &AST, Position Pos);
+
+/// Returns a list of ranges whose contents might be collapsible in an editor.
+/// This should include large scopes, preprocessor blocks etc.
+llvm::Expected<std::vector<FoldingRange>> getFoldingRanges(ParsedAST &AST);
+
+/// Returns a list of ranges whose contents might be collapsible in an editor.
+/// This version uses the pseudoparser which does not require the AST.
+llvm::Expected<std::vector<FoldingRange>>
+getFoldingRanges(const std::string &Code, bool LineFoldingOnly);
+
+} // namespace clangd
+} // namespace clang
+
+#endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_SEMANTICSELECTION_H

openspec/changes/explore-improve-folding-range-support/reference/clangd/llvmorg-21.1.8/clang-tools-extra/clangd/test/folding-range.test

@@ -0,0 +1,24 @@
+# RUN: clangd -lit-test < %s | FileCheck -strict-whitespace %s
+void f() {
+
+}
+---
+{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"processId":123,"rootPath":"clangd","capabilities":{"textDocument": {"foldingRange": {"lineFoldingOnly": true}}},"trace":"off"}}
+---
+{"jsonrpc":"2.0","method":"textDocument/didOpen","params":{"textDocument":{"languageId":"cpp","text":"void f() {\n\n}\n","uri":"test:///foo.cpp","version":1}}}
+---
+{"id":1,"jsonrpc":"2.0","method":"textDocument/foldingRange","params":{"textDocument":{"uri":"test:///foo.cpp"}}}
+# CHECK:      "id": 1,
+# CHECK-NEXT: "jsonrpc": "2.0",
+# CHECK-NEXT: "result": [
+# CHECK-NEXT:   {
+# CHECK-NEXT:     "endLine": 1,
+# CHECK-NEXT:     "kind": "region", 
+# CHECK-NEXT:     "startCharacter": 10,
+# CHECK-NEXT:     "startLine": 0
+# CHECK-NEXT:   }
+# CHECK-NEXT: ]
+---
+{"jsonrpc":"2.0","id":5,"method":"shutdown"}
+---
+{"jsonrpc":"2.0","method":"exit"}

openspec/changes/explore-improve-folding-range-support/reference/clangd/llvmorg-21.1.8/clang-tools-extra/clangd/unittests/SemanticSelectionTests.cpp

@@ -0,0 +1,459 @@
+//===-- SemanticSelectionTests.cpp  ----------------*- C++ -*--------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "Annotations.h"
+#include "ClangdServer.h"
+#include "Protocol.h"
+#include "SemanticSelection.h"
+#include "SyncAPI.h"
+#include "TestFS.h"
+#include "TestTU.h"
+#include "llvm/ADT/ArrayRef.h"
+#include "llvm/Support/Error.h"
+#include "gmock/gmock.h"
+#include "gtest/gtest.h"
+#include <vector>
+
+namespace clang {
+namespace clangd {
+namespace {
+
+using ::testing::ElementsAre;
+using ::testing::ElementsAreArray;
+using ::testing::UnorderedElementsAreArray;
+
+// front() is SR.range, back() is outermost range.
+std::vector<Range> gatherRanges(const SelectionRange &SR) {
+  std::vector<Range> Ranges;
+  for (const SelectionRange *S = &SR; S; S = S->parent.get())
+    Ranges.push_back(S->range);
+  return Ranges;
+}
+
+std::vector<Range>
+gatherFoldingRanges(llvm::ArrayRef<FoldingRange> FoldingRanges) {
+  std::vector<Range> Ranges;
+  Range NextRange;
+  for (const auto &R : FoldingRanges) {
+    NextRange.start.line = R.startLine;
+    NextRange.start.character = R.startCharacter;
+    NextRange.end.line = R.endLine;
+    NextRange.end.character = R.endCharacter;
+    Ranges.push_back(NextRange);
+  }
+  return Ranges;
+}
+
+TEST(SemanticSelection, All) {
+  const char *Tests[] = {
+      R"cpp( // Single statement in a function body.
+        [[void func() [[{
+          [[[[int v = [[1^00]]]];]]
+        }]]]]
+      )cpp",
+      R"cpp( // Expression
+        [[void func() [[{
+          int a = 1;
+          // int v = (10 + 2) * (a + a);
+          [[[[int v = [[[[([[[[10^]] + 2]])]] * (a + a)]]]];]]
+        }]]]]
+      )cpp",
+      R"cpp( // Function call.
+        int add(int x, int y) { return x + y; }
+        [[void callee() [[{
+          // int res = add(11, 22);
+          [[[[int res = [[add([[1^1]], 22)]]]];]]
+        }]]]]
+      )cpp",
+      R"cpp( // Tricky macros.
+        #define MUL ) * (
+        [[void func() [[{
+          // int var = (4 + 15 MUL 6 + 10);
+          [[[[int var = [[[[([[4 + [[1^5]]]] MUL]] 6 + 10)]]]];]]
+        }]]]]
+       )cpp",
+      R"cpp( // Cursor inside a macro.
+        #define HASH(x) ((x) % 10)
+        [[void func() [[{
+          [[[[int a = [[HASH([[[[2^3]] + 34]])]]]];]]
+        }]]]]
+       )cpp",
+      R"cpp( // Cursor on a macro.
+        #define HASH(x) ((x) % 10)
+        [[void func() [[{
+          [[[[int a = [[HA^SH(23)]]]];]]
+        }]]]]
+       )cpp",
+      R"cpp( // Multiple declaration.
+        [[void func() [[{
+          [[[[int var1, var^2]], var3;]]
+        }]]]]
+       )cpp",
+      R"cpp( // Before comment.
+        [[void func() [[{
+          int var1 = 1;
+          [[[[int var2 = [[[[var1]]^ /*some comment*/ + 41]]]];]]
+        }]]]]
+       )cpp",
+      // Empty file.
+      "[[^]]",
+      // FIXME: We should get the whole DeclStmt as a range.
+      R"cpp( // Single statement in TU.
+        [[int v = [[1^00]]]];
+      )cpp",
+      R"cpp( // Cursor at end of VarDecl.
+        [[int v = [[100]]^]];
+      )cpp",
+      // FIXME: No node found associated to the position.
+      R"cpp( // Cursor in between spaces.
+        void func() {
+          int v = 100 + [[^]]  100;
+        }
+      )cpp",
+      // Structs.
+      R"cpp(
+        struct AAA { struct BBB { static int ccc(); };};
+        [[void func() [[{
+          // int x = AAA::BBB::ccc();
+          [[[[int x = [[[[AAA::BBB::c^cc]]()]]]];]]
+        }]]]]
+      )cpp",
+      R"cpp(
+        struct AAA { struct BBB { static int ccc(); };};
+        [[void func() [[{
+          // int x = AAA::BBB::ccc();
+          [[[[int x = [[[[[[[[[[AA^A]]::]]BBB::]]ccc]]()]]]];]]
+        }]]]]
+      )cpp",
+      R"cpp( // Inside struct.
+        struct A { static int a(); };
+        [[struct B {
+          [[static int b() [[{
+            [[return [[[[1^1]] + 2]]]];
+          }]]]]
+        }]];
+      )cpp",
+      // Namespaces.
+      R"cpp(
+        [[namespace nsa {
+          [[namespace nsb {
+            static int ccc();
+            [[void func() [[{
+              // int x = nsa::nsb::ccc();
+              [[[[int x = [[[[nsa::nsb::cc^c]]()]]]];]]
+            }]]]]
+          }]]
+        }]]
+      )cpp",
+
+  };
+
+  for (const char *Test : Tests) {
+    auto T = Annotations(Test);
+    auto AST = TestTU::withCode(T.code()).build();
+    EXPECT_THAT(gatherRanges(llvm::cantFail(getSemanticRanges(AST, T.point()))),
+                ElementsAreArray(T.ranges()))
+        << Test;
+  }
+}
+
+TEST(SemanticSelection, RunViaClangdServer) {
+  MockFS FS;
+  MockCompilationDatabase CDB;
+  ClangdServer Server(CDB, FS, ClangdServer::optsForTest());
+
+  auto FooH = testPath("foo.h");
+  FS.Files[FooH] = R"cpp(
+    int foo(int x);
+    #define HASH(x) ((x) % 10)
+  )cpp";
+
+  auto FooCpp = testPath("Foo.cpp");
+  const char *SourceContents = R"cpp(
+  #include "foo.h"
+  [[void bar(int& inp) [[{
+    // inp = HASH(foo(inp));
+    [[inp = [[HASH([[foo([[in^p]])]])]]]];
+  }]]]]
+  $empty[[^]]
+  )cpp";
+  Annotations SourceAnnotations(SourceContents);
+  FS.Files[FooCpp] = std::string(SourceAnnotations.code());
+  Server.addDocument(FooCpp, SourceAnnotations.code());
+
+  auto Ranges = runSemanticRanges(Server, FooCpp, SourceAnnotations.points());
+  ASSERT_TRUE(bool(Ranges))
+      << "getSemanticRange returned an error: " << Ranges.takeError();
+  ASSERT_EQ(Ranges->size(), SourceAnnotations.points().size());
+  EXPECT_THAT(gatherRanges(Ranges->front()),
+              ElementsAreArray(SourceAnnotations.ranges()));
+  EXPECT_THAT(gatherRanges(Ranges->back()),
+              ElementsAre(SourceAnnotations.range("empty")));
+}
+
+TEST(FoldingRanges, ASTAll) {
+  const char *Tests[] = {
+      R"cpp(
+        #define FOO int foo() {\
+          int Variable = 42; \
+          return 0; \
+        }
+
+        // Do not generate folding range for braces within macro expansion.
+        FOO
+
+        // Do not generate folding range within macro arguments.
+        #define FUNCTOR(functor) functor
+        void func() {[[
+          FUNCTOR([](){});
+        ]]}
+
+        // Do not generate folding range with a brace coming from macro.
+        #define LBRACE {
+        void bar() LBRACE
+          int X = 42;
+        }
+      )cpp",
+      R"cpp(
+        void func() {[[
+          int Variable = 100;
+
+          if (Variable > 5) {[[
+            Variable += 42;
+          ]]} else if (Variable++)
+            ++Variable;
+          else {[[
+            Variable--;
+          ]]}
+
+          // Do not generate FoldingRange for empty CompoundStmts.
+          for (;;) {}
+
+          // If there are newlines between {}, we should generate one.
+          for (;;) {[[
+
+          ]]}
+        ]]}
+      )cpp",
+      R"cpp(
+        class Foo {
+        public:
+          Foo() {[[
+            int X = 1;
+          ]]}
+
+        private:
+          int getBar() {[[
+            return 42;
+          ]]}
+
+          // Braces are located at the same line: no folding range here.
+          void getFooBar() { }
+        };
+      )cpp",
+  };
+  for (const char *Test : Tests) {
+    auto T = Annotations(Test);
+    auto AST = TestTU::withCode(T.code()).build();
+    EXPECT_THAT(gatherFoldingRanges(llvm::cantFail(getFoldingRanges(AST))),
+                UnorderedElementsAreArray(T.ranges()))
+        << Test;
+  }
+}
+
+TEST(FoldingRanges, PseudoParserWithoutLineFoldings) {
+  const char *Tests[] = {
+      R"cpp(
+        #define FOO int foo() {\
+          int Variable = 42; \
+        }
+
+        // Do not generate folding range for braces within macro expansion.
+        FOO
+
+        // Do not generate folding range within macro arguments.
+        #define FUNCTOR(functor) functor
+        void func() {[[
+          FUNCTOR([](){});
+        ]]}
+
+        // Do not generate folding range with a brace coming from macro.
+        #define LBRACE {
+        void bar() LBRACE
+          int X = 42;
+        }
+      )cpp",
+      R"cpp(
+        void func() {[[
+          int Variable = 100;
+
+          if (Variable > 5) {[[
+            Variable += 42;
+          ]]} else if (Variable++)
+            ++Variable;
+          else {[[
+            Variable--;
+          ]]}
+
+          // Do not generate FoldingRange for empty CompoundStmts.
+          for (;;) {}
+
+          // If there are newlines between {}, we should generate one.
+          for (;;) {[[
+
+          ]]}
+        ]]}
+      )cpp",
+      R"cpp(
+        class Foo {[[
+        public:
+          Foo() {[[
+            int X = 1;
+          ]]}
+
+        private:
+          int getBar() {[[
+            return 42;
+          ]]}
+
+          // Braces are located at the same line: no folding range here.
+          void getFooBar() { }
+        ]]};
+      )cpp",
+      R"cpp(
+        // Range boundaries on escaped newlines.
+        class Foo \
+        \
+        {[[  \
+        public:
+          Foo() {[[\
+            int X = 1;
+          ]]}   \
+        ]]};
+      )cpp",
+      R"cpp(
+        /*[[ Multi
+          * line
+          *  comment
+          ]]*/
+      )cpp",
+      R"cpp(
+        //[[ Comment
+        // 1]]
+
+        //[[ Comment
+        // 2]]
+
+        // No folding for single line comment.
+
+        /*[[ comment 3
+        ]]*/
+
+        /*[[ comment 4
+        ]]*/
+
+        /*[[ foo */
+        /* bar ]]*/
+
+        /*[[ foo */
+        // baz
+        /* bar ]]*/
+
+        /*[[ foo */
+        /* bar*/
+        // baz]]
+
+        //[[ foo
+        /* bar */]]
+      )cpp",
+  };
+  for (const char *Test : Tests) {
+    auto T = Annotations(Test);
+    EXPECT_THAT(gatherFoldingRanges(llvm::cantFail(getFoldingRanges(
+                    T.code().str(), /*LineFoldingsOnly=*/false))),
+                UnorderedElementsAreArray(T.ranges()))
+        << Test;
+  }
+}
+
+TEST(FoldingRanges, PseudoParserLineFoldingsOnly) {
+  const char *Tests[] = {
+      R"cpp(
+        void func(int a) {[[
+            a++;]]
+        }
+      )cpp",
+      R"cpp(
+        // Always exclude last line for brackets.
+        void func(int a) {[[
+          if(a == 1) {[[
+            a++;]]
+          } else if (a == 2){[[
+            a--;]]
+          } else {  // No folding for 2 line bracketed ranges.
+          }]]
+        }
+      )cpp",
+      R"cpp(
+        /*[[ comment
+        * comment]]
+        */
+
+        /* No folding for this comment.
+        */
+
+        // No folding for this comment.
+
+        //[[ 2 single line comment.
+        // 2 single line comment.]]
+
+        //[[ >=2 line comments.
+        // >=2 line comments.
+        // >=2 line comments.]]
+
+        //[[ foo\
+        bar\
+        baz]]
+
+        /*[[ foo */
+        /* bar */]]
+        /* baz */
+
+        /*[[ foo */
+        /* bar]]
+        * This does not fold me */
+
+        //[[ foo
+        /* bar */]]
+      )cpp",
+      // FIXME: Support folding template arguments.
+      // R"cpp(
+      // template <[[typename foo, class bar]]> struct baz {};
+      // )cpp",
+
+  };
+  auto StripColumns = [](const std::vector<Range> &Ranges) {
+    std::vector<Range> Res;
+    for (Range R : Ranges) {
+      R.start.character = R.end.character = 0;
+      Res.push_back(R);
+    }
+    return Res;
+  };
+  for (const char *Test : Tests) {
+    auto T = Annotations(Test);
+    EXPECT_THAT(
+        StripColumns(gatherFoldingRanges(llvm::cantFail(
+            getFoldingRanges(T.code().str(), /*LineFoldingsOnly=*/true)))),
+        UnorderedElementsAreArray(StripColumns(T.ranges())))
+        << Test;
+  }
+}
+} // namespace
+} // namespace clangd
+} // namespace clang

openspec/changes/explore-improve-folding-range-support/specs/folding-ranges/spec.md

@@ -0,0 +1,70 @@
+## ADDED Requirements
+
+### Requirement: Folding range responses honor client capabilities
+The server SHALL render folding ranges according to the client's declared folding capabilities instead of always returning the richest possible payload.
+
+#### Scenario: Line-only folding is respected
+- **WHEN** the client declares `textDocument.foldingRange.lineFoldingOnly = true`
+- **THEN** the server MUST return folding ranges that remain valid when interpreted as whole-line folds, including adjusting end boundaries for bracketed or comment ranges whose closing delimiter is on the last line
+
+#### Scenario: Client line-only support is propagated through folding options
+- **WHEN** the client declares `textDocument.foldingRange.lineFoldingOnly = true`
+- **THEN** the server MUST invoke folding rendering with options equivalent to `line_folding_only = true`
+- **AND** collectors MUST NOT need to inspect client capability state to produce different raw ranges
+
+#### Scenario: Collapsed text is gated by client support
+- **WHEN** the client does not declare support for `textDocument.foldingRange.foldingRange.collapsedText`
+- **THEN** the server MUST omit `collapsedText` from the folding range response
+
+#### Scenario: Preferred range limits are applied deterministically
+- **WHEN** the client declares `textDocument.foldingRange.rangeLimit = N` and the server can produce more than `N` folding ranges for a document
+- **THEN** the server MUST return no more than `N` ranges and MUST choose them using a deterministic ordering rule
+
+#### Scenario: Standard kinds are emitted compatibly
+- **WHEN** a folding range represents a comment block, an include/import block, or any other foldable region
+- **THEN** the server MUST emit `kind = comment`, `kind = imports`, or `kind = region` respectively, and MUST NOT require clients to understand clice-specific kind strings in order to fold correctly
+
+### Requirement: Structural and comment folding baseline
+The server SHALL provide folding ranges for multi-line C/C++ structural regions and multi-line comments in the main file.
+
+#### Scenario: Multi-line comment blocks can be folded
+- **WHEN** a document contains a multi-line `/* ... */` comment or a contiguous block of `//` comments spanning more than one line
+- **THEN** the server MUST return a folding range for that comment block with `kind = comment`
+
+#### Scenario: Single-line comments are not folded
+- **WHEN** a document contains a single-line comment that does not extend across multiple lines and is not part of a larger contiguous comment block
+- **THEN** the server MUST NOT return a folding range for that comment
+
+#### Scenario: Existing structural regions remain foldable
+- **WHEN** a document contains a multi-line namespace, record, function body, parameter list, lambda body, initializer list, or other supported structural region already collected by clice
+- **THEN** the server MUST continue to return a folding range for that region if its boundaries can be mapped back to the main file
+
+### Requirement: Preprocessor regions fold as complete branch blocks
+The server SHALL provide complete and nested folding ranges for preprocessor branch structures instead of leaving the final branch in a conditional block unclosed.
+
+#### Scenario: Final conditional branch closes at endif
+- **WHEN** a document contains a `#if/#elif/#else/#endif` chain
+- **THEN** the server MUST generate a folding range for each multi-line branch body, including the last branch body that ends at `#endif`
+
+#### Scenario: Inactive conditional branches can be folded
+- **WHEN** a conditional branch is known to be inactive or skipped in the current preprocessing configuration
+- **THEN** the server MUST be able to return a folding range covering that inactive branch region using `kind = region`
+
+#### Scenario: Nested pragma regions are folded
+- **WHEN** a document contains nested `#pragma region` / `#pragma endregion` pairs in the main file
+- **THEN** the server MUST return properly nested folding ranges for each matched region pair
+
+### Requirement: C/C++ directive groups and multiline macros are foldable
+The server SHALL use clice's preprocessor metadata to expose foldable ranges that clangd does not currently provide.
+
+#### Scenario: Multi-line macro definitions can be folded
+- **WHEN** a document contains a multi-line macro definition whose body spans more than one physical line
+- **THEN** the server MUST return a folding range for that macro definition using `kind = region`
+
+#### Scenario: Consecutive include directives are grouped
+- **WHEN** a document contains a contiguous block of `#include` directives with no intervening non-trivia code lines
+- **THEN** the server MUST return a folding range covering that include block using `kind = imports`
+
+#### Scenario: Consecutive module imports are grouped
+- **WHEN** a document contains a contiguous block of C++ module `import` declarations with no intervening non-trivia code lines
+- **THEN** the server MUST return a folding range covering that import block using `kind = imports`

openspec/changes/explore-improve-folding-range-support/tasks.md

@@ -0,0 +1,39 @@
+## 1. Reference Snapshot
+
+- [x] 1.1 Download the clangd folding-range reference files for `llvmorg-21.1.8` into `openspec/changes/explore-improve-folding-range-support/reference/clangd/llvmorg-21.1.8/` using `curl` against GitHub raw URLs.
+- [x] 1.2 Include `SemanticSelection.{cpp,h}`, `ClangdServer.{cpp,h}`, `ClangdLSPServer.cpp`, `Protocol.{h,cpp}`, `test/folding-range.test`, and `unittests/SemanticSelectionTests.cpp`.
+- [x] 1.3 Record the exact raw GitHub URLs and downloaded file layout in a change-local comparison note.
+
+## 2. Comparison and Pipeline
+
+- [x] 2.1 Record a side-by-side comparison in the change artifacts between clangd's folding path and clice's current path, calling out confirmed parity gaps, clice-only capabilities, and known bugs.
+- [ ] 2.2 Keep the existing `RawFoldingRange` model as the settled collection contract while completing normalization and options-driven rendering.
+- [ ] 2.3 Replace direct exposure of clice-specific public folding kinds with a stable mapping to standard LSP `comment` / `imports` / `region` kinds.
+
+## 3. Comment and Structural Baseline
+
+- [ ] 3.1 Add a comment collector that folds multi-line block comments and contiguous multi-line `//` comment groups in the main file.
+- [ ] 3.2 Preserve existing AST structural folding behavior while routing it through the new normalization/rendering pipeline.
+- [ ] 3.3 Add focused unit tests for comment folding, single-line comment exclusion, and structural folding regressions.
+
+## 4. Preprocessor Folding
+
+- [ ] 4.1 Rework conditional-directive collection so each `#if/#elif/#else/#endif` branch body closes correctly, including the final branch ending at `#endif`.
+- [ ] 4.2 Add folding support for inactive conditional branches using the existing preprocessor condition metadata.
+- [ ] 4.3 Strengthen `#pragma region` handling and convert the current placeholder directive tests into assertion-backed coverage.
+
+## 5. Protocol and Rendering
+
+- [ ] 5.1 Capture client folding capabilities during initialize and translate them into `FoldingRangeOptions`/`Opts` when serving `textDocument/foldingRange`.
+- [ ] 5.2 Honor `lineFoldingOnly` through `opts.line_folding_only`, gate `collapsedText`, and apply deterministic `rangeLimit` trimming during folding-range rendering.
+- [ ] 5.3 Add integration coverage for line-only rendering, standard kind output, optional collapsed text, and range limiting.
+
+## 6. Clice-Specific Folding Extensions
+
+- [ ] 6.1 Add folding ranges for multi-line macro definitions using `directive.macros` and stable main-file source ranges.
+- [ ] 6.2 Add grouping folds for contiguous `#include` blocks and return them as `imports` ranges.
+- [ ] 6.3 Add grouping folds for contiguous C++ module `import` declarations and cover mixed include/import layouts with tests.
+
+## 7. Verification
+
+- [ ] 7.1 Run the relevant folding-range unit and integration tests, then fix any ordering, deduplication, or boundary regressions found during verification.

openspec/changes/split-folding-range-pipeline/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-22

openspec/changes/split-folding-range-pipeline/design.md

@@ -0,0 +1,192 @@
+## Context
+
+This change extracts decision `2` from `openspec/changes/explore-improve-folding-range-support/design.md` into a standalone proposal. The current folding implementation in `src/feature/folding_ranges.cpp` already has an internal `RawFoldingRange` handoff, but it still leaves two important concerns too implicit:
+
+- deciding which ranges survive deduplication and validation
+- shaping the final LSP response, including client-specific output rules such as `line_folding_only`
+
+Follow-up discussion clarified that the existing `RawFoldingRange` shape is finished for this extracted change. The remaining architectural gap is an explicit options path, passed as `Opts`/`FoldingRangeOptions`, so rendering can be configured without reworking collectors. This proposal therefore keeps scope narrow: it does not add new fold categories or redesign raw ranges, but it creates the normalization and options-driven rendering boundaries that later changes can build on without destabilizing existing structural folding.
+
+The downloaded clangd reference confirms both the value and the limit of the upstream design. clangd has useful, tested folding behavior for brace bodies, comment blocks, contiguous `//` groups, and `lineFoldingOnly`, but its implementation largely emits protocol-shaped `FoldingRange` objects directly from collection code. In `SemanticSelection.cpp`, both the AST path and the pseudo-parser path build `FoldingRange` results directly, and the pseudo-parser applies rendering details such as delimiter trimming and `lineFoldingOnly` adjustments while collecting ranges. That is a good behavior reference, but it is not the architecture this extracted change should copy.
+
+`clice` already has stronger ingredients for a real pipeline:
+
+- the existing `RawFoldingRange` gives collectors a feature-local representation that is not a final LSP response
+- `LocalSourceRange` gives us a main-file, half-open offset representation that is independent of LSP position encoding
+- directive metadata already captures information clangd does not expose well, including conditional-branch state, pragma regions, includes, imports, and macro references
+- the current tests are boundary-oriented, which makes them a good fit for validating raw spans before protocol rendering
+
+The design therefore separates "what fold exists in the source" from "how that fold should be emitted to this client". clangd's tested boundary rules are still relevant, but they should become renderer policy selected by options and normalization rules rather than collector output format.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Keep the existing `RawFoldingRange` collection contract stable while completing normalization and rendering boundaries.
+- Preserve the existing AST structural folding categories already supported by `clice`.
+- Make ordering, deduplication, and boundary validation deterministic and testable.
+- Add an explicit folding options object so `line_folding_only` can be configured by callers and consumed only by rendering.
+- Give later changes a stable extension point for comments, directives, and client-driven rendering options.
+
+**Non-Goals:**
+
+- Add comment folding in this change.
+- Fix preprocessor branch-closing behavior in this change.
+- Add new fold categories such as macro definitions or include/import grouping.
+- Redesign or replace the existing `RawFoldingRange` model.
+- Depend on initialize-time client capability plumbing being implemented first.
+
+## Decisions
+
+### 1. Use clangd as a behavior reference, not an architecture template
+
+This change should borrow clangd's confirmed folding behavior where it is useful, especially around multiline comments, contiguous `//` comment groups, main-file-only filtering, and `lineFoldingOnly` boundary shaping. It should not copy clangd's habit of emitting protocol-shaped `FoldingRange` objects directly from collection logic.
+
+Why:
+
+- clangd's tests are valuable because they pin down tricky folding behavior around comments, macro boundaries, and line-only rendering
+- clangd's data flow is intentionally narrow and mixes collection with response shaping
+- `clice` already has richer file-local and directive metadata that supports a cleaner internal representation
+
+Alternative considered:
+
+- Treat clangd's direct `FoldingRange` construction as the architecture to reproduce. Rejected because it would preserve the same coupling this extracted change is meant to remove.
+
+### 2. Treat the existing raw internal folding-range model as finished
+
+Collectors should continue to emit the existing internal `RawFoldingRange` structure instead of final LSP protocol objects. The raw model is sufficient for this extracted change and should not be redesigned as part of adding `line_folding_only` support.
+
+The raw model should remain shaped around file-local source structure, not client capability state. In the current implementation it carries:
+
+- a main-file `LocalSourceRange` span using half-open byte offsets
+- an optional public folding kind to preserve existing behavior
+- an optional collapsed-text hint
+
+```cpp
+struct RawFoldingRange {
+    LocalSourceRange range;
+    std::optional<protocol::FoldingRangeKind> kind;
+    std::string collapsed_text;
+};
+```
+
+The important design choice is that `range` represents the foldable source envelope in the main file while client-specific rendering state stays out of the raw model. For example:
+
+- brace-based structural folds keep their source span and let the renderer decide line-only boundary shaping
+- future block comments can keep the full `/* ... */` span and let the renderer decide whether to hide the closing delimiter or final line
+- future contiguous `//` groups can keep the grouped span and let the renderer decide line-only output
+
+Why:
+
+- collectors should describe what was found, not how it will be serialized
+- `LocalSourceRange` is already the natural coordinate system for `clice`
+- future comment and directive collectors can share the same pipeline contract
+- tests can validate collection independently from rendering
+- the missing `line_folding_only` behavior belongs in options and rendering, not in the raw range shape
+
+Alternatives considered:
+
+- Continue emitting LSP ranges directly from collectors. Rejected because it keeps protocol concerns entangled with source discovery.
+- Expand `RawFoldingRange` now with render-hint fields for line-only behavior. Rejected because follow-up discussion established the raw model as finished for this slice, and line-only support can be configured through rendering options instead.
+
+### 3. Normalize ranges before rendering
+
+All collected ranges should pass through a normalization step before any response is emitted. Normalization is responsible for deterministic ordering, duplicate removal, and rejection of degenerate or unmappable ranges.
+
+Normalization should operate on raw spans and raw metadata, not on already-rendered LSP line/character fields. Its responsibilities include:
+
+- deterministic ordering independent of collector traversal order
+- duplicate collapse for collectors that discover the same fold
+- invalid-range filtering after raw spans are mapped and validated
+- stable tie-breaking for overlapping ranges from different origins
+
+Collectors may still reject obviously invalid inputs, such as non-main-file locations that cannot be mapped to `LocalSourceRange`, but normalization remains the phase that decides which collected folds survive to rendering.
+
+Why:
+
+- duplicate or invalid ranges are easier to reason about in one place than across many collectors
+- stable ordering reduces regression noise and makes range limiting predictable later
+- metadata-aware normalization preserves fold meaning until the renderer maps it to public output
+- normalization lets new collectors plug in without each collector re-implementing cleanup logic
+
+Alternative considered:
+
+- Let each collector manage its own sorting and duplicate suppression. Rejected because cross-collector interactions would still remain undefined.
+
+### 4. Keep the current AST visitor as the first collector boundary
+
+The initial extraction should preserve the current AST visitor as one collector feeding the raw model. This reduces refactor risk while still creating the new phase boundaries.
+
+Why:
+
+- the existing structural fold coverage is valuable and should not be rewritten unnecessarily
+- an adapter-style refactor is easier to verify against current tests than a full collector redesign
+
+Alternative considered:
+
+- Rewrite collection around a brand-new multi-source manager immediately. Rejected because it adds scope before the phase split is proven.
+
+### 5. Move output shaping into an options-driven renderer
+
+The renderer should translate normalized ranges into LSP folding ranges. Boundary shaping, output kinds, and optional metadata emission should live there, even if some options still use default values until later protocol plumbing exists.
+
+Renderer input should be the normalized raw model plus a separate `FoldingRangeOptions` structure. The public feature API should follow the existing feature-options style, for example:
+
+```cpp
+struct FoldingRangeOptions {
+    bool line_folding_only = false;
+};
+
+auto folding_ranges(CompilationUnitRef unit,
+                    const FoldingRangeOptions& opts = {},
+                    PositionEncoding encoding = PositionEncoding::UTF16)
+    -> std::vector<protocol::FoldingRange>;
+```
+
+`line_folding_only` defaults to `false`, preserving the current behavior for existing callers. When server capability plumbing is added later, the server should translate `textDocument.foldingRange.lineFoldingOnly` into this option instead of exposing session state to collectors.
+
+The renderer then becomes responsible for:
+
+- converting `LocalSourceRange` into protocol positions for the requested encoding
+- applying line-only adjustments when `opts.line_folding_only = true`
+- mapping raw kind metadata to emitted LSP kinds
+- deciding whether collapsed text is emitted or suppressed
+- later applying deterministic `rangeLimit` trimming without changing collectors
+
+This is the key point where `clice` should intentionally diverge from clangd. clangd threads `lineFoldingOnly` into collection and directly produces protocol objects. `clice` should keep those capability and transport decisions isolated in rendering so collectors remain stable as client support evolves.
+
+Why:
+
+- rendering rules are a separate concern from source discovery
+- later work on line-only output, metadata gating, or public kind mapping should not force collector rewrites
+- clangd-style line-only shaping is still supported, but as renderer policy rather than collector output
+- isolating rendering makes behavioral diffs easier to review
+- a small options object makes the missing `line_folding_only` support explicit without expanding `RawFoldingRange`
+
+Alternative considered:
+
+- Keep final boundary shaping next to the AST collector and only add a small helper for sorting. Rejected because it only moves a symptom, not the architectural problem.
+
+## Risks / Trade-offs
+
+- [Refactoring the current path can accidentally change fold ordering] -> Mitigation: add deterministic-order assertions and compare outputs for existing structural fixtures.
+- [The raw model could become too abstract too early] -> Mitigation: do not redesign `RawFoldingRange` in this change; keep the existing fields unless implementation proves a concrete need.
+- [Line-only behavior can be accidentally encoded in collectors] -> Mitigation: expose `line_folding_only` only through `FoldingRangeOptions` and assert renderer-level behavior in tests.
+- [A renderer abstraction may appear premature before full capability plumbing exists] -> Mitigation: keep default render options aligned with current behavior and treat future options as extension points, not immediate scope.
+
+## Migration Plan
+
+1. Keep the existing `RawFoldingRange` collection path stable behind the current entrypoint.
+2. Introduce `FoldingRangeOptions` with `line_folding_only = false` by default.
+3. Insert normalization between collection and response emission.
+4. Move LSP object construction into a dedicated renderer that consumes normalized ranges plus options.
+5. Add line-only renderer tests and verify that existing structural folding fixtures still produce the expected default ranges.
+
+Rollback strategy:
+
+- If the refactor destabilizes output, keep the new helper types but temporarily route the old direct-emission path until normalization and rendering regressions are resolved.
+
+## Open Questions
+
+- Whether public kind remapping should land in this extracted change or remain a follow-up proposal once the renderer boundary exists.
+- Whether `FoldingRangeOptions` should initially contain only `line_folding_only`, or also reserve fields for later collapsed-text and `rangeLimit` behavior.

openspec/changes/split-folding-range-pipeline/proposal.md

@@ -0,0 +1,29 @@
+## Why
+
+`explore-improve-folding-range-support` combines several different concerns: upstream comparison work, baseline folding fixes, preprocessor extensions, and folding renderer behavior. The second design point in that change, splitting the folding-range pipeline into collection, normalization, and rendering, is the architectural slice that other work depends on and should be referenceable as its own proposal.
+
+Follow-up discussion clarified that the existing internal `RawFoldingRange` shape is finished for this slice. The missing architectural part is not another raw-range redesign; it is an explicit folding options path so callers can request client-specific rendering behavior, starting with `line_folding_only`.
+
+## What Changes
+
+- Extract the pipeline-splitting work from `explore-improve-folding-range-support` into a standalone change focused on folding-range architecture.
+- Treat the existing `RawFoldingRange` model as the settled internal collection contract for this change.
+- Define a normalization phase that performs deterministic sorting, duplicate removal, and boundary validation before response generation.
+- Define a folding options object, passed as `Opts`/`FoldingRangeOptions`, that configures rendering without changing collectors.
+- Define a rendering phase that owns line/column shaping, including `line_folding_only`, and optional metadata emission instead of mixing those concerns into collectors.
+- Preserve the current AST structural folding coverage while establishing extension points for future comment, directive, and capability-aware rendering work.
+
+## Capabilities
+
+### New Capabilities
+- `folding-range-pipeline`: Provide a deterministic folding-range pipeline that separates collection, normalization, and rendering while preserving existing structural folds.
+
+### Modified Capabilities
+- None.
+
+## Impact
+
+- `src/feature/folding_ranges.cpp` will keep raw-range collection but gain explicit normalization/rendering boundaries and options-driven rendering.
+- `src/feature/feature.h` will need a folding options type or equivalent public API extension so `line_folding_only` can be configured without changing collection.
+- `tests/unit/feature/folding_range_tests.cpp` will need regression coverage for structural folds, deterministic ordering, and `line_folding_only` boundary shaping.
+- `openspec/changes/explore-improve-folding-range-support/design.md` remains the source change from which this standalone proposal was extracted.

openspec/changes/split-folding-range-pipeline/specs/folding-range-pipeline/spec.md

@@ -0,0 +1,50 @@
+## ADDED Requirements
+
+### Requirement: Folding ranges are normalized before response emission
+The server SHALL convert collected folding candidates into a deterministic normalized set before emitting the folding range response.
+
+#### Scenario: Duplicate candidates collapse to one emitted fold
+- **WHEN** multiple collectors produce the same folding candidate for the same source span and raw metadata
+- **THEN** the server MUST emit at most one folding range for that candidate
+
+#### Scenario: Invalid candidates are dropped during normalization
+- **WHEN** a collected folding candidate does not span multiple lines or cannot be mapped back to the main file
+- **THEN** the server MUST omit that candidate from the emitted folding ranges
+
+#### Scenario: Output ordering is deterministic
+- **WHEN** the same document is analyzed repeatedly without source changes
+- **THEN** the server MUST emit folding ranges in a deterministic order that does not depend on collector traversal order
+
+### Requirement: Existing structural folding survives the pipeline split
+The server SHALL preserve the currently supported AST structural folding categories after collection, normalization, and rendering are separated.
+
+#### Scenario: Supported structural regions remain foldable
+- **WHEN** a document contains a supported multi-line namespace, record, function body, parameter list, lambda body, initializer list, call argument list, or compound statement
+- **THEN** the server MUST still return a folding range for that region when its boundaries can be mapped to the main file
+
+#### Scenario: Structural coverage is preserved through normalization
+- **WHEN** the document contains only currently supported AST-driven folding categories
+- **THEN** normalization and rendering MUST NOT remove a valid structural fold except when it is an exact duplicate or an invalid range
+
+### Requirement: Rendering decisions are applied after normalization
+The server SHALL derive final LSP folding-range output from normalized internal ranges instead of requiring collectors to emit protocol-shaped results directly.
+
+#### Scenario: Rendering options do not require collector changes
+- **WHEN** rendering rules change how line or metadata output is shaped for a normalized fold
+- **THEN** the server MUST apply that change in the rendering phase without requiring collector-specific logic changes
+
+#### Scenario: Metadata hints remain optional until rendering
+- **WHEN** a collected or normalized fold carries optional kind or collapsed-text hints
+- **THEN** the renderer MUST decide whether to surface, transform, or suppress that metadata in the emitted LSP range
+
+### Requirement: Folding rendering is configured through explicit options
+The server SHALL expose folding-specific rendering options so client capability behavior can be selected without changing collectors or raw ranges.
+
+#### Scenario: Default options preserve existing output
+- **WHEN** folding ranges are requested without explicit folding options
+- **THEN** rendering MUST behave as if `line_folding_only = false`
+
+#### Scenario: Line-only rendering is selected by options
+- **WHEN** folding ranges are rendered with `line_folding_only = true`
+- **THEN** the renderer MUST emit ranges that remain valid when interpreted as whole-line folds
+- **AND** collectors MUST NOT need to inspect client capability state or emit different raw ranges for line-only clients

openspec/changes/split-folding-range-pipeline/tasks.md

@@ -0,0 +1,19 @@
+## 1. Existing Raw Model and Collector Boundary
+
+- [x] 1.1 Treat the existing `RawFoldingRange` as the finished internal collection model for this change.
+- [ ] 1.2 Keep the existing AST structural folding path routed through raw ranges instead of reintroducing direct collector-to-LSP emission.
+- [ ] 1.3 Add regression fixtures or assertions that cover the currently supported structural fold categories before further rendering changes.
+
+## 2. Normalization, Opts, and Rendering
+
+- [ ] 2.1 Implement normalization for deterministic sorting, duplicate removal, and invalid-range filtering.
+- [ ] 2.2 Introduce `FoldingRangeOptions`/`Opts` with `line_folding_only = false` as the default.
+- [ ] 2.3 Introduce a dedicated renderer that converts normalized ranges plus `Opts` into final LSP folding-range objects.
+- [ ] 2.4 Honor `line_folding_only` in rendering by shaping emitted boundaries for clients that only support whole-line folds.
+- [ ] 2.5 Keep default rendered output compatible with current structural behavior while exposing extension points for future collectors and render rules.
+
+## 3. Verification
+
+- [ ] 3.1 Compare pre-refactor and post-refactor outputs for the existing structural folding test cases.
+- [ ] 3.2 Add focused tests for `line_folding_only` output using the new folding options path.
+- [ ] 3.3 Run relevant folding-range unit tests and fix any ordering, deduplication, or boundary regressions introduced by the new pipeline.

pixi.toml

@@ -14,17 +14,24 @@ readme = "README.md"
 documentation = "https://docs.clice.io/clice/"
 repository = "https://github.com/clice-io/clice"
 channels = ["conda-forge"]
-platforms = ["win-64", "linux-64", "osx-arm64"]
+platforms = ["win-64", "linux-64", "osx-arm64", "osx-64", "linux-aarch64", "win-arm64"]
 
 [environments]
 default = ["build", "test"]
 package = ["build", "test", "package"]
+cross-macos-x64 = ["build", "package", "cross-macos-x64"]
+cross-linux-aarch64 = ["build", "package", "cross-linux-aarch64"]
+cross-windows-arm64 = ["build", "package", "cross-windows-arm64"]
 node = ["node"]
 format = ["format"]
+test-run = ["test"]
 
 # ============================================================================== #
 #                                  DEPENDENCIES                                  #
 # ============================================================================== #
+[feature.build]
+platforms = ["win-64", "linux-64", "osx-arm64", "osx-64", "linux-aarch64"]
+
 [feature.build.dependencies]
 python = ">=3.13"
 cmake = ">=3.30"
@@ -35,6 +42,7 @@ lld = "==20.1.8"
 llvm-tools = "==20.1.8"
 clang-tools = "==20.1.8"
 compiler-rt = "==20.1.8"
+flatbuffers = "==25.9.23"
 
 [feature.build.target.win-64.dependencies]
 sccache = "*"
@@ -54,6 +62,43 @@ scripts = ["scripts/activate_linux.sh"]
 [feature.build.target.win-64.activation]
 scripts = ["scripts/activate_asan.bat"]
 
+# macOS x64 (from arm64): clang natively supports cross-arch, no extra deps.
+[feature.cross-macos-x64.target.osx-arm64.dependencies]
+
+[feature.cross-macos-x64.target.osx-arm64.activation]
+scripts = ["scripts/activate_cross_macos.sh"]
+
+# Linux aarch64 (from x64): needs aarch64 sysroot and cross gcc for libstdc++.
+[feature.cross-linux-aarch64.target.linux-64.dependencies]
+sysroot_linux-aarch64 = "==2.17"
+gcc_linux-aarch64 = "==14.2.0"
+gxx_linux-aarch64 = "==14.2.0"
+
+[feature.cross-linux-aarch64.target.linux-64.activation]
+scripts = ["scripts/activate_cross_linux.sh"]
+
+# Windows arm64 (from x64): Windows SDK on CI already includes ARM64 libs.
+[feature.cross-windows-arm64.target.win-64.dependencies]
+
+[feature.cross-windows-arm64.target.win-64.activation]
+scripts = ["scripts/activate_cross_windows.bat"]
+
+[feature.test.dependencies]
+python = ">=3.13"
+
+# On macOS, the system Apple clang emits vendor-specific flags that upstream
+# LLVM cannot parse.  Providing upstream clang + lld in PATH prevents
+# fallback to /usr/bin/clang++ and satisfies toolchain.cmake's -fuse-ld=lld.
+[feature.test.target.osx-64.dependencies]
+clang = "==20.1.8"
+clangxx = "==20.1.8"
+lld = "==20.1.8"
+
+[feature.test.target.osx-arm64.dependencies]
+clang = "==20.1.8"
+clangxx = "==20.1.8"
+lld = "==20.1.8"
+
 [feature.test.pypi-dependencies]
 pytest = "*"
 pytest-asyncio = ">=1.1.0"
@@ -63,15 +108,22 @@ lsprotocol = ">=2024.0.0"
 [feature.package.dependencies]
 xz = ">=5.8.1,<6"
 
-[feature.package.tasks.package]
+[feature.package.tasks.package-config]
+args = [{ arg = "type", default = "RelWithDebInfo" }]
 cmd = """
-cmake -B build/RelWithDebInfo -G Ninja \
-    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+cmake -B build/{{ type }} -G Ninja \
+    -DCMAKE_BUILD_TYPE={{ type }} \
     -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain.cmake \
-    -DCLICE_RELEASE=ON && \
-cmake --build build/RelWithDebInfo
+    -DCLICE_RELEASE=ON
 """
 
+[feature.package.tasks.package]
+args = [{ arg = "type", default = "RelWithDebInfo" }]
+depends-on = [
+    { task = "package-config", args = ["{{ type }}"] },
+    { task = "cmake-build", args = ["{{ type }}"] },
+]
+
 # ============================================================================== #
 #                                   CMAKE                                        #
 # ============================================================================== #
@@ -79,14 +131,13 @@ cmake --build build/RelWithDebInfo
 args = [
     { arg = "type", default = "RelWithDebInfo" },
     { arg = "ci", default = "OFF" },
-    { arg = "extra", default = "" },
 ]
 cmd = """
 cmake -B build/{{ type }} -G Ninja \
     -DCMAKE_BUILD_TYPE={{ type }} \
     -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain.cmake \
     -DCLICE_ENABLE_TEST=ON \
-    -DCLICE_CI_ENVIRONMENT={{ ci }} {{extra}} \
+    -DCLICE_CI_ENVIRONMENT={{ ci }}
 """
 
 [feature.build.tasks.cmake-build]
@@ -97,10 +148,9 @@ cmd = "cmake --build build/{{ type }}"
 args = [
     { arg = "type", default = "RelWithDebInfo" },
     { arg = "ci", default = "OFF" },
-    { arg = "extra", default = "" },
 ]
 depends-on = [
-    { task = "cmake-config", args = ["{{ type }}", "{{ ci }}", "{{extra}}"] },
+    { task = "cmake-config", args = ["{{ type }}", "{{ ci }}"] },
     { task = "cmake-build", args = ["{{ type }}"] },
 ]
 
@@ -108,7 +158,7 @@ depends-on = [
 args = [{ arg = "type", default = "RelWithDebInfo" }]
 depends-on = [{ task = "lint-cpp", args = ["{{ type }}"] }]
 
-[feature.build.tasks.unit-test]
+[feature.test.tasks.unit-test]
 args = [{ arg = "type", default = "RelWithDebInfo" }]
 cmd = './build/{{ type }}/bin/unit_tests --test-dir="./tests/data"'
 
@@ -131,6 +181,7 @@ args = [{ arg = "type", default = "RelWithDebInfo" }]
 depends-on = [
     { task = "unit-test", args = ["{{ type }}"] },
     { task = "integration-test", args = ["{{ type }}"] },
+    { task = "smoke-test", args = ["{{ type }}"] },
 ]
 
 # ============================================================================== #
@@ -152,9 +203,14 @@ gh workflow run upload-llvm.yml \
 args = ["file_name"]
 cmd = ["scripts/delete-artifacts.bash", "{{ file_name }}"]
 
+[dependencies]
+
 # ============================================================================== #
 #                             DOCS & VSCODE EXTENSION                            #
 # ============================================================================== #
+[feature.node]
+platforms = ["win-64", "linux-64", "osx-arm64", "osx-64", "linux-aarch64"]
+
 [feature.node.dependencies]
 nodejs = ">=20"
 pnpm = "*"
@@ -180,6 +236,9 @@ outputs = ["editors/vscode/node_modules/.modules.yaml"]
 # ============================================================================== #
 #                                    FORMAT                                      #
 # ============================================================================== #
+[feature.format]
+platforms = ["win-64", "linux-64", "osx-arm64", "osx-64", "linux-aarch64"]
+
 [feature.format.dependencies]
 ruff = "*"
 tombi = "*"

scripts/activate_cross_linux.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+# Clear conda cross-gcc flags so host x86_64 paths don't leak into the
+# aarch64 build. conda's gcc_linux-aarch64 activation sets
+# CFLAGS/CXXFLAGS/CPPFLAGS/LDFLAGS with -isystem/-L pointing at $CONDA_PREFIX
+# (x86_64 host paths). LIBRARY_PATH from ld_impl_linux-64 likewise points at
+# host libs. Empty-string export reliably overrides conda-installed values
+# regardless of whether pixi sources or calls this script.
+export CFLAGS=
+export CXXFLAGS=
+export CPPFLAGS=
+export LDFLAGS=
+export LIBRARY_PATH=

scripts/activate_cross_macos.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+# Clear conda host flags so arm64 host paths don't leak into the x86_64-macos
+# cross build. See scripts/activate_cross_linux.sh for rationale.
+export CFLAGS=
+export CXXFLAGS=
+export CPPFLAGS=
+export LDFLAGS=
+export LIBRARY_PATH=

scripts/activate_cross_windows.bat

@@ -0,0 +1,8 @@
+@echo off
+REM Clear conda host flags so host x64 paths don't leak into the aarch64-windows
+REM cross build. See scripts/activate_cross_linux.sh for rationale.
+set "CFLAGS="
+set "CXXFLAGS="
+set "CPPFLAGS="
+set "LDFLAGS="
+set "LIBRARY_PATH="

scripts/build-llvm.py

@@ -4,6 +4,7 @@ import subprocess
 import shutil
 import argparse
 import os
+import json
 from pathlib import Path
 
 
@@ -22,6 +23,66 @@ def normalize_mode(value: str) -> str:
     )
 
 
+def build_native_tools(project_root: Path, build_dir: Path) -> Path:
+    """Build native host tablegen tools for cross-compilation.
+
+    When cross-compiling LLVM, build tools like llvm-tblgen must run on the
+    host but would otherwise be compiled for the target architecture.  This
+    function performs a minimal native build and returns the bin directory
+    containing host-runnable executables.
+    """
+    native_dir = build_dir.parent / f"{build_dir.name}-native-tools"
+    native_dir.mkdir(exist_ok=True)
+    source_dir = project_root / "llvm"
+
+    cmake_args = [
+        "-G",
+        "Ninja",
+        "-DCMAKE_BUILD_TYPE=Release",
+        "-DLLVM_ENABLE_PROJECTS=clang;clang-tools-extra",
+        "-DLLVM_TARGETS_TO_BUILD=Native",
+        "-DLLVM_DISABLE_ASSEMBLY_FILES=ON",
+        "-DCMAKE_C_FLAGS=-w",
+        "-DCMAKE_CXX_FLAGS=-w",
+    ]
+
+    if sys.platform == "win32":
+        cmake_args += [
+            "-DCMAKE_C_COMPILER=clang-cl",
+            "-DCMAKE_CXX_COMPILER=clang-cl",
+        ]
+    else:
+        cmake_args += [
+            "-DCMAKE_C_COMPILER=clang",
+            "-DCMAKE_CXX_COMPILER=clang++",
+        ]
+
+    print(f"\nConfiguring native host tools in {native_dir}...")
+    subprocess.check_call(
+        ["cmake", "-S", str(source_dir), "-B", str(native_dir)] + cmake_args
+    )
+
+    required_tools = ["llvm-tblgen", "llvm-min-tblgen", "clang-tblgen"]
+    optional_tools = ["clang-tidy-confusable-chars-gen"]
+
+    for tool in required_tools:
+        print(f"Building native {tool}...")
+        subprocess.check_call(["cmake", "--build", str(native_dir), "--target", tool])
+
+    for tool in optional_tools:
+        try:
+            print(f"Building native {tool} (optional)...")
+            subprocess.check_call(
+                ["cmake", "--build", str(native_dir), "--target", tool]
+            )
+        except subprocess.CalledProcessError:
+            print(f"  {tool} not available, skipping.")
+
+    bin_dir = native_dir / "bin"
+    print(f"Native host tools ready in {bin_dir}")
+    return bin_dir
+
+
 def main():
     parser = argparse.ArgumentParser(
         description="Build LLVM with specific configurations."
@@ -48,6 +109,10 @@ def main():
         "--build-dir",
         help="Custom build directory (relative to project root or absolute)",
     )
+    parser.add_argument(
+        "--target-triple",
+        help="Cross-compilation target triple (e.g. x86_64-apple-darwin, aarch64-linux-gnu, aarch64-pc-windows-msvc)",
+    )
 
     args = parser.parse_args()
 
@@ -85,118 +150,46 @@ def main():
     print("--- Configuration ---")
     print(f"Mode:           {args.mode}")
     print(f"LTO:            {args.lto}")
+    print(f"Target Triple:  {args.target_triple or '(native)'}")
     print(f"Root:           {project_root}")
     print(f"Build Dir:      {build_dir}")
     print(f"Install Prefix: {install_prefix}")
     print(f"Toolchain:      {toolchain_file}")
     print("---------------------")
 
-    llvm_distribution_components = [
-        "LLVMDemangle",
-        "LLVMSupport",
-        "LLVMCore",
-        "LLVMOption",
-        "LLVMBinaryFormat",
-        "LLVMMC",
-        "LLVMMCParser",
-        "LLVMObject",
-        "LLVMProfileData",
-        "LLVMBitReader",
-        "LLVMBitstreamReader",
-        "LLVMRemarks",
-        "LLVMObjectYAML",
-        "LLVMAggressiveInstCombine",
-        "LLVMInstCombine",
-        "LLVMIRReader",
-        "LLVMTextAPI",
-        "LLVMSymbolize",
-        "LLVMDebugInfoDWARF",
-        "LLVMDebugInfoDWARFLowLevel",
-        "LLVMDebugInfoCodeView",
-        "LLVMDebugInfoGSYM",
-        "LLVMDebugInfoPDB",
-        "LLVMDebugInfoBTF",
-        "LLVMDebugInfoMSF",
-        "LLVMAsmParser",
-        "LLVMTargetParser",
-        "LLVMTransformUtils",
-        "LLVMAnalysis",
-        "LLVMScalarOpts",
-        "LLVMFrontendHLSL",
-        "LLVMFrontendOpenMP",
-        "LLVMFrontendOffloading",
-        "LLVMFrontendAtomic",
-        "LLVMFrontendDirective",
-        "LLVMWindowsDriver",
-        "clangIndex",
-        "clangAPINotes",
-        "clangAST",
-        "clangASTMatchers",
-        "clangBasic",
-        "clangDriver",
-        "clangFormat",
-        "clangFrontend",
-        "clangLex",
-        "clangParse",
-        "clangSema",
-        "clangSerialization",
-        "clangRewrite",
-        "clangAnalysis",
-        "clangEdit",
-        "clangSupport",
-        "clangStaticAnalyzerCore",
-        "clangStaticAnalyzerFrontend",
-        "clangTidy",
-        "clangTidyUtils",
-        "clangTidyAndroidModule",
-        "clangTidyAbseilModule",
-        "clangTidyAlteraModule",
-        "clangTidyBoostModule",
-        "clangTidyBugproneModule",
-        "clangTidyCERTModule",
-        "clangTidyConcurrencyModule",
-        "clangTidyCppCoreGuidelinesModule",
-        "clangTidyDarwinModule",
-        "clangTidyFuchsiaModule",
-        "clangTidyGoogleModule",
-        "clangTidyHICPPModule",
-        "clangTidyLinuxKernelModule",
-        "clangTidyLLVMModule",
-        "clangTidyLLVMLibcModule",
-        "clangTidyMiscModule",
-        "clangTidyModernizeModule",
-        "clangTidyObjCModule",
-        "clangTidyOpenMPModule",
-        "clangTidyPerformanceModule",
-        "clangTidyPortabilityModule",
-        "clangTidyReadabilityModule",
-        "clangTidyZirconModule",
-        "clangTooling",
-        "clangToolingCore",
-        "clangToolingInclusions",
-        "clangToolingInclusionsStdlib",
-        "clangToolingSyntax",
-        "clangToolingRefactoring",
-        "clangTransformer",
-        "clangCrossTU",
-        "clangAnalysisFlowSensitive",
-        "clangAnalysisFlowSensitiveModels",
-        "clangStaticAnalyzerCheckers",
-        "clangIncludeCleaner",
-        "llvm-headers",
-        "clang-headers",
-        "clang-tidy-headers",
-        "clang-resource-headers",
-    ]
+    components_path = Path(__file__).resolve().parent / "llvm-components.json"
+    with components_path.open() as f:
+        llvm_distribution_components = json.load(f)["components"]
 
     components_joined = ";".join(llvm_distribution_components)
     cmake_args = [
         "-G",
         "Ninja",
-        f"-DCMAKE_TOOLCHAIN_FILE={toolchain_file.as_posix()}",
         f"-DCMAKE_INSTALL_PREFIX={install_prefix}",
-        "-DCMAKE_C_FLAGS=-w",
-        "-DCMAKE_CXX_FLAGS=-w",
+    ]
+
+    if sys.platform == "win32":
+        # Use clang-cl (MSVC driver) on Windows so that LLVM's CMake
+        # generates correct MSVC-style linker flags for LTO, etc.
+        c_flags = "-w"
+        if args.target_triple:
+            c_flags += f" --target={args.target_triple}"
+        cmake_args += [
+            "-DCMAKE_C_COMPILER=clang-cl",
+            "-DCMAKE_CXX_COMPILER=clang-cl",
+            f"-DCMAKE_C_FLAGS={c_flags}",
+            f"-DCMAKE_CXX_FLAGS={c_flags}",
+            "-DLLVM_USE_LINKER=lld-link",
+        ]
+    else:
+        cmake_args += [
+            f"-DCMAKE_TOOLCHAIN_FILE={toolchain_file.as_posix()}",
+            "-DCMAKE_C_FLAGS=-w",
+            "-DCMAKE_CXX_FLAGS=-w",
+            "-DLLVM_USE_LINKER=lld",
+        ]
+
+    cmake_args += [
         "-DLLVM_ENABLE_ZLIB=OFF",
         "-DLLVM_ENABLE_ZSTD=OFF",
         "-DLLVM_ENABLE_LIBXML2=OFF",
@@ -231,7 +224,6 @@ def main():
         "-DCMAKE_JOB_POOL_LINK=console",
         "-DLLVM_ENABLE_PROJECTS=clang;clang-tools-extra",
         "-DLLVM_TARGETS_TO_BUILD=all",
-        "-DLLVM_USE_LINKER=lld",
         "-DLLVM_DISABLE_ASSEMBLY_FILES=ON",
         # Distribution
         f"-DLLVM_DISTRIBUTION_COMPONENTS={components_joined}",
@@ -256,8 +248,10 @@ def main():
     is_shared = "OFF"
     if args.mode == "Debug":
         cmake_args.append("-DCMAKE_BUILD_TYPE=Debug")
-        cmake_args.append("-DLLVM_USE_SANITIZER=Address")
-        is_shared = "ON"
+        # ASAN is incompatible with -MDd on Windows (clang-cl), skip it there.
+        if sys.platform != "win32":
+            cmake_args.append("-DLLVM_USE_SANITIZER=Address")
+            is_shared = "ON"
     elif args.mode == "Release":
         cmake_args.append("-DCMAKE_BUILD_TYPE=Release")
     elif args.mode == "RelWithDebInfo":
@@ -272,6 +266,24 @@ def main():
     else:
         cmake_args.append("-DLLVM_ENABLE_LTO=OFF")
 
+    if args.target_triple:
+        cmake_args.append(f"-DCLICE_TARGET_TRIPLE={args.target_triple}")
+        cmake_args.append(f"-DLLVM_HOST_TRIPLE={args.target_triple}")
+
+        # When cross-compiling, clear conda's host-platform flags so they
+        # don't leak into the target build (e.g. -L pointing to x86_64 libs).
+        # This must happen before the native-tools build too so we don't
+        # contaminate the native configure with target-arch link flags.
+        for var in ["LIBRARY_PATH", "LDFLAGS", "CFLAGS", "CXXFLAGS", "CPPFLAGS"]:
+            os.environ.pop(var, None)
+
+        # Cross-compilation needs native host tools (tablegen, etc.) that can
+        # run on the build machine.  macOS handles this transparently via
+        # Rosetta 2, but Linux and Windows require a separate native build.
+        if sys.platform != "darwin":
+            native_bin_dir = build_native_tools(project_root, build_dir)
+            cmake_args.append(f"-DLLVM_NATIVE_TOOL_DIR={native_bin_dir}")
+
     build_dir.mkdir(exist_ok=True)
 
     print(f"\nConfiguring in {build_dir}...")

scripts/llvm-components.json

@@ -0,0 +1,99 @@
+{
+  "components": [
+    "LLVMDemangle",
+    "LLVMSupport",
+    "LLVMCore",
+    "LLVMOption",
+    "LLVMBinaryFormat",
+    "LLVMMC",
+    "LLVMMCParser",
+    "LLVMObject",
+    "LLVMProfileData",
+    "LLVMBitReader",
+    "LLVMBitstreamReader",
+    "LLVMRemarks",
+    "LLVMObjectYAML",
+    "LLVMAggressiveInstCombine",
+    "LLVMInstCombine",
+    "LLVMIRReader",
+    "LLVMTextAPI",
+    "LLVMSymbolize",
+    "LLVMDebugInfoDWARF",
+    "LLVMDebugInfoDWARFLowLevel",
+    "LLVMDebugInfoCodeView",
+    "LLVMDebugInfoGSYM",
+    "LLVMDebugInfoPDB",
+    "LLVMDebugInfoBTF",
+    "LLVMDebugInfoMSF",
+    "LLVMAsmParser",
+    "LLVMTargetParser",
+    "LLVMTransformUtils",
+    "LLVMAnalysis",
+    "LLVMScalarOpts",
+    "LLVMFrontendHLSL",
+    "LLVMFrontendOpenMP",
+    "LLVMFrontendOffloading",
+    "LLVMFrontendAtomic",
+    "LLVMFrontendDirective",
+    "LLVMWindowsDriver",
+    "clangIndex",
+    "clangAPINotes",
+    "clangAST",
+    "clangASTMatchers",
+    "clangBasic",
+    "clangDriver",
+    "clangFormat",
+    "clangFrontend",
+    "clangLex",
+    "clangParse",
+    "clangSema",
+    "clangSerialization",
+    "clangRewrite",
+    "clangAnalysis",
+    "clangEdit",
+    "clangSupport",
+    "clangStaticAnalyzerCore",
+    "clangStaticAnalyzerFrontend",
+    "clangTidy",
+    "clangTidyUtils",
+    "clangTidyAndroidModule",
+    "clangTidyAbseilModule",
+    "clangTidyAlteraModule",
+    "clangTidyBoostModule",
+    "clangTidyBugproneModule",
+    "clangTidyCERTModule",
+    "clangTidyConcurrencyModule",
+    "clangTidyCppCoreGuidelinesModule",
+    "clangTidyDarwinModule",
+    "clangTidyFuchsiaModule",
+    "clangTidyGoogleModule",
+    "clangTidyHICPPModule",
+    "clangTidyLinuxKernelModule",
+    "clangTidyLLVMModule",
+    "clangTidyLLVMLibcModule",
+    "clangTidyMiscModule",
+    "clangTidyModernizeModule",
+    "clangTidyObjCModule",
+    "clangTidyOpenMPModule",
+    "clangTidyPerformanceModule",
+    "clangTidyPortabilityModule",
+    "clangTidyReadabilityModule",
+    "clangTidyZirconModule",
+    "clangTooling",
+    "clangToolingCore",
+    "clangToolingInclusions",
+    "clangToolingInclusionsStdlib",
+    "clangToolingSyntax",
+    "clangToolingRefactoring",
+    "clangTransformer",
+    "clangCrossTU",
+    "clangAnalysisFlowSensitive",
+    "clangAnalysisFlowSensitiveModels",
+    "clangStaticAnalyzerCheckers",
+    "clangIncludeCleaner",
+    "llvm-headers",
+    "clang-headers",
+    "clang-tidy-headers",
+    "clang-resource-headers"
+  ]
+}

scripts/setup-llvm.py

@@ -40,23 +40,52 @@ def detect_platform() -> str:
     raise RuntimeError(f"Unsupported platform: {plat}")
 
 
+def detect_arch() -> str:
+    import platform
+
+    machine = platform.machine().lower()
+    if machine in ("x86_64", "amd64"):
+        return "x64"
+    if machine in ("aarch64", "arm64"):
+        return "arm64"
+    raise RuntimeError(f"Unsupported architecture: {machine}")
+
+
 def pick_artifact(
-    manifest: list[dict], version: str, build_type: str, is_lto: bool, platform: str
+    manifest: list[dict],
+    version: str,
+    build_type: str,
+    is_lto: bool,
+    platform: str,
+    arch: str,
 ) -> dict:
     base_version = version.split("+", 1)[0]
+    saw_missing_arch = False
     for entry in manifest:
         if entry.get("version") != version:
             continue
         if entry.get("platform") != platform.lower():
             continue
+        entry_arch = entry.get("arch")
+        if entry_arch is None:
+            saw_missing_arch = True
+            continue
+        if entry_arch != arch:
+            continue
         if entry.get("build_type") != build_type:
             continue
         if bool(entry.get("lto")) != is_lto:
             continue
         return entry
+    if saw_missing_arch:
+        raise RuntimeError(
+            f"Manifest contains entries without an 'arch' field for version={base_version}, "
+            f"platform={platform}. The manifest format changed to require explicit "
+            f"architectures; regenerate it via scripts/update-llvm-version.py."
+        )
     raise RuntimeError(
         f"No matching LLVM artifact in manifest for version={base_version}, platform={platform}, "
-        f"build_type={build_type}, lto={is_lto}"
+        f"arch={arch}, build_type={build_type}, lto={is_lto}"
     )
 
 
@@ -264,6 +293,14 @@ def main() -> None:
     parser.add_argument("--install-path")
     parser.add_argument("--enable-lto", action="store_true")
     parser.add_argument("--offline", action="store_true")
+    parser.add_argument(
+        "--target-platform",
+        help="Override platform for cross-compilation (e.g. macosx, linux, windows)",
+    )
+    parser.add_argument(
+        "--target-arch",
+        help="Override architecture for cross-compilation (e.g. x64, arm64)",
+    )
     parser.add_argument("--output", required=True)
     args = parser.parse_args()
 
@@ -275,8 +312,11 @@ def main() -> None:
     )
     token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
     build_type = args.build_type
-    platform_name = detect_platform()
-    log(f"Platform detected: {platform_name}, normalized build type: {build_type}")
+    platform_name = args.target_platform if args.target_platform else detect_platform()
+    arch_name = args.target_arch if args.target_arch else detect_arch()
+    log(
+        f"Platform: {platform_name}, arch: {arch_name}, normalized build type: {build_type}"
+    )
     manifest = read_manifest(Path(args.manifest))
 
     binary_dir = Path(args.binary_dir).resolve()
@@ -304,7 +344,12 @@ def main() -> None:
     if install_path is None:
         needs_install = True
         artifact = pick_artifact(
-            manifest, args.version, build_type, args.enable_lto, platform_name
+            manifest,
+            args.version,
+            build_type,
+            args.enable_lto,
+            platform_name,
+            arch_name,
         )
         log(f"Selected artifact: {artifact.get('filename')} for download")
         filename = artifact["filename"]
@@ -317,7 +362,12 @@ def main() -> None:
         install_path = install_root
     elif needs_install:
         artifact = pick_artifact(
-            manifest, args.version, build_type, args.enable_lto, platform_name
+            manifest,
+            args.version,
+            build_type,
+            args.enable_lto,
+            platform_name,
+            arch_name,
         )
         log(f"Selected artifact: {artifact.get('filename')} for download")
         filename = artifact["filename"]

scripts/update-llvm-version.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+def copy_manifest(src: Path, dest: Path) -> None:
+    text = src.read_text(encoding="utf-8")
+
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as err:
+        print(f"Error: {src} is not valid JSON: {err}", file=sys.stderr)
+        sys.exit(1)
+
+    if not isinstance(data, list) or len(data) == 0:
+        print(f"Error: {src} must be a non-empty JSON array", file=sys.stderr)
+        sys.exit(1)
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    with dest.open("w", encoding="utf-8") as handle:
+        json.dump(data, handle, indent=2)
+        handle.write("\n")
+
+    print(f"Copied manifest: {src} -> {dest} ({len(data)} entries)")
+
+
+def update_package_cmake(path: Path, version: str) -> None:
+    text = path.read_text(encoding="utf-8")
+
+    pattern = r'setup_llvm\("[^"]*"\)'
+    matches = re.findall(pattern, text)
+
+    if len(matches) == 0:
+        print(f"Error: no setup_llvm(...) call found in {path}", file=sys.stderr)
+        sys.exit(1)
+
+    if len(matches) > 1:
+        print(
+            f"Error: expected exactly 1 setup_llvm(...) call in {path}, "
+            f"found {len(matches)}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    old_call = matches[0]
+    new_call = f'setup_llvm("{version}")'
+
+    if old_call == new_call:
+        print(f"Version in {path} is already {version}, no change needed")
+        return
+
+    updated = text.replace(old_call, new_call)
+    path.write_text(updated, encoding="utf-8")
+    print(f"Updated {path}: {old_call} -> {new_call}")
+
+
+def check_package_cmake(path: Path) -> None:
+    """Verify package.cmake has exactly one setup_llvm(...) call that the
+    update script can rewrite. Used by CI to catch drift before the next bump."""
+    text = path.read_text(encoding="utf-8")
+    matches = re.findall(r'setup_llvm\("[^"]*"\)', text)
+    if len(matches) == 0:
+        print(f"Error: no setup_llvm(...) call found in {path}", file=sys.stderr)
+        sys.exit(1)
+    if len(matches) > 1:
+        print(
+            f"Error: expected exactly 1 setup_llvm(...) call in {path}, "
+            f"found {len(matches)}: {matches}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    print(f"OK: {path} has a single setup_llvm(...) call: {matches[0]}")
+
+
+def check_manifest(path: Path) -> None:
+    """Verify the manifest is a well-formed non-empty array with required fields."""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as err:
+        print(f"Error: {path} is not valid JSON: {err}", file=sys.stderr)
+        sys.exit(1)
+    if not isinstance(data, list) or len(data) == 0:
+        print(f"Error: {path} must be a non-empty JSON array", file=sys.stderr)
+        sys.exit(1)
+    required = ("version", "platform", "arch", "build_type", "filename", "sha256")
+    for idx, entry in enumerate(data):
+        missing = [k for k in required if k not in entry]
+        if missing:
+            print(
+                f"Error: {path} entry {idx} is missing fields: {missing}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+    print(f"OK: {path} has {len(data)} well-formed entries")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Update LLVM version references in the clice project."
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Validate existing state without modifying files (for CI drift checks)",
+    )
+    parser.add_argument(
+        "--version",
+        help="New LLVM version string (e.g. 21.2.0); required unless --check",
+    )
+    parser.add_argument(
+        "--manifest-src",
+        help="Path to the source llvm-manifest.json; required unless --check",
+    )
+    parser.add_argument(
+        "--manifest-dest",
+        required=True,
+        help="Path to destination manifest (e.g. config/llvm-manifest.json)",
+    )
+    parser.add_argument(
+        "--package-cmake",
+        required=True,
+        help="Path to cmake/package.cmake",
+    )
+    args = parser.parse_args()
+
+    manifest_dest = Path(args.manifest_dest)
+    package_cmake = Path(args.package_cmake)
+
+    if not package_cmake.is_file():
+        print(f"Error: package.cmake not found: {package_cmake}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.check:
+        check_package_cmake(package_cmake)
+        check_manifest(manifest_dest)
+        print("Done (check mode).")
+        return
+
+    if not args.version or not args.manifest_src:
+        print(
+            "Error: --version and --manifest-src are required unless --check is set",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    manifest_src = Path(args.manifest_src)
+    if not manifest_src.is_file():
+        print(f"Error: manifest source not found: {manifest_src}", file=sys.stderr)
+        sys.exit(1)
+
+    copy_manifest(manifest_src, manifest_dest)
+    update_package_cmake(package_cmake, args.version)
+
+    print("Done.")
+
+
+if __name__ == "__main__":
+    main()

scripts/upload-llvm.py

@@ -27,6 +27,15 @@ def parse_platform(name: str) -> str:
     raise ValueError(f"Unable to determine platform from filename: {name}")
 
 
+def parse_arch(name: str) -> str:
+    lowered = name.lower()
+    if lowered.startswith("aarch64-") or lowered.startswith("arm64-"):
+        return "arm64"
+    if lowered.startswith("x64-") or lowered.startswith("x86_64-"):
+        return "x64"
+    raise ValueError(f"Unable to determine arch from filename: {name}")
+
+
 def parse_build_type(name: str) -> str:
     lowered = name.lower()
     if "debug" in lowered:
@@ -43,6 +52,7 @@ def build_metadata_entry(path: Path, version: str) -> dict:
         "lto": "-lto" in filename.lower(),
         "asan": "-asan" in filename.lower(),
         "platform": parse_platform(filename),
+        "arch": parse_arch(filename),
         "build_type": parse_build_type(filename),
     }
 

scripts/validate-llvm-components.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""
+Validate the LLVM distribution component list against the actual LLVM source tree.
+
+Scans the LLVM source for CMake library targets and compares them against
+a components JSON file to detect stale or misspelled entries.
+"""
+
+import argparse
+import difflib
+import json
+import re
+import sys
+from pathlib import Path
+
+
+# CMake function calls that define library targets.
+# The captured group uses [^\s)]+  to grab the target name without
+# trailing parentheses or whitespace.
+LLVM_LIB_PATTERNS = [
+    re.compile(r"add_llvm_component_library\(\s*([^\s)]+)"),
+    re.compile(r"add_llvm_library\(\s*([^\s)]+)"),
+]
+
+CLANG_LIB_PATTERNS = [
+    re.compile(r"add_clang_library\(\s*([^\s)]+)"),
+]
+
+# Header-only / custom install targets.
+HEADER_PATTERNS = [
+    re.compile(r"add_llvm_install_targets\(\s*([^\s)]+)"),
+    re.compile(r"add_custom_target\(\s*([^\s)]+)"),
+    re.compile(r"add_library\(\s*([^\s)]+)"),
+]
+
+# Targets we recognise as header-only distribution components.
+KNOWN_HEADER_TARGETS = {
+    "llvm-headers",
+    "clang-headers",
+    "clang-tidy-headers",
+    "clang-resource-headers",
+}
+
+
+def scan_targets(directory: Path, patterns: list[re.Pattern]) -> set[str]:
+    """Recursively scan *directory* for CMakeLists.txt files and extract target names."""
+    targets: set[str] = set()
+    if not directory.is_dir():
+        return targets
+    for cmake_file in directory.rglob("CMakeLists.txt"):
+        text = cmake_file.read_text(errors="replace")
+        for pattern in patterns:
+            for match in pattern.finditer(text):
+                targets.add(match.group(1))
+    return targets
+
+
+def scan_header_targets(llvm_src: Path) -> set[str]:
+    """Scan for well-known header / custom-install targets across the tree."""
+    found: set[str] = set()
+    for cmake_file in llvm_src.rglob("CMakeLists.txt"):
+        text = cmake_file.read_text(errors="replace")
+        for pattern in HEADER_PATTERNS:
+            for match in pattern.finditer(text):
+                name = match.group(1)
+                if name in KNOWN_HEADER_TARGETS:
+                    found.add(name)
+    return found
+
+
+def collect_source_targets(llvm_src: Path) -> set[str]:
+    """Return the full set of library / header targets found in the LLVM source tree."""
+    targets: set[str] = set()
+    targets |= scan_targets(llvm_src / "llvm" / "lib", LLVM_LIB_PATTERNS)
+    targets |= scan_targets(llvm_src / "clang" / "lib", CLANG_LIB_PATTERNS)
+    targets |= scan_targets(llvm_src / "clang-tools-extra", CLANG_LIB_PATTERNS)
+    targets |= scan_header_targets(llvm_src)
+    return targets
+
+
+def load_components(path: Path) -> list[str]:
+    with path.open("r", encoding="utf-8") as handle:
+        data = json.load(handle)
+    if isinstance(data, dict):
+        data = data.get("components", [])
+    if not isinstance(data, list) or not data:
+        print(f"Error: no component list found in {path}", file=sys.stderr)
+        sys.exit(1)
+    return data
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Validate LLVM distribution components against the source tree."
+    )
+    parser.add_argument(
+        "--llvm-src",
+        required=True,
+        help="Path to the llvm-project source root",
+    )
+    parser.add_argument(
+        "--components-file",
+        required=True,
+        help="Path to llvm-components.json",
+    )
+    args = parser.parse_args()
+
+    llvm_src = Path(args.llvm_src).expanduser().resolve()
+    components_file = Path(args.components_file).expanduser().resolve()
+
+    if not llvm_src.is_dir():
+        print(f"Error: LLVM source directory not found: {llvm_src}")
+        sys.exit(1)
+
+    if not (llvm_src / "llvm" / "CMakeLists.txt").exists():
+        print(f"Error: {llvm_src} does not look like an llvm-project root.")
+        sys.exit(1)
+
+    if not components_file.is_file():
+        print(f"Error: components file not found: {components_file}")
+        sys.exit(1)
+
+    components = load_components(components_file)
+    source_targets = collect_source_targets(llvm_src)
+
+    print(f"Found {len(source_targets)} targets in LLVM source tree")
+    print(f"Components file lists {len(components)} entries")
+
+    # Check for components that are missing from the source tree.
+    missing: list[tuple[str, list[str]]] = []
+    for name in components:
+        if name not in source_targets:
+            suggestions = difflib.get_close_matches(
+                name, source_targets, n=3, cutoff=0.6
+            )
+            missing.append((name, suggestions))
+
+    if missing:
+        print(f"\nError: {len(missing)} component(s) not found in the source tree:\n")
+        for name, suggestions in missing:
+            print(f"  - {name}")
+            if suggestions:
+                print(f"    Did you mean: {', '.join(suggestions)}?")
+        sys.exit(1)
+
+    # Warn about source targets not present in the component list.
+    component_set = set(components)
+    new_targets = sorted(source_targets - component_set - KNOWN_HEADER_TARGETS)
+    # Filter to targets that follow LLVM/Clang naming conventions to reduce noise.
+    noteworthy = [t for t in new_targets if t.startswith(("LLVM", "clang", "Clang"))]
+    if noteworthy:
+        print(
+            f"\nWarning: {len(noteworthy)} target(s) in source not listed in components:"
+        )
+        for name in noteworthy:
+            print(f"  + {name}")
+
+    print("\nAll components validated successfully.")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

src/feature/code_completion.cpp

@@ -296,7 +296,8 @@ public:
                            llvm::StringRef overload_key,
                            llvm::StringRef signature = {},
                            llvm::StringRef return_type = {},
-                           bool is_snippet = false) {
+                           bool is_snippet = false,
+                           bool is_deprecated = false) {
             if(label.empty()) {
                 return;
             }
@@ -327,6 +328,9 @@ public:
                         }
                         item.label_details = std::move(details);
                     }
+                    if(is_deprecated) {
+                        item.tags = std::vector{protocol::CompletionItemTag::Deprecated};
+                    }
                     overloads.push_back({
                         .item = std::move(item),
                         .score = *score,
@@ -355,6 +359,9 @@ public:
                 }
                 item.label_details = std::move(details);
             }
+            if(is_deprecated) {
+                item.tags = std::vector{protocol::CompletionItemTag::Deprecated};
+            }
             collected.push_back(std::move(item));
         };
 
@@ -431,13 +438,15 @@ public:
 
                     bool has_snippet = !snippet.empty();
                     auto insert = has_snippet ? llvm::StringRef(snippet) : llvm::StringRef(label);
+                    bool deprecated = candidate.Availability == CXAvailability_Deprecated;
                     try_add(label,
                             kind,
                             insert,
                             qualified_name.str(),
                             signature,
                             return_type,
-                            has_snippet);
+                            has_snippet,
+                            deprecated);
                     break;
                 }
             }

src/server/compiler.cpp

@@ -47,8 +47,13 @@ void Compiler::init_compile_graph() {
     // Lazy dependency resolver: scans a module file on demand to discover imports.
     auto resolve = [this](std::uint32_t path_id) -> llvm::SmallVector<std::uint32_t> {
         auto file_path = workspace.path_pool.resolve(path_id);
-        auto results =
-            workspace.cdb.lookup(file_path, {.query_toolchain = true, .suppress_logging = true});
+        std::vector<std::string> rule_append, rule_remove;
+        workspace.config.match_rules(file_path, rule_append, rule_remove);
+        auto results = workspace.cdb.lookup(file_path,
+                                            {.query_toolchain = true,
+                                             .suppress_logging = true,
+                                             .remove = rule_remove,
+                                             .append = rule_append});
         if(results.empty())
             return {};
 
@@ -97,7 +102,8 @@ void Compiler::init_compile_graph() {
         }
         auto args_hash = llvm::xxh3_64bits(llvm::StringRef(hash_input));
         auto pcm_filename = std::format("{}-{:016x}.pcm", safe_module_name, args_hash);
-        auto pcm_path = path::join(workspace.config.cache_dir, "cache", "pcm", pcm_filename);
+        auto pcm_path =
+            path::join(workspace.config.project.cache_dir, "cache", "pcm", pcm_filename);
 
         // Check if cached PCM is still valid.
         if(auto pcm_it = workspace.pcm_cache.find(path_id); pcm_it != workspace.pcm_cache.end()) {
@@ -156,7 +162,11 @@ bool Compiler::fill_compile_args(llvm::StringRef path,
     }
 
     // 2. Normal CDB lookup for the file itself.
-    auto results = workspace.cdb.lookup(path, {.query_toolchain = true});
+    //    Apply rules from config (append/remove flags based on file patterns).
+    std::vector<std::string> rule_append, rule_remove;
+    workspace.config.match_rules(path, rule_append, rule_remove);
+    CommandOptions opts{.query_toolchain = true, .remove = rule_remove, .append = rule_append};
+    auto results = workspace.cdb.lookup(path, opts);
     if(!results.empty()) {
         auto& cmd = results.front();
         directory = cmd.resolved.directory.str();
@@ -205,7 +215,13 @@ bool Compiler::fill_header_context_args(llvm::StringRef path,
     }
 
     auto host_path = workspace.path_pool.resolve(ctx_ptr->host_path_id);
-    auto host_results = workspace.cdb.lookup(host_path, {.query_toolchain = true});
+    // Apply rules matching the HEADER path (what the user is editing) on top of
+    // the host's command — rules are expected to apply uniformly to every file.
+    std::vector<std::string> rule_append, rule_remove;
+    workspace.config.match_rules(path, rule_append, rule_remove);
+    auto host_results = workspace.cdb.lookup(
+        host_path,
+        {.query_toolchain = true, .remove = rule_remove, .append = rule_append});
     if(host_results.empty()) {
         LOG_WARN("fill_header_context_args: host {} has no CDB entry", host_path);
         return false;
@@ -355,7 +371,7 @@ std::optional<HeaderFileContext> Compiler::resolve_header_context(std::uint32_t
     // Hash the preamble and write to cache directory.
     auto preamble_hash = llvm::xxh3_64bits(llvm::StringRef(preamble));
     auto preamble_filename = std::format("{:016x}.h", preamble_hash);
-    auto preamble_dir = path::join(workspace.config.cache_dir, "header_context");
+    auto preamble_dir = path::join(workspace.config.project.cache_dir, "header_context");
     auto preamble_path = path::join(preamble_dir, preamble_filename);
 
     if(!llvm::sys::fs::exists(preamble_path)) {
@@ -438,7 +454,7 @@ kota::task<bool> Compiler::ensure_pch(Session& session,
     auto preamble_hash = llvm::xxh3_64bits(preamble_text);
 
     // Deterministic content-addressed PCH path.
-    auto pch_path = path::join(workspace.config.cache_dir,
+    auto pch_path = path::join(workspace.config.project.cache_dir,
                                "cache",
                                "pch",
                                std::format("{:016x}.pch", preamble_hash));

src/server/config.cpp

@@ -1,99 +1,191 @@
 #include "server/config.h"
 
 #include <algorithm>
-#include <thread>
 
 #include "support/filesystem.h"
+#include "support/glob_pattern.h"
 #include "support/logging.h"
 
+#include "kota/codec/json/json.h"
 #include "kota/codec/toml.h"
+#include "llvm/Support/FileSystem.h"
+#include "llvm/Support/Path.h"
+#include "llvm/Support/Process.h"
+#include "llvm/Support/xxhash.h"
 
 namespace clice {
 
 /// Replace all occurrences of ${workspace} with the workspace root.
-static void substitute_workspace(std::string& value, const std::string& workspace_root) {
+/// No-op when workspace_root is empty, to avoid producing paths like "/cache"
+/// from "${workspace}/cache".
+static void substitute_workspace(std::string& value, llvm::StringRef workspace_root) {
+    if(workspace_root.empty())
+        return;
     constexpr std::string_view placeholder = "${workspace}";
-    std::string::size_type pos = 0;
+    std::size_t pos = 0;
     while((pos = value.find(placeholder, pos)) != std::string::npos) {
         value.replace(pos, placeholder.size(), workspace_root);
         pos += workspace_root.size();
     }
 }
 
-void CliceConfig::apply_defaults(const std::string& workspace_root) {
-    auto cpu_count = std::thread::hardware_concurrency();
-    if(cpu_count == 0)
-        cpu_count = 4;
-
-    if(stateful_worker_count == 0) {
-        stateful_worker_count = 2;
-    }
-    if(stateless_worker_count == 0) {
-        stateless_worker_count = 3;
-    }
-    if(worker_memory_limit == 0) {
-        worker_memory_limit = 4ULL * 1024 * 1024 * 1024;  // 4GB default
-    }
-    if(cache_dir.empty() && !workspace_root.empty()) {
-        cache_dir = path::join(workspace_root, ".clice");
+/// Try to resolve the default cache directory using XDG_CACHE_HOME.
+/// Returns empty string on failure.
+static std::string resolve_xdg_cache_dir(llvm::StringRef workspace_root) {
+    // Determine base: $XDG_CACHE_HOME or ~/.cache
+    std::string base;
+    if(auto xdg = llvm::sys::Process::GetEnv("XDG_CACHE_HOME"); xdg && !xdg->empty()) {
+        base = std::move(*xdg);
+    } else if(auto home = llvm::sys::Process::GetEnv("HOME"); home && !home->empty()) {
+        base = path::join(*home, ".cache");
+    } else {
+        return {};
     }
 
-    if(index_dir.empty() && !cache_dir.empty()) {
-        index_dir = path::join(cache_dir, "index");
-    }
+    // Use a hash of workspace_root to create a unique subdirectory.
+    auto hash = llvm::xxh3_64bits(workspace_root);
+    auto dir = path::join(base, "clice", std::format("{:016x}", hash));
 
-    if(logging_dir.empty() && !cache_dir.empty()) {
-        logging_dir = path::join(cache_dir, "logs");
+    if(auto ec = llvm::sys::fs::create_directories(dir)) {
+        LOG_WARN("Failed to create XDG cache directory {}: {}", dir, ec.message());
+        return {};
     }
-
-    // Apply variable substitution to string fields
-    substitute_workspace(compile_commands_path, workspace_root);
-    substitute_workspace(cache_dir, workspace_root);
-    substitute_workspace(index_dir, workspace_root);
-    substitute_workspace(logging_dir, workspace_root);
+    return dir;
 }
 
-std::optional<CliceConfig> CliceConfig::load(const std::string& path,
-                                             const std::string& workspace_root) {
-    auto content = fs::read(path);
-    if(!content) {
-        return std::nullopt;
-    }
+void Config::apply_defaults(llvm::StringRef workspace_root) {
+    auto& p = project;
 
-    auto result = kota::codec::toml::parse<CliceConfig>(*content);
+    if(p.max_active_file == 0)
+        p.max_active_file = 8;
+    if(!p.enable_indexing)
+        p.enable_indexing = true;
+    if(!p.idle_timeout_ms)
+        p.idle_timeout_ms = 3000;
+
+    if(p.stateful_worker_count == 0)
+        p.stateful_worker_count = 2;
+    if(p.stateless_worker_count == 0)
+        p.stateless_worker_count = 3;
+    if(p.worker_memory_limit == 0)
+        p.worker_memory_limit = 4ULL * 1024 * 1024 * 1024;  // 4GB
+
+    if(p.cache_dir.empty() && !workspace_root.empty()) {
+        p.cache_dir = resolve_xdg_cache_dir(workspace_root);
+        if(p.cache_dir.empty())
+            p.cache_dir = path::join(workspace_root, ".clice");
+    }
+    if(p.index_dir.empty() && !p.cache_dir.empty())
+        p.index_dir = path::join(p.cache_dir, "index");
+    if(p.logging_dir.empty() && !p.cache_dir.empty())
+        p.logging_dir = path::join(p.cache_dir, "logs");
+
+    // Variable substitution on string fields.
+    substitute_workspace(p.cache_dir, workspace_root);
+    substitute_workspace(p.index_dir, workspace_root);
+    substitute_workspace(p.logging_dir, workspace_root);
+    for(auto& entry: p.compile_commands_paths)
+        substitute_workspace(entry, workspace_root);
+
+    // Pre-compile glob patterns from rules.
+    compiled_rules.clear();
+    for(auto& rule: rules) {
+        CompiledRule compiled;
+        for(auto& pattern_str: rule.patterns) {
+            auto pat = GlobPattern::create(pattern_str);
+            if(!pat) {
+                LOG_WARN("Invalid glob pattern in rule: {}", pattern_str);
+                continue;
+            }
+            compiled.patterns.push_back(std::move(*pat));
+        }
+        // Drop the whole rule if no pattern compiled successfully — otherwise the
+        // append/remove flags would be silently attached to a rule that can never match.
+        if(compiled.patterns.empty()) {
+            if(!rule.patterns.empty())
+                LOG_WARN("Rule dropped: all glob patterns failed to compile");
+            continue;
+        }
+        compiled.append.assign(rule.append.begin(), rule.append.end());
+        compiled.remove.assign(rule.remove.begin(), rule.remove.end());
+        compiled_rules.push_back(std::move(compiled));
+    }
+}
+
+void Config::match_rules(llvm::StringRef file_path,
+                         std::vector<std::string>& append,
+                         std::vector<std::string>& remove) const {
+    // Rules are processed in declaration order so that a later rule can
+    // override an earlier one. Specifically, when a later rule removes
+    // an argument, we also strip any string-equal entry already added
+    // to `append` by an earlier matching rule — otherwise the append
+    // would silently survive (lookup applies removes to the base flags
+    // only, not to entries contributed via `append`).
+    for(auto& rule: compiled_rules) {
+        bool matched =
+            std::ranges::any_of(rule.patterns, [&](auto& pat) { return pat.match(file_path); });
+        if(!matched)
+            continue;
+
+        for(auto& r: rule.remove) {
+            std::erase(append, r);
+            remove.push_back(r);
+        }
+        append.insert(append.end(), rule.append.begin(), rule.append.end());
+    }
+}
+
+std::optional<Config> Config::load(llvm::StringRef path, llvm::StringRef workspace_root) {
+    auto content = fs::read(path);
+    if(!content)
+        return std::nullopt;
+
+    auto result = kota::codec::toml::parse<Config>(*content);
     if(!result) {
-        LOG_WARN("Failed to parse config file {}", path);
+        LOG_ERROR("Invalid clice.toml {}: {}", path, result.error().to_string());
         return std::nullopt;
     }
 
     auto config = std::move(*result);
     config.apply_defaults(workspace_root);
-
     LOG_INFO("Loaded config from {}", path);
     return config;
 }
 
-CliceConfig CliceConfig::load_from_workspace(const std::string& workspace_root) {
+std::optional<Config> Config::load_from_json(llvm::StringRef json, llvm::StringRef workspace_root) {
+    auto result = kota::codec::json::from_json<Config>(json);
+    if(!result) {
+        LOG_WARN("Failed to parse initializationOptions JSON: {}", result.error().message());
+        return std::nullopt;
+    }
+
+    auto config = std::move(*result);
+    config.apply_defaults(workspace_root);
+    LOG_INFO("Loaded config from initializationOptions");
+    return config;
+}
+
+Config Config::load_from_workspace(llvm::StringRef workspace_root) {
     if(!workspace_root.empty()) {
-        // Try standard config file locations
         for(auto* name: {"clice.toml", ".clice/config.toml"}) {
             auto config_path = path::join(workspace_root, name);
-            if(llvm::sys::fs::exists(config_path)) {
-                auto config = load(config_path, workspace_root);
-                if(config)
-                    return std::move(*config);
-            }
+            if(!llvm::sys::fs::exists(config_path))
+                continue;
+            if(auto config = load(config_path, workspace_root))
+                return std::move(*config);
+            // Present but malformed: fall through to defaults, but surface
+            // the situation clearly so users know their config wasn't applied.
+            LOG_WARN("Falling back to default configuration because {} is invalid", config_path);
         }
     }
 
-    // No config file found; use defaults
-    CliceConfig config;
+    Config config;
     config.apply_defaults(workspace_root);
     LOG_INFO(
         "No clice.toml found, using default configuration " "(stateful={}, stateless={}, memory_limit={}MB)",
-        config.stateful_worker_count,
-        config.stateless_worker_count,
-        config.worker_memory_limit / (1024 * 1024));
+        config.project.stateful_worker_count.value,
+        config.project.stateless_worker_count.value,
+        config.project.worker_memory_limit.value / (1024 * 1024));
     return config;
 }
 

src/server/config.h

@@ -3,44 +3,77 @@
 #include <cstdint>
 #include <optional>
 #include <string>
+#include <vector>
+
+#include "support/glob_pattern.h"
+
+#include "kota/meta/annotation.h"
+#include "llvm/ADT/StringRef.h"
 
 namespace clice {
 
-/// Configuration for the clice LSP server, loadable from clice.toml.
-struct CliceConfig {
-    // Worker configuration (0 = auto-detect from system resources)
-    std::uint32_t stateful_worker_count = 0;
-    std::uint32_t stateless_worker_count = 0;
-    std::uint64_t worker_memory_limit = 0;  // bytes; 0 = auto
+using kota::meta::defaulted;
 
-    // Compilation database path (empty = auto-detect)
-    std::string compile_commands_path;
+/// A file-pattern rule that appends/removes compilation flags.
+/// Corresponds to `[[rules]]` in clice.toml.
+struct ConfigRule {
+    defaulted<std::vector<std::string>> patterns;
+    defaulted<std::vector<std::string>> append;
+    defaulted<std::vector<std::string>> remove;
+};
 
-    // Cache directory (empty = default: <workspace>/.clice/)
-    std::string cache_dir;
+/// Corresponds to the `[project]` section in clice.toml.
+struct ProjectConfig {
+    defaulted<bool> clang_tidy = {};
+    defaulted<int> max_active_file = {};
 
-    // Index storage directory (default: <cache_dir>/index/)
-    std::string index_dir;
+    defaulted<std::string> cache_dir;
+    defaulted<std::string> index_dir;
+    defaulted<std::string> logging_dir;
 
-    // Logging directory (default: <cache_dir>/logs/)
-    std::string logging_dir;
+    defaulted<std::vector<std::string>> compile_commands_paths;
 
-    // Background indexing
-    bool enable_indexing = true;
-    int idle_timeout_ms = 3000;
+    std::optional<bool> enable_indexing;
+    std::optional<int> idle_timeout_ms;
+
+    defaulted<std::uint32_t> stateful_worker_count = {};
+    defaulted<std::uint32_t> stateless_worker_count = {};
+    defaulted<std::uint64_t> worker_memory_limit = {};
+};
+
+struct CompiledRule {
+    std::vector<GlobPattern> patterns;
+    std::vector<std::string> append;
+    std::vector<std::string> remove;
+};
+
+/// Configuration for the clice LSP server, loadable from clice.toml
+/// or passed via LSP initializationOptions.
+struct Config {
+    defaulted<ProjectConfig> project;
+
+    defaulted<std::vector<ConfigRule>> rules;
+
+    kota::meta::annotation<std::vector<CompiledRule>, kota::meta::attrs::skip> compiled_rules;
 
     /// Compute default values for any field left at its zero/empty sentinel.
-    void apply_defaults(const std::string& workspace_root);
+    void apply_defaults(llvm::StringRef workspace_root);
+
+    /// Collect append/remove flags from all rules whose patterns match `path`.
+    void match_rules(llvm::StringRef path,
+                     std::vector<std::string>& append,
+                     std::vector<std::string>& remove) const;
 
     /// Try to load configuration from a TOML file.
-    /// Performs ${workspace} variable substitution in string fields.
-    /// Returns std::nullopt if the file does not exist or cannot be parsed.
-    static std::optional<CliceConfig> load(const std::string& path,
-                                           const std::string& workspace_root);
+    static std::optional<Config> load(llvm::StringRef path, llvm::StringRef workspace_root);
+
+    /// Try to load configuration from a JSON string (e.g. initializationOptions).
+    static std::optional<Config> load_from_json(llvm::StringRef json,
+                                                llvm::StringRef workspace_root);
 
     /// Load config from the workspace, trying standard locations.
     /// Returns a default config (with apply_defaults) if no file is found.
-    static CliceConfig load_from_workspace(const std::string& workspace_root);
+    static Config load_from_workspace(llvm::StringRef workspace_root);
 };
 
 }  // namespace clice

src/server/indexer.cpp

@@ -625,14 +625,14 @@ void Indexer::enqueue(std::uint32_t server_path_id) {
 }
 
 void Indexer::schedule() {
-    if(!workspace.config.enable_indexing || indexing_active || indexing_scheduled)
+    if(!*workspace.config.project.enable_indexing || indexing_active || indexing_scheduled)
         return;
     indexing_scheduled = true;
 
     if(!index_idle_timer) {
         index_idle_timer = std::make_shared<kota::timer>(kota::timer::create(loop));
     }
-    index_idle_timer->start(std::chrono::milliseconds(workspace.config.idle_timeout_ms));
+    index_idle_timer->start(std::chrono::milliseconds(*workspace.config.project.idle_timeout_ms));
     loop.schedule(run_background_indexing());
 }
 
@@ -690,7 +690,7 @@ kota::task<> Indexer::run_background_indexing() {
 
     indexing_active = false;
     LOG_INFO("Background indexing complete: {} files processed", processed);
-    save(workspace.config.index_dir);
+    save(workspace.config.project.index_dir);
 }
 
 }  // namespace clice

src/server/master_server.cpp

@@ -60,47 +60,66 @@ kota::task<> MasterServer::load_workspace() {
     if(workspace_root.empty())
         co_return;
 
-    if(!workspace.config.cache_dir.empty()) {
-        auto ec = llvm::sys::fs::create_directories(workspace.config.cache_dir);
+    auto& cfg = workspace.config.project;
+
+    if(!cfg.cache_dir.empty()) {
+        auto ec = llvm::sys::fs::create_directories(cfg.cache_dir);
         if(ec) {
             LOG_WARN("Failed to create cache directory {}: {}",
-                     workspace.config.cache_dir,
+                     std::string_view(cfg.cache_dir),
                      ec.message());
         } else {
-            LOG_INFO("Cache directory: {}", workspace.config.cache_dir);
+            LOG_INFO("Cache directory: {}", std::string_view(cfg.cache_dir));
         }
 
         for(auto* subdir: {"cache/pch", "cache/pcm"}) {
-            auto dir = path::join(workspace.config.cache_dir, subdir);
-            auto ec2 = llvm::sys::fs::create_directories(dir);
-            if(ec2) {
+            auto dir = path::join(cfg.cache_dir, subdir);
+            if(auto ec2 = llvm::sys::fs::create_directories(dir))
                 LOG_WARN("Failed to create {}: {}", dir, ec2.message());
-            }
         }
 
-        // Clean up stale files first, then load — load_cache() only restores
-        // entries still listed in cache.json, so cleanup won't delete live files.
         workspace.cleanup_cache();
         workspace.load_cache();
     }
 
+    // Discover compile_commands.json: configured paths first, then auto-scan.
     std::string cdb_path;
-    if(!workspace.config.compile_commands_path.empty()) {
-        if(llvm::sys::fs::exists(workspace.config.compile_commands_path)) {
-            cdb_path = workspace.config.compile_commands_path;
-        } else {
-            LOG_WARN("Configured compile_commands_path not found: {}",
-                     workspace.config.compile_commands_path);
-        }
-    }
-
-    if(cdb_path.empty()) {
-        for(auto* subdir: {"build", "cmake-build-debug", "cmake-build-release", "out", "."}) {
-            auto candidate = path::join(workspace_root, subdir, "compile_commands.json");
+    for(auto& configured: cfg.compile_commands_paths) {
+        // Each entry can be a file or a directory containing compile_commands.json.
+        if(llvm::sys::fs::is_directory(configured)) {
+            auto candidate = path::join(configured, "compile_commands.json");
             if(llvm::sys::fs::exists(candidate)) {
                 cdb_path = std::move(candidate);
                 break;
             }
+        } else if(llvm::sys::fs::exists(configured)) {
+            cdb_path = configured;
+            break;
+        } else {
+            LOG_WARN("Configured compile_commands_path not found: {}", configured);
+        }
+    }
+
+    // Auto-scan: workspace root + all immediate subdirectories.
+    if(cdb_path.empty()) {
+        auto try_candidate = [&](llvm::StringRef dir) -> bool {
+            auto candidate = path::join(dir, "compile_commands.json");
+            if(llvm::sys::fs::exists(candidate)) {
+                cdb_path = std::move(candidate);
+                return true;
+            }
+            return false;
+        };
+
+        if(!try_candidate(workspace_root)) {
+            std::error_code ec;
+            for(llvm::sys::fs::directory_iterator it(workspace_root, ec), end; it != end && !ec;
+                it.increment(ec)) {
+                if(it->type() == llvm::sys::fs::file_type::directory_file) {
+                    if(try_candidate(it->path()))
+                        break;
+                }
+            }
         }
     }
 
@@ -112,7 +131,15 @@ kota::task<> MasterServer::load_workspace() {
     auto count = workspace.cdb.load(cdb_path);
     LOG_INFO("Loaded CDB from {} with {} entries", cdb_path, count);
 
-    auto report = scan_dependency_graph(workspace.cdb, workspace.path_pool, workspace.dep_graph);
+    auto report = scan_dependency_graph(workspace.cdb,
+                                        workspace.path_pool,
+                                        workspace.dep_graph,
+                                        /*cache=*/nullptr,
+                                        [this](llvm::StringRef path,
+                                               std::vector<std::string>& append,
+                                               std::vector<std::string>& remove) {
+                                            workspace.config.match_rules(path, append, remove);
+                                        });
     workspace.dep_graph.build_reverse_map();
 
     auto unresolved = report.includes_found - report.includes_resolved;
@@ -131,14 +158,13 @@ kota::task<> MasterServer::load_workspace() {
         report.includes_found,
         accuracy,
         report.waves);
-    if(unresolved > 0) {
+    if(unresolved > 0)
         LOG_WARN("{} unresolved includes", unresolved);
-    }
 
     workspace.build_module_map();
-    indexer.load(workspace.config.index_dir);
+    indexer.load(cfg.index_dir);
 
-    if(workspace.config.enable_indexing) {
+    if(*cfg.enable_indexing) {
         for(auto& entry: workspace.cdb.get_entries()) {
             auto file = workspace.cdb.resolve_path(entry.file);
             auto server_id = workspace.path_pool.intern(file);
@@ -164,6 +190,14 @@ void MasterServer::register_handlers() {
             workspace_root = uri_to_path(*init.root_uri);
         }
 
+        // Capture initializationOptions as raw JSON for config loading.
+        if(init.initialization_options.has_value()) {
+            auto json =
+                kota::codec::json::to_json<kota::ipc::lsp_config>(*init.initialization_options);
+            if(json)
+                init_options_json = std::move(*json);
+        }
+
         lifecycle = ServerLifecycle::Initialized;
         LOG_INFO("Initialized with workspace: {}", workspace_root);
 
@@ -244,27 +278,47 @@ void MasterServer::register_handlers() {
     });
 
     peer.on_notification([this](const protocol::InitializedParams& params) {
-        workspace.config = CliceConfig::load_from_workspace(workspace_root);
+        // Config priority: initializationOptions > clice.toml > defaults.
+        // Load the workspace config (with defaults applied) first, then overlay
+        // any initializationOptions on top so fields not mentioned in the JSON
+        // keep the values from clice.toml — kotatsu's deserializer only touches
+        // fields that are present in the input.
+        workspace.config = Config::load_from_workspace(workspace_root);
+        if(!init_options_json.empty()) {
+            if(auto ov = kota::codec::json::parse(init_options_json, workspace.config); !ov) {
+                LOG_WARN("Failed to apply initializationOptions: {}", ov.error().to_string());
+            } else {
+                // Re-run apply_defaults so overridden strings get workspace
+                // substitution and `compiled_rules` is rebuilt if `rules`
+                // changed. Defaults are gated on zero/empty sentinels, so
+                // existing values from the overlay are preserved.
+                workspace.config.apply_defaults(workspace_root);
+                LOG_INFO("Applied initializationOptions overlay");
+            }
+            init_options_json.clear();
+        }
 
-        if(!workspace.config.logging_dir.empty()) {
+        auto& cfg = workspace.config.project;
+
+        if(!cfg.logging_dir.empty()) {
             auto now = std::chrono::system_clock::now();
             auto pid = llvm::sys::Process::getProcessId();
-            auto session_dir = path::join(workspace.config.logging_dir,
-                                          std::format("{:%Y-%m-%d_%H-%M-%S}_{}", now, pid));
+            auto session_dir =
+                path::join(cfg.logging_dir, std::format("{:%Y-%m-%d_%H-%M-%S}_{}", now, pid));
             logging::file_logger("master", session_dir, logging::options);
             session_log_dir = session_dir;
         }
 
         LOG_INFO("Server ready (stateful={}, stateless={}, idle={}ms)",
-                 workspace.config.stateful_worker_count,
-                 workspace.config.stateless_worker_count,
-                 workspace.config.idle_timeout_ms);
+                 cfg.stateful_worker_count.value,
+                 cfg.stateless_worker_count.value,
+                 *cfg.idle_timeout_ms);
 
         WorkerPoolOptions pool_opts;
         pool_opts.self_path = self_path;
-        pool_opts.stateful_count = workspace.config.stateful_worker_count;
-        pool_opts.stateless_count = workspace.config.stateless_worker_count;
-        pool_opts.worker_memory_limit = workspace.config.worker_memory_limit;
+        pool_opts.stateful_count = cfg.stateful_worker_count;
+        pool_opts.stateless_count = cfg.stateless_worker_count;
+        pool_opts.worker_memory_limit = cfg.worker_memory_limit;
         pool_opts.log_dir = session_log_dir;
         if(!pool.start(pool_opts)) {
             LOG_ERROR("Failed to start worker pool");
@@ -292,7 +346,7 @@ void MasterServer::register_handlers() {
         lifecycle = ServerLifecycle::Exited;
         LOG_INFO("Exit notification received");
 
-        indexer.save(workspace.config.index_dir);
+        indexer.save(workspace.config.project.index_dir);
         workspace.save_cache();
 
         loop.schedule([this]() -> kota::task<> {

src/server/master_server.h

@@ -71,6 +71,7 @@ private:
     std::string self_path;
     std::string workspace_root;
     std::string session_log_dir;
+    std::string init_options_json;  ///< Raw JSON from initializationOptions, consumed once.
 
     kota::task<> load_workspace();
 

src/server/workspace.cpp

@@ -183,10 +183,10 @@ struct CacheData {
 }  // namespace
 
 void Workspace::load_cache() {
-    if(config.cache_dir.empty())
+    if(config.project.cache_dir.empty())
         return;
 
-    auto cache_path = path::join(config.cache_dir, "cache", "cache.json");
+    auto cache_path = path::join(config.project.cache_dir, "cache", "cache.json");
     auto content = fs::read(cache_path);
     if(!content) {
         LOG_DEBUG("No cache.json found at {}", cache_path);
@@ -218,7 +218,7 @@ void Workspace::load_cache() {
     };
 
     for(auto& entry: data.pch) {
-        auto pch_path = path::join(config.cache_dir, "cache", "pch", entry.filename);
+        auto pch_path = path::join(config.project.cache_dir, "cache", "pch", entry.filename);
         auto source = resolve(entry.source_file);
         if(!llvm::sys::fs::exists(pch_path) || source.empty())
             continue;
@@ -234,7 +234,7 @@ void Workspace::load_cache() {
     }
 
     for(auto& entry: data.pcm) {
-        auto pcm_path = path::join(config.cache_dir, "cache", "pcm", entry.filename);
+        auto pcm_path = path::join(config.project.cache_dir, "cache", "pcm", entry.filename);
         auto source = resolve(entry.source_file);
         if(!llvm::sys::fs::exists(pcm_path) || source.empty())
             continue;
@@ -252,7 +252,7 @@ void Workspace::load_cache() {
 }
 
 void Workspace::save_cache() {
-    if(config.cache_dir.empty())
+    if(config.project.cache_dir.empty())
         return;
 
     CacheData data;
@@ -306,7 +306,7 @@ void Workspace::save_cache() {
         return;
     }
 
-    auto cache_path = path::join(config.cache_dir, "cache", "cache.json");
+    auto cache_path = path::join(config.project.cache_dir, "cache", "cache.json");
     auto tmp_path = cache_path + ".tmp";
     auto write_result = fs::write(tmp_path, *json_str);
     if(!write_result) {
@@ -321,14 +321,14 @@ void Workspace::save_cache() {
 }
 
 void Workspace::cleanup_cache(int max_age_days) {
-    if(config.cache_dir.empty())
+    if(config.project.cache_dir.empty())
         return;
 
     auto now = std::chrono::system_clock::now();
     auto max_age = std::chrono::hours(max_age_days * 24);
 
     for(auto* subdir: {"cache/pch", "cache/pcm"}) {
-        auto dir = path::join(config.cache_dir, subdir);
+        auto dir = path::join(config.project.cache_dir, subdir);
         std::error_code ec;
         for(auto it = llvm::sys::fs::directory_iterator(dir, ec);
             !ec && it != llvm::sys::fs::directory_iterator();

src/server/workspace.h

@@ -170,7 +170,7 @@ struct PCMState {
 ///   - didSave         (on_file_saved: rescan disk, cascade invalidation)
 ///   - Background index (merge TUIndex results from stateless workers)
 struct Workspace {
-    CliceConfig config;
+    Config config;
     CompilationDatabase cdb;
 
     PathPool path_pool;

src/support/glob_pattern.cpp

@@ -289,7 +289,7 @@ std::expected<GlobPattern::SubGlobPattern, std::string>
     return pat;
 }
 
-bool GlobPattern::match(llvm::StringRef str) {
+bool GlobPattern::match(llvm::StringRef str) const {
     if(!str.consume_front(prefix)) {
         return false;
     }

src/support/glob_pattern.h

@@ -54,7 +54,7 @@ public:
     }
 
     /// \returns \p true if \p str matches this glob pattern
-    bool match(llvm::StringRef s);
+    bool match(llvm::StringRef s) const;
 
 private:
     /// GlobPattern is seperated into `Prefix + SubGlobPattern`

src/syntax/dependency_graph.cpp

@@ -256,7 +256,8 @@ kota::task<> scan_impl(CompilationDatabase& cdb,
                        DependencyGraph& graph,
                        ScanReport& report,
                        ScanCache* ext_cache,
-                       kota::event_loop& loop) {
+                       kota::event_loop& loop,
+                       const RuleMatcher& rule_matcher) {
     auto start_time = std::chrono::steady_clock::now();
 
     // Reuse context groups and configs from cache when available (warm runs).
@@ -355,9 +356,19 @@ kota::task<> scan_impl(CompilationDatabase& cdb,
             std::uint32_t config_id = next_config_id++;
             context_to_config_id[context] = config_id;
             auto representative_path = path_pool.resolve(file_ids[0]);
+
+            // Apply per-file rules so that `[[rules]]`-modified -I/-isystem/-std
+            // flags are reflected in the search config used by the scan.
+            // Rules are applied to the representative file and assumed to hold
+            // for the whole context group (same CompilationInfo).
+            std::vector<std::string> rule_append, rule_remove;
+            if(rule_matcher)
+                rule_matcher(representative_path, rule_append, rule_remove);
+
             auto t0 = std::chrono::steady_clock::now();
-            configs[config_id] =
-                cdb.lookup_search_config(representative_path, {.query_toolchain = true});
+            configs[config_id] = cdb.lookup_search_config(
+                representative_path,
+                {.query_toolchain = true, .remove = rule_remove, .append = rule_append});
             auto t1 = std::chrono::steady_clock::now();
             lookup_us += std::chrono::duration_cast<std::chrono::microseconds>(t1 - t0).count();
         }
@@ -819,14 +830,15 @@ kota::task<> scan_impl(CompilationDatabase& cdb,
 ScanReport scan_dependency_graph(CompilationDatabase& cdb,
                                  PathPool& path_pool,
                                  DependencyGraph& graph,
-                                 ScanCache* cache) {
+                                 ScanCache* cache,
+                                 const RuleMatcher& rule_matcher) {
     ScanReport report;
     if(cdb.get_entries().empty()) {
         return report;
     }
 
     kota::event_loop loop;
-    loop.schedule(scan_impl(cdb, path_pool, graph, report, cache, loop));
+    loop.schedule(scan_impl(cdb, path_pool, graph, report, cache, loop, rule_matcher));
     loop.run();
     return report;
 }

src/syntax/dependency_graph.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <cstdint>
+#include <functional>
 #include <string>
 #include <vector>
 
@@ -253,6 +254,12 @@ struct ScanCache {
     std::vector<WaveEntry> initial_wave;
 };
 
+/// Callback for per-file rule-based flag modification. Given a file path,
+/// populates `append`/`remove` with rule-configured arguments so they can be
+/// layered on top of the CDB command when extracting the search config.
+using RuleMatcher = std::function<
+    void(llvm::StringRef path, std::vector<std::string>& append, std::vector<std::string>& remove)>;
+
 /// Run the wavefront BFS scan over all files in the compilation database.
 /// Internally creates a local event loop for async I/O (file reads via worker
 /// thread pool, stat calls via libuv). Blocks until the scan is complete.
@@ -261,9 +268,14 @@ struct ScanCache {
 ///               avoids repeated readdir() and include-resolution work across
 ///               successive calls.  PathPool must NOT be reset between calls
 ///               when a persistent cache is used (path_id values must remain stable).
+/// @param rule_matcher  Optional callback applied per context group so that
+///               `[[rules]]`-modified include/std flags are reflected in the
+///               dependency graph (otherwise rule-affected files would have
+///               stale resolution).
 ScanReport scan_dependency_graph(CompilationDatabase& cdb,
                                  PathPool& path_pool,
                                  DependencyGraph& graph,
-                                 ScanCache* cache = nullptr);
+                                 ScanCache* cache = nullptr,
+                                 const RuleMatcher& rule_matcher = {});
 
 }  // namespace clice

tests/conftest.py

@@ -109,7 +109,9 @@ async def client(
     await c.start_io(*cmd)
 
     if workspace is not None:
-        await c.initialize(workspace)
+        init_options_marker = request.node.get_closest_marker("init_options")
+        init_options = init_options_marker.args[0] if init_options_marker else None
+        await c.initialize(workspace, initialization_options=init_options)
 
     yield c
 
@@ -239,6 +241,15 @@ def _generate_test_data_cdbs(data_dir: Path) -> None:
             dl_dir, [_entry(dl_dir, dl_main, [f"-I{dl_dir.as_posix()}", "-std=c++23"])]
         )
 
+    # config_rules_toml / config_rules_no_config — rules tests must start
+    # from a CDB that does NOT include the flag the rule will append, so the
+    # rule's effect is observable through diagnostics.
+    for name in ("config_rules_toml", "config_rules_no_config"):
+        cr_dir = data_dir / name
+        cr_main = cr_dir / "main.cpp"
+        if cr_main.exists():
+            _write(cr_dir, [_entry(cr_dir, cr_main)])
+
     # pch_test
     pt_dir = data_dir / "pch_test"
     if pt_dir.exists():

tests/data/config_rules_no_config/main.cpp

@@ -0,0 +1,7 @@
+int value() {
+    return FROM_INIT;
+}
+
+int main() {
+    return value();
+}

tests/data/config_rules_toml/clice.toml

@@ -0,0 +1,3 @@
+[[rules]]
+patterns = ["**/*.cpp"]
+append = ["-DFROM_TOML"]

tests/data/config_rules_toml/main.cpp

@@ -0,0 +1,7 @@
+int value() {
+    return FROM_TOML;
+}
+
+int main() {
+    return value();
+}

tests/integration/compilation/test_persistent_cache.py

@@ -24,9 +24,17 @@ from tests.integration.utils.cache import (
 from tests.integration.utils.assertions import assert_clean_compile
 
 
+def _pin_cache_to_workspace(tmp_path):
+    """Write a clice.toml that pins cache_dir to <workspace>/.clice/."""
+    (tmp_path / "clice.toml").write_text(
+        '[project]\ncache_dir = "${workspace}/.clice"\n'
+    )
+
+
 async def test_pch_written_to_cache_dir(client, tmp_path):
     """After opening a file with #include, a .pch file should appear
     in .clice/cache/pch/ with a hex-hash filename."""
+    _pin_cache_to_workspace(tmp_path)
     (tmp_path / "header.h").write_text("#pragma once\nstruct Foo { int x; };\n")
     (tmp_path / "main.cpp").write_text(
         '#include "header.h"\nint main() { Foo f; return f.x; }\n'
@@ -48,6 +56,7 @@ async def test_pch_written_to_cache_dir(client, tmp_path):
 
 async def test_cache_json_persisted(client, tmp_path):
     """After a PCH build, cache.json should be written with the entry."""
+    _pin_cache_to_workspace(tmp_path)
     (tmp_path / "header.h").write_text("#pragma once\nint global_val = 42;\n")
     (tmp_path / "main.cpp").write_text(
         '#include "header.h"\nint main() { return global_val; }\n'
@@ -74,6 +83,7 @@ async def test_cache_json_persisted(client, tmp_path):
 async def test_pch_reused_on_close_reopen(client, tmp_path):
     """Closing and reopening a file within the same session should reuse
     the cached PCH — no additional .pch files should be created."""
+    _pin_cache_to_workspace(tmp_path)
     (tmp_path / "header.h").write_text("#pragma once\nstruct Bar { int y; };\n")
     (tmp_path / "main.cpp").write_text(
         '#include "header.h"\nint main() { Bar b; return b.y; }\n'
@@ -108,6 +118,7 @@ async def test_pch_reused_on_close_reopen(client, tmp_path):
 async def test_pch_survives_server_restart(executable, tmp_path):
     """PCH cache should survive a full server restart — cache.json is
     loaded on startup and the existing .pch file is reused."""
+    _pin_cache_to_workspace(tmp_path)
     (tmp_path / "header.h").write_text("#pragma once\nstruct Baz { int z; };\n")
     (tmp_path / "main.cpp").write_text(
         '#include "header.h"\nint main() { Baz b; return b.z; }\n'
@@ -150,6 +161,7 @@ async def test_pch_survives_server_restart(executable, tmp_path):
 async def test_shared_preamble_shares_pch(client, tmp_path):
     """Two files with identical preambles should share the same PCH file
     (content-addressed by preamble hash)."""
+    _pin_cache_to_workspace(tmp_path)
     (tmp_path / "header.h").write_text("#pragma once\nint shared_val = 1;\n")
     (tmp_path / "a.cpp").write_text(
         '#include "header.h"\nint fa() { return shared_val; }\n'
@@ -176,6 +188,7 @@ async def test_shared_preamble_shares_pch(client, tmp_path):
 
 async def test_different_preamble_different_pch(client, tmp_path):
     """Files with different preambles should produce different PCH files."""
+    _pin_cache_to_workspace(tmp_path)
     (tmp_path / "a.h").write_text("#pragma once\nint val_a = 1;\n")
     (tmp_path / "b.h").write_text("#pragma once\nint val_b = 2;\n")
     (tmp_path / "a.cpp").write_text('#include "a.h"\nint fa() { return val_a; }\n')
@@ -199,6 +212,7 @@ async def test_different_preamble_different_pch(client, tmp_path):
 async def test_pch_rebuilt_on_header_change(client, tmp_path):
     """When a preamble header changes, a new PCH should be built
     (different hash → different filename). The old one remains for cleanup."""
+    _pin_cache_to_workspace(tmp_path)
     (tmp_path / "header.h").write_text("#pragma once\nstruct V1 { int a; };\n")
     (tmp_path / "main.cpp").write_text(
         '#include "header.h"\nint main() { V1 v; return v.a; }\n'
@@ -240,6 +254,7 @@ async def test_pch_rebuilt_on_header_change(client, tmp_path):
 
 async def test_no_tmp_files_after_build(client, tmp_path):
     """After a successful PCH build, no .tmp files should remain in the cache dir."""
+    _pin_cache_to_workspace(tmp_path)
     (tmp_path / "header.h").write_text("#pragma once\nint val = 1;\n")
     (tmp_path / "main.cpp").write_text(
         '#include "header.h"\nint main() { return val; }\n'
@@ -265,6 +280,7 @@ async def test_no_tmp_files_after_build(client, tmp_path):
 async def test_cache_dirs_created_on_startup(client, tmp_path):
     """The .clice/cache/pch/ and .clice/cache/pcm/ directories should be created
     when the server initializes a workspace."""
+    _pin_cache_to_workspace(tmp_path)
     (tmp_path / "main.cpp").write_text("int main() { return 0; }\n")
     write_cdb(tmp_path, ["main.cpp"])
     await client.initialize(tmp_path)

tests/integration/lifecycle/test_config.py

@@ -0,0 +1,68 @@
+"""Integration tests for clice configuration (clice.toml + initializationOptions).
+
+Each workspace's main.cpp references a macro that is only defined when the
+rule's `-D<macro>=...` is applied. When rules are applied, compilation is
+clean; otherwise an undeclared-identifier diagnostic surfaces.
+"""
+
+import pytest
+
+from tests.integration.utils.assertions import (
+    assert_clean_compile,
+    assert_has_errors,
+    get_errors,
+)
+
+
+@pytest.mark.workspace("config_rules_no_config")
+async def test_baseline_without_rules(client, workspace):
+    uri, _ = await client.open_and_wait(workspace / "main.cpp")
+    assert_has_errors(client, uri, "Expected diagnostics without any rules applied")
+    errors = get_errors(client.diagnostics[uri])
+    assert any("FROM_INIT" in (d.message or "") for d in errors), (
+        f"Expected a diagnostic referencing FROM_INIT, got: {errors}"
+    )
+
+
+@pytest.mark.workspace("config_rules_toml")
+async def test_rules_from_toml(client, workspace):
+    uri, _ = await client.open_and_wait(workspace / "main.cpp")
+    assert_clean_compile(client, uri)
+
+    symbols = await client.document_symbols(uri)
+    assert symbols, "Expected document symbols for value()/main()"
+    hover = await client.hover_at(uri, line=4, character=4)  # on 'main'
+    assert hover is not None
+
+
+@pytest.mark.workspace("config_rules_no_config")
+@pytest.mark.init_options(
+    {"rules": [{"patterns": ["**/*.cpp"], "append": ["-DFROM_INIT=1"]}]}
+)
+async def test_rules_from_init_options(client, workspace):
+    uri, _ = await client.open_and_wait(workspace / "main.cpp")
+    assert_clean_compile(client, uri)
+
+
+@pytest.mark.workspace("config_rules_toml")
+@pytest.mark.init_options(
+    {"rules": [{"patterns": ["**/*.cpp"], "append": ["-DUNRELATED"]}]}
+)
+async def test_init_options_replaces_toml_rules(client, workspace):
+    uri, _ = await client.open_and_wait(workspace / "main.cpp")
+    assert_has_errors(
+        client, uri, "initializationOptions should have overridden clice.toml rules"
+    )
+    errors = get_errors(client.diagnostics[uri])
+    assert any("FROM_TOML" in (d.message or "") for d in errors), (
+        f"Expected FROM_TOML diagnostic after override, got: {errors}"
+    )
+
+
+@pytest.mark.workspace("config_rules_no_config")
+@pytest.mark.init_options(
+    {"rules": [{"patterns": ["**/does_not_match.cpp"], "append": ["-DFROM_INIT=1"]}]}
+)
+async def test_rules_pattern_mismatch(client, workspace):
+    uri, _ = await client.open_and_wait(workspace / "main.cpp")
+    assert_has_errors(client, uri, "Rule pattern should not have matched main.cpp")

tests/integration/utils/client.py

@@ -86,16 +86,20 @@ class CliceClient(BaseLanguageClient):
 
     # ── Lifecycle ────────────────────────────────────────────────────
 
-    async def initialize(self, workspace: Path) -> InitializeResult:
-        result = await self.initialize_async(
-            InitializeParams(
-                capabilities=ClientCapabilities(),
-                root_uri=workspace.as_uri(),
-                workspace_folders=[
-                    WorkspaceFolder(uri=workspace.as_uri(), name="test")
-                ],
-            )
+    async def initialize(
+        self,
+        workspace: Path,
+        *,
+        initialization_options: dict | None = None,
+    ) -> InitializeResult:
+        params = InitializeParams(
+            capabilities=ClientCapabilities(),
+            root_uri=workspace.as_uri(),
+            workspace_folders=[WorkspaceFolder(uri=workspace.as_uri(), name="test")],
         )
+        if initialization_options is not None:
+            params.initialization_options = initialization_options
+        result = await self.initialize_async(params)
         self.initialized(InitializedParams())
         self.init_result = result
         return result

tests/pytest.ini

@@ -1,3 +1,5 @@
 [pytest]
 asyncio_mode = auto
-markers = workspace
+markers =
+    workspace
+    init_options

tests/unit/feature/code_completion_tests.cpp

@@ -233,6 +233,33 @@ void bar() {
     }
 }
 
+TEST_CASE(DeprecatedTag) {
+    code_complete(R"cpp(
+[[deprecated]] int foooo(int x);
+int z = fo$(pos)
+)cpp");
+
+    auto it = find_item("foooo");
+    ASSERT_TRUE(it != items.end());
+    ASSERT_TRUE(it->tags.has_value());
+    auto& tags = *it->tags;
+    ASSERT_TRUE(std::ranges::find(tags, protocol::CompletionItemTag::Deprecated) != tags.end());
+}
+
+TEST_CASE(NotDeprecated) {
+    code_complete(R"cpp(
+int foooo(int x);
+int z = fo$(pos)
+)cpp");
+
+    auto it = find_item("foooo");
+    ASSERT_TRUE(it != items.end());
+    // Non-deprecated should have no Deprecated tag.
+    ASSERT_TRUE(!it->tags.has_value() ||
+                std::ranges::find(*it->tags, protocol::CompletionItemTag::Deprecated) ==
+                    it->tags->end());
+}
+
 TEST_CASE(NoBundleOverloads) {
     feature::CodeCompletionOptions opts;
     opts.bundle_overloads = false;

tests/unit/server/config_tests.cpp

@@ -0,0 +1,501 @@
+#include <cstdlib>
+
+#include "test/temp_dir.h"
+#include "test/test.h"
+#include "server/config.h"
+#include "support/filesystem.h"
+
+#include "kota/codec/json/json.h"
+#include "kota/codec/toml.h"
+
+namespace clice::testing {
+
+// POSIX setenv/unsetenv don't exist on Windows; map to _putenv_s
+// (passing an empty value to _putenv_s removes the variable).
+static void set_env(const char* name, const char* value) {
+#ifdef _WIN32
+    ::_putenv_s(name, value);
+#else
+    ::setenv(name, value, 1);
+#endif
+}
+
+static void unset_env(const char* name) {
+#ifdef _WIN32
+    ::_putenv_s(name, "");
+#else
+    ::unsetenv(name);
+#endif
+}
+
+TEST_SUITE(Config) {
+
+TEST_CASE(ParsePartialProject) {
+    auto result = kota::codec::toml::parse<ProjectConfig>(R"(cache_dir = "/tmp/test")");
+    EXPECT_TRUE(result.has_value());
+    EXPECT_EQ(std::string_view(result->cache_dir), "/tmp/test");
+    EXPECT_EQ(result->clang_tidy.value, false);
+    EXPECT_EQ(result->max_active_file.value, 0);
+    EXPECT_FALSE(result->enable_indexing.has_value());
+    EXPECT_FALSE(result->idle_timeout_ms.has_value());
+}
+
+TEST_CASE(ParseConfigRule) {
+    auto result = kota::codec::toml::parse<ConfigRule>(R"(
+patterns = ["**/*.cpp"]
+append = ["-std=c++20"]
+)");
+    EXPECT_TRUE(result.has_value());
+    EXPECT_EQ(result->patterns.size(), 1u);
+    EXPECT_EQ(result->patterns[0], "**/*.cpp");
+    EXPECT_EQ(result->append[0], "-std=c++20");
+    EXPECT_TRUE(result->remove.empty());
+}
+
+TEST_CASE(ParseFullConfig) {
+    auto result = kota::codec::toml::parse<Config>(R"(
+[project]
+cache_dir = "/tmp/test"
+clang_tidy = true
+enable_indexing = false
+
+[[rules]]
+patterns = ["**/*.cpp"]
+append = ["-std=c++20"]
+)");
+    EXPECT_TRUE(result.has_value());
+    EXPECT_EQ(std::string_view(result->project.cache_dir), "/tmp/test");
+    EXPECT_EQ(result->project.clang_tidy.value, true);
+    EXPECT_EQ(*result->project.enable_indexing, false);
+    EXPECT_EQ(result->rules.size(), 1u);
+    EXPECT_EQ(result->rules[0].patterns[0], "**/*.cpp");
+}
+
+TEST_CASE(ParseEmptyConfig) {
+    auto result = kota::codec::toml::parse<Config>("");
+    EXPECT_TRUE(result.has_value());
+    EXPECT_TRUE(result->rules.empty());
+    EXPECT_TRUE(std::string_view(result->project.cache_dir).empty());
+}
+
+TEST_CASE(ParseOnlyRules) {
+    auto result = kota::codec::toml::parse<Config>(R"(
+[[rules]]
+patterns = ["*.h"]
+remove = ["-Werror"]
+)");
+    EXPECT_TRUE(result.has_value());
+    EXPECT_EQ(result->rules.size(), 1u);
+    EXPECT_EQ(result->rules[0].patterns[0], "*.h");
+    EXPECT_EQ(result->rules[0].remove[0], "-Werror");
+    EXPECT_TRUE(std::string_view(result->project.cache_dir).empty());
+}
+
+TEST_CASE(MatchRulesBasic) {
+    Config config;
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/*.cpp"},
+        .append = {"-std=c++20"},
+        .remove = {"-std=c++17"},
+    });
+    config.apply_defaults("");
+
+    std::vector<std::string> append, remove;
+    config.match_rules("/src/foo.cpp", append, remove);
+    EXPECT_EQ(append.size(), 1u);
+    EXPECT_EQ(append[0], "-std=c++20");
+    EXPECT_EQ(remove.size(), 1u);
+    EXPECT_EQ(remove[0], "-std=c++17");
+}
+
+TEST_CASE(MatchRulesNoMatch) {
+    Config config;
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/*.cpp"},
+        .append = {"-DFOO"},
+    });
+    config.apply_defaults("");
+
+    std::vector<std::string> append, remove;
+    config.match_rules("/src/foo.h", append, remove);
+    EXPECT_TRUE(append.empty());
+    EXPECT_TRUE(remove.empty());
+}
+
+TEST_CASE(MatchRulesMultiple) {
+    Config config;
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/*.cpp"},
+        .append = {"-DCPP"},
+    });
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/test_*.cpp"},
+        .append = {"-DTEST"},
+    });
+    config.apply_defaults("");
+
+    std::vector<std::string> append, remove;
+    config.match_rules("/src/test_foo.cpp", append, remove);
+    EXPECT_EQ(append.size(), 2u);
+    EXPECT_EQ(append[0], "-DCPP");
+    EXPECT_EQ(append[1], "-DTEST");
+}
+
+TEST_CASE(ApplyDefaults) {
+    Config config;
+    config.apply_defaults("/workspace");
+    EXPECT_EQ(*config.project.enable_indexing, true);
+    EXPECT_EQ(*config.project.idle_timeout_ms, 3000);
+    EXPECT_EQ(config.project.max_active_file.value, 8);
+    EXPECT_EQ(config.project.stateful_worker_count.value, 2u);
+    EXPECT_EQ(config.project.stateless_worker_count.value, 3u);
+    EXPECT_FALSE(config.project.cache_dir.empty());
+    EXPECT_FALSE(config.project.index_dir.empty());
+    EXPECT_FALSE(config.project.logging_dir.empty());
+}
+
+TEST_CASE(ApplyDefaultsEmptyWorkspace) {
+    Config config;
+    config.apply_defaults("");
+    EXPECT_TRUE(config.project.cache_dir.empty());
+    EXPECT_TRUE(config.project.index_dir.empty());
+    EXPECT_TRUE(config.project.logging_dir.empty());
+}
+
+TEST_CASE(ApplyDefaultsPreserveSet) {
+    Config config;
+    config.project.cache_dir = "/custom";
+    config.project.enable_indexing = false;
+    config.apply_defaults("/workspace");
+    EXPECT_EQ(std::string_view(config.project.cache_dir), "/custom");
+    EXPECT_EQ(*config.project.enable_indexing, false);
+}
+
+TEST_CASE(LoadFromJson) {
+    auto result = Config::load_from_json(R"({
+        "project": {
+            "cache_dir": "/opt/cache",
+            "clang_tidy": true,
+            "enable_indexing": false
+        },
+        "rules": [
+            { "patterns": ["**/*.cpp"], "append": ["-DFOO"] }
+        ]
+    })",
+                                         "/workspace");
+    EXPECT_TRUE(result.has_value());
+    EXPECT_EQ(std::string_view(result->project.cache_dir), "/opt/cache");
+    EXPECT_EQ(result->project.clang_tidy.value, true);
+    EXPECT_EQ(*result->project.enable_indexing, false);
+    EXPECT_EQ(result->rules.size(), 1u);
+    EXPECT_EQ(result->compiled_rules.size(), 1u);
+}
+
+TEST_CASE(LoadFromJsonInvalid) {
+    auto result = Config::load_from_json("{not valid json", "/workspace");
+    EXPECT_FALSE(result.has_value());
+}
+
+TEST_CASE(LoadMalformedToml) {
+    TempDir tmp;
+    tmp.touch("clice.toml", "[project\nbroken");
+    auto result = Config::load(tmp.path("clice.toml"), tmp.root.str().str());
+    EXPECT_FALSE(result.has_value());
+}
+
+TEST_CASE(LoadMissingFile) {
+    auto result = Config::load("/nonexistent/clice.toml", "/workspace");
+    EXPECT_FALSE(result.has_value());
+}
+
+TEST_CASE(WorkspaceVarSubst) {
+    Config config;
+    config.project.cache_dir = "${workspace}/cache";
+    config.project.index_dir = "${workspace}/idx";
+    config.project.logging_dir = "${workspace}/logs";
+    config.project.compile_commands_paths = {"${workspace}/build"};
+    config.apply_defaults("/my/ws");
+    EXPECT_EQ(std::string_view(config.project.cache_dir), "/my/ws/cache");
+    EXPECT_EQ(std::string_view(config.project.index_dir), "/my/ws/idx");
+    EXPECT_EQ(std::string_view(config.project.logging_dir), "/my/ws/logs");
+    EXPECT_EQ(config.project.compile_commands_paths[0], "/my/ws/build");
+}
+
+TEST_CASE(XdgCacheDir) {
+    TempDir tmp;
+    auto cache_base = tmp.path("xdg");
+    set_env("XDG_CACHE_HOME", cache_base.c_str());
+    Config config;
+    config.apply_defaults("/some/ws");
+    unset_env("XDG_CACHE_HOME");
+
+    // Normalize separators: on Windows path::join uses '\\' but the test
+    // expects posix-style comparisons.
+    std::string cache = path::convert_to_slash(std::string_view(config.project.cache_dir));
+    std::string base = path::convert_to_slash(cache_base);
+    EXPECT_TRUE(llvm::StringRef(cache).starts_with(base));
+    EXPECT_TRUE(cache.find("/clice/") != std::string::npos);
+}
+
+TEST_CASE(InvalidGlobPattern) {
+    Config config;
+    // All-invalid patterns: rule must be dropped entirely, not appended as empty.
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/****.{c,cc}"},
+        .append = {"-DSHOULD_NOT_APPEAR"},
+    });
+    // Mixed valid/invalid: only the invalid pattern is skipped; rule remains.
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/****.{c,cc}", "**/*.cpp"},
+        .append = {"-DCPP"},
+    });
+    config.apply_defaults("");
+    EXPECT_EQ(config.compiled_rules.size(), 1u);
+
+    std::vector<std::string> append, remove;
+    config.match_rules("/src/foo.cpp", append, remove);
+    EXPECT_EQ(append.size(), 1u);
+    EXPECT_EQ(append[0], "-DCPP");
+}
+
+TEST_CASE(ConfigPriorityJson) {
+    // initializationOptions-sourced config should override an on-disk default.
+    auto from_json =
+        Config::load_from_json(R"({ "project": { "max_active_file": 42 } })", "/workspace");
+    EXPECT_TRUE(from_json.has_value());
+    EXPECT_EQ(from_json->project.max_active_file.value, 42);
+    // Unset fields still receive defaults.
+    EXPECT_EQ(*from_json->project.enable_indexing, true);
+    EXPECT_EQ(from_json->project.stateful_worker_count.value, 2u);
+}
+
+TEST_CASE(XdgHashUnique) {
+    // Different workspace roots must map to different cache dirs,
+    // same workspace root must map to the same dir (deterministic).
+    TempDir tmp;
+    auto cache_base = tmp.path("xdg");
+    set_env("XDG_CACHE_HOME", cache_base.c_str());
+
+    Config a, b, c;
+    a.apply_defaults("/ws/project-a");
+    b.apply_defaults("/ws/project-b");
+    c.apply_defaults("/ws/project-a");
+    unset_env("XDG_CACHE_HOME");
+
+    EXPECT_NE(std::string_view(a.project.cache_dir), std::string_view(b.project.cache_dir));
+    EXPECT_EQ(std::string_view(a.project.cache_dir), std::string_view(c.project.cache_dir));
+}
+
+TEST_CASE(HomeFallback) {
+    // With XDG_CACHE_HOME unset but HOME set, cache dir should be under $HOME/.cache/clice.
+    TempDir tmp;
+    unset_env("XDG_CACHE_HOME");
+    auto home = tmp.path("home");
+    // Save prior value so we restore cleanly.
+    const char* prior = std::getenv("HOME");
+    std::string prior_home = prior ? prior : "";
+    set_env("HOME", home.c_str());
+
+    Config config;
+    config.apply_defaults("/some/ws");
+
+    if(prior_home.empty())
+        unset_env("HOME");
+    else
+        set_env("HOME", prior_home.c_str());
+
+    std::string cache = path::convert_to_slash(std::string_view(config.project.cache_dir));
+    std::string home_posix = path::convert_to_slash(home);
+    EXPECT_TRUE(llvm::StringRef(cache).starts_with(home_posix + "/.cache/clice/"));
+}
+
+TEST_CASE(WorkspaceCacheFallback) {
+    // No XDG, no HOME → should fall back to ${workspace}/.clice.
+    unset_env("XDG_CACHE_HOME");
+    const char* prior = std::getenv("HOME");
+    std::string prior_home = prior ? prior : "";
+    unset_env("HOME");
+
+    Config config;
+    config.apply_defaults("/ws/root");
+
+    if(!prior_home.empty())
+        set_env("HOME", prior_home.c_str());
+
+    EXPECT_EQ(path::convert_to_slash(std::string_view(config.project.cache_dir)),
+              "/ws/root/.clice");
+    EXPECT_EQ(path::convert_to_slash(std::string_view(config.project.index_dir)),
+              "/ws/root/.clice/index");
+    EXPECT_EQ(path::convert_to_slash(std::string_view(config.project.logging_dir)),
+              "/ws/root/.clice/logs");
+}
+
+TEST_CASE(WorkspaceSubstEmpty) {
+    // Empty workspace_root must not rewrite "${workspace}" into "" and produce
+    // bogus paths like "/cache" — the placeholder should be left intact.
+    Config config;
+    config.project.cache_dir = "${workspace}/cache";
+    config.apply_defaults("");
+    EXPECT_EQ(std::string_view(config.project.cache_dir), "${workspace}/cache");
+}
+
+TEST_CASE(WorkspaceSubstRepeated) {
+    // Multiple ${workspace} occurrences in one string all get substituted.
+    Config config;
+    config.project.cache_dir = "${workspace}/a/${workspace}/b";
+    config.apply_defaults("/root");
+    EXPECT_EQ(std::string_view(config.project.cache_dir), "/root/a//root/b");
+}
+
+TEST_CASE(CompilePathsList) {
+    // compile_commands_paths should substitute ${workspace} on every entry.
+    Config config;
+    config.project.compile_commands_paths = {
+        "${workspace}/build",
+        "/abs/path/compile_commands.json",
+        "${workspace}/out",
+    };
+    config.apply_defaults("/ws");
+    EXPECT_EQ(config.project.compile_commands_paths.size(), 3u);
+    EXPECT_EQ(config.project.compile_commands_paths[0], "/ws/build");
+    EXPECT_EQ(config.project.compile_commands_paths[1], "/abs/path/compile_commands.json");
+    EXPECT_EQ(config.project.compile_commands_paths[2], "/ws/out");
+}
+
+TEST_CASE(TomlErrorLocated) {
+    // Malformed TOML (bad table header, missing close-bracket) must return nullopt.
+    TempDir tmp;
+    tmp.touch("clice.toml", "[project\nclang_tidy = true\n");
+    auto result = Config::load(tmp.path("clice.toml"), tmp.root.str());
+    EXPECT_FALSE(result.has_value());
+}
+
+TEST_CASE(WorkspaceMalformedFallback) {
+    // load_from_workspace must fall back to defaults when clice.toml is malformed,
+    // not propagate the failure.
+    TempDir tmp;
+    tmp.touch("clice.toml", "[project\ninvalid");
+    auto config = Config::load_from_workspace(tmp.root.str());
+    // Defaults still applied.
+    EXPECT_EQ(config.project.stateful_worker_count.value, 2u);
+    EXPECT_EQ(*config.project.enable_indexing, true);
+}
+
+TEST_CASE(RuleOrderLaterRemoveWins) {
+    // Later rule's `remove` must cancel an earlier rule's matching `append`.
+    Config config;
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/*.cpp"},
+        .append = {"-DFOO", "-DBAR"},
+    });
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/*.cpp"},
+        .remove = {"-DFOO"},
+    });
+    config.apply_defaults("");
+
+    std::vector<std::string> append, remove;
+    config.match_rules("/src/a.cpp", append, remove);
+
+    // -DFOO should have been stripped from append; -DBAR remains.
+    EXPECT_EQ(append.size(), 1u);
+    EXPECT_EQ(append[0], "-DBAR");
+    // remove is still forwarded so base CDB flags also get filtered.
+    EXPECT_EQ(remove.size(), 1u);
+    EXPECT_EQ(remove[0], "-DFOO");
+}
+
+TEST_CASE(RuleOrderLaterAppendWins) {
+    // Later append comes after earlier append — at compiler level, last wins
+    // for flags like -O; verify the ordering is preserved.
+    Config config;
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/*.cpp"},
+        .append = {"-O2"},
+    });
+    config.rules.push_back(ConfigRule{
+        .patterns = {"**/*.cpp"},
+        .append = {"-O3"},
+    });
+    config.apply_defaults("");
+
+    std::vector<std::string> append, remove;
+    config.match_rules("/src/a.cpp", append, remove);
+    EXPECT_EQ(append.size(), 2u);
+    EXPECT_EQ(append[0], "-O2");
+    EXPECT_EQ(append[1], "-O3");
+}
+
+TEST_CASE(InitOptionsOverlayPreservesToml) {
+    // Mirror the master_server flow: load workspace config from clice.toml first,
+    // then overlay initializationOptions JSON. Fields absent in the JSON must
+    // keep their clice.toml values; fields present in the JSON override.
+    TempDir tmp;
+    tmp.touch("clice.toml", R"(
+[project]
+cache_dir = "/from/toml"
+clang_tidy = true
+max_active_file = 16
+
+[[rules]]
+patterns = ["**/*.cpp"]
+append = ["-DFROM_TOML"]
+)");
+
+    auto config = Config::load_from_workspace(tmp.root.str());
+    EXPECT_EQ(std::string_view(config.project.cache_dir), "/from/toml");
+    EXPECT_EQ(config.project.clang_tidy.value, true);
+    EXPECT_EQ(config.project.max_active_file.value, 16);
+    EXPECT_EQ(config.compiled_rules.size(), 1u);
+
+    // Overlay only `max_active_file` via JSON.
+    auto ov = kota::codec::json::parse(R"({ "project": { "max_active_file": 99 } })", config);
+    EXPECT_TRUE(ov.has_value());
+    config.apply_defaults(tmp.root.str());
+
+    // Overridden field.
+    EXPECT_EQ(config.project.max_active_file.value, 99);
+    // Untouched fields stay at TOML values.
+    EXPECT_EQ(std::string_view(config.project.cache_dir), "/from/toml");
+    EXPECT_EQ(config.project.clang_tidy.value, true);
+    // Rules from clice.toml must survive the overlay.
+    EXPECT_EQ(config.rules.size(), 1u);
+    EXPECT_EQ(config.compiled_rules.size(), 1u);
+    EXPECT_EQ(config.rules[0].append[0], "-DFROM_TOML");
+}
+
+TEST_CASE(InitOptionsOverlayRulesReplace) {
+    // When `rules` is present in the overlay JSON, it replaces the whole array
+    // (kotatsu deserializes the vector by value). `compiled_rules` must be
+    // rebuilt after apply_defaults so stale compiled entries don't linger.
+    TempDir tmp;
+    tmp.touch("clice.toml", R"(
+[[rules]]
+patterns = ["**/*.cpp"]
+append = ["-DTOML_ONLY"]
+)");
+    auto config = Config::load_from_workspace(tmp.root.str());
+    EXPECT_EQ(config.compiled_rules.size(), 1u);
+
+    auto ov = kota::codec::json::parse(
+        R"({ "rules": [ { "patterns": ["**/*.cc"], "append": ["-DFROM_JSON"] } ] })",
+        config);
+    EXPECT_TRUE(ov.has_value());
+    config.apply_defaults(tmp.root.str());
+
+    EXPECT_EQ(config.rules.size(), 1u);
+    EXPECT_EQ(config.rules[0].append[0], "-DFROM_JSON");
+    EXPECT_EQ(config.compiled_rules.size(), 1u);
+
+    // Original TOML rule no longer applies.
+    std::vector<std::string> append, remove;
+    config.match_rules("/src/x.cpp", append, remove);
+    EXPECT_TRUE(append.empty());
+    config.match_rules("/src/x.cc", append, remove);
+    EXPECT_EQ(append.size(), 1u);
+    EXPECT_EQ(append[0], "-DFROM_JSON");
+}
+
+};  // TEST_SUITE(Config)
+
+}  // namespace clice::testing