refactor: 边图查询收敛成 mcpp.build.dep_graph,而不是再手写一遍

自审时发现的问题,而且正是本 PR 通篇在反对的那个模式:我给 tool store 的 upstream
key **手写了一遍图遍历**,而 prepare.cppm 里**已经有**一个走同一张边图的递归遍历
(`self(self, …)`,构建缓存的 per-package key),带 memo 和环检测 —— 我那份是它的
一个更弱的副本。

核实后:`dependencyEdges` 有 14 处读者,其中大多数问的是同两个问题 ——「X 直接依赖
谁」和「X 的传递闭包」。两个 build.mcpp 调用点(发 `MCPP_DEP_<NAME>_DIR` 的那两处)
已经漂成了近乎逐字重复的两份,而 #355 正要再加第三个变体。

新增 `src/build/dep_graph.cppm`:
- `direct_dependencies` / `transitive_dependencies`(按边类型模板化 ——
  `DependencyEdge` 是 prepare_build 里的局部结构体,把它搬出来的代价远大于这次要
  还的债)
- `name_spellings`:一个依赖可被寻址的两种拼写(canonical 与去 namespace 的尾段)。
  不是图查询,但放这里理由相同:三处各自展开过同一个 rfind 分割,第四处正要出现。

**刻意不迁移**构建缓存那条递归 fold:它不是闭包查询 —— 它对每个节点算一个值(该包
完整的 cache key)、把环当**硬错误**而不是跳过、还顺带穿了一个 taint 标记。把它塞进
通用遍历要么丢掉这些性质,要么让抽象一路长到只描述一个调用者。**回答不同问题的两次
遍历不是重复。**

验证:单测 57/57;125/145(正是覆盖 MCPP_DEP_*_DIR 的两个)与 111/186/187/188/189
全通过。

Author: speak-agent

src/build/dep_graph.cppm

@@ -0,0 +1,98 @@
+// mcpp.build.dep_graph — queries over the resolved consumer→dependency edge
+// graph.
+//
+// WHY THIS EXISTS
+//
+// prepare.cppm records one authoritative edge graph during resolution, and by
+// now fourteen places read it. Most ask one of exactly two questions —
+// "what does package X depend on directly?" and "what is X's transitive
+// closure?" — and each had hand-written the loop. Two of them (the two
+// build.mcpp call sites emitting MCPP_DEP_<NAME>_DIR) were near-identical
+// copies, and #355 added a third variant plus a hand-rolled BFS.
+//
+// That is the shape this codebase keeps paying for (#233/#240/#242/#344): the
+// same decision derived in N places does not fail when you add the N+1th, it
+// fails later, somewhere else. Feature activation already learned it the hard
+// way — activation and resolution each walked their own idea of "the edges"
+// and silently disagreed about transitive requests (#242/#243).
+//
+// Templated on the edge type rather than owning it: `DependencyEdge` is a
+// local struct inside prepare_build, and moving it out would be a much larger
+// change than the one this pays for. An edge only has to expose
+// `consumerPackageIndex` and `dependencyPackageIndex`.
+//
+// WHAT IS DELIBERATELY *NOT* HERE
+//
+// The build cache's per-package key walk (prepare.cppm, `self(self, …)`) is
+// NOT a closure query and is not migrated. It is a memoized fold that computes
+// a value per node (that package's full cache key), treats a cycle as a hard
+// ERROR rather than something to skip, and threads a taint flag alongside.
+// Folding it into a generic traversal would either lose those properties or
+// force the abstraction to grow until it described exactly one caller. Two
+// walks that answer genuinely different questions are not duplication.
+
+export module mcpp.build.dep_graph;
+
+import std;
+
+export namespace mcpp::build::dep_graph {
+
+// Package indices this consumer depends on DIRECTLY, in edge-record order,
+// deduplicated. Order is preserved because several callers surface it to the
+// user (dependency dirs, diagnostics) and a stable order keeps output
+// diffable.
+template <class Edge>
+std::vector<std::size_t>
+direct_dependencies(const std::vector<Edge>& edges, std::size_t consumer) {
+    std::vector<std::size_t> out;
+    for (auto const& e : edges) {
+        if (e.consumerPackageIndex != consumer) continue;
+        if (std::find(out.begin(), out.end(), e.dependencyPackageIndex) == out.end())
+            out.push_back(e.dependencyPackageIndex);
+    }
+    return out;
+}
+
+// Every package reachable from `from`, excluding `from` itself. Sorted and
+// deduplicated, so a caller folding it into a cache key gets a stable answer
+// without re-sorting.
+//
+// A cycle is TOLERATED here (the visited set terminates it) rather than
+// reported. This is a reachability question, and the callers that must reject
+// a cycle — the build-cache key walk — detect it where they can say which
+// package the cycle runs through, which is the only form of that message worth
+// printing.
+template <class Edge>
+std::vector<std::size_t>
+transitive_dependencies(const std::vector<Edge>& edges, std::size_t from) {
+    std::set<std::size_t> seen;
+    std::vector<std::size_t> stack{from};
+    while (!stack.empty()) {
+        auto cur = stack.back();
+        stack.pop_back();
+        for (auto const& e : edges) {
+            if (e.consumerPackageIndex != cur) continue;
+            if (!seen.insert(e.dependencyPackageIndex).second) continue;
+            stack.push_back(e.dependencyPackageIndex);
+        }
+    }
+    seen.erase(from);
+    return {seen.begin(), seen.end()};
+}
+
+// The two spellings a dependency is addressable by: its canonical package name
+// and, when it is namespaced, the namespace-stripped tail.
+//
+// Not a graph query, but it lives here for the same reason: three call sites
+// had each open-coded the `rfind('.')` split, and a fourth was about to. A
+// consumer may write `compat.zlib` or `zlib`, and every place that surfaces a
+// dependency by name has to accept both.
+inline std::vector<std::string> name_spellings(const std::string& canonical) {
+    std::vector<std::string> out{canonical};
+    if (auto dot = canonical.rfind('.');
+        dot != std::string::npos && dot + 1 < canonical.size())
+        out.push_back(canonical.substr(dot + 1));
+    return out;
+}
+
+} // namespace mcpp::build::dep_graph

src/build/prepare.cppm

@@ -35,6 +35,7 @@ import mcpp.build.cache_key;
 import mcpp.build.build_program;
 import mcpp.build.directives;   // directive table: mark / fold_private_tail
 import mcpp.build.tool_store;   // #355 host tools: store layout + key + overrides
+import mcpp.build.dep_graph;    // queries over the resolved edge graph
 import mcpp.build.backend;      // BuildOptions for the tool sub-build
 import mcpp.build.ninja;        // make_ninja_backend — driving that sub-build
 import mcpp.lockfile;
@@ -2613,6 +2614,7 @@ prepare_build(bool print_fingerprint,
         std::vector<std::string> requestedTools;
     };
     std::vector<DependencyEdge> dependencyEdges;
+    namespace dg = mcpp::build::dep_graph;
     // #355: consumer package index → (env var, absolute path) for each host
     // tool that consumer requested. Filled by the provisioning pass below;
     // read by BOTH build.mcpp call sites (the dependency loop and the root),
@@ -2681,6 +2683,22 @@ prepare_build(bool print_fingerprint,
         mcpp::build::directives::fold_private_tail(pkg.privateBuild, ran, t);
     };
 
+    // mcpp#241: the (name → dir) pairs a package's build.mcpp receives as
+    // MCPP_DEP_<NAME>_DIR. ONE owner: the dependency loop and the root call
+    // site had drifted into two near-identical copies of this, and #355 was
+    // about to add a third. Each dependency is emitted under BOTH its
+    // canonical name and its namespace-stripped tail, so
+    // `mcpp::dep_dir("compat.zlib")` and `mcpp::dep_dir("zlib")` both resolve
+    // regardless of which spelling the author used in `deps`.
+    auto fillDepDirs = [&](mcpp::build::BuildProgramEnv& e, std::size_t consumer) {
+        for (auto d : dg::direct_dependencies(dependencyEdges, consumer)) {
+            auto const& depPkg = packages[d];
+            for (auto const& spelling :
+                     dg::name_spellings(depPkg.manifest.package.name))
+                e.depDirs.emplace_back(spelling, depPkg.root);
+        }
+    };
+
     // A declared build-graph node's Source outputs must be visible to the
     // scan, so they are materialized as placeholders and joined to the source
     // set here — the same two lists `generated=` feeds, for the same reason
@@ -3931,12 +3949,16 @@ prepare_build(bool print_fingerprint,
             // construction rather than by luck.
             for (auto const& [depName, spec] : m->dependencies) {
                 if (!spec.hostModule) continue;
-                for (auto const& edge : dependencyEdges) {
-                    if (edge.consumerPackageIndex != 0) continue;
-                    auto const& depPkg = packages[edge.dependencyPackageIndex];
+                for (auto d : dg::direct_dependencies(dependencyEdges, 0)) {
+                    auto const& depPkg = packages[d];
                     auto const& canon = depPkg.manifest.package.name;
-                    if (canon != depName && !depName.ends_with(canon)
-                        && !canon.ends_with(depName)) continue;
+                    // Match on either spelling, the same way `deps` keys and
+                    // MCPP_DEP_<NAME>_DIR do — a consumer may have written
+                    // `compat.zlib` or `zlib`.
+                    bool hit = false;
+                    for (auto const& s : dg::name_spellings(canon))
+                        if (depName == s || depName.ends_with("." + s)) hit = true;
+                    if (!hit) continue;
                     auto rel = mcpp::manifest::resolve_lib_root_path(depPkg.manifest);
                     hostModulesByConsumer[0].emplace_back(canon, depPkg.root / rel);
                     break;
@@ -4043,26 +4065,11 @@ prepare_build(bool print_fingerprint,
                     // packages (a frozen version cannot change its own deps),
                     // but a path dependency can: bump something two levels down
                     // and the tool's direct list is unchanged, so a stale binary
-                    // stays in the store. That is a silently wrong artifact —
-                    // the failure mode this project has paid for more than once
-                    // — and the closure walk costs nothing.
-                    {
-                        std::set<std::size_t> seen{depIdx};
-                        std::vector<std::size_t> queue{depIdx};
-                        while (!queue.empty()) {
-                            auto cur = queue.back();
-                            queue.pop_back();
-                            for (auto const& edge : dependencyEdges) {
-                                if (edge.consumerPackageIndex != cur) continue;
-                                auto up = edge.dependencyPackageIndex;
-                                if (!seen.insert(up).second) continue;
-                                queue.push_back(up);
-                                key.upstreamKeys.push_back(std::format("{}@{}",
-                                    packages[up].manifest.package.name,
-                                    packages[up].manifest.package.version));
-                            }
-                        }
-                    }
+                    // stays in the store — a silently wrong artifact.
+                    for (auto up : dg::transitive_dependencies(dependencyEdges, depIdx))
+                        key.upstreamKeys.push_back(std::format("{}@{}",
+                            packages[up].manifest.package.name,
+                            packages[up].manifest.package.version));
                     std::ranges::sort(key.upstreamKeys);
 
                     const auto cacheRoot = mcpp::home::cache_root();
@@ -4211,25 +4218,12 @@ prepare_build(bool print_fingerprint,
             bpEnv.artifactsDir = workRoot / "target" / ".build-mcpp" / "deps"
                 / (dirSafe(pkg.manifest.package.name) + "@" + pkg.manifest.package.version);
             bpEnv.genBase      = bpEnv.artifactsDir / "out";
-            // mcpp#241: expose this package's resolved dependencies (verdir /
-            // payload root) as MCPP_DEP_<NAME>_DIR. Uses the authoritative
-            // consumer→dep edge graph (no name-guessing); covers feature-
-            // activated deps too (mergeActiveFeatureDeps folded them into
-            // `dependencies` before the edges were recorded). A dep is emitted
-            // under BOTH its canonical package name AND its namespace-stripped
-            // short name, so `mcpp::dep_dir("compat.zlib")` and
-            // `mcpp::dep_dir("zlib")` both resolve regardless of which spelling
-            // the author used in `deps`. (The ROOT project's build.mcpp gets
-            // the same treatment at its own call site right after this loop.)
-            for (auto const& edge : dependencyEdges) {
-                if (edge.consumerPackageIndex != i) continue;
-                auto const& depPkg = packages[edge.dependencyPackageIndex];
-                const auto& canon = depPkg.manifest.package.name;
-                bpEnv.depDirs.emplace_back(canon, depPkg.root);
-                if (auto dot = canon.rfind('.'); dot != std::string::npos
-                        && dot + 1 < canon.size())
-                    bpEnv.depDirs.emplace_back(canon.substr(dot + 1), depPkg.root);
-            }
+            // mcpp#241: this package's resolved dependencies as
+            // MCPP_DEP_<NAME>_DIR, from the authoritative edge graph (no
+            // name-guessing); covers feature-activated deps too
+            // (mergeActiveFeatureDeps folded them in before the edges were
+            // recorded). Shared owner — see fillDepDirs.
+            fillDepDirs(bpEnv, i);
             // #355: the host tools THIS package requested (resolved above).
             if (auto tit = toolEnvByConsumer.find(i); tit != toolEnvByConsumer.end())
                 bpEnv.toolPaths = tit->second;
@@ -4361,18 +4355,8 @@ prepare_build(bool print_fingerprint,
         // contract hash — and therefore the build.mcpp cache — is unchanged
         // across the move for feature-identical builds.
         bpEnv.features     = feature_closure(*m, parse_feature_request(overrides.features));
-        // mcpp#241 (root): the root's resolved direct deps, from the same
-        // authoritative edge graph as the dep loop (consumer index 0 = root),
-        // emitted under canonical AND namespace-stripped names.
-        for (auto const& edge : dependencyEdges) {
-            if (edge.consumerPackageIndex != 0) continue;
-            auto const& depPkg = packages[edge.dependencyPackageIndex];
-            const auto& canon = depPkg.manifest.package.name;
-            bpEnv.depDirs.emplace_back(canon, depPkg.root);
-            if (auto dot = canon.rfind('.'); dot != std::string::npos
-                    && dot + 1 < canon.size())
-                bpEnv.depDirs.emplace_back(canon.substr(dot + 1), depPkg.root);
-        }
+        // mcpp#241 (root): consumer index 0, same owner as the dep loop.
+        fillDepDirs(bpEnv, 0);
         // #355: the host tools the ROOT package requested (consumer index 0).
         if (auto tit = toolEnvByConsumer.find(0u); tit != toolEnvByConsumer.end())
             bpEnv.toolPaths = tit->second;