clangd Non-Self-Contained Header Hook

Make non-self-contained C/C++ headers parse cleanly under clangd in VS Code.

When a header relies on transitive includes from its TU's preamble (std::string_view without #include <string_view>, forward-decls without the full type, macros set upstream of #include "foo.h", etc.), clangd parsed alone produces a cascade of false-positive errors, broken hover, broken go-to-def, and so on. This extension hooks the clangd language client to observe outgoing didOpen notifications, builds a TU→header include graph, synthesizes a fake preamble from a recently-seen includer, prepends it to the buffer text sent to clangd, and bidirectionally remaps line/column positions across ~30 LSP request/response methods so the unmodified header is what you see. Diagnostics whose ranges fall inside the synthesized preamble are dropped; edits that target the preamble are filtered out before they hit the buffer.

The synthesized preamble is wrapped in #if __INCLUDE_LEVEL__ == 0 ... #endif, so it's only active when clangd parses the header as the translation root — when the same header is later #include'd through some other file's chain the body is skipped, no redefinition cascades.

This is a port of clangd-preamble.nvim.

Requirements

• VS Code 1.75+
• The official clangd extension (declared as an extension dependency).

Install

Download the latest vscode-clangd-preamble.vsix from the Releases page and run:

code --install-extension vscode-clangd-preamble.vsix

The extension activates automatically when a C, C++, CUDA, or Objective-C/C++ file is opened. It piggybacks on the running clangd language client — no configuration required for the common case.

Commands

All commands live under the clangd category in the command palette.

Settings

Status bar

When the active editor is a header with an injected preamble, the status bar shows Preamble: <TU>.cpp with a tooltip listing the includer TU, preamble line count, direct/indirect flag, and dropped-diagnostic count. Clicking it runs Refresh Current Header. While a header is waiting for an includer TU or for the background graph lookup/PCH readiness, a highlighted status item shows Preamble: pending instead. The editor stays usable and the unmodified header is sent to clangd during this interval, so diagnostics can be temporarily inaccurate. Self-contained headers leave the pending state once the background check completes, and the status item stays hidden.

How it works

1. Include graph. Outgoing didOpen for .cpp/.cc/.cxx/.c/.C/.mm files is intercepted; the file's #include directives are parsed into a TU↔header graph indexed by basename.
2. Non-blocking open. A header's original didOpen is forwarded immediately. Includer discovery uses asynchronous filesystem operations and cooperative event-loop yields, so a large graph/path search does not block the VS Code extension host, SCM views, or diff editors. Once resolved, the extension replays didOpen with the synthetic preamble.
3. Includer pick. The graph is queried in the background for the TU with the shortest prefix-before-this-header (tie-break: most recent observation) by default. clangd-preamble.defaultSelector can instead make the default follow the most recently observed includer TU. Per-header selector choices override this setting. Companion-TU fallback (Foo.cpp next to Foo.h) covers the header-opened-alone case. If no direct includer is known, the graph lazily walks observed TU include chains up to clangd-preamble.indirectIncludeDepth and can build a preamble from the includes before the chain that reaches the target header. Direct includers always win, so indirect chains are not searched while a direct TU candidate exists.
4. Self-contained skip. Headers with 3 or more own #include directives are likely self-contained and skipped automatically — the preamble can only introduce conflicts in that case. Manual commands (Refresh Current Header, Enable for Current File) override. If such a skipped header later publishes clangd diagnostics, it is treated as non-self-contained and replayed through the normal includer search.
5. Cycle filter. Each prefix entry is checked (1 level deep) against the target header's basename — entries that transitively re-include the target are dropped to prevent redefinition cascades.
6. Dedup. Prefix entries that appear in the header's own #include set are dropped, and within-prefix duplicates are collapsed — bugprone-duplicate-include doesn't fire.
7. Synthesis. The remaining entries are wrapped in #if __INCLUDE_LEVEL__ == 0 ... // __NSC_PREAMBLE_END__ ... #endif and prepended to the header's didOpen.text.
8. Position remap. ~30 LSP methods (hover, definition, references, completion, semantic-tokens full+range+delta, inlay hints, formatting, prepare-rename / rename, code-action with context.diagnostics back-shift, document-symbol, folding-range, code-lens, selection-range, linked-editing- range, call-hierarchy, type-hierarchy, …) shift positions and ranges in both directions so the user sees user-space coordinates.
9. Diagnostic suppression. The handleDiagnostics middleware drops entries whose range is fully in the preamble, clips entries straddling the boundary, and shifts surviving entries to user-space. Suppressed entries are kept for Dump Suppressed Preamble Diagnostics.
10. Pending-header replay. If a header is opened before any matching TU has been observed, the original didOpen is stashed; when a later TU's didOpen populates the graph with a basename match, the stored open is replayed through the wrapped notify so the preamble injection runs against the latest live buffer text, including edits made while resolution was pending.
11. Pre-wrap catch-up. vscode-languageclient may have already sent didOpen for documents that were open at activation, before our sendNotification wrapper went in. At install we observe open TU buffers into the graph and replay open headers without state.
12. Source-after-header refresh. When a TU's didOpen arrives via the editor for the first time, active header state whose includer pick now resolves to that TU is replayed — so a header parsed against a disk-read companion gets re-evaluated when the user finally opens the source.
13. Graph cache. Observed and project-scanned TU include entries are stored in VS Code workspace storage. On activation the cache is restored only for files whose size and mtime still match; file change/delete/rename events invalidate the affected TU/header entries. Cache validation and saves also use the asynchronous graph path.
14. Compile-flags refresh. workspace/didChangeConfiguration carries clangd's compilationDatabaseChanges extension (used by vscode-clangd-cmake to deliver per-file flags). clangd updates its in-memory CDB on receipt but does not reparse already-open files — so we replay didOpen for any active header whose includer TU is in the change set.

Caveats

• Header opened alone with no companion .cpp and no observed TU yields a pass-through (no preamble) until either an includer TU's didOpen is observed or Scan Project for Includer TUs is run.
• Pull-diagnostics (textDocument/diagnostic) is not yet handled; rely on push (publishDiagnostics) for now.
• The same header reached through two distinct buffers via different paths is treated as two separate buffers (each gets its own state).

Build from source

npm install
npm run build              # esbuild bundle to out/extension.js
npm run typecheck          # tsc --noEmit
npx @vscode/vsce package   # produces vscode-clangd-preamble.vsix

License

MIT — see LICENSE.