Clarify folding pipeline and options handling

.gitignore

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

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.