fix: preserve hermetic clangd configuration

Author: wellwei

CHANGELOG.md

@@ -1,5 +1,15 @@
 # 更新日志
 
+## 0.2.4
+
+- 修复 hermetic mcpp 编译数据库被插件追加 `--query-driver` 后导致的 clangd 标准库和
+  模块误诊断；仅在编译命令未自带完整 sysroot、标准库和 no-default-config 配置时补充
+  query driver。
+- 模块检查优先选择项目源码，避免误选 `.mcpp` 依赖缓存或 `target` 生成源码，改善补全、
+  跳转和诊断稳定性。
+- 将 `build.mcpp` 作为独立的语法高亮语言处理，不再让 clangd 把 mcpp 构建脚本当作普通
+  C++ 翻译单元。
+
 ## 0.2.3
 
 - 为精确文件名 `build.mcpp` 增加 C++ 语言关联，复用 VS Code 内置 C++ 高亮和现有模块

README.md

@@ -6,7 +6,7 @@
 
 把 mcpp 工程、C++ 模块语法和官方 clangd 扩展接入 VS Code。
 
-当前版本为 `0.2.3`。扩展负责工程发现、clangd 配置、模块状态检查以及常用
+当前版本为 `0.2.4`。扩展负责工程发现、clangd 配置、模块状态检查以及常用
 mcpp CLI 操作；它不实现新的 C++ 语言服务器，也不替代 mcpp 的构建逻辑。
 
 > 当前完整的模块语义能力只支持 LLVM/Clang 工具链。GCC 和 MSVC 工程仍可使用
@@ -36,7 +36,7 @@ mcpp CLI 操作；它不实现新的 C++ 语言服务器，也不替代 mcpp 的
 VSIX，然后在 VS Code 中执行 **Extensions: Install from VSIX...**，或者运行：
 
 ```sh
-code --install-extension /path/to/mcpp-vscode-0.2.3.vsix
+code --install-extension /path/to/mcpp-vscode-0.2.4.vsix
 ```
 
 安装后确认当前 VS Code profile 中同时存在 `mcpp-community.mcpp-vscode` 和
@@ -83,14 +83,20 @@ xlings 安装。
 
 - 将精确文件名 `mcpp.toml` 识别为独立的 mcpp TOML 语言，内置表、键、字符串、数字、
   布尔、日期时间和注释高亮。
-- 将 `build.mcpp`、`.cppm`、`.ixx`、`.mpp` 和 `.ccm` 关联到 VS Code 内置 `cpp` 语言。
-- 向 `source.cpp` 注入模块语法规则。
+- 将精确文件名 `build.mcpp` 识别为独立的 mcpp build language，并复用 C++ TextMate
+  grammar；`.cppm`、`.ixx`、`.mpp` 和 `.ccm` 继续关联到 VS Code 内置 `cpp` 语言。
+- 向 C++ 源文件注入模块语法规则。
 - 覆盖 `module`、`export module`、`import`、`export import`、模块名和模块分区。
 - 支持尚未输入分号的编辑中间态。
 
 语法高亮只负责词法着色。错误模块名、不可见声明等红色诊断来自语言服务器，不能由
 TextMate 语法规则提供。
 
+`build.mcpp` 是由 mcpp 宿主执行的构建脚本，不是普通 C++ 翻译单元。当前扩展只为它
+提供 C++ 风格的语法高亮和编辑器括号/注释规则，不启动 clangd 语义诊断；因此
+`import mcpp;` 不会再被误报为缺少 C++ 模块。真正的 mcpp API 补全需要 mcpp 核心
+未来生成宿主 helper 的 CDB 和 PCM 映射。
+
 ### LLVM 与 clangd 集成
 
 扩展读取 mcpp 生成的 `compile_commands.json`，然后：
@@ -99,7 +105,8 @@ TextMate 语法规则提供。
 2. 从显式设置、编译器目录、匹配的 xlings `llvm-tools` 目录和 `PATH` 中查找 clangd。
 3. 执行编译器和 clangd 的版本命令，比较 LLVM 版本与 revision。
 4. 保留用户已有的 `clangd.arguments`，展开 `${workspaceFolder}` 和
-   `${workspaceRoot}`，并添加精确的 `--query-driver`。
+   `${workspaceRoot}`；只有在 CDB 未提供完整 sysroot、标准库和 no-default-config
+   参数时，才添加精确的 `--query-driver`。
 5. 根据 CDB 中是否已有显式 PCM 映射以及 `mcpp.modulesSupport` 设置，决定是否增加
    clangd 实验模块参数。
 6. 必要时重启官方 clangd 扩展，并执行一次最长 60 秒的 `clangd --check`。

docs/superpowers/plans/2026-08-05-clangd-hermetic-cdb-build-script.md

@@ -0,0 +1,140 @@
+# Clangd Hermetic CDB and build.mcpp Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Remove false clangd diagnostics from hermetic mcpp projects, keep module checks on project sources, and prevent clangd from treating `build.mcpp` as an ordinary C++ translation unit.
+
+**Architecture:** Keep clangd's query-driver discovery for ordinary or cross-toolchain CDBs, but skip it when the selected mcpp command already declares a no-default-config sysroot and standard library. Give `build.mcpp` its own language id backed by the C++ TextMate grammar so syntax highlighting remains while the official clangd extension no longer claims the document. Rank real project sources above `.mcpp` dependency-cache and `target` commands for the extension's direct module check.
+
+**Tech Stack:** TypeScript 5.9, VS Code extension manifests and TextMate grammars, Node.js built-in test runner, clangd 22.1.8, VSCE.
+
+---
+
+### Task 1: Preserve hermetic compilation commands
+
+**Files:**
+- Modify: `src/analysis.ts`
+- Modify: `src/extension.ts`
+- Test: `test/analysis.test.ts`
+
+- [x] **Step 1: Write the failing hermetic CDB argument tests**
+
+Add tests that pass the selected CDB arguments through `buildClangdArguments`. A command containing `--no-default-config`, `-nostdinc++`, an explicit `-isystem.../include/c++/v1`, and `--sysroot=...` must remove a previously managed `--query-driver`; an ordinary command must still receive the selected compiler as its query driver.
+
+- [x] **Step 2: Run the analysis test and verify RED**
+
+Run: `npm run compile && node --test dist/test/analysis.test.js`
+
+Expected: the hermetic test fails because the current implementation always appends `--query-driver`.
+
+- [x] **Step 3: Implement the minimum query-driver policy**
+
+Add `compilationArguments?: readonly string[]` to `ClangdArgumentOptions`. Treat a command as self-contained only when all four hermetic markers are present, remove managed query-driver arguments, and append the selected compiler only for non-self-contained commands. Pass `context.analysis.arguments` from both the workspace configuration path and direct `clangd --check` path in `src/extension.ts`.
+
+- [x] **Step 4: Run the focused tests and verify GREEN**
+
+Run: `npm run compile && node --test dist/test/analysis.test.js`
+
+Expected: all analysis tests pass.
+
+### Task 2: Select a project-owned module check source
+
+**Files:**
+- Modify: `src/analysis.ts`
+- Test: `test/analysis.test.ts`
+
+- [x] **Step 1: Write the failing dependency-cache ranking test**
+
+Create a CDB fixture whose first LLVM command points to `/work/app/.mcpp/.../transaction.cpp` with PCM flags and whose later command points to `/work/app/src/main.cpp` with the same flags. Assert that `analyzeCompilationDatabase` selects `/work/app/src/main.cpp`.
+
+- [x] **Step 2: Run the focused test and verify RED**
+
+Run: `npm run compile && node --test dist/test/analysis.test.js`
+
+Expected: the new test selects the `.mcpp` command and fails.
+
+- [x] **Step 3: Implement project-source ranking**
+
+Keep the existing in-project and module-interface scoring, but add a higher score for paths below the command directory whose first component is neither `.mcpp` nor `target`. Preserve the existing fallback when a CDB contains only dependency or generated commands.
+
+- [x] **Step 4: Run the focused tests and verify GREEN**
+
+Run: `npm run compile && node --test dist/test/analysis.test.js`
+
+Expected: all analysis tests pass and the selected UChat check source is a member source file.
+
+### Task 3: Make build.mcpp syntax-only
+
+**Files:**
+- Modify: `package.json`
+- Create: `syntaxes/mcpp-build.tmLanguage.json`
+- Create: `syntaxes/mcpp-build-language-configuration.json`
+- Modify: `test/artifacts.test.ts`
+- Modify: `README.md`
+
+- [x] **Step 1: Write the failing manifest and grammar tests**
+
+Assert that the manifest declares exact filename language `mcpp-build`, that `files.associations` no longer maps `build.mcpp` to `cpp`, and that the new grammar maps `mcpp-build` to `source.mcpp-build` and includes the external `source.cpp` grammar. Keep the assertion that no broad `*.mcpp` association exists.
+
+- [x] **Step 2: Run the artifact tests and verify RED**
+
+Run: `npm run compile && node --test dist/test/artifacts.test.js`
+
+Expected: the manifest still maps `build.mcpp` to `cpp`, so the new assertions fail.
+
+- [x] **Step 3: Implement the custom language**
+
+Register `mcpp-build` with `filenames: ["build.mcpp"]`, a C++-style language configuration, and a TextMate grammar whose root scope is `source.mcpp-build` and whose patterns include `source.cpp`. Remove only the exact `build.mcpp -> cpp` default; keep `.cppm`, `.ixx`, `.mpp`, and `.ccm` associated with `cpp`. Add `onLanguage:mcpp-build` activation.
+
+- [x] **Step 4: Document the semantic boundary**
+
+Update README wording so `build.mcpp` is described as C++-style syntax highlighting without clangd diagnostics, while real C++ module files continue to use clangd. Explain that semantic support for `import mcpp;` requires a future mcpp-generated host-helper CDB and PCM mapping.
+
+- [x] **Step 5: Run the artifact tests and verify GREEN**
+
+Run: `npm run compile && node --test dist/test/artifacts.test.js`
+
+Expected: all artifact tests pass.
+
+### Task 4: Version, full verification, package, install, and tag
+
+**Files:**
+- Modify: `package.json`
+- Modify: `package-lock.json`
+- Modify: `CHANGELOG.md`
+
+- [x] **Step 1: Bump the extension version**
+
+Run: `npm version 0.2.4 --no-git-tag-version`
+
+Add a `0.2.4` changelog entry covering hermetic query-driver handling, project-source checks, and syntax-only `build.mcpp` handling.
+
+- [x] **Step 2: Run the full regression suite**
+
+Run: `npm test`
+
+Expected: all tests pass with zero failures.
+
+- [x] **Step 3: Reproduce the original UChat clangd symptom**
+
+Run matching clangd 22.1.8 against each UChat `RedisMgr.cpp` using its member CDB and the arguments produced by the fixed policy. Confirm there are no `template_instantiate_undefined`, `ovl_no_viable_function_in_call`, SDK type, or module ODR diagnostics.
+
+- [x] **Step 4: Package and inspect the VSIX**
+
+Run: `npm run package`
+
+Expected: `mcpp-vscode-0.2.4.vsix` is created. Inspect its manifest and archive contents to confirm the new language grammar and configuration are included.
+
+- [x] **Step 5: Commit only the repair files**
+
+Stage the plan, source, focused tests, manifest, lockfile, grammar, README, and changelog files. Do not stage pre-existing modified or untracked design documents. Commit as `fix: preserve hermetic clangd configuration`.
+
+- [x] **Step 6: Create the local release tag**
+
+Create annotated tag `v0.2.4` on the verified repair commit. Do not push it or create a GitHub Release.
+
+- [x] **Step 7: Install and verify the packaged extension**
+
+Run: `code --install-extension /Users/cltx/projects/mcpp/mcpp-vscode/mcpp-vscode-0.2.4.vsix --force`
+
+Then run `code --list-extensions --show-versions` and verify `mcpp-community.mcpp-vscode@0.2.4`. A VS Code window reload is required before the new language registration and clangd arguments take effect.

package-lock.json

@@ -2,7 +2,7 @@
   "name": "mcpp-vscode",
   "displayName": "mcpp",
   "description": "mcpp 与 C++ 模块的 VS Code 集成",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "publisher": "mcpp-community",
   "license": "Apache-2.0",
   "icon": "images/logo.png",
@@ -23,6 +23,7 @@
   "activationEvents": [
     "workspaceContains:mcpp.toml",
     "onLanguage:cpp",
+    "onLanguage:mcpp-build",
     "onCommand:mcpp.configureClangd",
     "onCommand:mcpp.refreshCompilationDatabase",
     "onCommand:mcpp.checkModuleSupport",
@@ -133,6 +134,17 @@
       }
     },
     "languages": [
+      {
+        "id": "mcpp-build",
+        "aliases": [
+          "mcpp build script",
+          "build.mcpp"
+        ],
+        "filenames": [
+          "build.mcpp"
+        ],
+        "configuration": "./syntaxes/mcpp-build-language-configuration.json"
+      },
       {
         "id": "mcpp-toml",
         "aliases": [
@@ -146,14 +158,18 @@
     ],
     "configurationDefaults": {
       "files.associations": {
-        "build.mcpp": "cpp",
         "*.ccm": "cpp",
         "*.cppm": "cpp",
         "*.ixx": "cpp",
         "*.mpp": "cpp"
       }
     },
     "grammars": [
+      {
+        "language": "mcpp-build",
+        "scopeName": "source.mcpp-build",
+        "path": "./syntaxes/mcpp-build.tmLanguage.json"
+      },
       {
         "language": "mcpp-toml",
         "scopeName": "source.toml.mcpp",

package.json

@@ -35,6 +35,7 @@ export interface ToolIdentityComparison {
 
 export interface ClangdArgumentOptions {
   compilerPath: string;
+  compilationArguments?: readonly string[];
   modulesSupport: ModulesSupportMode;
   clangdIdentity?: ToolIdentity;
   platform: NodeJS.Platform;
@@ -201,6 +202,7 @@ export function analyzeCompilationDatabase(contents: string): CompilationDatabas
     const moduleInterface = /\.(?:cppm|ixx|mpp|ccm)$/i.test(sourceFile);
     const inProject = candidate.directory !== undefined && isWithinDirectory(candidate.directory, sourceFile);
     return (inProject ? 200 : 0)
+      + (candidate.directory !== undefined && isProjectSource(candidate.directory, sourceFile) ? 200 : 0)
       + (moduleInterface ? 100 : 0)
       + (candidate.hasPrebuiltModules ? 10 : 0);
   };
@@ -217,6 +219,18 @@ function isWithinDirectory(directory: string, file: string): boolean {
     || (relative !== ".." && !relative.startsWith(`..${pathApi.sep}`) && !pathApi.isAbsolute(relative));
 }
 
+function isProjectSource(directory: string, file: string): boolean {
+  if (!isWithinDirectory(directory, file)) {
+    return false;
+  }
+  const windows = /^[A-Za-z]:[\\/]/.test(directory) || directory.includes("\\")
+    || /^[A-Za-z]:[\\/]/.test(file) || file.includes("\\");
+  const pathApi = windows ? path.win32 : path.posix;
+  const relative = pathApi.relative(pathApi.resolve(directory), pathApi.resolve(file));
+  const firstComponent = relative.split(pathApi.sep)[0];
+  return firstComponent !== ".mcpp" && firstComponent !== "target";
+}
+
 function removeManagedArguments(arguments_: readonly string[]): string[] {
   const result: string[] = [];
 
@@ -238,6 +252,34 @@ function removeManagedArguments(arguments_: readonly string[]): string[] {
   return result;
 }
 
+function hasValueFlag(arguments_: readonly string[], flag: string): boolean {
+  return arguments_.some((argument, index) => (
+    (argument === flag && index + 1 < arguments_.length)
+    || argument.startsWith(`${flag}=`)
+  ));
+}
+
+function hasExplicitLibcxxPath(arguments_: readonly string[]): boolean {
+  return arguments_.some((argument, index) => {
+    const value = argument === "-isystem"
+      ? arguments_[index + 1] ?? ""
+      : argument.startsWith("-isystem")
+        ? argument.slice("-isystem".length)
+        : "";
+    return /[\\/]include[\\/]c\+\+[\\/]v1(?:[\\/]|$)/.test(value);
+  });
+}
+
+function isHermeticClangCommand(arguments_: readonly string[] | undefined): boolean {
+  if (arguments_ === undefined) {
+    return false;
+  }
+  return arguments_.includes("--no-default-config")
+    && arguments_.includes("-nostdinc++")
+    && hasExplicitLibcxxPath(arguments_)
+    && hasValueFlag(arguments_, "--sysroot");
+}
+
 function expandWorkspaceVariables(argument: string, workspaceFolder?: string): string {
   if (workspaceFolder === undefined) {
     return argument;
@@ -276,7 +318,9 @@ export function buildClangdArguments(
 ): string[] {
   const result = removeManagedArguments(existingArguments)
     .map((argument) => expandWorkspaceVariables(argument, options.workspaceFolder));
-  result.push(`--query-driver=${options.compilerPath}`);
+  if (!isHermeticClangCommand(options.compilationArguments)) {
+    result.push(`--query-driver=${options.compilerPath}`);
+  }
 
   if (shouldEnableExperimentalModules(options)) {
     result.push("--experimental-modules-support");

src/analysis.ts

@@ -310,6 +310,7 @@ async function configureClangd(
     clangd.path,
     {
       compilerPath: context.analysis.compilerPath,
+      compilationArguments: context.analysis.arguments,
       modulesSupport,
       clangdIdentity: clangd.version.identity,
       platform: process.platform,
@@ -522,6 +523,7 @@ async function runModuleSupportCheck(
     officialClangdConfiguration(context.project).get<string[]>("arguments", []),
     {
       compilerPath: context.analysis.compilerPath,
+      compilationArguments: context.analysis.arguments,
       modulesSupport: projectConfiguration(context.project)
         .get<ModulesSupportMode>("modulesSupport", "auto"),
       clangdIdentity: clangd.version.identity,