fix(build): #390 修复补全 —— 摄入点收敛 + emitter 兜底 + 合并去重自愈

按 review(#391) 补全同一决策的全部推导点,不再依赖「所有摄入点都被找全」:

- P1: 补上 plan.cppm expand_manifest_include_entry(绝对分支与
  generated/ 裸拼接回退)、scanner.cppm rewrite_rel_copy(cxxflags 的
  -Ithird_party/inc 通道)、flags.cppm [build] include_dirs 全局 cxxflags
  通道;并在 emit_compile_commands 加最后一层兜底:file/directory/-c/-o/-I
  统一 make_preferred,对 CDB 契约给出无条件保证。
- P2: merge_compile_commands 去重键改为归一化路径(lexically_normal +
  make_preferred),旧 CDB 里的混合分隔符条目与 fresh 原生拼写视为同一
  文件 → 升级后第一次 build 即自愈,用户无需手删 compile_commands.json。
  已在带旧条目的工程上实测:注入混合条目后重建,归零。
- P3: e2e 76 的 Windows 断言改为平台无关的「同时含 \ 与 / 即失败」
  (消掉 os.name 依赖,避免 MSYS python 假绿);新增 extra.cpp 必须进
  CDB 的 grep 守卫;python3 缺失时显式 SKIP。
- native_path_from_generic 改用标准库 make_preferred;include_dirs 绝对
  分支不再做 generic_string 窄串往返(ANSI 代码页拼不出的名字会抛,
  mcpp#230)。
- 单测:NormalizedFileKeysHealStaleSeparatorSpellings(合并自愈)、
  EmittedPathsUseNativeSeparators(emitter 兜底)、
  Plan.ExpandManifestIncludeEntryNativeSpelling(plan.cppm 摄入点,
  expand_manifest_include_entry 为此从匿名命名空间提出并导出)。

注:directives::abs_against 归一化会改写 build.mcpp 指令路径的拼写,
声明输入指纹一次性失效 → 一次多余重建,属预期。

Author: ZheFeng7110

src/build/compile_commands.cppm

@@ -142,16 +142,28 @@ std::vector<std::string> split_flags(std::string_view s) {
 
 namespace {
 
+// The CDB's path contract: NATIVE separators, unconditionally. Every
+// ingestion point (manifest globs, include_dirs, build.mcpp directives) is
+// normalized at the source, but this is the LAST line — a path that slips
+// through with a mixed `root\a/b` spelling (MSVC keeps input `/` verbatim)
+// breaks CLion, and no amount of "all ingestion points are covered" can be
+// proven. make_preferred() is a no-op on POSIX.
+std::string native_string(const std::filesystem::path& p) {
+    auto n = p;
+    n.make_preferred();
+    return n.string();
+}
+
 std::vector<std::string> local_include_args(const CompileUnit& cu) {
     std::vector<std::string> args;
     args.reserve(cu.localIncludeDirs.size());
     for (auto const& inc : cu.localIncludeDirs) {
-        args.push_back("-I" + inc.string());
+        args.push_back("-I" + native_string(inc));
     }
     // #249: after-dirs keep their -idirafter spelling in the compile DB so
     // tooling (clangd) reproduces the compiler's search order.
     for (auto const& inc : cu.localIncludeDirsAfter) {
-        args.push_back("-idirafter" + inc.string());
+        args.push_back("-idirafter" + native_string(inc));
     }
     return args;
 }
@@ -186,7 +198,7 @@ std::string emit_compile_commands(const BuildPlan& plan, const CompileFlags& fla
                             : isCSource   ? flags.cc
                                           : flags.cxx;
 
-        auto output_path = (plan.outputDir / cu.object).string();
+        auto output_path = native_string(plan.outputDir / cu.object);
 
         // Build arguments array.
         nlohmann::json args = nlohmann::json::array();
@@ -198,13 +210,13 @@ std::string emit_compile_commands(const BuildPlan& plan, const CompileFlags& fla
         for (auto& f : package_flag_args(cu, isCSource))
             args.push_back(std::move(f));
         args.push_back("-c");
-        args.push_back(cu.source.string());
+        args.push_back(native_string(cu.source));
         args.push_back("-o");
         args.push_back(output_path);
 
         nlohmann::json entry;
-        entry["directory"] = plan.projectRoot.string();
-        entry["file"] = cu.source.string();
+        entry["directory"] = native_string(plan.projectRoot);
+        entry["file"] = native_string(cu.source);
         entry["arguments"] = std::move(args);
         entry["output"] = output_path;
 
@@ -222,11 +234,25 @@ std::string merge_compile_commands(
     if (freshJ.is_discarded() || !freshJ.is_array())
         return std::string(fresh);
 
+    // Dedup key = the file's PATH, spelled the way a fresh plan spells it
+    // (native separators). A prior CDB written before the mixed-separator
+    // fix (#390) carries `root\generated/modules\x.cppm` entries that are
+    // the SAME file as the fresh `root\generated\modules\x.cppm` — a literal
+    // string comparison would keep both and the user's upgrade would not
+    // visibly fix anything. Normalizing makes the merge self-healing: the
+    // stale mixed entry is skipped on the first `mcpp build` after upgrade.
+    // fileExists still probes the raw spelling — Windows accepts both.
+    auto norm_key = [](std::string_view f) {
+        auto p = std::filesystem::path(std::string(f)).lexically_normal();
+        p.make_preferred();
+        return p.string();
+    };
+
     // Files the current plan already covers — those entries are authoritative.
     std::set<std::string> freshFiles;
     for (auto const& e : freshJ) {
         if (e.contains("file") && e["file"].is_string())
-            freshFiles.insert(e["file"].get<std::string>());
+            freshFiles.insert(norm_key(e["file"].get<std::string>()));
     }
 
     // Keep fresh order, then append still-valid prior entries the plan doesn't
@@ -238,7 +264,7 @@ std::string merge_compile_commands(
         for (auto const& e : existingJ) {
             if (!e.contains("file") || !e["file"].is_string()) continue;
             auto f = e["file"].get<std::string>();
-            if (freshFiles.contains(f)) continue;             // fresh wins
+            if (freshFiles.contains(norm_key(f))) continue;       // fresh wins
             if (!fileExists(std::filesystem::path(f))) continue;  // pruned
             merged.push_back(e);
         }

src/build/flags.cppm

@@ -317,7 +317,13 @@ CompileFlags compute_flags(const BuildPlan& plan) {
     // once ninja hands the resolved command line to the shell.
     std::vector<std::string> includeTokens;
     for (auto& inc : plan.manifest.buildConfig.includeDirs) {
-        std::filesystem::path p = inc.has_root_path() ? inc : (plan.projectRoot / inc);
+        // make_preferred: a multi-segment TOML entry like `generated/inc`
+        // keeps its `/` on MSVC, and the bare `projectRoot / inc` join would
+        // be MIXED — reaching both the ninja command line and the CDB's
+        // arguments (via f.cxx → split_flags). Same rule as every other
+        // manifest-path ingestion point (#390); no-op on POSIX.
+        auto p = inc.has_root_path() ? inc : (plan.projectRoot / inc);
+        p.make_preferred();
         includeTokens.push_back(include_token(d, p));
     }
     // #249: `[build] include_dirs_after` — searched AFTER the toolchain's
@@ -327,8 +333,8 @@ CompileFlags compute_flags(const BuildPlan& plan) {
     // (documented degradation; clang-MSVC uses the gnu dialect).
     const bool msvcInclude = d.includePrefix == std::string_view("/I");
     for (auto& inc : plan.manifest.buildConfig.includeDirsAfter) {
-        std::filesystem::path ip(inc);
-        std::filesystem::path p = ip.has_root_path() ? ip : (plan.projectRoot / ip);
+        auto p = inc.has_root_path() ? inc : (plan.projectRoot / inc);
+        p.make_preferred();
         includeTokens.push_back(
             include_token(d, p, msvcInclude ? "/I" : "-idirafter"));
     }

src/build/plan.cppm

@@ -220,6 +220,14 @@ make_plan(const mcpp::manifest::Manifest&         manifest,
          // simply makes those units uncacheable.
          const std::vector<std::filesystem::path>& storeRoots = {});
 
+// Expand one manifest `include_dirs` entry against the project root — the
+// #249 consistency join + the expand_dir_glob the dep path uses. Exported
+// (like modgraph's glob_literal_prefix) so unit tests can assert its
+// native-separator contract directly; see the definition below.
+std::vector<std::filesystem::path>
+expand_manifest_include_entry(const std::filesystem::path& root,
+                              const std::filesystem::path& inc);
+
 } // namespace mcpp::build
 
 namespace mcpp::build {
@@ -368,22 +376,42 @@ std::vector<std::string> shared_library_link_flags(
     return flags;
 }
 
+}  // namespace
+
 // #249 consistency fix: expand include_dirs entries with the same
 // `expand_dir_glob` the dep path (prepare.cppm) uses, so a main-manifest
 // `include_dirs = ["*/include"]` glob works identically here. For a literal
 // (wildcard-free) entry expand_dir_glob only returns EXISTING directories,
 // whereas this helper historically joined unconditionally — keep the plain
 // join as a fallback so an -I for a dir created later (e.g. by a build
 // step) isn't silently dropped.
+//
+// Deliberately OUTSIDE the anonymous namespace: it is exported for its unit
+// test (like modgraph's glob_literal_prefix), and the two
+// local_include_dirs_*_for_manifest consumers below ride along so a single
+// namespace split serves the whole trio.
 std::vector<std::filesystem::path>
 expand_manifest_include_entry(const std::filesystem::path& root,
                               const std::filesystem::path& inc)
 {
-    if (inc.is_absolute()) return { inc };
+    if (inc.is_absolute()) {
+        // A TOML value like `C:/SDL2/include` keeps its `/` on MSVC — make
+        // it native so the CDB's -I (via local_include_args) is uniform.
+        auto n = inc;
+        n.make_preferred();
+        return { std::move(n) };
+    }
     const auto glob = inc.generic_string();
     auto expanded = mcpp::modgraph::expand_dir_glob(root, glob);
-    if (expanded.empty() && glob.find('*') == std::string::npos)
-        expanded.push_back(root / inc);
+    if (expanded.empty() && glob.find('*') == std::string::npos) {
+        // Same native-spelling rule for the bare join (see above): `root / p`
+        // with a multi-segment `generated/inc` is MIXED on MSVC, and this
+        // fallback exists precisely for dirs like `generated/` that a later
+        // build step creates — the #390 shape.
+        auto joined = root / inc;
+        joined.make_preferred();
+        expanded.push_back(std::move(joined));
+    }
     return expanded;
 }
 
@@ -412,6 +440,8 @@ local_include_dirs_after_for_manifest(const std::filesystem::path& root,
     return dirs;
 }
 
+namespace {
+
 void append_unique_path(std::vector<std::filesystem::path>& out,
                         std::filesystem::path path)
 {

src/build/prepare.cppm

@@ -2997,11 +2997,13 @@ prepare_build(bool print_fingerprint,
         std::vector<std::filesystem::path> dirs;
         for (auto const& inc : manifest.buildConfig.includeDirs) {
             if (inc.is_absolute()) {
-                // Native spelling (see native_path_from_generic): a TOML
-                // `C:/SDL2/include` stays mixed on MSVC and leaks into the
-                // CDB's -I otherwise.
-                appendUniquePath(dirs,
-                    mcpp::modgraph::native_path_from_generic(inc.generic_string()));
+                // Native spelling: a TOML `C:/SDL2/include` stays mixed on
+                // MSVC and leaks into the CDB's -I otherwise. Direct
+                // make_preferred — no generic_string round trip, which can
+                // throw for names the ANSI codepage cannot spell (mcpp#230).
+                auto n = inc;
+                n.make_preferred();
+                appendUniquePath(dirs, std::move(n));
                 continue;
             }
             for (auto& dir : mcpp::modgraph::expand_dir_glob(
@@ -3021,8 +3023,9 @@ prepare_build(bool print_fingerprint,
         std::vector<std::filesystem::path> dirs;
         for (auto const& inc : manifest.buildConfig.includeDirsAfter) {
             if (inc.is_absolute()) {
-                appendUniquePath(dirs,
-                    mcpp::modgraph::native_path_from_generic(inc.generic_string()));
+                auto n = inc;
+                n.make_preferred();
+                appendUniquePath(dirs, std::move(n));
                 continue;
             }
             for (auto& dir : mcpp::modgraph::expand_dir_glob(

src/modgraph/glob.cppm

@@ -24,16 +24,12 @@ export namespace mcpp::modgraph {
 // to parse. Ninja never notices because it renders everything via
 // generic_string(); the CDB is the first `.string()` consumer.
 //
-// POSIX is untouched (its native separator already is `/`). Replacing only
-// `/` is also safe for already-native Windows input: it never contains `/`.
+// POSIX is untouched (`make_preferred()` is a no-op there, and it is also
+// safe for already-native Windows input, which never contains `/`).
 std::filesystem::path native_path_from_generic(std::string_view s) {
-    constexpr char kSep = std::filesystem::path::preferred_separator;
-    if (kSep == '/') return std::filesystem::path(s);
-    std::string p(s);
-    for (auto& c : p) {
-        if (c == '/') c = kSep;
-    }
-    return std::filesystem::path(std::move(p));
+    std::filesystem::path p(s);
+    p.make_preferred();
+    return p;
 }
 
 // Does `candidate` match `glob`, interpreted relative to `root`?

src/modgraph/scanner.cppm

@@ -501,10 +501,18 @@ namespace {
 
 // has_root_path: leave absolute AND root-relative ("/x" on Windows)
 // spellings alone — only genuinely root-less paths are project-relative.
+// Both branches normalize to NATIVE separators: a `-Ithird_party/inc` cxxflag
+// would otherwise come back as `C:\proj\third_party/inc` on MSVC (path keeps
+// the input `/` verbatim) and reach the CDB's arguments via packageCxxflags.
 std::string rewrite_rel_copy(const std::string& p, const std::filesystem::path& root) {
     std::filesystem::path fp(p);
-    if (fp.has_root_path()) return p;
-    return (root / fp).string();
+    if (fp.has_root_path()) {
+        fp.make_preferred();
+        return fp.string();
+    }
+    auto joined = root / fp;
+    joined.make_preferred();
+    return joined.string();
 }
 
 void rewrite_rel(std::string& p, const std::filesystem::path& root) {
@@ -691,8 +699,12 @@ local_include_dirs_for(const std::filesystem::path& root,
         if (inc.is_absolute()) {
             // A TOML value like `C:/SDL2/include` keeps its `/` on MSVC —
             // normalize so the CDB's -I comes out native (mixed separators
-            // break CLion). See mcpp::modgraph::native_path_from_generic.
-            dirs.push_back(native_path_from_generic(inc.generic_string()));
+            // break CLion). Direct make_preferred, no generic_string round
+            // trip: the narrow conversion can throw for names the ANSI
+            // codepage cannot spell (mcpp#230).
+            auto n = inc;
+            n.make_preferred();
+            dirs.push_back(std::move(n));
             continue;
         }
         for (auto& d : expand_dir_glob(root, inc.generic_string())) {
@@ -711,7 +723,9 @@ local_include_dirs_after_for(const std::filesystem::path& root,
     std::vector<std::filesystem::path> dirs;
     for (auto const& inc : manifest.buildConfig.includeDirsAfter) {
         if (inc.is_absolute()) {
-            dirs.push_back(native_path_from_generic(inc.generic_string()));
+            auto n = inc;
+            n.make_preferred();
+            dirs.push_back(std::move(n));
             continue;
         }
         for (auto& d : expand_dir_glob(root, inc.generic_string())) {

tests/e2e/76_compile_commands_generated.sh

@@ -55,26 +55,36 @@ grep -qE '"command"|"arguments"' "$cdb" || {
 # The minimal project's source (src/main.cpp) must have an entry.
 grep -q 'main\.cpp' "$cdb" || { echo "FAIL: $cdb has no entry for src/main.cpp"; cat "$cdb"; exit 1; }
 
+# The multi-segment glob must ACTUALLY have contributed an entry — if the
+# glob silently missed, every separator assertion below is vacuous green.
+grep -q 'extra\.cpp' "$cdb" || {
+    echo "FAIL: $cdb has no entry for generated/modules/extra.cpp — multi-segment glob missed"
+    cat "$cdb"; exit 1
+}
+
 # Deeper structural validation when a JSON parser is available (GitHub-hosted
-# runners ship python3). Skips cleanly where it isn't, keeping the grep checks
-# above as the portable baseline.
+# runners ship python3). Explicitly reports the skip where it isn't, so a
+# silent pass can never masquerade as validation coverage.
 if command -v python3 >/dev/null 2>&1; then
     python3 - "$cdb" <<'PY' || exit 1
-import json, sys, os
+import json, sys
 d = json.load(open(sys.argv[1], encoding="utf-8"))
 assert isinstance(d, list) and d, "CDB must be a non-empty JSON array"
 for e in d:
     assert "file" in e and "directory" in e, "entry missing file/directory: %r" % e
     assert ("command" in e) or ("arguments" in e), "entry missing command/arguments: %r" % e
-    # Native separators on Windows: a multi-segment manifest glob used to
-    # yield MIXED `root\generated/modules\x.cppm` file paths (MSVC's path
-    # keeps the `/` from the glob prefix), which CLion refuses to parse.
-    # Ninja hides the problem (it renders generic_string()); the CDB is
-    # the .string() consumer.
-    if os.name == "nt" and "/" in e["file"]:
-        raise AssertionError("file must use native separators on Windows: %r" % e["file"])
+    # Platform-independent mixed-separator check: the #390 bug spelled a
+    # Windows file as `root\generated/modules\x.cppm` (MSVC's path keeps the
+    # `/` from the manifest glob prefix, and the directory walk propagates
+    # it). On POSIX a backslash never appears in a path, so the assertion is
+    # trivially true there and catches exactly the bug on Windows — no
+    # os.name / platform sniffing needed.
+    f = e["file"]
+    assert not ("\\" in f and "/" in f), "mixed separators in file: %r" % f
 print("  json validation OK (%d entries)" % len(d))
 PY
+else
+    echo "SKIP: python3 not on PATH — JSON validation not run"
 fi
 
 echo "OK"

tests/unit/test_build_flags.cpp

@@ -97,35 +97,51 @@ TEST(BuildFlagsAtomic, StaticLinkEmittedWhenArchivePresent) {
 // BOTH the joined spelling (`-iquotehdr`) and the separated spelling
 // (`-isystem` followed by a standalone next element). All four of these
 // project-relative paths must resolve to the same "/proj/hdr" target.
+//
+// The expected spelling is NATIVE (#390): `-I/abs/hdr` written with forward
+// slashes keeps them on MSVC, and the old expectation `(root / "hdr").string()`
+// was itself the mixed `"/proj\hdr"` shape this family of bugs produced.
+// make_preferred() makes the expectation platform-correct on both sides.
 TEST(BuildFlags, NormalizeIncludeFlagsRewritesFullIncludeFamily) {
     std::filesystem::path root = "/proj";
+    auto expected = [](const std::filesystem::path& p) {
+        auto n = p;
+        n.make_preferred();
+        return n.string();
+    };
     std::vector<std::string> flags = {
         "-Ihdr", "-iquotehdr", "-isystem", "hdr", "-idirafterhdr",
     };
 
     mcpp::modgraph::normalize_include_flags(root, flags);
 
     ASSERT_EQ(flags.size(), 5u);
-    EXPECT_EQ(flags[0], "-I" + (root / "hdr").string());
-    EXPECT_EQ(flags[1], "-iquote" + (root / "hdr").string());
+    EXPECT_EQ(flags[0], "-I" + expected(root / "hdr"));
+    EXPECT_EQ(flags[1], "-iquote" + expected(root / "hdr"));
     EXPECT_EQ(flags[2], "-isystem");                       // prefix itself untouched
-    EXPECT_EQ(flags[3], (root / "hdr").string());          // separated element rewritten
-    EXPECT_EQ(flags[4], "-idirafter" + (root / "hdr").string());
+    EXPECT_EQ(flags[3], expected(root / "hdr"));           // separated element rewritten
+    EXPECT_EQ(flags[4], "-idirafter" + expected(root / "hdr"));
 }
 
 // Absolute paths and root-relative spellings are left alone (matches the
-// pre-#226 -I behavior), for both the joined and separated forms.
+// pre-#226 -I behavior), for both the joined and separated forms — only the
+// separator spelling is normalized to native (#390; a no-op on POSIX).
 TEST(BuildFlags, NormalizeIncludeFlagsLeavesAbsolutePathsAlone) {
     std::filesystem::path root = "/proj";
+    auto expected = [](const std::filesystem::path& p) {
+        auto n = p;
+        n.make_preferred();
+        return n.string();
+    };
     std::vector<std::string> flags = {
         "-I/abs/hdr", "-isystem", "/abs/hdr", "-DKEEP",
     };
 
     mcpp::modgraph::normalize_include_flags(root, flags);
 
-    EXPECT_EQ(flags[0], "-I/abs/hdr");
+    EXPECT_EQ(flags[0], "-I" + expected("/abs/hdr"));
     EXPECT_EQ(flags[1], "-isystem");
-    EXPECT_EQ(flags[2], "/abs/hdr");
+    EXPECT_EQ(flags[2], expected("/abs/hdr"));
     EXPECT_EQ(flags[3], "-DKEEP");
 }