Upstream defects register (clangd, mcpp)

[Sunrisepeak]

Register of upstream defects mcppls depends on. This body is the index; each comment below is one problem.

Bundled: clangd 23.1.0 (clangd/clangd release). Code workarounds: src/engine/clangd/workarounds.cpp (WA-CLANGD-<n>, listed by mcppls report); deliberate limits: .agents/docs/design.md §7.

Rules: a new problem gets a comment and a row here; adding or removing a workaround updates its comment; link upstream issues/fixes when they exist; walk this list before bumping the bundled clangd.

clangd / LLVM

ID	Problem	Upstream	mcppls
UP-01	Module name ending in . hangs the preprocessor (crashes on Windows)	unfiled; fixed on main? (deferred)	WA-CLANGD-001; disk check (0.0.5)
UP-02	Unresolved import can deadlock the unit's build	unfiled	WA-CLANGD-002; disk check (0.0.5)
UP-03	Modules a file needs are built one at a time	unfiled (perf)	WA-CLANGD-003
UP-04	Finding a module's unit scans the whole database	unfiled (perf)	WA-CLANGD-004
UP-05	MSVC STL aligned allocation rejected (align_val_t ambiguous)	fixed in 23.1.1 (llvm-project#218152)	WA-CLANGD-005
UP-06	Stops answering one file while answering others	unfiled	quarantine
UP-07	Stuck with no CPU after rapid module edits	unfiled	StuckWatch restart
UP-08	Background index does not build module imports (definitions indexed apart from their declarations)	unfiled (gap); cf. clangd/clangd#2569	WA-CLANGD-008: implementation units built in the foreground; search by name (0.0.6)
UP-09	No textDocument/semanticTokens/range	unfiled (gap)	capability gated
UP-10	import std; then an unprovided export import never finishes	unfiled	known limit
UP-11	Module scanning fails on link-phase driver errors	unfiled	fixed in mcppls 0.0.5 (-c)
UP-12	Windows: Build AST crash on a module unit with unresolved imports	unfiled; needs stack	avoided by -c; crash file set aside (0.0.5)
UP-13	Windows: Build AST crash on some units even with correct commands	unfiled; needs stack	contained (0.0.5)
UP-14	Imports added in an unsaved buffer are not built until save	unfiled	WA-CLANGD-007; disk check (0.0.5)
UP-15	Missing ; after import is reported on the next line	unfiled	WA-CLANGD-006 (0.0.5)
UP-16	C++26 contracts and reflection are not implemented	gap (upstream work in progress)	documented; VS Code colors contract keywords
UP-17	A function defined in an open unit is missing from the index (prepare_build)	unfiled; not reduced yet	definition found by name (0.0.6)

mcpp

ID	Problem	Upstream	mcppls
UP-M1	mcpp: macOS deployment target ignored when cross-compiling	fixed (mcpp#685, 2026.9.24.1)	done in 0.0.5
UP-M2	mcpp: emit build-database fails whole on one member's failure	fixed (mcpp#699, 2026.9.26.2)	partial answer used; download offer for a missing member (0.0.6)
UP-M3	mcpp: build programs cannot tell a plan/emit pass	filed: mcpp#699	none
UP-M4	mcpp: a rule's inputs are translation units; generated output points at an empty directory	filed: mcpp#724	inputs left out; project's target/ read; missing reported (0.0.6)
UP-M5	mcpp 2026.9.27.1: workspace = true in a path-dependency member fails	filed: mcpp#725	CI pins 2026.9.26.1

[Sunrisepeak]

UP-01 · Module name ending in . hangs the preprocessor (crashes on Windows)

• Symptom: in an import/module directive, a name ending in . with nothing but whitespace or a comment after it on that line (every import a.b passes through import a.) sends the preprocessor into a loop (P1857 directive lexing). Linux/macOS: never finishes. Windows: exits 0x80000003. Also without --experimental-modules-support.
• Affected: clangd 23.1.0. 22.1.8 and main 510126255 are fine.
• Upstream: unfiled. Likely fixed on main by 6dcfc17b1b (#187846), not in 23.1.2; not bisected.
• mcppls: WA-CLANGD-001 — the text sent to clangd gets a ; after the dot on the same line (positions unchanged).
• Remove when: the bundled and the oldest supported clangd finish import a. at once (canary: conformance/fixtures/workaround-canaries).
• Evidence: .agents/docs/2026-09-25-import-hang-status-highlight.md §1; fixtures typing-import, typing-import-spin.
• Hole (2026-09-26, measured): WA-CLANGD-001 rewrites only the text sent over LSP. With files.autoSave, the file on disk holds import hello.; clangd resolves prerequisite modules from the file on disk (UP-14), and the file's Worker:<file> thread then spins at 100 % CPU (buffer only: 2 ticks / 20 s; on disk: ~2000). Fixing the buffer does not stop it; only a clangd restart does. Every request for that file waits behind it, so clangd-backed completion (keywords) and hover disappear, and repeated autosaves drive restarts into the cap. Fix plan F16.
• Decision (2026-09-26): mcppls first ships the disk-side mitigation (fix plan F16: isolate the file before clangd reads the half-typed name; restart only as a fallback). Upstream work is deferred — handled later; bundling a self-built 23.1.x with the fix cherry-picked is the fallback if no backport comes.
• Shipped (mcppls 0.0.5): the disk side is covered: a file whose text on disk has such a name is set aside before clangd builds it, a build begun on it just before is let finish for 1.5 s or clangd is restarted without it, and the file goes back once the disk is fixed (fixture typing-autosave; hello project: 0 CPU for every clangd thread over 20 s with import hello. on disk).
• TODO (deferred): bisect (6dcfc17b1b?), file, ask for a 23.1.x backport.

[Sunrisepeak]

UP-02 · Unresolved import can deadlock the unit's build

• Symptom: building a module unit whose import resolves to nothing can deadlock clangd.
• Affected: clangd 23.1.
• Upstream: unfiled.
• mcppls: WA-CLANGD-002 — such imports get an empty stand-in unit.
• Remove when: clangd reports a diagnostic for such a unit instead of stalling.
• Evidence: robustness design C2, experiments S12/S17; fixture module-faults.
• Through the disk (2026-09-26): clangd reads a file's imports from disk (UP-14), so an autosave of import hello.e (a module that does not exist yet), below a working import, stalls every request for the file — the stand-in the plan withheld while the name was typed never came. mcppls 0.0.5: the plan gives a file being edited a stand-in for every module its text on disk imports, the scanner counts an import whose ; is not typed yet (as clang does), and a file whose disk imports the database clangd has read cannot resolve yet is set aside until it can (fixture typing-autosave).

[Sunrisepeak]

UP-03 · Modules a file needs are built one at a time

• Symptom: clangd builds the modules a file needs serially; cold start is slow.
• Affected: clangd 23.1.
• Upstream: unfiled (performance).
• mcppls: WA-CLANGD-003 — mcppls prepares the modules in parallel first (prime units).
• Remove when: clangd builds independent modules concurrently.
• Evidence: cold-start plan 4.4; fixture timing.

[Sunrisepeak]

UP-04 · Finding a module's unit scans the whole database

• Symptom: to find the unit providing a module, clangd scans every file in the database, in every worker (ProjectModules.cpp, CompileCommandsProjectModules).
• Affected: clangd 23.1.
• Upstream: unfiled (performance).
• mcppls: WA-CLANGD-004 — the database names each unit (-fmodule-file=<name>=<path>, -fmodule-output=); clangd scans only that file to confirm.
• Remove when: clangd looks a module's unit up without a whole-database scan.
• Evidence: usable plan W7; fixture timing.

[Sunrisepeak]

UP-05 · MSVC STL aligned allocation rejected (align_val_t ambiguous)

• Symptom: clangd rejects MSVC STL's aligned allocation; align_val_t is ambiguous inside its std module.
• Affected: clangd 23.1.0.
• Upstream: fixed — llvm-project#218152, in 23.1.1. clangd/clangd has published no release after 23.1.0.
• mcppls: WA-CLANGD-005 — units using MSVC STL get -fno-aligned-allocation.
• Remove when: the bundled clangd is 23.1.1 or later.
• Evidence: .agents/docs/design.md §7; fixtures cmake-msvc-std, mcpp-msvc.
• TODO: bump the bundled clangd once clangd/clangd releases ≥ 23.1.1.

[Sunrisepeak]

UP-06 · Stops answering one file while answering others

• Symptom: requests for one file go unanswered while others are answered.
• Affected: clangd 23.1 (experiments S2, S12).
• Upstream: unfiled.
• mcppls: Quarantine (src/engine/clangd/guard.cppm) — the file is set aside and answered by mcppls's own engine, handed back when it changes or its term ends.

[Sunrisepeak]

UP-07 · Stuck with no CPU after rapid module edits

• Symptom: after a module's source changes twice within a second, clangd leaves a request unanswered, answers nothing else and uses no CPU.
• Affected: clangd 23.1.
• Upstream: unfiled.
• mcppls: StuckWatch restarts it (docs/50-troubleshooting.md). Not detected on Windows, where clangd's CPU time is unreadable; files are set aside one by one instead.

[Sunrisepeak]

UP-08 · Background index does not build module imports

• Symptom: a function defined in an implementation unit nobody opened resolves to its declaration only. Measured 2026-09-27: every module unit's background indexing logs Failed to compile …, index may be incomplete (16 of 16 units of a small partitioned module; math.cpp indexed with 0 symbols), and a definition whose signature uses a type from a module is indexed as a different symbol from its declaration (workspace/symbol returns both). In mcpp's own prepare module, go-to-definition on phase0_manifest_and_workspace(PrepareState&) stayed on its declaration for as long as it was measured (420 s). Opening the defining unit fixes it (the foreground builds its modules), and the symbols stay after it is closed.
• Affected: clangd 23.1.0 (BackgroundIndex::index() in clang-tools-extra/clangd/index/Background.cpp builds the compiler instance with no ModulesBuilder).
• Upstream: unfiled; the same gap is behind the symptoms of [C++20 modules] Important features still missing for the module support of clangd clangd/clangd#2569 (references and rename inside modules).
• mcppls: 0.0.5 built up to four of the module's other units, chosen by file name, and asked again. 0.0.6: WA-CLANGD-008 builds implementation units through clangd's foreground (the units of an opened file's module and its imports first, a unit changed on disk again, the rest when idle; mcppls.index.primeImplementationUnits), the search picks the units that define the name, and a definition clangd still cannot link is found by name (plan .agents/docs/2026-09-27-qt-demo-navigation-discovery-plan.md §2.3, N-7, N-8; fixture mcpp-partition-definition, which 0.0.5 fails).
• Not covered: Find References, Call Hierarchy and Rename across files that were never open.
• Remove when: clangd's background index builds the modules a unit imports before indexing it.

[Sunrisepeak]

UP-09 · No textDocument/semanticTokens/range

• Symptom: clangd has no range request for semantic tokens; advertising it made clients get "method not found".
• Affected: clangd 23.1.
• Upstream: unfiled (feature gap).
• mcppls: advertises range only when every engine can answer it (src/orchestrator/tokens.cppm).

[Sunrisepeak]

UP-10 · import std; then an unprovided export import never finishes

• Symptom: a file where import std; precedes an export import of something nothing provides never finishes, when the command names std's unit (-fmodule-file=std=…). Minimal: export module m; import std; export import :p;.
• Affected: clangd 23.1 and main 510126255.
• Upstream: unfiled; to be filed with UP-01.
• mcppls: known limit, no workaround (.agents/docs/design.md §7): only stray files outside the database get such a command; the first-diagnostics guard sets them aside after 120 s.
• Evidence: import-hang plan §13 item 4.

[Sunrisepeak]

UP-11 · Module scanning fails on link-phase driver errors

• Symptom: the P1689 scan (ModuleDependencyScanner::scan → getP1689ModuleDependencyFile) runs the command as written and fails on Compilation->containsError(), while AST building (createInvocation) inserts -fsyntax-only. A driver error that only exists for a link (e.g. LTO requires -fuse-ld=lld for windows-msvc with -flto and no -c) fails every scan: no BMI is built, yet ASTs look fine.
• Affected: clangd 23.1.0, any host (the check is per target).
• Upstream: unfiled — suggest scanning only up to the compile phase, as the AST path does.
• mcppls: the trigger was mcppls's own bug (Windows/MSVC: generated clangd compile commands with -flto but no -c break module scanning #23: engine commands lacked -c). Fixed in 0.0.5: every engine command carries -c (fixture compdb-lto-msvc); a scan that still fails on a command is told as an environment issue with the driver's words (fixture compdb-rejected-command).
• Evidence: Windows/MSVC: generated clangd compile commands with -flto but no -c break module scanning #23; clang/lib/Driver/Driver.cpp (err_drv_lto_without_lld), clang/lib/Tooling/DependencyScanningTool.cpp:121; reproduced locally and in GalTranslPP CI (run 36178100611).

[Sunrisepeak]

UP-12 · Windows: Build AST crash on a module unit with unresolved imports

• Symptom: on Windows, Build AST of a module unit whose imports cannot resolve (no BMIs) crashes, 0x80000003. Example: GalTranslPP GPPDefines.ixx (only export imports and declarations).
• Affected: clangd 23.1.0 (clangd/clangd Windows release). Same input does not crash on Linux.
• Upstream: unfiled — needs a stack and a minimal repro.
• mcppls: triggered by UP-11; with -c the BMIs build and the crash is gone (--check: crash as written, exit 0 with -c). Fix plan F1, plus precise quarantine from clangd's crash context (F3).
• Evidence: GalTranslPP CI run 36178100611, experiments E3a/E3b/E3c.
• Notes: clangd prints only Signalled during AST worker action: Build AST, Filename: and Exception Code: 0x80000003; no stack, no minidump, no event-log entry. Same code as UP-01 on Windows. UTF-8 BOM is not the common factor.
• TODO: stack via the SDK's cdb.exe in that CI; compare clangd 22.1.8; reduce; file.

[Sunrisepeak]

UP-13 · Windows: Build AST crash on some units even with correct commands

• Symptom: on Windows, Build AST of NormalJsonTranslator.Core.cpp (global module fragment including pybind11/toml11/proxy, then module X; and several imports) crashes, 0x80000003, even with -c, working BMIs and cross-module hover.
• Affected: clangd 23.1.0 (clangd/clangd Windows release). Not on Linux.
• Upstream: unfiled — needs a stack and a minimal repro.
• mcppls: containment only, shipped in 0.0.5: the file clangd names in its crash context is the one set aside (fixture clangd-crash-context), clangd waits for the build tool's model instead of crashing on a provisional one, and a provisional model's crashes are forgotten when it is replaced.
• Evidence: GalTranslPP CI run 36178100611, experiment E3d; run 36164741493.
• TODO: as UP-12.

[Sunrisepeak]

UP-M1 · mcpp: macOS deployment target ignored when cross-compiling

• Symptom: cross-compiling to aarch64-macos from Linux ignores macos_deployment_target (always minos 14.0); users on macOS 11–13 cannot launch the server.
• Upstream: fixed — macos_deployment_target / MACOSX_DEPLOYMENT_TARGET are ignored when cross-compiling to aarch64-macos from a non-Apple host (always minos 14.0) mcpp-community/mcpp#685, mcpp 2026.9.24.1.
• mcppls: done in 0.0.5 — built with mcpp 2026.9.26.1, macos_deployment_target = "11.0", minos 11.0 verified.