fix: PR #9 review 打磨——补 [build-dependencies] 段头、[[...]] 数组表不出建议、README 文档化

- SECTION_HEADERS 增加 [build-dependencies]（mcpp 真实依赖表，契约测试已覆盖）
- [[...]] 数组表段头不提供建议，避免把数组表意图悄悄替换成普通段 [x]
- 补行为测试（数组表 / build-dependencies 模板）与段头注册表关键组断言
- README：能力矩阵、已实现功能、设置三处补充结构补全说明

Author: wellwei

README.md

@@ -18,6 +18,7 @@ mcpp CLI 操作；它不实现新的 C++ 语言服务器，也不替代 mcpp 的
 | --- | --- | --- | --- |
 | 识别 mcpp 工程 | 支持 | 支持 | 支持 |
 | `mcpp.toml` TOML 语法高亮 | 支持 | 支持 | 支持 |
+| `mcpp.toml` 结构补全（段头 + 写法模板） | 支持 | 支持 | 支持 |
 | `build.mcpp`、`.cppm`、`.ixx`、`.mpp`、`.ccm` 文件关联 | 支持 | 支持 | 支持 |
 | `module`、`export module`、`import` 语法高亮 | 支持 | 支持 | 支持 |
 | 构建、运行、测试、清理命令 | 支持 | 支持 | 支持 |
@@ -97,6 +98,19 @@ TextMate 语法规则提供。
 `import mcpp;` 不会再被误报为缺少 C++ 模块。真正的 mcpp API 补全需要 mcpp 核心
 未来生成宿主 helper 的 CDB 和 PCM 映射。
 
+### mcpp.toml 结构补全
+
+- 段头补全：26 个段（`[package]`、`[targets.<name>]`、`[dependencies]`、`[build-dependencies]`、
+  `[features]`、`[indices]`、`[pack]` 等），参数化段带可跳转占位符。
+- 写法模板：依赖段的依赖写法（版本 / 路径 / git / features / tools）、`[features]` 表形式、
+  capabilities / xlings / tools.overrides / generated_files 等开放段的条目形态。
+- 每条建议携带显式替换范围，部分输入（`[dep`、`na`）不会残留无效文本；所有语义规则有真实
+  mcpp 契约测试（44 例，无 mcpp 环境自动跳过）。
+- 范围边界：不提供静态字段键/枚举（等上游版本化 manifest schema），不提供依赖包名/版本候选
+  （等上游批量 catalog 接口）；未知自定义段与 `[[...]]` 数组表不提供建议。
+- 由 `mcpp.tomlCompletion` 设置控制（默认开启）；未受信任工作区仅做纯文本分析，不执行任何
+  外部程序。
+
 ### LLVM 与 clangd 集成
 
 扩展读取 mcpp 生成的 `compile_commands.json`，然后：
@@ -172,7 +186,8 @@ xlings 补齐匹配版本的 llvm-tools（含 clangd），最后重新读取 CDB
   "mcpp.path": "/path/to/mcpp",
   "mcpp.clangd.path": "/path/to/matching/clangd",
   "mcpp.modulesSupport": "auto",
-  "mcpp.configureCppTools": true
+  "mcpp.configureCppTools": true,
+  "mcpp.tomlCompletion": true
 }
 ```
 
@@ -182,6 +197,7 @@ xlings 补齐匹配版本的 llvm-tools（含 clangd），最后重新读取 CDB
 | `mcpp.clangd.path` | 空 | 与 CDB 中 LLVM 编译器匹配的 clangd；空值表示自动发现 |
 | `mcpp.modulesSupport` | `auto` | `auto`、`on` 或 `off`，控制 clangd 实验模块参数 |
 | `mcpp.configureCppTools` | `true` | 手动配置 clangd 时，是否询问关闭当前工作区的 cpptools IntelliSense |
+| `mcpp.tomlCompletion` | `true` | 为 `mcpp.toml` 提供结构补全：段头与写法模板（snippet）；所有建议带显式替换范围，并经真实 mcpp 契约测试验证 |
 
 `mcpp.path` 只影响插件执行 mcpp CLI 命令。工程实际编译器来自
 `compile_commands.json`，`mcpp.clangd.path` 只指定语言服务器，三者相互独立。

src/mcppTomlCompletion.ts

@@ -43,6 +43,7 @@ export const SECTION_HEADERS: readonly SectionHeaderSpec[] = [
   { group: "generated_files", label: "[generated_files]", header: "[generated_files]", detail: "生成文件（路径 → 内容）" },
   { group: "dependencies", label: "[dependencies]", header: "[dependencies]", detail: "运行时依赖" },
   { group: "dev-dependencies", label: "[dev-dependencies]", header: "[dev-dependencies]", detail: "开发/测试依赖" },
+  { group: "build-dependencies", label: "[build-dependencies]", header: "[build-dependencies]", detail: "构建期依赖（仅构建期拉取，运行时不可见）" },
   { group: "workspace", label: "[workspace]", header: "[workspace]", detail: "工作空间成员声明" },
   { group: "workspace.dependencies", label: "[workspace.dependencies]", header: "[workspace.dependencies]", detail: "集中声明依赖版本，成员用 workspace = true 继承" },
   { group: "features", label: "[features]", header: "[features]", detail: "feature 定义" },
@@ -189,6 +190,11 @@ export function computeMcppTomlCompletions(
   const context = contextAt(lines, line, character);
 
   if (context.kind === "section-header") {
+    // mcpp manifest 不使用 TOML 数组表（[[...]]）；[[ 内不提供建议，
+    // 避免把用户意图的数组表悄悄替换成普通段 [x]（未知段会被 mcpp 静默忽略）。
+    if (context.isArray) {
+      return [];
+    }
     // parser 的替换范围从段名 token 开始；段头建议插入的是完整 "[xxx]"，
     // 需要把范围扩展到本行的 "["，避免留下 "[["。仅当 "[" 是行内首个
     // 非空白字符时才扩展（section-header 上下文正常都满足，防御奇怪输入）。

test/mcppTomlCompletion.test.ts

@@ -15,6 +15,7 @@ test("suggests section headers on a partial bracket line", () => {
   assert.ok(suggestions.length > 0);
   assert.ok(suggestions.every((suggestion) => suggestion.kind === "section"));
   assert.ok(labels(suggestions).includes("[dependencies]"));
+  assert.ok(labels(suggestions).includes("[build-dependencies]"));
   assert.ok(labels(suggestions).includes("[workspace]"));
   assert.ok(labels(suggestions).includes("[indices]"));
   // 每条建议都带显式替换范围（覆盖已输入的 "[dep"）。
@@ -26,6 +27,13 @@ test("suggests section headers on a partial bracket line", () => {
   assert.equal(targets?.insertSnippet, "[targets.${1:name}]");
 });
 
+test("offers nothing inside [[...]] array-table headers", () => {
+  // mcpp manifest 不使用 TOML 数组表（[[...]]）：[[ 内不出建议，
+  // 避免把用户意图的数组表悄悄替换成普通段 [x]。
+  assert.deepEqual(computeMcppTomlCompletions(["[[dep"], 0, 5), []);
+  assert.deepEqual(computeMcppTomlCompletions(["[[dependencies]"], 0, 3), []);
+});
+
 test("suggests section headers at the top of the document", () => {
   const suggestions = computeMcppTomlCompletions([""], 0, 0);
   assert.ok(suggestions.length > 0);
@@ -61,6 +69,12 @@ test("suggests dependency templates in conditional dependency sections", () => {
   assert.ok(labels(suggestions).includes('name = "version"'));
 });
 
+test("suggests dependency templates in build-dependencies", () => {
+  const suggestions = computeMcppTomlCompletions(["[build-dependencies]", ""], 1, 0);
+  assert.ok(labels(suggestions).includes('name = "version"'));
+  assert.ok(suggestions.every((suggestion) => suggestion.kind === "template"));
+});
+
 test("suggests templates in free-key sections", () => {
   const features = computeMcppTomlCompletions(["[features]", ""], 1, 0);
   assert.ok(features.every((suggestion) => suggestion.kind === "template"));

test/mcppTomlContract.test.ts

@@ -121,7 +121,7 @@ function fixtureFor(entry: SectionHeaderSpec): { manifest: string; files: Record
 test("段头注册表形态：数量与关键段齐全（防止测试与实现脱节）", { skip: skipReason }, () => {
   assert.ok(SECTION_HEADERS.length >= 20, `段头注册表只有 ${SECTION_HEADERS.length} 条（期望 ≥ 20）`);
   const groups = new Set(SECTION_HEADERS.map((entry) => entry.group));
-  for (const key of ["package", "dependencies", "workspace", "pack"]) {
+  for (const key of ["package", "dependencies", "build-dependencies", "workspace", "pack"]) {
     assert.ok(groups.has(key), `段头注册表缺少关键段 ${key}`);
   }
   const labels = SECTION_HEADERS.map((entry) => entry.label);