refactor(toolchain): CommandDialect + backend surface normalization (Part A)

New mcpp.toolchain.dialect: command-line *spellings* (gnu vs msvc) as a
value-type traits table — flags.cppm and ninja rule templates now spell
-I/-D/-std=/-c/-o/-O/-g/ar-invocations through it instead of hardcoding
GNU syntax. BmiTraits gains the module-flag spellings (compileModulesFlag,
stdBmiUsePrefix, moduleOutputPrefix, bmiSearchPrefix), replacing the
is_clang()/stdlib_id branches in flags.cppm. ProviderCapabilities gains
has_builtin_p1689_scan (drops ninja_backend's is_gcc gate). Toolchain gains
envOverrides (EnvVar list — std::pair member trips GCC-16 module pendings)
merged into ninja's child env; the MSVC backend will carry INCLUDE/LIB/PATH
through it. gcc::std_module_build_commands normalizes the provider surface
to the command-sequence shape clang already has. resolve_link_model returns
the empty PE model explicitly on Windows.

Zero-diff verified: build.ninja byte-identical (modulo the mcpp self-path
var) for GCC and LLVM toolchains on a multi-module import-std project;
mcpp test 31/31.

Author: Sunrisepeak

src/build/flags.cppm

@@ -16,6 +16,7 @@ import mcpp.build.plan;
 import mcpp.platform;
 import mcpp.toolchain.clang;
 import mcpp.toolchain.detect;
+import mcpp.toolchain.dialect;
 import mcpp.toolchain.linkmodel;
 import mcpp.toolchain.provider;
 import mcpp.toolchain.registry;
@@ -122,10 +123,13 @@ std::string atomic_link_flag(const std::vector<std::filesystem::path>& linkDirs,
 CompileFlags compute_flags(const BuildPlan& plan) {
     CompileFlags f;
 
-    // ProviderCapabilities: centralised query point for per-toolchain decisions.
-    // Prefer caps.* checks over ad-hoc is_clang()/is_musl_target() calls for
-    // any new branching added to this function.
+    // Central query points for per-toolchain decisions — prefer these over
+    // ad-hoc is_clang()/is_gcc() calls:
+    //   caps   — what the toolchain can do (scan-deps, stdlib id, …)
+    //   d      — how a flag is SPELT (GNU "-I" vs MSVC "/I")
+    //   traits — BMI mechanics + module-flag spellings
     auto caps = mcpp::toolchain::capabilities_for(plan.toolchain);
+    const auto& d = mcpp::toolchain::dialect_for(plan.toolchain);
 
     // macOS minimum supported OS version for produced binaries.
     // Precedence: MACOSX_DEPLOYMENT_TARGET env (explicit per-invocation
@@ -152,7 +156,7 @@ CompileFlags compute_flags(const BuildPlan& plan) {
     std::string include_flags;
     for (auto& inc : plan.manifest.buildConfig.includeDirs) {
         auto abs = inc.is_absolute() ? inc : (plan.projectRoot / inc);
-        include_flags += " -I" + escape_path(abs);
+        include_flags += std::format(" {}{}", d.includePrefix, escape_path(abs));
     }
 
     // Sysroot / payload paths — resolved ONCE by the toolchain link model
@@ -208,11 +212,11 @@ CompileFlags compute_flags(const BuildPlan& plan) {
         f.sysroot = link_toolchain_flags;
     }
 
-    // Binutils -B flag
+    // Binutils -B flag — a GCC/libstdc++ payload concern (musl bundles its
+    // own as/ld; Clang and MSVC never take an external binutils).
     bool isMuslTc = mcpp::toolchain::is_musl_target(plan.toolchain);
-    bool isClang = mcpp::toolchain::is_clang(plan.toolchain);
     std::filesystem::path binutilsBin;
-    if (!isMuslTc && !isClang) {
+    if (!isMuslTc && caps.stdlib_id == "libstdc++") {
         auto ar = mcpp::toolchain::archive_tool(plan.toolchain);
         if (!ar.empty())
             binutilsBin = ar.parent_path();
@@ -231,8 +235,8 @@ CompileFlags compute_flags(const BuildPlan& plan) {
     // unless the profile pins -O0.
     auto& prof = plan.manifest.buildConfig;
     std::string opt_flag = isMuslTc && prof.optLevel != "0"
-        ? " -Og" : (" -O" + prof.optLevel);
-    if (prof.debug) opt_flag += " -g";
+        ? " -Og" : std::format(" {}{}", d.optPrefix, prof.optLevel);
+    if (prof.debug) opt_flag += std::format(" {}", d.debugFlags);
     if (prof.lto)   opt_flag += " -flto";
 
     // User link flags
@@ -247,20 +251,25 @@ CompileFlags compute_flags(const BuildPlan& plan) {
         plan.manifest.buildConfig.cStandard.empty() ? "c11" : plan.manifest.buildConfig.cStandard;
 
     // Assemble
-    // -fmodules is a GCC-only flag; Clang uses a different module ABI and does
-    // not need it.  caps.stdlib_id distinguishes GCC (libstdc++) from Clang
-    // (libc++ / msvc-stl) without an extra is_clang() call.
-    std::string module_flag = (caps.stdlib_id == "libstdc++") ? " -fmodules" : "";
+    // Module-flag spellings come from BmiTraits: GCC needs -fmodules on every
+    // TU (BMIs implicit); Clang/MSVC reference the staged std BMI and a BMI
+    // search dir explicitly (spelled -fmodule-file=/-fprebuilt-module-path vs
+    // /reference//ifcSearchDir).
+    auto traits = mcpp::toolchain::bmi_traits(plan.toolchain);
+    std::string module_flag{traits.compileModulesFlag};
     std::string std_module_flag;
-    if (isClang && !plan.stdBmiPath.empty()) {
-        std_module_flag = " -fmodule-file=std=" + escape_path(staged_std_bmi_path(plan));
+    if (!traits.stdBmiUsePrefix.empty() && !plan.stdBmiPath.empty()) {
+        std_module_flag = std::string(traits.stdBmiUsePrefix)
+                        + escape_path(staged_std_bmi_path(plan));
     }
     std::string std_compat_module_flag;
-    if (isClang && !plan.stdCompatBmiPath.empty()) {
+    if (!traits.stdCompatBmiUsePrefix.empty() && !plan.stdCompatBmiPath.empty()) {
+        // NOTE: staging path is Clang's today; registry-dispatch when the
+        // MSVC backend lands (std.compat.ixx staging).
         auto compatDst = mcpp::toolchain::clang::staged_std_compat_bmi_path(plan.outputDir);
-        std_compat_module_flag = " -fmodule-file=std.compat=" + escape_path(compatDst);
+        std_compat_module_flag = std::string(traits.stdCompatBmiUsePrefix)
+                               + escape_path(compatDst);
     }
-    auto traits = mcpp::toolchain::bmi_traits(plan.toolchain);
     std::string prebuilt_module_flag;
     if (traits.needsPrebuiltModulePath) {
         // Absolute path: a bare `pcm.cache` / `gcm.cache` works at ninja
@@ -272,22 +281,32 @@ CompileFlags compute_flags(const BuildPlan& plan) {
         // resolution fails with `module 'X' not found`. The other
         // `-fmodule-file=` flags in this block are already escape_path'd
         // (absolute) for the same reason — this one was a leftover.
-        prebuilt_module_flag = std::format(" -fprebuilt-module-path={}",
-            escape_path(plan.outputDir / traits.bmiDir));
+        prebuilt_module_flag = std::string(traits.bmiSearchPrefix)
+                             + escape_path(plan.outputDir / traits.bmiDir);
     }
     std::string cxx_std_flag =
-        plan.cppStandardFlag.empty() ? std::string("-std=c++23") : plan.cppStandardFlag;
+        plan.cppStandardFlag.empty()
+            ? std::format("{}c++23", d.stdPrefix) : plan.cppStandardFlag;
     f.cxx = std::format("{}{}{}{}{}{}{}{}{}{}", cxx_std_flag, module_flag, std_module_flag,
                         std_compat_module_flag, prebuilt_module_flag,
                         opt_flag, pic_flag, compile_toolchain_flags, b_flag, include_flags);
-    f.cc = std::format("-std={}{}{}{}{}{}", c_std, opt_flag, pic_flag, compile_toolchain_flags,
-                       b_flag, include_flags);
+    f.cc = std::format("{}{}{}{}{}{}{}", d.stdPrefix, c_std, opt_flag, pic_flag,
+                       compile_toolchain_flags, b_flag, include_flags);
 
     // Link flags
     f.staticStdlib = plan.manifest.buildConfig.staticStdlib;
     f.linkage = plan.manifest.buildConfig.linkage;
     std::string full_static = (mcpp::platform::supports_full_static && f.linkage == "static") ? " -static" : "";
-    std::string static_stdlib = (f.staticStdlib && !isClang && !mcpp::platform::is_windows) ? " -static-libstdc++" : "";
+    // Static C++ stdlib: a libstdc++ (GCC/MinGW) concern. On Windows a MinGW
+    // toolchain also statically links libgcc, so produced binaries don't
+    // depend on libstdc++-6.dll / libgcc_s DLLs from the toolchain dir
+    // (portable-by-default, same spirit as the macOS static-libc++ path).
+    std::string static_stdlib;
+    if (f.staticStdlib && caps.stdlib_id == "libstdc++") {
+        static_stdlib = " -static-libstdc++";
+        if constexpr (mcpp::platform::is_windows)
+            static_stdlib += " -static-libgcc";
+    }
     std::string runtime_dirs;
     if constexpr (mcpp::platform::supports_rpath) {
         // Toolchain runtime dirs (glibc/gcc) as before...
@@ -320,7 +339,16 @@ CompileFlags compute_flags(const BuildPlan& plan) {
     if (prof.strip) link_extra += " -s";
 
     if constexpr (mcpp::platform::is_windows) {
-        f.ld = user_ldflags + link_extra;
+        // PE link: no rpath/loader/payload model. MSVC-ABI Clang needs
+        // nothing extra (MSVC STL/SDK via the driver); MinGW adds the static
+        // libstdc++/libgcc pair (static_stdlib above) and -B so its own
+        // binutils resolve, plus `-static` for full static when requested
+        // (MinGW supports it, unlike MSVC-ABI links).
+        std::string mingw_static =
+            (caps.stdlib_id == "libstdc++" && f.linkage == "static")
+                ? " -static" : "";
+        f.ld = std::format("{}{}{}{}{}", mingw_static, static_stdlib, b_flag,
+                           user_ldflags, link_extra);
     } else if constexpr (mcpp::platform::needs_explicit_libcxx) {
         // macOS. Two min-version concerns (see xlings
         // .agents/docs/2026-06-05-macos-min-version-support.md):

src/build/ninja_backend.cppm

@@ -25,6 +25,8 @@ import mcpp.build.hermetic;
 import mcpp.build.compile_commands;
 import mcpp.dyndep;
 import mcpp.toolchain.detect;
+import mcpp.toolchain.dialect;
+import mcpp.toolchain.provider;
 import mcpp.toolchain.registry;
 import mcpp.xlings;
 import mcpp.platform;
@@ -258,10 +260,12 @@ std::string emit_ninja_string(const BuildPlan& plan) {
     // dyndep requires P1689 scanning capability:
     //   GCC: built-in -fdeps-format=p1689r5
     //   Clang: external clang-scan-deps tool (same P1689 output format)
-    bool has_scanner = mcpp::toolchain::is_gcc(plan.toolchain)
-                    || !plan.scanDepsPath.empty();
+    //   (MSVC /scanDependencies is the future third driver — scanner design §3a)
+    auto caps = mcpp::toolchain::capabilities_for(plan.toolchain);
+    bool has_scanner = caps.has_builtin_p1689_scan || !plan.scanDepsPath.empty();
     bool dyndep = dyndep_mode_enabled() && has_scanner;
     auto traits = mcpp::toolchain::bmi_traits(plan.toolchain);
+    const auto& dial = mcpp::toolchain::dialect_for(plan.toolchain);
     std::string out;
     auto append = [&](std::string s) { out += std::move(s); };
 
@@ -331,53 +335,65 @@ std::string emit_ninja_string(const BuildPlan& plan) {
     // Runtime library paths for private toolchain executables are scoped onto
     // the ninja subprocess instead of being emitted into each visible rule.
 
+    // Command spellings come from the toolchain's CommandDialect (gnu vs
+    // msvc); the rule *structure* is shared across compilers.
     std::string module_output_flag = traits.needsExplicitModuleOutput
-        ? " -fmodule-output=$bmi_out" : "";
+        ? std::string(traits.moduleOutputPrefix) + "$bmi_out" : "";
+    const std::string compile_tail = std::format(
+        "{} $in {}$out", dial.compileOnly, dial.outputObjPrefix);
     append("rule cxx_module\n");
     if constexpr (mcpp::platform::is_windows) {
         // Windows: skip BMI restat optimization (requires POSIX shell).
         append(std::format("  command = "
-               "$cxx $local_includes $cxxflags $unit_cxxflags{} -c $in -o $out\n", module_output_flag));
+               "$cxx $local_includes $cxxflags $unit_cxxflags{} {}\n",
+               module_output_flag, compile_tail));
     } else {
         append(std::format("  command = "
                "if [ -n \"$bmi_out\" ] && [ -f \"$bmi_out\" ]; then "
                  "cp -p \"$bmi_out\" \"$bmi_out.bak\"; "
                "fi && "
-               "$cxx $local_includes $cxxflags $unit_cxxflags{} -c $in -o $out && "
+               "$cxx $local_includes $cxxflags $unit_cxxflags{} {} && "
                "if [ -n \"$bmi_out\" ] && [ -f \"$bmi_out.bak\" ] && "
                   "cmp -s \"$bmi_out\" \"$bmi_out.bak\"; then "
                  "mv \"$bmi_out.bak\" \"$bmi_out\"; "
                "else "
                  "rm -f \"$bmi_out.bak\"; "
-               "fi\n", module_output_flag));
+               "fi\n", module_output_flag, compile_tail));
     }
     append("  description = MOD $out\n");
     if (dyndep)
         append("  restat = 1\n");
     append("\n");
 
     append("rule cxx_object\n");
-    append("  command = $cxx $local_includes $cxxflags $unit_cxxflags -c $in -o $out\n");
+    append(std::format(
+        "  command = $cxx $local_includes $cxxflags $unit_cxxflags {}\n",
+        compile_tail));
     append("  description = OBJ $out\n");
     if (dyndep)
         append("  restat = 1\n");
     append("\n");
 
     if (need_c_rule) {
         append("rule c_object\n");
-        append("  command = $cc $local_includes $cflags $unit_cflags -c $in -o $out\n");
+        append(std::format(
+            "  command = $cc $local_includes $cflags $unit_cflags {}\n",
+            compile_tail));
         append("  description = CC $out\n");
         if (dyndep)
             append("  restat = 1\n");
         append("\n");
     }
 
+    // Link rule: driver-style today (g++/clang++ act as the linker). The
+    // dialect's LinkStyle::SeparateLinker (link.exe /OUT: + rspfile) is the
+    // MSVC backend's insertion point — unreachable until that lands.
     append("rule cxx_link\n");
     append("  command = $cxx $in -o $out $ldflags $unit_ldflags\n");
     append("  description = LINK $out\n\n");
 
     append("rule cxx_archive\n");
-    append("  command = $ar rcs $out $in\n");
+    append(std::format("  command = {}\n", dial.archiveCmd));
     append("  description = AR $out\n\n");
 
     append("rule cxx_shared\n");
@@ -811,6 +827,11 @@ std::expected<BuildResult, BuildError> NinjaBackend::build(const BuildPlan& plan
     std::vector<std::pair<std::string, std::string>> nenv;
     if (r.runtimeEnvKey != "-" && !r.runtimeEnvValue.empty())
         nenv.emplace_back(r.runtimeEnvKey, r.runtimeEnvValue);
+    // Toolchain-declared env (empty for GCC/Clang; MSVC's INCLUDE/LIB/PATH).
+    // NOTE: not persisted in the fast-path cache yet — revisit when the MSVC
+    // backend lands (its fast path must re-derive these from detection).
+    for (auto& ev : plan.toolchain.envOverrides)
+        nenv.emplace_back(ev.key, ev.value);
 
     auto cap = mcpp::platform::process::capture_exec(nargv, nenv);
     std::string out = cap.output;

src/toolchain/dialect.cppm

@@ -0,0 +1,109 @@
+// mcpp.toolchain.dialect — command-line *spelling* per compiler family.
+//
+// The single data point for how a flag is spelt: GNU driver style
+// (GCC / Clang / MinGW share one instance) vs MSVC cl.exe style. Consumers
+// (flags.cppm, ninja_backend.cppm, plan.cppm) concatenate these fragments
+// instead of hardcoding "-I"/"-o"/"ar rcs" — adding a compiler family is a
+// second row of data, not another if/else at every call site.
+//
+// Deliberately a value-type aggregate, not a class hierarchy — same
+// rationale as BmiTraits (2026-05-15-clang-parity-and-toolchain-abstraction
+// §2.3): the differences are strings and booleans, not behavior.
+//
+// See .agents/docs/2026-07-13-toolchain-backend-abstraction-msvc-mingw-design.md §2.1.
+
+export module mcpp.toolchain.dialect;
+
+import std;
+import mcpp.toolchain.model;
+
+export namespace mcpp::toolchain {
+
+struct CommandDialect {
+    std::string_view id;               // "gnu" | "msvc"
+
+    // Flag spellings. Prefixes are concatenated with their (already
+    // ninja-escaped) argument by the caller.
+    std::string_view includePrefix;    // "-I"     | "/I"
+    std::string_view definePrefix;     // "-D"     | "/D"
+    std::string_view stdPrefix;        // "-std="  | "/std:"
+    std::string_view compileOnly;      // "-c"     | "/c"
+    std::string_view outputObjPrefix;  // "-o "    | "/Fo:"
+    std::string_view optPrefix;        // "-O"     | "/O"
+    std::string_view debugFlags;       // "-g"     | "/Zi /FS"
+    std::string_view alwaysFlags;      // ""       | "/nologo /EHsc /utf-8"
+
+    // Artifact naming.
+    std::string_view objExt;           // ".o"     | ".obj"
+
+    // Ninja integration.
+    // deps mode for header dependencies ("" = none today for gnu — module
+    // deps go through the P1689/dyndep pipeline instead).
+    std::string_view ninjaDepsMode;    // ""       | "msvc"
+    // Whether link/archive command lines must go through a response file
+    // (Windows 8191-char command-line limit; cl/link/lib accept @file).
+    bool rspfileLink = false;
+
+    // Link step shape: the compiler driver links (g++/clang++ $in -o $out)
+    // or a separate linker is invoked (link.exe /OUT:).
+    enum class LinkStyle { Driver, SeparateLinker };
+    LinkStyle linkStyle = LinkStyle::Driver;
+
+    // Full ninja command template for static archives.
+    std::string_view archiveCmd;       // "$ar rcs $out $in" | "$ar /nologo /OUT:$out $in"
+};
+
+// Dialect lookup. GCC / Clang / MinGW → gnu; MSVC → msvc.
+const CommandDialect& dialect_for(const Toolchain& tc);
+
+} // namespace mcpp::toolchain
+
+namespace mcpp::toolchain {
+
+namespace {
+
+constexpr CommandDialect kGnuDialect{
+    .id              = "gnu",
+    .includePrefix   = "-I",
+    .definePrefix    = "-D",
+    .stdPrefix       = "-std=",
+    .compileOnly     = "-c",
+    .outputObjPrefix = "-o ",
+    .optPrefix       = "-O",
+    .debugFlags      = "-g",
+    .alwaysFlags     = "",
+    .objExt          = ".o",
+    .ninjaDepsMode   = "",
+    .rspfileLink     = false,
+    .linkStyle       = CommandDialect::LinkStyle::Driver,
+    .archiveCmd      = "$ar rcs $out $in",
+};
+
+// Native cl.exe. Unreachable in builds until the MSVC backend lands
+// (prepare.cppm gates CompilerId::MSVC) — the row exists so the data model
+// is complete and unit-tested ahead of that work.
+constexpr CommandDialect kMsvcDialect{
+    .id              = "msvc",
+    .includePrefix   = "/I",
+    .definePrefix    = "/D",
+    .stdPrefix       = "/std:",
+    .compileOnly     = "/c",
+    .outputObjPrefix = "/Fo:",
+    .optPrefix       = "/O",
+    .debugFlags      = "/Zi /FS",
+    .alwaysFlags     = "/nologo /EHsc /utf-8",
+    .objExt          = ".obj",
+    .ninjaDepsMode   = "msvc",
+    .rspfileLink     = true,
+    .linkStyle       = CommandDialect::LinkStyle::SeparateLinker,
+    .archiveCmd      = "$ar /nologo /OUT:$out $in",
+};
+
+} // namespace
+
+const CommandDialect& dialect_for(const Toolchain& tc) {
+    if (tc.compiler == CompilerId::MSVC) return kMsvcDialect;
+    return kGnuDialect;
+}
+
+} // namespace mcpp::toolchain