Clarify folding pipeline and options handling

.github/workflows/main.yml

@@ -7,10 +7,6 @@ on:
   pull_request:
     branches: [main]
 
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
-
 jobs:
   changes:
     if: ${{ !startsWith(github.ref, 'refs/tags/') }}

.github/workflows/test-cmake.yml

@@ -96,20 +96,9 @@ jobs:
           if-no-files-found: error
           retention-days: 1
 
-      - name: Unit tests
+      - name: Run tests
         if: ${{ !matrix.build_only }}
-        timeout-minutes: 5
-        run: pixi run unit-test ${{ matrix.build_type }}
-
-      - name: Integration tests
-        if: ${{ !matrix.build_only }}
-        timeout-minutes: 20
-        run: pixi run integration-test ${{ matrix.build_type }}
-
-      - name: Smoke tests
-        if: ${{ !matrix.build_only }}
-        timeout-minutes: 15
-        run: pixi run smoke-test ${{ matrix.build_type }}
+        run: pixi run test ${{ matrix.build_type }}
 
       - name: Print cache stats and stop server
         if: always()
@@ -157,14 +146,5 @@ jobs:
         if: runner.os != 'Windows'
         run: chmod +x build/${{ matrix.build_type }}/bin/*
 
-      - name: Unit tests
-        timeout-minutes: 5
-        run: pixi run -e test-run unit-test ${{ matrix.build_type }}
-
-      - name: Integration tests
-        timeout-minutes: 20
-        run: pixi run -e test-run integration-test ${{ matrix.build_type }}
-
-      - name: Smoke tests
-        timeout-minutes: 10
-        run: pixi run -e test-run smoke-test ${{ matrix.build_type }}
+      - 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/

benchmarks/scan_benchmark.cpp

@@ -26,7 +26,7 @@
 #include "support/path_pool.h"
 #include "syntax/dependency_graph.h"
 
-#include "kota/codec/json/json.h"
+#include "kota/codec/json/serializer.h"
 #include "kota/deco/deco.h"
 #include "llvm/Support/FileSystem.h"
 

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

@@ -1078,7 +1078,6 @@ environments:
       - pypi: https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl
-      - pypi: https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl
       linux-aarch64:
       - conda: https://conda.anaconda.org/conda-forge/linux-aarch64/_openmp_mutex-4.5-20_gnu.conda
@@ -1153,7 +1152,6 @@ environments:
       - pypi: https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl
-      - pypi: https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl
       osx-64:
       - conda: https://conda.anaconda.org/conda-forge/osx-64/bzip2-1.0.8-h500dc9f_9.conda
@@ -1226,7 +1224,6 @@ environments:
       - pypi: https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl
-      - pypi: https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl
       osx-arm64:
       - conda: https://conda.anaconda.org/conda-forge/osx-arm64/bzip2-1.0.8-hd037594_8.conda
@@ -1292,7 +1289,6 @@ environments:
       - pypi: https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl
-      - pypi: https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl
       win-64:
       - conda: https://conda.anaconda.org/conda-forge/win-64/bzip2-1.0.8-h0ad9c76_8.conda
@@ -1347,7 +1343,6 @@ environments:
       - pypi: https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl
-      - pypi: https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl
   format:
     channels:
@@ -1709,7 +1704,6 @@ environments:
       - pypi: https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl
-      - pypi: https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl
       linux-aarch64:
       - conda: https://conda.anaconda.org/conda-forge/linux-aarch64/_openmp_mutex-4.5-20_gnu.conda
@@ -1788,7 +1782,6 @@ environments:
       - pypi: https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl
-      - pypi: https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl
       osx-64:
       - conda: https://conda.anaconda.org/conda-forge/osx-64/bzip2-1.0.8-h500dc9f_9.conda
@@ -1865,7 +1858,6 @@ environments:
       - pypi: https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl
-      - pypi: https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl
       osx-arm64:
       - conda: https://conda.anaconda.org/conda-forge/osx-arm64/bzip2-1.0.8-hd037594_8.conda
@@ -1934,7 +1926,6 @@ environments:
       - pypi: https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl
-      - pypi: https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl
       win-64:
       - conda: https://conda.anaconda.org/conda-forge/win-64/bzip2-1.0.8-h0ad9c76_8.conda
@@ -1991,7 +1982,6 @@ environments:
       - pypi: https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl
-      - pypi: https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl
   test-run:
     channels:
@@ -2035,7 +2025,6 @@ environments:
       - pypi: https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl
-      - pypi: https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl
       linux-aarch64:
       - conda: https://conda.anaconda.org/conda-forge/linux-aarch64/_openmp_mutex-4.5-20_gnu.conda
@@ -2069,7 +2058,6 @@ environments:
       - pypi: https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl
-      - pypi: https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl
       osx-64:
       - conda: https://conda.anaconda.org/conda-forge/osx-64/bzip2-1.0.8-h500dc9f_9.conda
@@ -2125,7 +2113,6 @@ environments:
       - pypi: https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl
-      - pypi: https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl
       osx-arm64:
       - conda: https://conda.anaconda.org/conda-forge/osx-arm64/bzip2-1.0.8-hd037594_9.conda
@@ -2181,7 +2168,6 @@ environments:
       - pypi: https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl
-      - pypi: https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl
       win-64:
       - conda: https://conda.anaconda.org/conda-forge/win-64/bzip2-1.0.8-h0ad9c76_9.conda
@@ -2213,7 +2199,6 @@ environments:
       - pypi: https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl
-      - pypi: https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl
       win-arm64:
       - conda: https://conda.anaconda.org/conda-forge/win-arm64/bzip2-1.0.8-h50b96f5_9.conda
@@ -2244,7 +2229,6 @@ environments:
       - pypi: https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl
-      - pypi: https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl
       - pypi: https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl
 packages:
 - conda: https://conda.anaconda.org/conda-forge/linux-64/_libgcc_mutex-0.1-conda_forge.tar.bz2
@@ -7811,13 +7795,6 @@ packages:
   - coverage>=6.2 ; extra == 'testing'
   - hypothesis>=5.7.1 ; extra == 'testing'
   requires_python: '>=3.10'
-- pypi: https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl
-  name: pytest-timeout
-  version: 2.4.0
-  sha256: c42667e5cdadb151aeb5b26d114aff6bdf5a907f176a007a30b940d3d865b5c2
-  requires_dist:
-  - pytest>=7.0.0
-  requires_python: '>=3.7'
 - conda: https://conda.anaconda.org/conda-forge/linux-64/python-3.14.2-h32b2ec7_100_cp314.conda
   build_number: 100
   sha256: a120fb2da4e4d51dd32918c149b04a08815fd2bd52099dad1334647984bb07f1

pixi.toml

@@ -102,7 +102,6 @@ lld = "==20.1.8"
 [feature.test.pypi-dependencies]
 pytest = "*"
 pytest-asyncio = ">=1.1.0"
-pytest-timeout = "*"
 pygls = ">=2.0.0"
 lsprotocol = ">=2024.0.0"
 
@@ -166,8 +165,8 @@ cmd = './build/{{ type }}/bin/unit_tests --test-dir="./tests/data"'
 [feature.test.tasks.integration-test]
 args = [{ arg = "type", default = "RelWithDebInfo" }]
 cmd = """
-pytest -s --log-cli-level=INFO --timeout=300 --timeout-method=thread \
-    tests/integration --executable=./build/{{ type }}/bin/clice
+pytest -s --log-cli-level=INFO tests/integration \
+    --executable=./build/{{ type }}/bin/clice
 """
 
 [feature.test.tasks.smoke-test]

src/compile/compilation.cpp

@@ -219,10 +219,9 @@ public:
 
     auto CreateASTConsumer(clang::CompilerInstance& instance, llvm::StringRef file)
         -> std::unique_ptr<clang::ASTConsumer> final {
-        auto consumer = WrapperFrontendAction::CreateASTConsumer(instance, file);
-        if(!consumer)
-            return nullptr;
-        return std::make_unique<ProxyASTConsumer>(std::move(consumer), unit);
+        return std::make_unique<ProxyASTConsumer>(
+            WrapperFrontendAction::CreateASTConsumer(instance, file),
+            unit);
     }
 
     /// Make this public.
@@ -242,7 +241,6 @@ CompilationStatus CompilationUnitRef::Self::run_clang(
     std::unique_ptr diagnostic_consumer = self.create_diagnostic();
     std::unique_ptr invocation = self.create_invocation(params, diagnostic_consumer.get());
     if(!invocation) {
-        LOG_WARN("run_clang: invocation creation failed");
         return CompilationStatus::SetupFail;
     }
 
@@ -257,7 +255,6 @@ CompilationStatus CompilationUnitRef::Self::run_clang(
     }
 
     if(!instance.createTarget()) {
-        LOG_WARN("run_clang: target creation failed");
         return CompilationStatus::SetupFail;
     }
 
@@ -272,7 +269,6 @@ CompilationStatus CompilationUnitRef::Self::run_clang(
         /// But if we fail to `BeginSourceFile` we don't need to call `EndSourceFile`. So just
         /// reset it.
         self.action.reset();
-        LOG_WARN("run_clang: BeginSourceFile failed");
         return CompilationStatus::SetupFail;
     }
 
@@ -306,8 +302,6 @@ CompilationStatus CompilationUnitRef::Self::run_clang(
     /// in crash frequently. So forbidden it here and return as error.
     if(!instance.getFrontendOpts().OutputFile.empty() &&
        instance.getDiagnostics().hasErrorOccurred()) {
-        LOG_WARN("run_clang: errors during PCH/PCM generation, output={}",
-                 instance.getFrontendOpts().OutputFile);
         return CompilationStatus::FatalError;
     }
 

src/compile/compilation_unit.cpp

@@ -81,8 +81,7 @@ auto CompilationUnitRef::file_offset(clang::SourceLocation location) -> std::uin
 }
 
 auto CompilationUnitRef::file_path(clang::FileID fid) -> llvm::StringRef {
-    if(!fid.isValid())
-        return {};
+    assert(fid.isValid() && "Invalid fid");
     if(auto it = self->path_cache.find(fid); it != self->path_cache.end()) {
         return it->second;
     }

src/semantic/ast_utility.cpp

@@ -308,10 +308,6 @@ const clang::NamedDecl* decl_of_impl(const void* T) {
 }
 
 auto decl_of(clang::QualType type) -> const clang::NamedDecl* {
-    if(type.isNull()) {
-        return nullptr;
-    }
-
     // Strip type-sugar that wraps the underlying type without adding a decl
     // (e.g. ElaboratedType for "struct Foo" vs plain "Foo").
     if(auto ET = type->getAs<clang::ElaboratedType>()) {

src/server/compiler.cpp

@@ -122,11 +122,9 @@ void Compiler::init_compile_graph() {
 
         auto result = co_await pool.send_stateless(bp);
         if(!result.has_value() || !result.value().success) {
-            auto error_msg = result.has_value() ? result.value().error : result.error().message;
-            LOG_WARN("BuildPCM failed for module {}: {}", mod_it->second, error_msg);
-            peer.send_notification(protocol::LogMessageParams{
-                protocol::MessageType::Warning,
-                std::format("PCM build failed for module {}: {}", mod_it->second, error_msg)});
+            LOG_WARN("BuildPCM failed for module {}: {}",
+                     mod_it->second,
+                     result.has_value() ? result.value().error : result.error().message);
             co_return false;
         }
 
@@ -173,10 +171,6 @@ bool Compiler::fill_compile_args(llvm::StringRef path,
         auto& cmd = results.front();
         directory = cmd.resolved.directory.str();
         arguments = cmd.to_string_argv();
-        LOG_DEBUG("fill_compile_args: CDB match for {} (dir={}, {} args)",
-                  path,
-                  directory,
-                  arguments.size());
         return true;
     }
 
@@ -496,22 +490,6 @@ kota::task<bool> Compiler::ensure_pch(Session& session,
     auto completion = std::make_shared<kota::event>();
     workspace.pch_cache[path_id].building = completion;
 
-    if(workspace.config.project.cache_dir.empty()) {
-        LOG_WARN("PCH build skipped: cache_dir is not configured");
-        workspace.pch_cache[path_id].building.reset();
-        completion->set();
-        co_return false;
-    }
-
-    // Ensure the PCH cache directory exists.
-    auto pch_dir = path::join(workspace.config.project.cache_dir, "cache", "pch");
-    if(auto ec = llvm::sys::fs::create_directories(pch_dir)) {
-        LOG_WARN("Cannot create PCH cache dir {}: {}", pch_dir, ec.message());
-        workspace.pch_cache[path_id].building.reset();
-        completion->set();
-        co_return false;
-    }
-
     // Build a new PCH via stateless worker.
     worker::BuildParams bp;
     bp.kind = worker::BuildKind::BuildPCH;
@@ -527,11 +505,9 @@ kota::task<bool> Compiler::ensure_pch(Session& session,
     auto result = co_await pool.send_stateless(bp);
 
     if(!result.has_value() || !result.value().success) {
-        auto error_msg = result.has_value() ? result.value().error : result.error().message;
-        LOG_WARN("PCH build failed for {}: {}", path, error_msg);
-        peer.send_notification(protocol::LogMessageParams{
-            protocol::MessageType::Warning,
-            std::format("PCH build failed for {}: {}", path, error_msg)});
+        LOG_WARN("PCH build failed for {}: {}",
+                 path,
+                 result.has_value() ? result.value().error : result.error().message);
         workspace.pch_cache[path_id].building.reset();
         completion->set();
         co_return false;
@@ -738,10 +714,6 @@ kota::task<bool> Compiler::ensure_compiled(Session& session) {
         params.version = sess->version;
         params.text = sess->text;
         if(!self->fill_compile_args(file_path, params.directory, params.arguments, sess)) {
-            LOG_WARN("ensure_compiled: no compile args for {}", uri_str);
-            self->peer.send_notification(protocol::LogMessageParams{
-                protocol::MessageType::Warning,
-                std::format("No compile arguments available for {}", file_path)});
             finish_compile();
             co_return;
         }
@@ -749,9 +721,6 @@ kota::task<bool> Compiler::ensure_compiled(Session& session) {
         if(!co_await self
                 ->ensure_deps(*sess, params.directory, params.arguments, params.pch, params.pcms)) {
             LOG_WARN("Dependency preparation failed for {}, skipping compile", uri_str);
-            self->peer.send_notification(protocol::LogMessageParams{
-                protocol::MessageType::Warning,
-                std::format("Dependency preparation failed for {}", file_path)});
             finish_compile();
             co_return;
         }
@@ -783,9 +752,6 @@ kota::task<bool> Compiler::ensure_compiled(Session& session) {
 
         if(!result.has_value()) {
             LOG_WARN("Compile failed for {}: {}", uri_str, result.error().message);
-            self->peer.send_notification(protocol::LogMessageParams{
-                protocol::MessageType::Error,
-                std::format("Compilation failed for {}: {}", file_path, result.error().message)});
             self->clear_diagnostics(uri_str);
             finish_compile();
             co_return;
@@ -834,17 +800,11 @@ Compiler::RawResult Compiler::forward_query(worker::QueryKind kind,
     auto text = session.text;
 
     if(!co_await ensure_compiled(session)) {
-        LOG_WARN("forward_query: compilation failed for {}", path);
-        co_await kota::fail("Compilation failed");
+        co_return serde_raw{"null"};
     }
 
     auto sit = sessions.find(path_id);
-    if(sit == sessions.end()) {
-        LOG_WARN("forward_query: session lost after compile for {}", path);
-        co_await kota::fail("Document was closed during compilation");
-    }
-    if(sit->second.ast_dirty) {
-        LOG_DEBUG("forward_query: still dirty after compile for {} (concurrent edit)", path);
+    if(sit == sessions.end() || sit->second.ast_dirty) {
         co_return serde_raw{"null"};
     }
 
@@ -856,13 +816,8 @@ Compiler::RawResult Compiler::forward_query(worker::QueryKind kind,
 
     if(position) {
         auto offset = mapper.to_offset(*position);
-        if(!offset) {
-            LOG_WARN("forward_query: invalid position {}:{} for {}",
-                     position->line,
-                     position->character,
-                     path);
-            co_await kota::fail("Invalid position: failed to convert to byte offset");
-        }
+        if(!offset)
+            co_return serde_raw{"null"};
         wp.offset = *offset;
     }
 
@@ -876,8 +831,7 @@ Compiler::RawResult Compiler::forward_query(worker::QueryKind kind,
 
     auto result = co_await pool.send_stateful(path_id, wp);
     if(!result.has_value()) {
-        LOG_WARN("forward_query: worker failed for {}: {}", path, result.error().message);
-        co_await kota::fail(result.error().message);
+        co_return serde_raw{};
     }
     co_return std::move(result.value());
 }
@@ -896,36 +850,27 @@ Compiler::RawResult Compiler::forward_build(worker::BuildKind kind,
     wp.version = session.version;
     wp.text = session.text;
     if(!fill_compile_args(path, wp.directory, wp.arguments, &session)) {
-        LOG_WARN("forward_build: compile args not available for {}", path);
-        co_await kota::fail("Compile arguments not available");
+        co_return serde_raw{};
     }
 
     if(!co_await ensure_deps(session, wp.directory, wp.arguments, wp.pch, wp.pcms)) {
-        LOG_WARN("forward_build: dependency preparation failed for {}", path);
-        co_await kota::fail("Dependency preparation failed");
+        co_return serde_raw{};
     }
 
     // After co_await, verify session still exists.
     if(sessions.find(path_id) == sessions.end()) {
-        LOG_WARN("forward_build: session lost after co_await for {}", path);
-        co_await kota::fail("Document was closed during compilation");
+        co_return serde_raw{};
     }
 
     lsp::PositionMapper mapper(wp.text, lsp::PositionEncoding::UTF16);
     auto offset = mapper.to_offset(position);
-    if(!offset) {
-        LOG_WARN("forward_build: invalid position {}:{} for {}",
-                 position.line,
-                 position.character,
-                 path);
-        co_await kota::fail("Invalid position: failed to convert to byte offset");
-    }
+    if(!offset)
+        co_return serde_raw{"null"};
     wp.offset = *offset;
 
     auto result = co_await pool.send_stateless(wp);
     if(!result.has_value()) {
-        LOG_WARN("forward_build: worker failed for {}: {}", path, result.error().message);
-        co_await kota::fail(result.error().message);
+        co_return serde_raw{};
     }
     co_return std::move(result.value().result_json);
 }
@@ -943,10 +888,8 @@ Compiler::RawResult Compiler::handle_completion(const protocol::Position& positi
            pctx.kind == CompletionContext::IncludeAngled) {
             std::string directory;
             std::vector<std::string> arguments;
-            if(!fill_compile_args(path, directory, arguments)) {
-                LOG_WARN("handle_completion: compile args not available for {}", path);
-                co_await kota::fail("Compile arguments not available for include completion");
-            }
+            if(!fill_compile_args(path, directory, arguments))
+                co_return serde_raw{"[]"};
 
             std::vector<const char*> args_ptrs;
             args_ptrs.reserve(arguments.size());

src/server/compiler.h

@@ -14,7 +14,7 @@
 #include "syntax/completion.h"
 
 #include "kota/async/async.h"
-#include "kota/codec/json/json.h"
+#include "kota/codec/raw_value.h"
 #include "kota/ipc/codec/json.h"
 #include "kota/ipc/lsp/protocol.h"
 #include "kota/ipc/peer.h"

src/server/config.cpp

@@ -6,9 +6,8 @@
 #include "support/glob_pattern.h"
 #include "support/logging.h"
 
-#include "kota/async/io/system.h"
 #include "kota/codec/json/json.h"
-#include "kota/codec/toml/toml.h"
+#include "kota/codec/toml.h"
 #include "llvm/Support/FileSystem.h"
 #include "llvm/Support/Path.h"
 #include "llvm/Support/Process.h"
@@ -66,10 +65,8 @@ void Config::apply_defaults(llvm::StringRef workspace_root) {
 
     if(p.stateful_worker_count == 0)
         p.stateful_worker_count = 2;
-    if(p.stateless_worker_count == 0) {
-        auto cores = kota::sys::parallelism();
-        p.stateless_worker_count = std::max(cores / 2, 2u);
-    }
+    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
 
@@ -168,7 +165,7 @@ std::optional<Config> Config::load_from_json(llvm::StringRef json, llvm::StringR
     return config;
 }
 
-Config Config::load_from_workspace(llvm::StringRef workspace_root, std::string* warning) {
+Config Config::load_from_workspace(llvm::StringRef workspace_root) {
     if(!workspace_root.empty()) {
         for(auto* name: {"clice.toml", ".clice/config.toml"}) {
             auto config_path = path::join(workspace_root, name);
@@ -179,9 +176,6 @@ Config Config::load_from_workspace(llvm::StringRef workspace_root, std::string*
             // 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);
-            if(warning)
-                *warning = std::format("Configuration file {} is invalid, falling back to defaults",
-                                       config_path);
         }
     }
 

src/server/config.h

@@ -73,10 +73,7 @@ struct Config {
 
     /// Load config from the workspace, trying standard locations.
     /// Returns a default config (with apply_defaults) if no file is found.
-    /// If `warning` is non-null and a config file was found but malformed,
-    /// the warning message is written there.
-    static Config load_from_workspace(llvm::StringRef workspace_root,
-                                      std::string* warning = nullptr);
+    static Config load_from_workspace(llvm::StringRef workspace_root);
 };
 
 }  // namespace clice

src/server/indexer.cpp

@@ -1,6 +1,5 @@
 #include "server/indexer.h"
 
-#include <algorithm>
 #include <string>
 #include <variant>
 #include <vector>
@@ -625,23 +624,6 @@ void Indexer::enqueue(std::uint32_t server_path_id) {
     index_queue.push_back(server_path_id);
 }
 
-void Indexer::pause_indexing() {
-    ++pause_depth;
-    if(pause_depth == 1) {
-        resume_event.reset();
-        LOG_DEBUG("Background indexing paused");
-    }
-}
-
-void Indexer::resume_indexing() {
-    if(pause_depth > 0)
-        --pause_depth;
-    if(pause_depth == 0) {
-        resume_event.set();
-        LOG_DEBUG("Background indexing resumed");
-    }
-}
-
 void Indexer::schedule() {
     if(!*workspace.config.project.enable_indexing || indexing_active || indexing_scheduled)
         return;
@@ -654,76 +636,6 @@ void Indexer::schedule() {
     loop.schedule(run_background_indexing());
 }
 
-kota::task<> Indexer::index_one(std::uint32_t server_path_id) {
-    auto file_path = std::string(workspace.path_pool.resolve(server_path_id));
-
-    if(sessions.contains(server_path_id))
-        co_return;
-
-    if(!need_update(file_path))
-        co_return;
-
-    // For module interface units, compile their PCM (and transitive deps)
-    // first so the stateless worker has the artifacts it needs.
-    if(workspace.compile_graph && workspace.path_to_module.contains(server_path_id)) {
-        co_await workspace.compile_graph->compile(server_path_id);
-    }
-
-    worker::BuildParams params;
-    params.kind = worker::BuildKind::Index;
-    params.file = file_path;
-    if(!compiler.fill_compile_args(file_path, params.directory, params.arguments, nullptr))
-        co_return;
-
-    workspace.fill_pcm_deps(params.pcms);
-
-    LOG_INFO("Background indexing: {}", file_path);
-
-    auto result = co_await pool.send_stateless(params);
-    if(result.has_value() && result.value().success && !result.value().tu_index_data.empty()) {
-        LOG_INFO("Background indexing got TUIndex for {}: {} bytes",
-                 file_path,
-                 result.value().tu_index_data.size());
-        merge(result.value().tu_index_data.data(), result.value().tu_index_data.size());
-    } else if(result.has_value() && !result.value().success) {
-        LOG_WARN("Background index failed for {}: {}", file_path, result.value().error);
-    } else if(result.has_value() && result.value().tu_index_data.empty()) {
-        LOG_WARN("Background index returned empty TUIndex for {}", file_path);
-    } else {
-        LOG_WARN("Background index IPC error for {}: {}", file_path, result.error().message);
-    }
-}
-
-kota::task<> Indexer::monitor_resources(std::uint32_t generation) {
-    while(generation == monitor_generation) {
-        co_await kota::sleep(std::chrono::milliseconds(3000), loop);
-
-        if(generation != monitor_generation)
-            break;
-
-        auto mem = kota::sys::memory();
-        if(mem.total == 0)
-            continue;
-
-        // Respect cgroup/container limits when present.
-        auto effective_total =
-            (mem.constrained > 0 && mem.constrained < mem.total) ? mem.constrained : mem.total;
-        auto ratio = static_cast<double>(mem.available) / static_cast<double>(effective_total);
-
-        if(ratio < 0.15 && max_concurrent > 1) {
-            --max_concurrent;
-            LOG_INFO("Index concurrency -> {} (memory pressure: {:.0f}% available)",
-                     max_concurrent,
-                     ratio * 100);
-        } else if(ratio > 0.30 && max_concurrent < baseline_concurrent) {
-            ++max_concurrent;
-            LOG_DEBUG("Index concurrency -> {} (memory OK: {:.0f}% available)",
-                      max_concurrent,
-                      ratio * 100);
-        }
-    }
-}
-
 kota::task<> Indexer::run_background_indexing() {
     if(index_idle_timer) {
         co_await index_idle_timer->wait();
@@ -736,88 +648,48 @@ kota::task<> Indexer::run_background_indexing() {
     }
 
     indexing_active = true;
-    ++monitor_generation;
-    loop.schedule(monitor_resources(monitor_generation));
+    std::size_t processed = 0;
 
-    // Put module interface units first so their PCMs are built before
-    // non-module files that might import them.
-    std::stable_partition(
-        index_queue.begin() + index_queue_pos,
-        index_queue.end(),
-        [this](std::uint32_t id) { return workspace.path_to_module.contains(id); });
+    while(index_queue_pos < index_queue.size()) {
+        auto server_path_id = index_queue[index_queue_pos];
+        index_queue_pos++;
 
-    auto batch = index_queue.size() - index_queue_pos;
-    std::size_t dispatched = 0;
-    std::size_t completed = 0;
-    finished = 0;
+        auto file_path = std::string(workspace.path_pool.resolve(server_path_id));
 
-    // Progress reporting via LSP $/progress.
-    std::optional<lsp::ProgressReporter<kota::ipc::JsonPeer>> progress;
-    if(peer) {
-        progress.emplace(*peer, protocol::ProgressToken(std::string("clice/backgroundIndex")));
-        auto create_result = co_await progress->create();
-        if(!create_result.has_error()) {
-            progress->begin("Indexing", std::format("0/{} files", batch), 0);
+        if(sessions.contains(server_path_id))
+            continue;
+
+        if(!need_update(file_path))
+            continue;
+
+        worker::BuildParams params;
+        params.kind = worker::BuildKind::Index;
+        params.file = file_path;
+        if(!compiler.fill_compile_args(file_path, params.directory, params.arguments, nullptr))
+            continue;
+
+        workspace.fill_pcm_deps(params.pcms);
+
+        LOG_INFO("Background indexing: {}", file_path);
+
+        auto result = co_await pool.send_stateless(params);
+        if(result.has_value() && result.value().success && !result.value().tu_index_data.empty()) {
+            LOG_INFO("Background indexing got TUIndex for {}: {} bytes",
+                     file_path,
+                     result.value().tu_index_data.size());
+            merge(result.value().tu_index_data.data(), result.value().tu_index_data.size());
+            ++processed;
+        } else if(result.has_value() && !result.value().success) {
+            LOG_WARN("Background index failed for {}: {}", file_path, result.value().error);
+        } else if(result.has_value() && result.value().tu_index_data.empty()) {
+            LOG_WARN("Background index returned empty TUIndex for {}", file_path);
         } else {
-            progress.reset();
+            LOG_WARN("Background index IPC error for {}: {}", file_path, result.error().message);
         }
     }
 
-    while(index_queue_pos < index_queue.size() || inflight > 0) {
-        // Dispatch new tasks up to max_concurrent.
-        while(index_queue_pos < index_queue.size() && inflight < max_concurrent) {
-            // Wait if paused by a user request.
-            if(pause_depth > 0) {
-                co_await resume_event.wait();
-            }
-
-            auto server_path_id = index_queue[index_queue_pos++];
-
-            // Quick pre-filter: skip open files and fresh files without
-            // consuming a concurrency slot.
-            auto file_path = std::string(workspace.path_pool.resolve(server_path_id));
-            if(sessions.contains(server_path_id) || !need_update(file_path)) {
-                ++completed;
-                continue;
-            }
-
-            ++inflight;
-            ++dispatched;
-
-            // Launch the index task.  On completion it decrements
-            // inflight, bumps finished, and signals the event.
-            loop.schedule([](Indexer* self, std::uint32_t id, kota::event& done) -> kota::task<> {
-                co_await self->index_one(id);
-                --self->inflight;
-                ++self->finished;
-                done.set();
-            }(this, server_path_id, completion_event));
-        }
-
-        if(inflight == 0)
-            break;
-
-        // Wait for at least one task to finish.
-        co_await completion_event.wait();
-        completion_event.reset();
-
-        // Drain all completions that occurred since last wake.
-        completed += std::exchange(finished, 0);
-
-        // Report progress.
-        if(progress) {
-            auto pct = batch > 0 ? static_cast<std::uint32_t>(completed * 100 / batch) : 100;
-            progress->report(std::format("{}/{} files", completed, batch), pct);
-        }
-    }
-
-    if(progress) {
-        progress->end(std::format("Indexed {} files", dispatched));
-    }
-
     indexing_active = false;
-    ++monitor_generation;  // Stop the monitor coroutine.
-    LOG_INFO("Background indexing complete: {} files dispatched", dispatched);
+    LOG_INFO("Background indexing complete: {} files processed", processed);
     save(workspace.config.project.index_dir);
 }
 

src/server/indexer.h

@@ -12,9 +12,7 @@
 #include "server/workspace.h"
 
 #include "kota/async/async.h"
-#include "kota/ipc/codec/json.h"
 #include "kota/ipc/lsp/position.h"
-#include "kota/ipc/lsp/progress.h"
 #include "kota/ipc/lsp/protocol.h"
 #include "llvm/ADT/DenseMap.h"
 #include "llvm/ADT/SmallVector.h"
@@ -64,47 +62,6 @@ public:
         loop(loop), workspace(workspace), sessions(sessions), pool(pool), compiler(compiler),
         is_file_open(std::move(is_file_open)) {}
 
-    /// Set the LSP peer for progress reporting.  Must be called before
-    /// schedule() if progress notifications are desired.
-    void set_peer(kota::ipc::JsonPeer* p) {
-        peer = p;
-    }
-
-    /// Temporarily pause background indexing to give priority to user
-    /// requests.  Indexing tasks already dispatched to workers continue,
-    /// but no new tasks will be sent until resume_indexing() is called.
-    void pause_indexing();
-
-    /// Resume background indexing after a pause.
-    void resume_indexing();
-
-    /// RAII guard that pauses indexing for its lifetime.
-    struct [[nodiscard]] ScopedPause {
-        Indexer& indexer;
-
-        explicit ScopedPause(Indexer& idx) : indexer(idx) {
-            indexer.pause_indexing();
-        }
-
-        ~ScopedPause() {
-            indexer.resume_indexing();
-        }
-
-        ScopedPause(const ScopedPause&) = delete;
-        ScopedPause& operator=(const ScopedPause&) = delete;
-    };
-
-    ScopedPause scoped_pause() {
-        return ScopedPause{*this};
-    }
-
-    /// Set the maximum number of concurrent index tasks.
-    /// Also sets the baseline that dynamic adjustment will restore to.
-    void set_max_concurrency(std::size_t n) {
-        max_concurrent = std::max<std::size_t>(n, 1);
-        baseline_concurrent = max_concurrent;
-    }
-
     /// Add a file to the background indexing queue.
     void enqueue(std::uint32_t server_path_id);
 
@@ -218,9 +175,6 @@ private:
     /// server-path-id-keyed sessions map to project-level path_ids.
     std::function<bool(std::uint32_t)> is_file_open;
 
-    /// LSP peer for progress reporting (optional, not owned).
-    kota::ipc::JsonPeer* peer = nullptr;
-
     /// Background indexing queue and scheduling state.
     std::vector<std::uint32_t> index_queue;
     std::size_t index_queue_pos = 0;
@@ -228,30 +182,7 @@ private:
     bool indexing_scheduled = false;
     std::shared_ptr<kota::timer> index_idle_timer;
 
-    /// Concurrency control for background indexing.
-    std::size_t max_concurrent = 2;
-    std::size_t baseline_concurrent = 2;
-    std::size_t inflight = 0;
-    std::size_t finished = 0;  ///< Incremented by each completed dispatch task.
-
-    /// Pause/resume: when paused, new index tasks wait on this event.
-    /// Uses a counter so nested pause/resume pairs work correctly.
-    std::size_t pause_depth = 0;
-    kota::event resume_event{true};
-
-    /// Completion event — signalled by each finished dispatch task so the
-    /// main loop can wake up.  Must be a member (not local to the coroutine)
-    /// because inflight tasks capture it by reference and may outlive the
-    /// coroutine frame during server shutdown.
-    kota::event completion_event;
-
-    /// Generation counter — incremented each run so a stale monitor_resources
-    /// coroutine can detect that its owning run has ended.
-    std::uint32_t monitor_generation = 0;
-
     kota::task<> run_background_indexing();
-    kota::task<> index_one(std::uint32_t server_path_id);
-    kota::task<> monitor_resources(std::uint32_t generation);
 };
 
 }  // namespace clice

src/server/master_server.cpp

@@ -56,9 +56,9 @@ MasterServer::MasterServer(kota::event_loop& loop,
 
 MasterServer::~MasterServer() = default;
 
-void MasterServer::load_workspace() {
+kota::task<> MasterServer::load_workspace() {
     if(workspace_root.empty())
-        return;
+        co_return;
 
     auto& cfg = workspace.config.project;
 
@@ -125,10 +125,7 @@ void MasterServer::load_workspace() {
 
     if(cdb_path.empty()) {
         LOG_WARN("No compile_commands.json found in workspace {}", workspace_root);
-        peer.send_notification(protocol::LogMessageParams{
-            protocol::MessageType::Warning,
-            std::format("No compile_commands.json found in workspace {}", workspace_root)});
-        return;
+        co_return;
     }
 
     auto count = workspace.cdb.load(cdb_path);
@@ -286,18 +283,10 @@ void MasterServer::register_handlers() {
         // 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.
-        std::string config_warning;
-        workspace.config = Config::load_from_workspace(workspace_root, &config_warning);
-        if(!config_warning.empty())
-            peer.send_notification(
-                protocol::LogMessageParams{protocol::MessageType::Warning, config_warning});
+        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());
-                peer.send_notification(protocol::LogMessageParams{
-                    protocol::MessageType::Warning,
-                    std::format("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`
@@ -333,8 +322,6 @@ void MasterServer::register_handlers() {
         pool_opts.log_dir = session_log_dir;
         if(!pool.start(pool_opts)) {
             LOG_ERROR("Failed to start worker pool");
-            peer.send_notification(protocol::LogMessageParams{protocol::MessageType::Error,
-                                                              "Failed to start worker pool"});
             return;
         }
 
@@ -344,10 +331,7 @@ void MasterServer::register_handlers() {
             indexer.schedule();
         };
 
-        indexer.set_peer(&peer);
-        indexer.set_max_concurrency(cfg.stateless_worker_count.value);
-
-        load_workspace();
+        loop.schedule(load_workspace());
     });
 
     peer.on_request(
@@ -501,7 +485,7 @@ void MasterServer::register_handlers() {
         auto path_id = workspace.path_pool.intern(path);
         auto sit = sessions.find(path_id);
         if(sit == sessions.end())
-            co_await kota::fail("Document not open");
+            co_return serde_raw{"null"};
         co_return co_await compiler.forward_query(worker::QueryKind::Hover,
                                                   sit->second,
                                                   params.text_document_position_params.position);
@@ -513,7 +497,7 @@ void MasterServer::register_handlers() {
         auto path_id = workspace.path_pool.intern(path);
         auto sit = sessions.find(path_id);
         if(sit == sessions.end())
-            co_await kota::fail("Document not open");
+            co_return serde_raw{"null"};
         co_return co_await compiler.forward_query(worker::QueryKind::SemanticTokens, sit->second);
     });
 
@@ -523,7 +507,7 @@ void MasterServer::register_handlers() {
             auto path_id = workspace.path_pool.intern(path);
             auto sit = sessions.find(path_id);
             if(sit == sessions.end())
-                co_await kota::fail("Document not open");
+                co_return serde_raw{"null"};
             co_return co_await compiler.forward_query(worker::QueryKind::InlayHints,
                                                       sit->second,
                                                       {},
@@ -536,7 +520,7 @@ void MasterServer::register_handlers() {
             auto path_id = workspace.path_pool.intern(path);
             auto sit = sessions.find(path_id);
             if(sit == sessions.end())
-                co_await kota::fail("Document not open");
+                co_return serde_raw{"null"};
             co_return co_await compiler.forward_query(worker::QueryKind::FoldingRange, sit->second);
         });
 
@@ -546,7 +530,7 @@ void MasterServer::register_handlers() {
         auto path_id = workspace.path_pool.intern(path);
         auto sit = sessions.find(path_id);
         if(sit == sessions.end())
-            co_await kota::fail("Document not open");
+            co_return serde_raw{"null"};
         co_return co_await compiler.forward_query(worker::QueryKind::DocumentSymbol, sit->second);
     });
 
@@ -556,7 +540,7 @@ void MasterServer::register_handlers() {
         auto path_id = workspace.path_pool.intern(path);
         auto sit = sessions.find(path_id);
         if(sit == sessions.end())
-            co_await kota::fail("Document not open");
+            co_return serde_raw{"null"};
         auto& session = sit->second;
         auto result = co_await compiler.forward_query(worker::QueryKind::DocumentLink, session);
         if(!result.has_value())
@@ -589,7 +573,7 @@ void MasterServer::register_handlers() {
             auto path_id = workspace.path_pool.intern(path);
             auto sit = sessions.find(path_id);
             if(sit == sessions.end())
-                co_await kota::fail("Document not open");
+                co_return serde_raw{"null"};
             co_return co_await compiler.forward_query(worker::QueryKind::CodeAction, sit->second);
         });
 
@@ -644,7 +628,7 @@ void MasterServer::register_handlers() {
         auto path_id = workspace.path_pool.intern(path);
         auto sit = sessions.find(path_id);
         if(sit == sessions.end())
-            co_await kota::fail("Document not open");
+            co_return serde_raw{"null"};
         co_return co_await compiler.forward_query(worker::QueryKind::GoToDefinition,
                                                   sit->second,
                                                   pos);
@@ -686,33 +670,28 @@ void MasterServer::register_handlers() {
 
     /// Feature requests — stateless forwarding.
 
-    peer.on_request(
-        [this](RequestContext& ctx, const protocol::CompletionParams& params) -> RawResult {
-            auto path = uri_to_path(params.text_document_position_params.text_document.uri);
-            auto path_id = workspace.path_pool.intern(path);
-            auto sit = sessions.find(path_id);
-            if(sit == sessions.end())
-                co_await kota::fail("Document not open");
-            auto pause = indexer.scoped_pause();
-            auto result =
-                co_await compiler.handle_completion(params.text_document_position_params.position,
-                                                    sit->second);
-            co_return std::move(result);
-        });
-
     peer.on_request([this](RequestContext& ctx,
-                           const protocol::SignatureHelpParams& params) -> RawResult {
+                           const protocol::CompletionParams& params) -> RawResult {
         auto path = uri_to_path(params.text_document_position_params.text_document.uri);
         auto path_id = workspace.path_pool.intern(path);
         auto sit = sessions.find(path_id);
         if(sit == sessions.end())
-            co_await kota::fail("Document not open");
-        auto pause = indexer.scoped_pause();
-        auto result = co_await compiler.forward_build(worker::BuildKind::SignatureHelp,
+            co_return serde_raw{"null"};
+        co_return co_await compiler.handle_completion(params.text_document_position_params.position,
+                                                      sit->second);
+    });
+
+    peer.on_request(
+        [this](RequestContext& ctx, const protocol::SignatureHelpParams& params) -> RawResult {
+            auto path = uri_to_path(params.text_document_position_params.text_document.uri);
+            auto path_id = workspace.path_pool.intern(path);
+            auto sit = sessions.find(path_id);
+            if(sit == sessions.end())
+                co_return serde_raw{"null"};
+            co_return co_await compiler.forward_build(worker::BuildKind::SignatureHelp,
                                                       params.text_document_position_params.position,
                                                       sit->second);
-        co_return std::move(result);
-    });
+        });
 
     /// Hierarchy queries — index-based.
 
@@ -738,8 +717,10 @@ void MasterServer::register_handlers() {
                         const protocol::CallHierarchyIncomingCallsParams& params) -> RawResult {
         auto info = resolve_item(params.item.uri, params.item.range, params.item.data);
         if(!info)
-            co_await kota::fail("Failed to resolve call hierarchy item");
+            co_return serde_raw{"null"};
         auto results = indexer.find_incoming_calls(info->hash);
+        if(results.empty())
+            co_return serde_raw{"null"};
         co_return to_raw(results);
     });
 
@@ -748,8 +729,10 @@ void MasterServer::register_handlers() {
                         const protocol::CallHierarchyOutgoingCallsParams& params) -> RawResult {
         auto info = resolve_item(params.item.uri, params.item.range, params.item.data);
         if(!info)
-            co_await kota::fail("Failed to resolve call hierarchy item");
+            co_return serde_raw{"null"};
         auto results = indexer.find_outgoing_calls(info->hash);
+        if(results.empty())
+            co_return serde_raw{"null"};
         co_return to_raw(results);
     });
 
@@ -776,8 +759,10 @@ void MasterServer::register_handlers() {
                              const protocol::TypeHierarchySupertypesParams& params) -> RawResult {
             auto info = resolve_item(params.item.uri, params.item.range, params.item.data);
             if(!info)
-                co_await kota::fail("Failed to resolve type hierarchy item");
+                co_return serde_raw{"null"};
             auto results = indexer.find_supertypes(info->hash);
+            if(results.empty())
+                co_return serde_raw{"null"};
             co_return to_raw(results);
         });
 
@@ -786,14 +771,18 @@ void MasterServer::register_handlers() {
                              const protocol::TypeHierarchySubtypesParams& params) -> RawResult {
             auto info = resolve_item(params.item.uri, params.item.range, params.item.data);
             if(!info)
-                co_await kota::fail("Failed to resolve type hierarchy item");
+                co_return serde_raw{"null"};
             auto results = indexer.find_subtypes(info->hash);
+            if(results.empty())
+                co_return serde_raw{"null"};
             co_return to_raw(results);
         });
 
     peer.on_request(
         [this](RequestContext& ctx, const protocol::WorkspaceSymbolParams& params) -> RawResult {
             auto results = indexer.search_symbols(params.query);
+            if(results.empty())
+                co_return serde_raw{"null"};
             co_return to_raw(results);
         });
 

src/server/master_server.h

@@ -12,7 +12,7 @@
 #include "server/workspace.h"
 
 #include "kota/async/async.h"
-#include "kota/codec/json/json.h"
+#include "kota/codec/raw_value.h"
 #include "kota/ipc/peer.h"
 #include "llvm/ADT/DenseMap.h"
 
@@ -73,7 +73,7 @@ private:
     std::string session_log_dir;
     std::string init_options_json;  ///< Raw JSON from initializationOptions, consumed once.
 
-    void load_workspace();
+    kota::task<> load_workspace();
 
     using RawResult = kota::task<kota::codec::RawValue, kota::ipc::Error>;
 };

src/server/protocol.h

@@ -9,7 +9,7 @@
 
 #include "syntax/token.h"
 
-#include "kota/codec/json/json.h"
+#include "kota/codec/raw_value.h"
 #include "kota/ipc/lsp/protocol.h"
 #include "kota/ipc/protocol.h"
 

src/server/stateful_worker.cpp

@@ -94,7 +94,6 @@ class StatefulWorker {
     kota::task<kota::codec::RawValue> with_ast(llvm::StringRef path, F&& fn) {
         auto it = documents.find(path);
         if(it == documents.end()) {
-            LOG_WARN("with_ast: document not found: {}", path.str());
             co_return kota::codec::RawValue{"null"};
         }
 
@@ -106,10 +105,8 @@ class StatefulWorker {
         co_await doc->strand.lock();
 
         auto result = co_await kota::queue([&]() -> kota::codec::RawValue {
-            if(!doc->has_ast || (!doc->unit.completed() && !doc->unit.fatal_error())) {
-                LOG_WARN("with_ast: AST not available for {}", path.str());
+            if(!doc->has_ast || (!doc->unit.completed() && !doc->unit.fatal_error()))
                 return kota::codec::RawValue{"null"};
-            }
             return fn(*doc);
         });
 

src/server/stateless_worker.cpp

@@ -15,22 +15,6 @@
 
 namespace clice {
 
-/// RAII guard that lowers the current process's scheduling priority and
-/// restores it on destruction.
-struct ScopedNice {
-    int saved;
-
-    explicit ScopedNice(int increment = 10) {
-        auto p = kota::sys::priority();
-        saved = p ? *p : 0;
-        kota::sys::set_priority(saved + increment);
-    }
-
-    ~ScopedNice() {
-        kota::sys::set_priority(saved);
-    }
-};
-
 using kota::ipc::RequestResult;
 using RequestContext = kota::ipc::BincodePeer::RequestContext;
 
@@ -244,8 +228,6 @@ static worker::BuildResult handle_completion(const worker::BuildParams& params)
     cp.completion = {params.file, params.offset};
 
     auto items = feature::code_complete(cp);
-    if(items.empty())
-        LOG_DEBUG("Completion: no items returned for {}:{}", params.file, params.offset);
     LOG_DEBUG("Completion done: {} items, {}ms", items.size(), timer.ms());
 
     worker::BuildResult result;
@@ -269,7 +251,7 @@ static worker::BuildResult handle_signature_help(const worker::BuildParams& para
     cp.completion = {params.file, params.offset};
 
     auto help = feature::signature_help(cp);
-    LOG_DEBUG("SignatureHelp done: {} signatures, {}ms", help.signatures.size(), timer.ms());
+    LOG_DEBUG("SignatureHelp done: {}ms", timer.ms());
 
     worker::BuildResult result;
     result.result_json = to_raw(help);
@@ -301,10 +283,7 @@ int run_stateless_worker_mode(const std::string& worker_name, const std::string&
             switch(params.kind) {
                 case K::BuildPCH: return handle_build_pch(params);
                 case K::BuildPCM: return handle_build_pcm(params);
-                case K::Index: {
-                    ScopedNice guard;
-                    return handle_index(params);
-                }
+                case K::Index: return handle_index(params);
                 case K::Completion: return handle_completion(params);
                 case K::SignatureHelp: return handle_signature_help(params);
             }

src/server/worker_common.h

@@ -8,7 +8,8 @@
 
 #include "compile/compilation.h"
 
-#include "kota/codec/json/json.h"
+#include "kota/codec/json/serializer.h"
+#include "kota/codec/raw_value.h"
 #include "kota/ipc/codec/json.h"
 
 namespace clice {

src/server/worker_pool.cpp

@@ -13,13 +13,14 @@ namespace {
 
 /// Coroutine that drains a worker's stderr pipe.
 /// Workers write their own log files, so this only captures unexpected output
-/// (crash stacktraces, assertion failures, sanitizer reports, etc.).
+/// (crash stacktraces, assertion failures, etc.) that bypasses spdlog.
 kota::task<> drain_stderr(kota::pipe stderr_pipe, std::string prefix) {
     std::string buffer;
     while(true) {
         auto result = co_await stderr_pipe.read();
-        if(!result.has_value())
+        if(!result.has_value()) {
             break;
+        }
         auto& chunk = result.value();
         if(chunk.empty())
             break;
@@ -33,7 +34,7 @@ kota::task<> drain_stderr(kota::pipe stderr_pipe, std::string prefix) {
                 break;
             auto line = buffer.substr(pos, nl - pos);
             if(!line.empty()) {
-                LOG_WARN("{} {}", prefix, line);
+                LOG_DEBUG("{} {}", prefix, line);
             }
             pos = nl + 1;
         }
@@ -41,7 +42,7 @@ kota::task<> drain_stderr(kota::pipe stderr_pipe, std::string prefix) {
     }
 
     if(!buffer.empty()) {
-        LOG_WARN("{} {}", prefix, buffer);
+        LOG_DEBUG("{} {}", prefix, buffer);
     }
 }
 
@@ -107,29 +108,24 @@ bool WorkerPool::spawn_worker(const std::string& self_path,
     });
 
     auto& w = workers.back();
-    w.alive = true;
-    ++alive_count_;
     loop.schedule(w.peer->run());
 
     return true;
 }
 
 bool WorkerPool::start(const WorkerPoolOptions& options) {
-    options_ = options;
     log_dir_ = options.log_dir;
 
     for(std::uint32_t i = 0; i < options.stateless_count; ++i) {
         if(!spawn_worker(options.self_path, false, 0)) {
             return false;
         }
-        loop.schedule(monitor_worker(stateless_workers.size() - 1, false));
     }
 
     for(std::uint32_t i = 0; i < options.stateful_count; ++i) {
         if(!spawn_worker(options.self_path, true, options.worker_memory_limit)) {
             return false;
         }
-        loop.schedule(monitor_worker(stateful_workers.size() - 1, true));
     }
 
     // Register evicted notification handler for each stateful worker
@@ -149,24 +145,29 @@ bool WorkerPool::start(const WorkerPoolOptions& options) {
 
 kota::task<> WorkerPool::stop() {
     LOG_INFO("WorkerPool stopping...");
-    shutting_down_ = true;
 
-    // Close output pipes to signal workers to exit gracefully.
-    for(auto& w: stateless_workers)
+    // Close output pipes to signal workers to exit gracefully
+    for(auto& w: stateless_workers) {
         w.peer->close_output();
-    for(auto& w: stateful_workers)
+    }
+    for(auto& w: stateful_workers) {
         w.peer->close_output();
+    }
 
-    // Send SIGTERM.  monitor_worker coroutines handle the wait.
-    for(auto& w: stateless_workers)
+    // Send SIGTERM to all workers
+    for(auto& w: stateless_workers) {
         w.proc.kill(SIGTERM);
-    for(auto& w: stateful_workers)
+    }
+    for(auto& w: stateful_workers) {
         w.proc.kill(SIGTERM);
+    }
 
-    // Wait until all monitor_worker coroutines have finished.
-    if(alive_count_ > 0) {
-        all_exited_.reset();
-        co_await all_exited_.wait();
+    // Wait for all worker processes to exit
+    for(auto& w: stateless_workers) {
+        co_await w.proc.wait();
+    }
+    for(auto& w: stateful_workers) {
+        co_await w.proc.wait();
     }
 
     LOG_INFO("WorkerPool stopped");
@@ -197,10 +198,7 @@ std::size_t WorkerPool::assign_worker(std::uint32_t path_id) {
 std::size_t WorkerPool::pick_least_loaded() {
     std::size_t best = 0;
     for(std::size_t i = 1; i < stateful_workers.size(); ++i) {
-        if(!stateful_workers[i].alive)
-            continue;
-        if(!stateful_workers[best].alive ||
-           stateful_workers[i].owned_documents < stateful_workers[best].owned_documents) {
+        if(stateful_workers[i].owned_documents < stateful_workers[best].owned_documents) {
             best = i;
         }
     }
@@ -235,127 +233,4 @@ void WorkerPool::clear_owner(std::size_t worker_index) {
     }
 }
 
-kota::task<> WorkerPool::monitor_worker(std::size_t index, bool stateful) {
-    auto& workers = stateful ? stateful_workers : stateless_workers;
-    auto& w = workers[index];
-    auto name = std::string(stateful ? "SF-" : "SL-") + std::to_string(index);
-
-    auto result = co_await w.proc.wait();
-    w.alive = false;
-    --alive_count_;
-
-    if(shutting_down_) {
-        if(alive_count_ == 0)
-            all_exited_.set();
-        co_return;
-    }
-
-    if(result.has_value()) {
-        auto& exit = result.value();
-        if(exit.term_signal != 0) {
-            LOG_ERROR("Worker {} killed by signal {} (restarts: {})",
-                      name,
-                      exit.term_signal,
-                      w.restart_count);
-        } else {
-            LOG_ERROR("Worker {} exited with code {} (restarts: {})",
-                      name,
-                      exit.status,
-                      w.restart_count);
-        }
-    } else {
-        LOG_ERROR("Worker {} lost: {} (restarts: {})",
-                  name,
-                  result.error().message(),
-                  w.restart_count);
-    }
-
-    if(stateful)
-        clear_owner(index);
-
-    constexpr unsigned max_restarts = 5;
-    if(w.restart_count >= max_restarts) {
-        LOG_ERROR("Worker {} exceeded max restarts ({}), giving up", name, max_restarts);
-        co_return;
-    }
-
-    if(!respawn_worker(index, stateful)) {
-        LOG_ERROR("Worker {} respawn failed", name);
-    }
-}
-
-bool WorkerPool::respawn_worker(std::size_t index, bool stateful) {
-    auto& workers = stateful ? stateful_workers : stateless_workers;
-    auto old_restart_count = workers[index].restart_count + 1;
-    auto worker_name = std::string(stateful ? "SF-" : "SL-") + std::to_string(index);
-
-    // Close the old peer and retire it so its coroutines (run/write_loop)
-    // can finish naturally before the object is destroyed.
-    if(workers[index].peer) {
-        workers[index].peer->close();
-        retired_peers.push_back(std::move(workers[index].peer));
-    }
-
-    kota::process::options opts;
-    opts.file = options_.self_path;
-    if(stateful) {
-        opts.args = {options_.self_path,
-                     "--mode",
-                     "stateful-worker",
-                     "--worker-memory-limit",
-                     std::to_string(options_.worker_memory_limit)};
-    } else {
-        opts.args = {options_.self_path, "--mode", "stateless-worker"};
-    }
-    opts.args.push_back("--worker-name");
-    opts.args.push_back(worker_name);
-    if(!log_dir_.empty()) {
-        opts.args.push_back("--log-dir");
-        opts.args.push_back(log_dir_);
-    }
-    opts.streams = {
-        kota::process::stdio::pipe(true, false),
-        kota::process::stdio::pipe(false, true),
-        kota::process::stdio::pipe(false, true),
-    };
-
-    auto result = kota::process::spawn(opts, loop);
-    if(!result) {
-        LOG_ERROR("Failed to respawn worker {}: {}", worker_name, result.error().message());
-        return false;
-    }
-
-    auto& spawn = *result;
-    auto transport = std::make_unique<kota::ipc::StreamTransport>(std::move(spawn.stdout_pipe),
-                                                                  std::move(spawn.stdin_pipe));
-    auto peer = std::make_unique<kota::ipc::BincodePeer>(loop, std::move(transport));
-
-    std::string prefix = "[" + worker_name + "]";
-    loop.schedule(drain_stderr(std::move(spawn.stderr_pipe), prefix));
-
-    workers[index] = WorkerProcess{
-        .proc = std::move(spawn.proc),
-        .peer = std::move(peer),
-        .owned_documents = 0,
-        .alive = true,
-        .restart_count = old_restart_count,
-    };
-
-    auto& w = workers[index];
-    ++alive_count_;
-    loop.schedule(w.peer->run());
-
-    if(stateful) {
-        w.peer->on_notification([this](const worker::EvictedParams& params) {
-            if(on_evicted)
-                on_evicted(params.path);
-        });
-    }
-
-    loop.schedule(monitor_worker(index, stateful));
-
-    LOG_INFO("Worker {} restarted (attempt {})", worker_name, old_restart_count);
-    return true;
-}
-
 }  // namespace clice

src/server/worker_pool.h

@@ -64,8 +64,6 @@ private:
         kota::process proc;
         std::unique_ptr<kota::ipc::BincodePeer> peer;
         std::size_t owned_documents = 0;
-        bool alive = true;
-        unsigned restart_count = 0;
     };
 
     kota::event_loop& loop;
@@ -82,19 +80,8 @@ private:
     void clear_owner(std::size_t worker_index);
     std::size_t pick_least_loaded();
 
-    bool shutting_down_ = false;
-    std::size_t alive_count_ = 0;
-    kota::event all_exited_{true};  // Signalled when alive_count_ reaches 0.
-    WorkerPoolOptions options_;
     std::string log_dir_;
-
-    /// Peers moved here during respawn so their coroutines can finish
-    /// before the object is destroyed.
-    llvm::SmallVector<std::unique_ptr<kota::ipc::BincodePeer>> retired_peers;
-
     bool spawn_worker(const std::string& self_path, bool stateful, std::uint64_t memory_limit);
-    bool respawn_worker(std::size_t index, bool stateful);
-    kota::task<> monitor_worker(std::size_t index, bool stateful);
 };
 
 template <typename Params>
@@ -104,10 +91,11 @@ RequestResult<Params> WorkerPool::send_stateful(std::uint32_t path_id,
     if(stateful_workers.empty()) {
         co_return kota::outcome_error(kota::ipc::Error{"No stateful workers available"});
     }
+    // No timeout: compile tasks run as detached tasks (loop.schedule) that
+    // are immune to LSP $/cancelRequest.  Adding a timeout here would use
+    // kotatsu's with_token/when_any which has a spurious-cancellation bug
+    // that kills requests within milliseconds instead of the configured period.
     auto idx = assign_worker(path_id);
-    if(!stateful_workers[idx].alive) {
-        co_return kota::outcome_error(kota::ipc::Error{"Assigned stateful worker is down"});
-    }
     co_return co_await stateful_workers[idx].peer->send_request(params, opts);
 }
 
@@ -117,16 +105,9 @@ RequestResult<Params> WorkerPool::send_stateless(const Params& params,
     if(stateless_workers.empty()) {
         co_return kota::outcome_error(kota::ipc::Error{"No stateless workers available"});
     }
-    // Round-robin, skipping dead workers.
-    auto start = next_stateless;
-    for(std::size_t i = 0; i < stateless_workers.size(); ++i) {
-        auto idx = (start + i) % stateless_workers.size();
-        if(stateless_workers[idx].alive) {
-            next_stateless = (idx + 1) % stateless_workers.size();
-            co_return co_await stateless_workers[idx].peer->send_request(params, opts);
-        }
-    }
-    co_return kota::outcome_error(kota::ipc::Error{"All stateless workers are down"});
+    auto idx = next_stateless;
+    next_stateless = (next_stateless + 1) % stateless_workers.size();
+    co_return co_await stateless_workers[idx].peer->send_request(params, opts);
 }
 
 template <typename Params>
@@ -134,8 +115,6 @@ void WorkerPool::notify_stateful(std::uint32_t path_id, const Params& params) {
     auto it = owner.find(path_id);
     if(it == owner.end())
         return;
-    if(!stateful_workers[it->second].alive)
-        return;
     stateful_workers[it->second].peer->send_notification(params);
 }
 

tests/conftest.py

@@ -10,14 +10,6 @@ import pytest
 from tests.integration.utils.client import CliceClient
 
 
-@pytest.hookimpl(tryfirst=True, hookwrapper=True)
-def pytest_runtest_makereport(item, call):
-    """Store test outcome so fixtures can detect failures."""
-    outcome = yield
-    rep = outcome.get_result()
-    setattr(item, f"rep_{rep.when}", rep)
-
-
 def pytest_addoption(parser: pytest.Parser) -> None:
     parser.addoption(
         "--executable",
@@ -83,8 +75,7 @@ def workspace(request: pytest.FixtureRequest, test_data_dir: Path) -> Path | Non
     """
     marker = request.node.get_closest_marker("workspace")
     if marker is None:
-        yield None
-        return
+        return None
     if not marker.args or not isinstance(marker.args[0], str):
         raise pytest.UsageError(
             "@pytest.mark.workspace requires a string argument, e.g. "
@@ -97,10 +88,7 @@ def workspace(request: pytest.FixtureRequest, test_data_dir: Path) -> Path | Non
     clice_dir = path / ".clice"
     if clice_dir.exists():
         shutil.rmtree(clice_dir)
-    yield path
-    # Post-test cleanup: remove cache generated during the test.
-    if clice_dir.exists():
-        shutil.rmtree(clice_dir)
+    return path
 
 
 @pytest.fixture
@@ -122,20 +110,12 @@ async def client(
 
     if workspace is not None:
         init_options_marker = request.node.get_closest_marker("init_options")
-        init_options = dict(init_options_marker.args[0]) if init_options_marker else {}
-        # Force cache_dir into the workspace so .clice/ cleanup prevents stale PCH.
-        project = dict(init_options.get("project", {}))
-        project.setdefault("cache_dir", str(workspace / ".clice"))
-        init_options["project"] = project
+        init_options = init_options_marker.args[0] if init_options_marker else None
         await c.initialize(workspace, initialization_options=init_options)
 
     yield c
 
-    test_failed = (
-        getattr(request.node, "rep_call", None) is not None
-        and request.node.rep_call.failed
-    )
-    await _shutdown_client(c, verbose=test_failed)
+    await _shutdown_client(c)
 
 
 def generate_cdb(workspace: Path) -> None:
@@ -168,12 +148,8 @@ async def make_client(executable: Path, workspace: Path) -> CliceClient:
     return c
 
 
-async def _shutdown_client(c: CliceClient, *, verbose: bool = False) -> None:
-    """Gracefully shut down a client, force-kill if needed.
-
-    When verbose=True (typically on test failure), dump collected log messages
-    and server stderr to help diagnose the failure.
-    """
+async def _shutdown_client(c: CliceClient) -> None:
+    """Gracefully shut down a client, force-kill if needed."""
     try:
         await asyncio.wait_for(c.shutdown_async(None), timeout=3.0)
     except Exception:
@@ -189,25 +165,15 @@ async def _shutdown_client(c: CliceClient, *, verbose: bool = False) -> None:
 
     try:
         server = getattr(c, "_server", None)
-        if server:
-            if server.returncode is not None:
-                print(f"[server] exit code: {server.returncode}", flush=True)
-            if server.stderr:
-                stderr_data = await asyncio.wait_for(server.stderr.read(), timeout=2.0)
-                if stderr_data:
-                    for line in stderr_data.decode(
-                        "utf-8", errors="replace"
-                    ).splitlines():
-                        if "[warn]" in line or "[error]" in line or "Sanitizer" in line:
-                            print(f"[server] {line}", flush=True)
+        if server and server.stderr:
+            stderr_data = await asyncio.wait_for(server.stderr.read(), timeout=2.0)
+            if stderr_data:
+                for line in stderr_data.decode("utf-8", errors="replace").splitlines():
+                    if "[warn]" in line or "[error]" in line:
+                        print(f"[server] {line}", flush=True)
     except Exception:
         pass
 
-    if verbose and c.log_messages:
-        for msg in c.log_messages:
-            level = {1: "ERROR", 2: "WARN", 3: "INFO", 4: "LOG"}.get(msg.type, "?")
-            print(f"[logMessage/{level}] {msg.message}", flush=True)
-
     try:
         c._stop_event.set()
         for task in c._async_tasks:

tests/integration/compilation/test_persistent_cache.py

@@ -16,7 +16,6 @@ from lsprotocol.types import (
 
 from tests.conftest import make_client, shutdown_client
 from tests.integration.utils import write_cdb, doc
-from tests.integration.utils.wait import MTIME_GRANULARITY, SETTLE_TIME
 from tests.integration.utils.cache import (
     list_pch_files,
     list_pcm_files,
@@ -101,7 +100,7 @@ async def test_pch_reused_on_close_reopen(client, tmp_path):
 
     # Close.
     client.text_document_did_close(DidCloseTextDocumentParams(text_document=doc(uri)))
-    await asyncio.sleep(SETTLE_TIME)
+    await asyncio.sleep(0.5)
 
     # Clear diagnostics so we can wait for fresh ones.
     client.diagnostics.pop(uri, None)
@@ -228,7 +227,7 @@ async def test_pch_rebuilt_on_header_change(client, tmp_path):
     assert len(pch_before) >= 1
 
     # Modify header — changes preamble content hash.
-    await asyncio.sleep(MTIME_GRANULARITY)
+    await asyncio.sleep(1.1)
     (tmp_path / "header.h").write_text("#pragma once\nstruct V2 { int b; };\n")
     # Also update main.cpp to use V2 so it compiles cleanly.
     (tmp_path / "main.cpp").write_text(
@@ -237,7 +236,7 @@ async def test_pch_rebuilt_on_header_change(client, tmp_path):
 
     # Close and reopen to get fresh preamble.
     client.text_document_did_close(DidCloseTextDocumentParams(text_document=doc(uri)))
-    await asyncio.sleep(SETTLE_TIME)
+    await asyncio.sleep(0.5)
     client.diagnostics.pop(uri, None)
 
     uri2, _ = await client.open_and_wait(tmp_path / "main.cpp")

tests/integration/compilation/test_staleness.py

@@ -21,7 +21,7 @@ from lsprotocol.types import (
 )
 
 from tests.integration.utils import write_cdb, doc
-from tests.integration.utils.wait import MTIME_GRANULARITY, wait_for_recompile
+from tests.integration.utils.wait import wait_for_recompile
 from tests.integration.utils.assertions import assert_clean_compile, assert_has_errors
 
 
@@ -42,7 +42,7 @@ async def test_header_change_invalidates_ast(client, tmp_path):
 
     # Modify header on disk — introduce an error.
     # Ensure mtime advances past filesystem granularity (1s on some FSes).
-    await asyncio.sleep(MTIME_GRANULARITY)
+    await asyncio.sleep(1.1)
     (tmp_path / "header.h").write_text(
         "inline int value() { return }\n"
     )  # syntax error
@@ -71,7 +71,7 @@ async def test_header_change_invalidates_pch(client, tmp_path):
 
     # Modify header — rename struct field.
     # Ensure mtime advances past filesystem granularity (1s on some FSes).
-    await asyncio.sleep(MTIME_GRANULARITY)
+    await asyncio.sleep(1.1)
     (tmp_path / "header.h").write_text(
         "#pragma once\nstruct Foo { int y; };\n"  # x -> y
     )
@@ -115,22 +115,16 @@ async def test_touch_without_content_change_skips_recompile(client, tmp_path):
     assert_clean_compile(client, uri)
 
     # Touch the header — mtime changes but content stays the same.
-    await asyncio.sleep(MTIME_GRANULARITY)
+    await asyncio.sleep(1.1)
     original_content = (tmp_path / "header.h").read_text()
     (tmp_path / "header.h").write_text(original_content)
 
     # Hover triggers ensure_compiled which runs deps_changed.
     # Layer 2 hash confirms nothing actually changed → cached AST reused.
-    # The first hover may see ast_dirty=true (mtime changed, hash check in progress),
-    # so retry to let the hash check complete.
-    hover = None
-    for _ in range(3):
-        hover = await client.text_document_hover_async(
-            HoverParams(text_document=doc(uri), position=Position(line=1, character=4))
-        )
-        if hover is not None:
-            break
-        await asyncio.sleep(SETTLE_TIME)
+    # Hover on "main" (line 1, col 4) which should be hoverable.
+    hover = await client.text_document_hover_async(
+        HoverParams(text_document=doc(uri), position=Position(line=1, character=4))
+    )
     assert hover is not None
 
     # No new diagnostics should appear — the file is still clean.
@@ -151,7 +145,7 @@ async def test_header_replaced_with_different_content(client, tmp_path):
     assert_clean_compile(client, uri)
 
     # Replace header — delete and recreate with a breaking change.
-    await asyncio.sleep(MTIME_GRANULARITY)
+    await asyncio.sleep(1.1)
     (tmp_path / "header.h").unlink()
     (tmp_path / "header.h").write_text("inline int renamed_value() { return 1; }\n")
 
@@ -176,7 +170,7 @@ async def test_fix_error_clears_diagnostics(client, tmp_path):
     assert_has_errors(client, uri, "Expected diagnostics from broken header")
 
     # Fix the header.
-    await asyncio.sleep(MTIME_GRANULARITY)
+    await asyncio.sleep(1.1)
     (tmp_path / "header.h").write_text("inline int value() { return 1; }\n")
 
     # Hover triggers recompilation — diagnostics should clear.
@@ -204,7 +198,7 @@ async def test_multiple_files_share_header(client, tmp_path):
     assert_clean_compile(client, uri_b)
 
     # Break the shared header.
-    await asyncio.sleep(MTIME_GRANULARITY)
+    await asyncio.sleep(1.1)
     (tmp_path / "shared.h").write_text("inline int shared() { return }\n")
 
     # Both files should get diagnostics after hover.
@@ -229,7 +223,7 @@ async def test_transitive_header_change(client, tmp_path):
     assert_clean_compile(client, uri)
 
     # Modify the transitive dep (base.h).
-    await asyncio.sleep(MTIME_GRANULARITY)
+    await asyncio.sleep(1.1)
     (tmp_path / "base.h").write_text("inline int base() { return }\n")  # broken
 
     await wait_for_recompile(client, uri)
@@ -316,7 +310,7 @@ async def test_didclose_then_reopen(client, tmp_path):
     client.text_document_did_close(DidCloseTextDocumentParams(text_document=doc(uri)))
 
     # Modify on disk while closed.
-    await asyncio.sleep(MTIME_GRANULARITY)
+    await asyncio.sleep(1.1)
     (tmp_path / "main.cpp").write_text("int main() { return }\n")  # broken
 
     # Reopen — should compile the new (broken) content from disk.
@@ -327,7 +321,7 @@ async def test_didclose_then_reopen(client, tmp_path):
 
 
 async def test_didclose_clears_hover(client, tmp_path):
-    """After didClose, hover on the closed file should return an error."""
+    """After didClose, hover on the closed file should return None."""
     (tmp_path / "main.cpp").write_text("int main() { return 0; }\n")
     write_cdb(tmp_path, ["main.cpp"])
     await client.initialize(tmp_path)
@@ -336,10 +330,10 @@ async def test_didclose_clears_hover(client, tmp_path):
 
     client.text_document_did_close(DidCloseTextDocumentParams(text_document=doc(uri)))
 
-    with pytest.raises(Exception, match="Document not open"):
-        await client.text_document_hover_async(
-            HoverParams(text_document=doc(uri), position=Position(line=0, character=4))
-        )
+    hover = await client.text_document_hover_async(
+        HoverParams(text_document=doc(uri), position=Position(line=0, character=4))
+    )
+    assert hover is None, "Hover on closed file should return None"
 
 
 async def test_didsave_triggers_recompile_for_dependents(client, tmp_path):
@@ -355,7 +349,7 @@ async def test_didsave_triggers_recompile_for_dependents(client, tmp_path):
     assert_clean_compile(client, uri)
 
     # Modify header on disk and send didSave.
-    await asyncio.sleep(MTIME_GRANULARITY)
+    await asyncio.sleep(1.1)
     (tmp_path / "header.h").write_text("inline int value() { return }\n")  # broken
     client.text_document_did_save(
         DidSaveTextDocumentParams(

tests/integration/features/test_server.py

@@ -10,7 +10,6 @@ from lsprotocol.types import (
 )
 
 from tests.integration.utils import doc
-from tests.integration.utils.wait import SETTLE_TIME
 from tests.integration.utils.workspace import did_change
 
 
@@ -71,7 +70,7 @@ async def test_semantic_token_modifier_legend(client, workspace):
 @pytest.mark.workspace("hello_world")
 async def test_did_open_close_cycle(client, workspace):
     uri, _ = client.open(workspace / "main.cpp")
-    await asyncio.sleep(SETTLE_TIME)
+    await asyncio.sleep(0.5)
     client.close(uri)
 
 
@@ -84,8 +83,8 @@ async def test_shutdown_exit(client, workspace):
 async def test_feature_requests_after_close(client, workspace):
     uri, _ = client.open(workspace / "main.cpp")
     client.close(uri)
-    with pytest.raises(Exception, match="Document not open"):
-        await client.hover_at(uri, 0, 0)
+    result = await client.hover_at(uri, 0, 0)
+    assert result is None
 
 
 @pytest.mark.workspace("hello_world")
@@ -95,7 +94,7 @@ async def test_incremental_change(client, workspace):
         content += f"\n// change {i}"
         did_change(client, uri, i + 1, content)
         await asyncio.sleep(0.05)
-    await asyncio.sleep(SETTLE_TIME * 2)
+    await asyncio.sleep(1)
     client.close(uri)
 
 
@@ -192,23 +191,23 @@ async def test_rapid_changes_stress(client, workspace):
     for i in range(20):
         content += f"\n// stress change {i}\n"
         did_change(client, uri, i + 1, content)
-    await asyncio.sleep(SETTLE_TIME * 2)
+    await asyncio.sleep(2)
     client.close(uri)
 
 
 @pytest.mark.workspace("hello_world")
 async def test_save_notification(client, workspace):
     uri, _ = client.open(workspace / "main.cpp")
-    await asyncio.sleep(SETTLE_TIME)
+    await asyncio.sleep(0.5)
     client.text_document_did_save(DidSaveTextDocumentParams(text_document=doc(uri)))
-    await asyncio.sleep(SETTLE_TIME)
+    await asyncio.sleep(0.5)
     client.close(uri)
 
 
 @pytest.mark.workspace("hello_world")
 async def test_hover_on_unknown_file(client, workspace):
-    with pytest.raises(Exception, match="Document not open"):
-        await client.hover_at("file:///nonexistent/fake.cpp", 0, 0)
+    result = await client.hover_at("file:///nonexistent/fake.cpp", 0, 0)
+    assert result is None
 
 
 @pytest.mark.workspace("hello_world")

tests/integration/lifecycle/test_file_operation.py

@@ -13,14 +13,13 @@ from lsprotocol.types import (
 )
 
 from tests.integration.utils import doc
-from tests.integration.utils.wait import IDLE_TIMEOUT
 from tests.integration.utils.workspace import did_change
 
 
 @pytest.mark.workspace("hello_world")
 async def test_did_open(client, workspace):
     client.open(workspace / "main.cpp")
-    await asyncio.sleep(IDLE_TIMEOUT)
+    await asyncio.sleep(5)
 
 
 @pytest.mark.workspace("hello_world")
@@ -30,13 +29,13 @@ async def test_did_change(client, workspace):
         content += "\n"
         await asyncio.sleep(0.2)
         did_change(client, uri, i + 1, content)
-    await asyncio.sleep(IDLE_TIMEOUT)
+    await asyncio.sleep(5)
 
 
 @pytest.mark.workspace("clang_tidy")
 async def test_clang_tidy(client, workspace):
     client.open(workspace / "main.cpp")
-    await asyncio.sleep(IDLE_TIMEOUT)
+    await asyncio.sleep(5)
 
 
 @pytest.mark.workspace("hello_world")
@@ -57,7 +56,7 @@ async def test_hover_save_close(client, workspace):
         )
     )
     client.text_document_did_close(DidCloseTextDocumentParams(text_document=doc(uri)))
-    with pytest.raises(Exception, match="Document not open"):
-        await client.text_document_hover_async(
-            HoverParams(text_document=doc(uri), position=Position(line=0, character=0))
-        )
+    closed_hover = await client.text_document_hover_async(
+        HoverParams(text_document=doc(uri), position=Position(line=0, character=0))
+    )
+    assert closed_hover is None

tests/integration/modules/test_modules.py

@@ -14,7 +14,6 @@ from lsprotocol.types import (
 )
 
 from tests.integration.utils.assertions import assert_clean_compile, assert_has_errors
-from tests.integration.utils.wait import IDLE_TIMEOUT
 
 
 @pytest.mark.workspace("modules/single_module_no_deps")
@@ -268,7 +267,7 @@ async def test_circular_module_dependency(client, workspace):
     the server remains responsive by opening a non-cyclic file afterwards.
     """
     client.open(workspace / "cycle_a.cppm")
-    await asyncio.sleep(IDLE_TIMEOUT)
+    await asyncio.sleep(5.0)
 
     uri_ok, _ = await client.open_and_wait(workspace / "ok.cppm")
     diags = client.diagnostics.get(uri_ok, [])

tests/integration/stress/test_rapid_edit.py

@@ -10,7 +10,6 @@ from lsprotocol.types import (
 )
 
 from tests.integration.utils import doc
-from tests.integration.utils.wait import SETTLE_TIME
 from tests.integration.utils.workspace import did_change
 
 
@@ -54,7 +53,7 @@ async def test_rapid_edits_with_hover(client, workspace):
         await asyncio.sleep(0.02)  # ~20ms between edits
 
     # Wait a moment for in-flight requests to settle.
-    await asyncio.sleep(SETTLE_TIME * 2)
+    await asyncio.sleep(1.0)
 
     # Final hover must succeed and return correct result.
     final_hover = await asyncio.wait_for(

tests/integration/utils/assertions.py

@@ -1,6 +1,6 @@
-"""Diagnostic and log message assertion helpers for integration tests."""
+"""Diagnostic assertion helpers for integration tests."""
 
-from lsprotocol.types import Diagnostic, DiagnosticSeverity, MessageType
+from lsprotocol.types import Diagnostic, DiagnosticSeverity
 
 
 def get_errors(diagnostics: list[Diagnostic]) -> list[Diagnostic]:
@@ -48,23 +48,3 @@ def assert_clean_compile(client, uri: str) -> None:
     """Assert the file compiled without any diagnostics at all."""
     diags = client.diagnostics.get(uri, [])
     assert len(diags) == 0, f"Expected clean compile, got: {diags}"
-
-
-def has_log_message(
-    client, substring: str, *, severity: MessageType | None = None
-) -> bool:
-    """Check if any log message contains the given substring."""
-    for msg in client.log_messages:
-        if severity is not None and msg.type != severity:
-            continue
-        if substring in msg.message:
-            return True
-    return False
-
-
-def assert_no_log_errors(client) -> None:
-    """Assert that no error-level log messages were received."""
-    errors = [m for m in client.log_messages if m.type == MessageType.Error]
-    assert len(errors) == 0, (
-        f"Expected no log errors, got: {[e.message for e in errors]}"
-    )

tests/integration/utils/client.py

@@ -7,7 +7,6 @@ from urllib.parse import unquote
 from lsprotocol.types import (
     PROGRESS,
     TEXT_DOCUMENT_PUBLISH_DIAGNOSTICS,
-    WINDOW_LOG_MESSAGE,
     WINDOW_WORK_DONE_PROGRESS_CREATE,
     ClientCapabilities,
     CodeActionContext,
@@ -25,7 +24,6 @@ from lsprotocol.types import (
     InitializeParams,
     InitializeResult,
     InitializedParams,
-    LogMessageParams,
     Position,
     ProgressParams,
     PublishDiagnosticsParams,
@@ -50,7 +48,6 @@ class CliceClient(BaseLanguageClient):
         super().__init__("clice-test-client", "0.1.0")
         self.diagnostics: dict[str, list[Diagnostic]] = {}
         self.diagnostics_events: dict[str, asyncio.Event] = {}
-        self.log_messages: list[LogMessageParams] = []
         self.progress_tokens: list[str] = []
         self.progress_events: list[dict] = []
         self.init_result: InitializeResult | None = None
@@ -67,10 +64,6 @@ class CliceClient(BaseLanguageClient):
                 if key in self.diagnostics_events:
                     self.diagnostics_events[key].set()
 
-        @self.feature(WINDOW_LOG_MESSAGE)
-        def on_log_message(params: LogMessageParams) -> None:
-            self.log_messages.append(params)
-
         @self.feature(WINDOW_WORK_DONE_PROGRESS_CREATE)
         def on_create_progress(params: WorkDoneProgressCreateParams) -> None:
             token = str(params.token) if isinstance(params.token, int) else params.token

tests/integration/utils/wait.py

@@ -9,11 +9,6 @@ from lsprotocol.types import (
     WorkspaceSymbolParams,
 )
 
-# Standard timing constants — use these instead of hardcoded sleep values.
-MTIME_GRANULARITY = 1.1  # Filesystem mtime precision (1s on many FSes, +0.1 margin)
-SETTLE_TIME = 0.5  # Time for server to stabilize after an operation
-IDLE_TIMEOUT = 5.0  # Time to wait for server idle in lifecycle tests
-
 
 async def wait_for_recompile(client, uri: str, *, timeout: float = 60.0) -> None:
     """Trigger recompilation via hover and wait for fresh diagnostics.

tests/replay.py

@@ -13,9 +13,6 @@ import re
 import signal
 import sys
 import time
-
-# Force line-buffered stdout so CI sees output immediately.
-sys.stdout.reconfigure(line_buffering=True)
 from pathlib import Path
 from urllib.parse import quote, unquote
 
@@ -112,9 +109,7 @@ async def write_lsp_message(writer: asyncio.StreamWriter, payload: str):
     await writer.drain()
 
 
-async def replay_one(
-    trace_path: Path, clice_bin: Path, timeout: int, wall_timeout: int = 300
-) -> bool | None:
+async def replay_one(trace_path: Path, clice_bin: Path, timeout: int) -> bool | None:
     """Replay a single trace. Returns True=PASS, False=FAIL, None=SKIP."""
     records = load_trace(trace_path)
     if not records:
@@ -184,21 +179,8 @@ async def replay_one(
     last_method = None
     sent_count = 0
 
-    wall_deadline = wall_start + wall_timeout
-
-    def remaining_wall():
-        return max(0, wall_deadline - time.monotonic())
-
     try:
         for i, rec in enumerate(records):
-            if remaining_wall() <= 0:
-                elapsed = time.monotonic() - wall_start
-                print(
-                    f"  result: TIMEOUT (wall-clock {wall_timeout}s exceeded, {elapsed:.1f}s)"
-                )
-                success = False
-                break
-
             if i > 0:
                 delay = rec["ts"] - records[i - 1]["ts"]
                 if delay > 0:
@@ -214,7 +196,7 @@ async def replay_one(
                 try:
                     await asyncio.wait_for(
                         asyncio.gather(*pending.values(), return_exceptions=True),
-                        timeout=min(timeout, remaining_wall()),
+                        timeout=timeout,
                     )
                 except asyncio.TimeoutError:
                     elapsed = time.monotonic() - wall_start
@@ -228,19 +210,7 @@ async def replay_one(
             if msg_id is not None and method is not None:
                 pending[msg_id] = asyncio.get_event_loop().create_future()
 
-            try:
-                await asyncio.wait_for(
-                    write_lsp_message(proc.stdin, rec["msg"]),
-                    timeout=min(30, remaining_wall()),
-                )
-            except asyncio.TimeoutError:
-                elapsed = time.monotonic() - wall_start
-                print(
-                    f"  result: HANG (write blocked at {last_method},"
-                    f" sent={sent_count}/{len(records)}, {elapsed:.1f}s)"
-                )
-                success = False
-                break
+            await write_lsp_message(proc.stdin, rec["msg"])
             sent_count = i + 1
 
     except (ConnectionError, BrokenPipeError):
@@ -261,7 +231,7 @@ async def replay_one(
         try:
             await asyncio.wait_for(
                 asyncio.gather(*pending.values(), return_exceptions=True),
-                timeout=min(timeout, remaining_wall()),
+                timeout=timeout,
             )
         except asyncio.TimeoutError:
             elapsed = time.monotonic() - wall_start
@@ -324,7 +294,7 @@ async def async_main(args):
             print(f"SKIP: {trace} (not found)")
             skipped += 1
             continue
-        result = await replay_one(trace, args.clice, args.timeout, args.wall_timeout)
+        result = await replay_one(trace, args.clice, args.timeout)
         if result is None:
             skipped += 1
         elif result:
@@ -347,16 +317,7 @@ def main():
     p.add_argument("traces", nargs="+", type=Path, help="JSONL trace files")
     p.add_argument("--clice", required=True, type=Path, help="Path to clice binary")
     p.add_argument(
-        "--timeout",
-        type=int,
-        default=120,
-        help="Per-request timeout in seconds (default: 120)",
-    )
-    p.add_argument(
-        "--wall-timeout",
-        type=int,
-        default=300,
-        help="Max wall-clock time per trace in seconds (default: 300)",
+        "--timeout", type=int, default=120, help="Timeout in seconds (default: 120)"
     )
     args = p.parse_args()
     sys.exit(asyncio.run(async_main(args)))

tests/unit/feature/document_link_tests.cpp

@@ -21,6 +21,11 @@ void run(llvm::StringRef source, llvm::StringRef standard = "-std=c++17") {
     links = feature::document_links(*unit, feature::PositionEncoding::UTF8);
 }
 
+auto to_local_range(const protocol::Range& range) -> LocalSourceRange {
+    feature::PositionMapper converter(unit->interested_content(), feature::PositionEncoding::UTF8);
+    return LocalSourceRange(*converter.to_offset(range.start), *converter.to_offset(range.end));
+}
+
 void EXPECT_LINK(std::size_t index, llvm::StringRef name, llvm::StringRef path) {
     auto& link = links[index];
     auto expected = range(name, "main.cpp");

tests/unit/feature/folding_range_tests.cpp

@@ -37,10 +37,19 @@ void run(llvm::StringRef code) {
 }
 
 auto to_local_range(const protocol::FoldingRange& range) -> LocalSourceRange {
-    return Tester::to_local_range(protocol::Range{
-        .start = {.line = range.start_line, .character = range.start_character.value_or(0)},
-        .end = {.line = range.end_line,   .character = range.end_character.value_or(0)  },
-    });
+    feature::PositionMapper converter(unit->interested_content(), feature::PositionEncoding::UTF8);
+
+    auto start = protocol::Position{
+        .line = range.start_line,
+        .character = range.start_character.value_or(0),
+    };
+
+    auto end = protocol::Position{
+        .line = range.end_line,
+        .character = range.end_character.value_or(0),
+    };
+
+    return LocalSourceRange(*converter.to_offset(start), *converter.to_offset(end));
 }
 
 void EXPECT_FOLDING(std::uint32_t index,

tests/unit/server/config_tests.cpp

@@ -6,7 +6,7 @@
 #include "support/filesystem.h"
 
 #include "kota/codec/json/json.h"
-#include "kota/codec/toml/toml.h"
+#include "kota/codec/toml.h"
 
 namespace clice::testing {
 
@@ -148,7 +148,7 @@ TEST_CASE(ApplyDefaults) {
     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_GE(config.project.stateless_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());

tests/unit/server/stateful_worker_tests.cpp

@@ -5,7 +5,7 @@
 #include "server/protocol.h"
 #include "server/worker_test_helpers.h"
 
-#include "kota/codec/json/json.h"
+#include "kota/codec/raw_value.h"
 
 namespace clice::testing {
 

tests/unit/server/stateless_worker_tests.cpp

@@ -6,6 +6,7 @@
 #include "server/worker_test_helpers.h"
 
 #include "kota/codec/bincode/bincode.h"
+#include "kota/codec/raw_value.h"
 
 namespace clice::testing {
 

tests/unit/test/tester.h

@@ -8,7 +8,6 @@
 #include "test/test.h"
 #include "command/command.h"
 #include "compile/compilation.h"
-#include "feature/feature.h"
 #include "support/logging.h"
 
 namespace clice::testing {
@@ -83,12 +82,6 @@ struct Tester {
 
     LocalSourceRange range(llvm::StringRef name = "", llvm::StringRef file = "");
 
-    LocalSourceRange to_local_range(const kota::ipc::protocol::Range& range) {
-        feature::PositionMapper converter(unit->interested_content(),
-                                          feature::PositionEncoding::UTF8);
-        return LocalSourceRange(*converter.to_offset(range.start), *converter.to_offset(range.end));
-    }
-
     void clear();
 };