platform: one macos/macosx spelling rule, and the manifest asks it

Two names for one platform: mcpp's triple vocabulary says macos, an xpkg
descriptor and xlings' project file say macosx. The manifest parser had a
second copy of that fold and a second copy of the host key, both hand-rolled
beside a rule modules/platform already had.

mcpp.platform.axis gains xpkg_platform_key_for, which is now the only place
that knows, and TargetPlatform::for_os is written in terms of it rather than
repeating the table. The manifest reads it for both directions — canonicalising
a written key and folding a requested platform — and takes the host from
xpkg_platform instead of its own #if.

Both spellings are therefore accepted wherever a platform is named, and a new
unit test asserts that the two write the same declaration on every host by
resolving explicitly rather than against the one it runs on.

Author: speak-agent

docs/05-mcpp-toml.md

@@ -1909,9 +1909,11 @@ The namespace may be written on either half. Writing it on the key requires
 halves with different values is an error, and so is naming one package twice
 under two spellings.
 
-Platform keys are xlings' own — `linux`, `macosx`, `windows` — plus `default`;
-`macos` is accepted as an alias. A table with no key for this host and no
-`default` declares nothing here.
+Platform keys are xlings' own — `linux`, `macosx`, `windows` — plus `default`.
+`macos` and `macosx` are the same platform written in two vocabularies (mcpp's
+triples say one, descriptors and xlings' project file say the other) and both
+are accepted wherever a platform is named. A table with no key for this host
+and no `default` declares nothing here.
 
 #### Which version a tool the project did not name resolves to
 

docs/zh/05-mcpp-toml.md

@@ -1629,8 +1629,10 @@ mcpp 既供给它——机器上没有就装,有就映射——也把它物化
 命名空间写在哪一半都可以。写在键上**必须带引号**,因为 TOML 的裸键不能含冒号。
 两半都写且不一致是错误;同一个包用两种拼法出现两次也是错误。
 
-平台键是 xlings 自己的 —— `linux`、`macosx`、`windows`,外加 `default`;`macos`
-作为别名接受。表里既没有本机这一项也没有 `default`,就表示在这里什么都不声明。
+平台键是 xlings 自己的 —— `linux`、`macosx`、`windows`,外加 `default`。`macos`
+与 `macosx` 是同一个平台的两套词汇(mcpp 的三元组说前者,描述符与 xlings 的项目
+文件说后者),**凡是点名平台的地方两者都接受**。表里既没有本机这一项也没有
+`default`,就表示在这里什么都不声明。
 
 #### 工程没点名的工具,其版本的来源
 

modules/manifest/src/toml.cppm

@@ -12,6 +12,7 @@ import mcpp.version_req;
 import mcpp.pm.dependency_selector;
 import mcpp.pm.index_spec;
 import mcpp.platform;
+import mcpp.platform.axis;   // the one macos/macosx spelling rule
 
 // ⚠️ ANONYMOUS NAMESPACE, AND THIS COST TWO WINDOWS JOBS TO LEARN.
 //
@@ -119,15 +120,17 @@ struct LoadContext {
 // list. The unresolved declaration is kept beside it in
 // `XlingsConfig::workspaceByPlatform`, because the descriptor emitter needs
 // every platform at once and cannot re-derive what was already collapsed.
+//
+// ⚠️ `macos` AND `macosx` ARE ONE PLATFORM, AND THE RULE IS NOT WRITTEN HERE.
+// mcpp's triple vocabulary says `macos`; a descriptor and xlings' project file
+// say `macosx`. `mcpp::platform::xpkg_platform_key_for` is the one place that
+// knows, and `xpkg_platform` is the host in the same vocabulary — an earlier
+// draft of this section hand-rolled both, which is the second copy of a rule
+// this file exists to avoid.
 inline std::string_view host_platform_key() {
-    if constexpr (mcpp::platform::is_windows) return "windows";
-    else if constexpr (mcpp::platform::is_macos) return "macosx";
-    else return "linux";
+    return mcpp::platform::xpkg_platform;
 }
 
-// The three platforms a descriptor has a block for, in xlings' spelling.
-inline constexpr std::string_view kXlingsPlatforms[] = {"linux", "macosx", "windows"};
-
 // Split `<scope>:<rest>` on the FIRST colon. xlings writes a namespace this
 // way on a version (`"mcpp": "xim:2026.8.30.2"` in a real subos file) and mcpp
 // additionally accepts it on the key, so one splitter serves both halves.
@@ -148,15 +151,16 @@ platform_values(const mcpp::libs::toml::Value& v) {
         return std::unexpected(std::string(
             "expected a string or a { <platform> = \"...\" } table"));
     for (auto& [k, val] : v.as_table()) {
-        std::string canon = (k == "macos") ? "macosx" : k;
-        const bool known = canon == "default"
-            || std::ranges::find(kXlingsPlatforms, canon) != std::ranges::end(kXlingsPlatforms);
-        if (!known)
+        auto canon = k == "default"
+            ? std::optional<std::string_view>("default")
+            : mcpp::platform::xpkg_platform_key_for(k);
+        if (!canon)
             return std::unexpected(std::format(
-                "unknown platform key '{}'; expected one of linux, macosx, windows, default", k));
+                "unknown platform key '{}'; expected one of linux, macosx "
+                "(or macos), windows, default", k));
         if (!val.is_string())
             return std::unexpected(std::format("platform key '{}' must be a string", k));
-        out.emplace_back(std::move(canon), val.as_string());
+        out.emplace_back(std::string(*canon), val.as_string());
     }
     return out;
 }
@@ -166,9 +170,10 @@ platform_values(const mcpp::libs::toml::Value& v) {
 inline std::optional<std::string>
 value_for_platform(const std::vector<std::pair<std::string, std::string>>& vals,
                    std::string_view platform) {
-    // The alias is folded on BOTH sides: a caller may name the host `macos`
-    // (mcpp's spelling elsewhere) while the stored key is canonical.
-    const std::string_view want = (platform == "macos") ? "macosx" : platform;
+    // Folded on BOTH sides: a caller may name the host `macos` (mcpp's triple
+    // spelling) while the stored key is already canonical.
+    const std::string_view want =
+        mcpp::platform::xpkg_platform_key_for(platform).value_or(platform);
     auto pick = [&](std::string_view k) -> std::optional<std::string> {
         for (auto const& [key, v] : vals) if (key == k) return v;
         return std::nullopt;
@@ -1505,7 +1510,7 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
             // Every platform, for the descriptor emitter. Resolved per
             // platform rather than stored raw: the emitter wants the answer,
             // and `default` is part of producing it.
-            for (auto plat : kXlingsPlatforms) {
+            for (auto plat : mcpp::platform::xpkg_platforms) {
                 auto v = value_for_platform(*vals, plat);
                 if (!v) continue;
                 auto e = make_xlings_entry(k, *v);

modules/platform/src/axis.cppm

@@ -32,6 +32,25 @@ import mcpp.platform;
 
 export namespace mcpp::platform {
 
+// THE spelling rule, and the only one.
+//
+// One platform has two names: the triple vocabulary says `macos`, an xpkg
+// descriptor and xlings' own project file say `macosx`. Every place that has
+// to accept both — a target's `os` token, a `[xlings.workspace]` platform
+// table, a descriptor's per-OS section — asks here, so the alias cannot be
+// half-known. `nullopt` means the token names no platform at all, which the
+// caller decides how to treat: `for_os` falls back to the host, a manifest
+// parser reports it.
+inline std::optional<std::string_view> xpkg_platform_key_for(std::string_view os) {
+    if (os == "macos" || os == "macosx") return "macosx";
+    if (os == "windows")                 return "windows";
+    if (os == "linux")                   return "linux";
+    return std::nullopt;
+}
+
+// The three keys a descriptor has a block for, in that vocabulary.
+inline constexpr std::string_view xpkg_platforms[] = {"linux", "macosx", "windows"};
+
 // A resolved xpkg platform key. Only obtainable through one of the axis
 // types below, so possession of one implies somebody decided which axis it
 // came from.
@@ -66,12 +85,11 @@ public:
     // "macos" where xpkg descriptors say "macosx"; that translation lives
     // here so no caller has to remember it.
     static TargetPlatform for_os(std::string_view tripleOs) {
-        if (tripleOs == "macos" || tripleOs == "macosx") return TargetPlatform("macosx");
-        if (tripleOs == "windows")                       return TargetPlatform("windows");
-        if (tripleOs == "linux")                         return TargetPlatform("linux");
         // Unknown/absent os token: fall back to the host, which is what the
         // whole code base did unconditionally before #254.
-        return TargetPlatform(std::string(mcpp::platform::xpkg_platform));
+        return TargetPlatform(std::string(
+            xpkg_platform_key_for(tripleOs)
+                .value_or(mcpp::platform::xpkg_platform)));
     }
 
     // For tooling that walks platforms it is not running on and is not

tests/unit/test_manifest.cpp

@@ -4520,7 +4520,8 @@ deps = [{ linxu = "qemu-user-aarch64" }]
 )");
     ASSERT_FALSE(m.has_value());
     EXPECT_NE(m.error().message.find("linxu"), std::string::npos) << m.error().message;
-    EXPECT_NE(m.error().message.find("linux, macosx, windows, default"), std::string::npos)
+    EXPECT_NE(m.error().message.find("linux, macosx (or macos), windows, default"),
+              std::string::npos)
         << m.error().message;
     EXPECT_NE(m.error().message.find("deps[0]"), std::string::npos) << m.error().message;
 }
@@ -4706,3 +4707,37 @@ OPENBLAS_NUM_THREADS = "1"
     EXPECT_NE(m.error().message.find("[xlings.envs]"), std::string::npos)
         << m.error().message;
 }
+
+// `macos` and `macosx` are one platform under two vocabularies — mcpp's triple
+// says the first, a descriptor and xlings' project file say the second. The
+// rule lives in mcpp.platform.axis; this asserts the manifest reaches it,
+// on every host, by resolving explicitly rather than against this one.
+TEST(Manifest, XlingsWorkspaceAcceptsBothMacosSpellings) {
+    auto with_macos = mcpp::manifest::parse_string(R"(
+[package]
+name = "app"
+version = "0.1.0"
+[xlings.workspace]
+llvm = { macos = "20", default = "22" }
+)");
+    ASSERT_TRUE(with_macos.has_value()) << with_macos.error().format();
+    auto with_macosx = mcpp::manifest::parse_string(R"(
+[package]
+name = "app"
+version = "0.1.0"
+[xlings.workspace]
+llvm = { macosx = "20", default = "22" }
+)");
+    ASSERT_TRUE(with_macosx.has_value()) << with_macosx.error().format();
+    // Same platform, so the same per-platform declaration and the same
+    // host-resolved answer, whichever way it was written.
+    EXPECT_EQ(with_macos->xlings.workspaceByPlatform,
+              with_macosx->xlings.workspaceByPlatform);
+    EXPECT_EQ(with_macos->xlings.workspace, with_macosx->xlings.workspace);
+    EXPECT_NE(std::ranges::find(with_macos->xlings.workspaceByPlatform.at("macosx"),
+                                "llvm@20"),
+              with_macos->xlings.workspaceByPlatform.at("macosx").end());
+    EXPECT_NE(std::ranges::find(with_macos->xlings.workspaceByPlatform.at("linux"),
+                                "llvm@22"),
+              with_macos->xlings.workspaceByPlatform.at("linux").end());
+}