Merge branch 'feat/eight-t1' into feat/eight-reports

Author: speak-agent

docs/07-workspace.md

@@ -350,14 +350,28 @@ mcpp searches upward from the current directory; if it finds an `mcpp.toml` cont
 
 ### 5.3 The `-p, --package` Option
 
-`-p` works with `build`, `test`, `run`, and other commands to select the target member. Its value is either the last path segment of a member's directory name or the full relative path:
+`-p` works with `build`, `test`, `run`, and other commands to select the target
+member. Its value is resolved in one order, because the option names a
+*package*:
+
+1. a member's qualified name, `<namespace>.<name>` (only meaningful for a
+   member that declares a namespace);
+2. otherwise, a member's bare `package.name` — refused, naming every match, if
+   two or more members share it;
+3. otherwise, a member's path as written in `[workspace] members`, or its
+   directory's last segment (the historical spellings, kept as a fallback).
 
 ```bash
-mcpp build -p server        # matches apps/server
+mcpp build -p server        # matches apps/server (by directory or package name)
 mcpp test -p core           # matches libs/core
 mcpp run -p server -- --port 8080
 ```
 
+A value that is one member's package name and a different member's directory
+selects the member named by the package, with a warning naming the other one —
+the option promises a package, so an exact package-name match outranks a
+directory that merely happens to share the spelling.
+
 `--workspace` (on `build` and `test`) is the fan-out form: it acts on **every**
 member. `mcpp test --workspace` reports each member separately and continues past a
 failing member, exiting non-zero if any member failed — ideal as a single,

docs/specs/manifest-semantics.md

@@ -434,10 +434,15 @@ mcpp 2026.9.26.2,#703)。**
 ## 9. 工作空间继承与构建需求的作用域
 
 1. 工作空间成员**必须**恰好接收一次 `[workspace.package]`、`[workspace.build]` 与
-   `x.workspace = true` 条目的继承,无论它是命令构建的包、另一个成员的 `path` 依赖、
-   通过 `git` 引用的托管在 git 上的工作空间的成员,还是索引包归档内的成员(描述符的
-   `mcpp` 字段指向该成员的清单)。后两种情况按该成员所在仓库或归档的工作空间根继承,
-   相对路径以该根为锚点;在归档内查找工作空间根时**禁止**越出该版本的安装根。
+   `x.workspace = true` 条目的继承,无论它是命令构建的包、带 `[package]` 的工作空间根
+   自己的 `path` 依赖所到达的成员、另一个成员的 `path` 依赖、通过 `git` 引用的托管在
+   git 上的工作空间的成员,还是索引包归档内的成员(描述符的 `mcpp` 字段指向该成员的
+   清单)。后两种情况按该成员所在仓库或归档的工作空间根继承,相对路径以该根为锚点;
+   在归档内查找工作空间根时**禁止**越出该版本的安装根。工作空间的上下文(它是哪个
+   工作空间、工作空间根在哪里)取决于清单**在哪里**,与命令走的是哪条分支无关——带
+   `[package]` 的工作空间根按自身构建时,同样要在解析任何依赖之前建立这一上下文。
+   `-p`/`--package` 首先按成员的包身份(限定名 `<namespace>.<name>`,其次是裸包名)
+   为其命名,目录路径与目录名是回落拼法。
 2. 向量按工作空间、成员、命中的 `[target.<selector>.build]` 的顺序追加;`defines` 按
    §8 的集合语义合并。标量仅在成员未**声明**该键时取工作空间的值。
 3. 继承**必须**在 `defines` 展开之前、在清单被固定进构建图之前完成。实现**必须**拒绝

docs/zh/07-workspace.md

@@ -332,15 +332,23 @@ mcpp 从当前目录向上搜索；若发现某个 `mcpp.toml` 含 `[workspace]`
 
 ### 5.3 `-p, --package` 选项
 
-`-p` 可用于 `build`、`test`、`run` 等命令，指定目标成员。参数值可以是成员目录名
-的最后一段，也可以是完整相对路径：
+`-p` 可用于 `build`、`test`、`run` 等命令，指定目标成员。选项名说的是**包**，
+参数值按下述顺序解析：
+
+1. 成员的限定名 `<namespace>.<name>`（只有声明了 namespace 的成员才有这个拼法）；
+2. 否则，成员裸的 `package.name`——如果两个以上成员共享它，拒绝并点名每一个匹配；
+3. 否则，成员在 `[workspace] members` 里写的路径，或其目录名的最后一段（历史拼法，
+   作为回落保留）。
 
 ```bash
-mcpp build -p server        # matches apps/server
+mcpp build -p server        # matches apps/server（按目录或包名）
 mcpp test -p core           # matches libs/core
 mcpp run -p server -- --port 8080
 ```
 
+参数值若既是某个成员的包名，又是另一个成员的目录，选中包名所命名的那个成员，并给
+出警告点名另一个成员——选项名的是包，包名的精确匹配压过恰好同名的目录。
+
 `--workspace`（用于 `build` 与 `test`）是扇出形式：作用于**每个**成员。
 `mcpp test --workspace` 逐成员分别汇报，遇失败继续，只要有任一成员失败就非零
 退出——很适合作为"一个测试众多库的工作空间"单条、无需 shell 的 CI 步骤。

src/build/prepare/manifest.cpp

@@ -228,19 +228,14 @@ std::expected<void, std::string> phase0_manifest_and_workspace(PrepareState& sta
         std::string targetMember;
 
         if (!state.overrides.package_filter.empty()) {
-            // -p <name>: find matching member by directory basename or path
-            for (auto& mp : state.m->workspace.members) {
-                auto basename = std::filesystem::path(mp).filename().string();
-                if (basename == state.overrides.package_filter || mp == state.overrides.package_filter) {
-                    targetMember = mp;
-                    break;
-                }
-            }
-            if (targetMember.empty()) {
-                return std::unexpected(std::format(
-                    "workspace member '{}' not found in [workspace].members",
-                    state.overrides.package_filter));
-            }
+            // `-p <name>`: the package identity first, the member's
+            // directory as a fallback -- one resolver shared with every
+            // other `-p`/`--package` command
+            // (mcpp::project::resolve_member_dir, #725).
+            auto matched = mcpp::project::resolve_member_dir(
+                *state.m, *state.root, state.overrides.package_filter);
+            if (!matched) return std::unexpected(matched.error());
+            targetMember = matched->lexically_relative(*state.root).generic_string();
         } else if (state.m->package.name.empty()) {
             // Virtual workspace: find a member with a program target ("is
             // this the program", #622 A3's `is_program()`, so a member whose
@@ -265,8 +260,17 @@ std::expected<void, std::string> phase0_manifest_and_workspace(PrepareState& sta
         }
         // else: rooted workspace with [package] — build root normally. Its own
         // `x.workspace = true` entries name its own [workspace.dependencies].
-        else if (state.m->workspace.present)
+        // The workspace context is set here too (#725): it is a property of
+        // where the manifest lives, not of the branch that was taken, so a
+        // member this package reaches through its OWN `path` dependencies
+        // (`depIsMember`, graph.cpp) is recognised as a member and receives
+        // `[workspace.package]`, `[workspace.build]` and `x.workspace = true`
+        // the same way a sibling's `path` dependency does.
+        else if (state.m->workspace.present) {
+            state.runtimeWorkspaceRoot = *state.root;
+            state.wsManifest = *state.m;
             mcpp::project::merge_workspace_deps(*state.m, *state.m, *state.root);
+        }
 
         if (!targetMember.empty()) {
             auto memberDir = *state.root / targetMember;

src/cli.cppm

@@ -375,7 +375,7 @@ int run(int argc, char** argv) {
             .option(cl::Option("static").help(
                 "Force static linking (-static). On Linux, prefer pairing with --target <arch>-linux-musl"))
             .option(cl::Option("package").short_name('p').takes_value().value_name("NAME")
-                .help("Build only the named workspace member"))
+                .help("Build only the named workspace member (package name first, then directory)"))
             .option(cl::Option("profile").takes_value().value_name("NAME")
                 .help("Build profile: dev (default) | release | dist | <[profile.*] name>"))
             .option(cl::Option("release").help("Shorthand for --profile release"))
@@ -419,7 +419,7 @@ int run(int argc, char** argv) {
             .option(cl::Option("target-triple").takes_value().value_name("TRIPLE")
                 .help("Alias for --target"))
             .option(cl::Option("package").short_name('p').takes_value().value_name("NAME")
-                .help("Run only the named workspace member (single-member; no --workspace fan-out)"))
+                .help("Run only the named workspace member (package name first, then directory; single-member, no --workspace fan-out)"))
             // DECLARED ON THE THREE COMMANDS THAT BUILD BEFORE THEY ACT, AS ON
             // `build`. The value has always reached them: the pre-parse loop
             // above publishes it as MCPP_TOOLCHAIN for every command, and
@@ -519,7 +519,7 @@ int run(int argc, char** argv) {
             .option(cl::Option("strict")
                 .help("Treat manifest schema warnings (unknown feature/platform) as errors"))
             .option(cl::Option("package").short_name('p').takes_value().value_name("NAME")
-                .help("Run tests only for the named workspace member"))
+                .help("Run tests only for the named workspace member (package name first, then directory)"))
             .option(cl::Option("toolchain").takes_value().value_name("SPEC")
                 .help("Build the tests with this toolchain for one invocation, e.g. llvm@22.1.8"))
             .option(cl::Option("cache").takes_value().value_name("MODE")
@@ -684,7 +684,7 @@ int run(int argc, char** argv) {
                     .help("Describe the variant built for no accelerator"))
                 .option(cl::Option("static").help("Describe the build with --static"))
                 .option(cl::Option("package").short_name('p').takes_value().value_name("NAME")
-                    .help("Describe only the named workspace member"))
+                    .help("Describe only the named workspace member (package name first, then directory)"))
                 .option(cl::Option("profile").takes_value().value_name("NAME")
                     .help("Build profile: dev (default) | release | dist | <[profile.*] name>"))
                 .option(cl::Option("release").help("Shorthand for --profile release"))

src/project.cppm

@@ -12,6 +12,7 @@ export module mcpp.project;
 
 import std;
 import mcpp.manifest;
+import mcpp.ui;
 
 namespace mcpp::project {
 
@@ -468,35 +469,166 @@ load_effective_manifest(const std::filesystem::path& dir) {
     return EffectiveManifest{ std::move(*m), std::move(*ws), wsRoot, true };
 }
 
+// One declared workspace member, with the identity its own manifest states.
+//
+// #725: `-p, --package <NAME>` promises a package (SPEC-001's `(namespace,
+// name)`), so resolving it needs each member's OWN declaration, not only the
+// directory `[workspace] members` names it with.
+export struct WorkspaceMember {
+    std::string            memberPath;  // as written in [workspace] members
+    std::filesystem::path  dir;         // rootDir / memberPath
+    std::string            namespace_;  // "" when undeclared, or unreadable
+    std::string            name;        // "" when the manifest could not be
+                                        // read -- such a member still matches
+                                        // by directory or path (step 3 below)
+};
+
+// A member's qualified name the way SPEC-001 spells one: `<namespace>.<name>`.
+// Meaningless (and not attempted by the resolver below) when the member
+// declares no namespace -- SPEC-001 §3.1: an unnamespaced package's bare name
+// already IS its full identity, so there is no separate dotted spelling to
+// match against.
+export std::string qualified_member_name(const WorkspaceMember& m) {
+    return m.namespace_.empty() ? m.name : m.namespace_ + "." + m.name;
+}
+
+// Every declared member, with its own package identity. Loaded the way a
+// member is always loaded (`insideWorkspace = true`, so an omitted
+// `package.version` is not refused here); a member whose manifest fails to
+// parse keeps an empty name rather than aborting the listing, because `-p`
+// still owes an answer about the members that DO parse.
+export std::vector<WorkspaceMember>
+workspace_members(const mcpp::manifest::Manifest& rootManifest,
+                  const std::filesystem::path& rootDir) {
+    std::vector<WorkspaceMember> out;
+    out.reserve(rootManifest.workspace.members.size());
+    for (auto& mp : rootManifest.workspace.members) {
+        WorkspaceMember wm;
+        wm.memberPath = mp;
+        wm.dir = rootDir / mp;
+        if (auto mm = mcpp::manifest::load(wm.dir / "mcpp.toml", {.insideWorkspace = true})) {
+            wm.namespace_ = mm->package.namespace_;
+            wm.name       = mm->package.name;
+        }
+        out.push_back(std::move(wm));
+    }
+    return out;
+}
+
 // Resolve which member directory a workspace command acts on, for the
-// single-member case. Shares the match rule (basename OR member path) with
-// prepare_build's member switch, so `build -p X` and `test -p X` agree.
+// single-member case. Shared by every `-p`/`--package` reader (build, test,
+// run, emit, and prepare_build's own root-level switch, #725), so
+// `build -p X` and `test -p X` always agree on what X means.
+//
+// A value is resolved in this order, because the option names a package
+// (SPEC-001) and a directory is a fallback spelling docs/07 §5.3 has always
+// documented:
+//   1. a member's qualified name, `<namespace>.<name>` (only attempted for a
+//      member that declares a namespace -- see `qualified_member_name`);
+//   2. otherwise, a member's bare package name -- refused, naming every
+//      match's qualified name, when two or more members share it;
+//   3. otherwise, a member's path as written in `[workspace] members`, or its
+//      directory's last segment. Two members sharing a directory basename
+//      keep today's first-match selection (a script written against it keeps
+//      working), with a warning naming the others and their paths.
+// A value that is one member's package name (step 2) and a different
+// member's directory (step 3) selects the step-2 member, with a warning
+// naming the other member and its path.
+//
 // Returns:
 //   - the member dir   when `package_filter` names a member,
 //   - empty path       when no switch applies (not a workspace, or a rooted
 //                      workspace with no filter → act on the root package),
-//   - error            when the filter names an unknown member, or a *virtual*
-//                      workspace is addressed with no filter (the caller must
-//                      pick a member with -p or fan out with --workspace).
+//   - error            when the filter names no member, names more than one,
+//                      or a *virtual* workspace is addressed with no filter
+//                      (the caller must pick a member with -p or fan out with
+//                      --workspace).
 export std::expected<std::filesystem::path, std::string>
 resolve_member_dir(const mcpp::manifest::Manifest& rootManifest,
                    const std::filesystem::path& rootDir,
                    std::string_view package_filter) {
     if (!rootManifest.workspace.present) return std::filesystem::path{};
-    if (!package_filter.empty()) {
-        for (auto& mp : rootManifest.workspace.members) {
-            auto basename = std::filesystem::path(mp).filename().string();
-            if (basename == package_filter || mp == package_filter)
-                return rootDir / mp;
+    if (package_filter.empty()) {
+        if (rootManifest.package.name.empty()) {
+            return std::unexpected(std::string(
+                "virtual workspace: specify -p <member> or --workspace"));
         }
+        return std::filesystem::path{};  // rooted workspace, no filter → root
+    }
+
+    auto members = workspace_members(rootManifest, rootDir);
+
+    // Step 1: the qualified name. Unique by construction (SPEC-001 §3.3 asks
+    // a single index to keep `(namespace, name)` unique; two workspace
+    // members sharing one is a manifest defect this resolver does not
+    // adjudicate), so the first hit is taken without a warning.
+    for (auto const& m : members)
+        if (!m.namespace_.empty() && qualified_member_name(m) == package_filter)
+            return m.dir;
+
+    // Step 2: the bare package name, ignoring namespace.
+    std::vector<std::size_t> byName;
+    for (std::size_t i = 0; i < members.size(); ++i)
+        if (!members[i].name.empty() && members[i].name == package_filter)
+            byName.push_back(i);
+    if (byName.size() > 1) {
+        std::string names;
+        for (auto i : byName)
+            names += (names.empty() ? "" : ", ") + qualified_member_name(members[i]);
         return std::unexpected(std::format(
-            "workspace member '{}' not found in [workspace].members", package_filter));
+            "-p '{}' is ambiguous: it is the package name of {} members ({}). "
+            "Write the qualified name (<namespace>.<name>) to select one.",
+            package_filter, byName.size(), names));
+    }
+
+    // Step 3: the directory path or basename `[workspace] members` writes.
+    std::vector<std::size_t> byPath;
+    for (std::size_t i = 0; i < members.size(); ++i) {
+        auto basename = members[i].dir.filename().string();
+        if (basename == package_filter || members[i].memberPath == package_filter)
+            byPath.push_back(i);
+    }
+
+    if (byName.size() == 1) {
+        const auto& picked = members[byName.front()];
+        if (!byPath.empty() && byPath.front() != byName.front()) {
+            const auto& other = members[byPath.front()];
+            mcpp::ui::warning(std::format(
+                "-p '{}' is the package name of member '{}' ({}) and also the "
+                "directory of member '{}' ({}); the package is selected. Write "
+                "'{}' to select the other member.",
+                package_filter, picked.memberPath, qualified_member_name(picked),
+                other.memberPath, qualified_member_name(other), other.memberPath));
+        }
+        return picked.dir;
+    }
+
+    if (!byPath.empty()) {
+        if (byPath.size() > 1) {
+            std::string others;
+            for (std::size_t k = 1; k < byPath.size(); ++k)
+                others += std::format("{}'{}'", others.empty() ? "" : ", ",
+                                      members[byPath[k]].memberPath);
+            mcpp::ui::warning(std::format(
+                "-p '{}' matches more than one member's directory; '{}' is "
+                "selected (the first listed in [workspace] members). Also "
+                "matched: {}.",
+                package_filter, members[byPath.front()].memberPath, others));
+        }
+        return members[byPath.front()].dir;
     }
-    if (rootManifest.package.name.empty()) {
-        return std::unexpected(std::string(
-            "virtual workspace: specify -p <member> or --workspace"));
+
+    std::string list;
+    for (auto const& m : members) {
+        auto label = m.name.empty() ? std::string("?")
+                   : (m.namespace_.empty() ? m.name
+                                            : std::format("{} ({})", m.name,
+                                                          qualified_member_name(m)));
+        list += std::format("\n  {} at '{}'", label, m.memberPath);
     }
-    return std::filesystem::path{};  // rooted workspace, no filter → root package
+    return std::unexpected(std::format(
+        "workspace member '{}' not found. [workspace] members:{}",
+        package_filter, list));
 }
 
 } // namespace mcpp::project