feat: use mcpp.lock commit as offline anchor for git deps

ZheFeng7110 · ZheFeng7110 · commit c3e709543dfe · 2026-08-01T17:36:55.000+08:00
- Add LockedGitSource + parse_git_source to lock_io.cppm. - Load mcpp.lock in prepare_build and use recorded branch commit to skip git ls-remote when the local cache still matches. - For tag/rev, reuse cached clone and fail early in --offline when missing. - Update e2e test 24 to assert branch deps do not re-ls-remote on rebuild. - Add unit tests for git source parsing. Closes #329
diff --git a/src/build/prepare.cppm b/src/build/prepare.cppm
@@ -46,6 +46,7 @@ import mcpp.pm.index_refresh;
 import mcpp.pm.mangle;
 import mcpp.pm.compat;
 import mcpp.pm.dep_spec;
+import mcpp.pm.lock_io;
 import mcpp.version_req;
 import mcpp.ui;
 import mcpp.log;
@@ -838,6 +839,26 @@ prepare_build(bool print_fingerprint,
         mcpp::diag::warning("manifest/schema", w);
     }
 
+    // Load mcpp.lock once. Git-based deps can use it as an offline anchor:
+    // if a branch is already resolved to a commit and the local cache matches,
+    // no network round-trip is needed.
+    std::map<std::string, mcpp::pm::LockedGitSource> gitLockAnchors;
+    {
+        auto lockPath = *root / "mcpp.lock";
+        if (std::filesystem::exists(lockPath)) {
+            if (auto lock = mcpp::lockfile::load(lockPath); lock) {
+                for (auto const& p : lock->packages) {
+                    if (auto parsed = mcpp::pm::parse_git_source(p.source); parsed) {
+                        gitLockAnchors.emplace(p.name, std::move(*parsed));
+                    }
+                }
+            } else {
+                mcpp::diag::warning("lockfile",
+                    std::format("ignoring mcpp.lock: {}", lock.error().message));
+            }
+        }
+    }
+
     // Global-cache mode: --cache > MCPP_BUILD_CACHE > [build] cache > global.
     // An unparseable value is a warning (error under --strict) and falls
     // through to the next source rather than silently meaning "global" — a typo
@@ -2987,24 +3008,102 @@ prepare_build(bool print_fingerprint,
             // them to a commit before forming the cache key; this lets
             // `mcpp update <dep>` pick up a moved branch without deleting
             // unrelated git caches.
+            //
+            // mcpp.lock acts as an offline anchor: if a branch is already
+            // resolved to a commit and the local cache still matches it,
+            // we skip the network round-trip entirely.
             auto mcppHome = mcpp::home::root();   // single resolver (#311)
             std::string resolvedGitRev = spec.gitRev;
+            bool skipLsRemote = false;
+
+            // Look up an offline anchor for this git dep.
+            std::optional<std::string> lockedCommit;
+            if (auto it = gitLockAnchors.find(name); it != gitLockAnchors.end()) {
+                auto const& anchor = it->second;
+                if (anchor.refKind == spec.gitRefKind && anchor.ref == spec.gitRev) {
+                    lockedCommit = anchor.resolvedCommit;
+                }
+            }
+
+            auto computeGitRoot = [&](const std::string& rev) {
+                std::hash<std::string> H;
+                auto urlHash = std::format("{:016x}",
+                    H(spec.git + "|" + spec.gitRefKind + "|" + spec.gitRev
+                      + "|" + rev));
+                return mcppHome / "git" / urlHash;
+            };
+
+            auto readCacheHead = [&](const std::filesystem::path& gitRoot)
+                -> std::string
+            {
+                auto cmd = std::format("git -C {} rev-parse HEAD 2>&1",
+                    mcpp::platform::shell::quote(gitRoot.string()));
+                auto r = mcpp::platform::process::capture(cmd);
+                if (r.exit_code != 0) return {};
+                std::string head = r.output;
+                head.erase(head.find_last_not_of(" \r\n\t") + 1);
+                return head;
+            };
+
             if (spec.gitRefKind == "branch") {
                 auto ref = std::format("refs/heads/{}", spec.gitRev);
-                auto cmd = std::format(
-                    "git ls-remote {} {} 2>&1",
-                    mcpp::platform::shell::quote(spec.git),
-                    mcpp::platform::shell::quote(ref));
-                auto r = mcpp::platform::process::capture(cmd);
-                if (r.exit_code != 0) {
-                    return std::unexpected(std::format(
-                        "git ls-remote of '{}' failed:\n{}", spec.git, r.output));
+                if (lockedCommit && !lockedCommit->empty()) {
+                    resolvedGitRev = *lockedCommit;
+                    auto gitRoot = computeGitRoot(resolvedGitRev);
+                    if (std::filesystem::exists(gitRoot / ".git") &&
+                        readCacheHead(gitRoot) == resolvedGitRev) {
+                        skipLsRemote = true;
+                        mcpp::ui::info("Resolved",
+                            std::format("{} ({} = {}) from lock",
+                                spec.git, spec.gitRefKind, spec.gitRev));
+                    }
+                }
+                if (!skipLsRemote) {
+                    if (mcpp::platform::env::offline_mode()) {
+                        if (lockedCommit) {
+                            return std::unexpected(std::format(
+                                "git dep '{}' locked to commit {} but its local cache is missing or stale; "
+                                "run without --offline to refresh, or `mcpp update {}` to re-resolve",
+                                name, *lockedCommit, name));
+                        } else {
+                            return std::unexpected(std::format(
+                                "git dep '{}' uses branch '{}' and mcpp.lock has no commit; "
+                                "cannot resolve offline. Run `mcpp update {}` or build without --offline.",
+                                name, spec.gitRev, name));
+                        }
+                    }
+                    auto cmd = std::format(
+                        "git ls-remote {} {} 2>&1",
+                        mcpp::platform::shell::quote(spec.git),
+                        mcpp::platform::shell::quote(ref));
+                    auto r = mcpp::platform::process::capture(cmd);
+                    if (r.exit_code != 0) {
+                        return std::unexpected(std::format(
+                            "git ls-remote of '{}' failed:\n{}", spec.git, r.output));
+                    }
+                    std::istringstream is(r.output);
+                    is >> resolvedGitRev;
+                    if (resolvedGitRev.empty()) {
+                        return std::unexpected(std::format(
+                            "git branch '{}' not found in '{}'", spec.gitRev, spec.git));
+                    }
+                }
+            } else {
+                // tag/rev: the declared ref is already a stable identity.
+                // If the lock already recorded this dep and the clone is present,
+                // we still use it; otherwise fall through to clone.
+                auto gitRoot = computeGitRoot(resolvedGitRev);
+                if (std::filesystem::exists(gitRoot / ".git")) {
+                    mcpp::ui::info("Resolved",
+                        std::format("{} ({} = {}) from cache",
+                            spec.git, spec.gitRefKind, spec.gitRev));
                 }
-                std::istringstream is(r.output);
-                is >> resolvedGitRev;
-                if (resolvedGitRev.empty()) {
+                if (!std::filesystem::exists(gitRoot / ".git") &&
+                    mcpp::platform::env::offline_mode()) {
                     return std::unexpected(std::format(
-                        "git branch '{}' not found in '{}'", spec.gitRev, spec.git));
+                        "git dep '{}' is locked but its local cache is missing; "
+                        "run without --offline to clone, or `mcpp update {}` to re-resolve.",
+                        name, name));
                 }
             }
 
diff --git a/src/pm/lock_io.cppm b/src/pm/lock_io.cppm
@@ -33,6 +33,22 @@ struct LockedPackage {
     std::string hash;       // "sha256:..." or "fnv1a:..."
 };
 
+// Parsed form of a git source string as written to mcpp.lock.
+// Supported forms:
+//   git+https://host/repo#branch=develop@5848943...
+//   git+https://host/repo#tag=v1.0.0
+//   git+https://host/repo#rev=5848943...
+// The resolvedCommit field is optional because old lock entries or
+// tag/rev sources may not carry a resolved commit.
+struct LockedGitSource {
+    std::string url;
+    std::string refKind;                       // "branch", "tag", or "rev"
+    std::string ref;
+    std::optional<std::string> resolvedCommit; // for branch entries with @commit
+};
+
+std::optional<LockedGitSource> parse_git_source(std::string_view source);
+
 struct Lockfile {
     int                                 schemaVersion = 2;
     std::vector<LockedIndex>            indices;
@@ -159,4 +175,37 @@ std::string compute_hash(const Lockfile& lock) {
     return std::format("{:016x}", h);
 }
 
+std::optional<LockedGitSource> parse_git_source(std::string_view source) {
+    constexpr std::string_view prefix = "git+";
+    if (!source.starts_with(prefix)) return std::nullopt;
+
+    auto rest = source.substr(prefix.size());
+    auto hashPos = rest.find('#');
+    if (hashPos == std::string_view::npos) return std::nullopt;
+
+    LockedGitSource out;
+    out.url = std::string(rest.substr(0, hashPos));
+    auto fragment = rest.substr(hashPos + 1);
+
+    // fragment is one of: branch=develop@commit, tag=v1.0.0, rev=abc123
+    auto eqPos = fragment.find('=');
+    if (eqPos == std::string_view::npos) return std::nullopt;
+
+    out.refKind = std::string(fragment.substr(0, eqPos));
+    if (out.refKind != "branch" && out.refKind != "tag" && out.refKind != "rev")
+        return std::nullopt;
+
+    auto refPart = fragment.substr(eqPos + 1);
+    auto atPos = refPart.find('@');
+    if (atPos == std::string_view::npos) {
+        out.ref = std::string(refPart);
+    } else {
+        out.ref = std::string(refPart.substr(0, atPos));
+        out.resolvedCommit = std::string(refPart.substr(atPos + 1));
+    }
+
+    if (out.ref.empty()) return std::nullopt;
+    return out;
+}
+
 } // namespace mcpp::pm
diff --git a/tests/e2e/24_git_dependency.sh b/tests/e2e/24_git_dependency.sh
@@ -153,6 +153,11 @@ out=$(${triple}${fp_dir}/bin/branchapp)
     echo "FAIL: branch dep v1 not invoked: $out"
     cat branch-v1.log; exit 1; }
 
+# Second build with the lock in place must not hit the network for ls-remote.
+build2=$("$MCPP" build 2>&1)
+echo "$build2" | grep -q 'ls-remote' && { echo "FAIL: branch dep re-ls-remoted on rebuild"; exit 1; } || true
+echo "$build2" | grep -q 'Cloning' && { echo "FAIL: branch dep re-cloned on rebuild"; exit 1; } || true
+
 grep -q 'source  = "git+' mcpp.lock || {
     echo "FAIL: git dep lock source is not marked as git"
     cat mcpp.lock; exit 1; }
diff --git a/tests/unit/test_pm_lock_io.cpp b/tests/unit/test_pm_lock_io.cpp
@@ -0,0 +1,56 @@
+#include <gtest/gtest.h>
+
+import std;
+import mcpp.pm.lock_io;
+
+TEST(PmLockIo, ParseGitBranchWithCommit) {
+    auto parsed = mcpp::pm::parse_git_source(
+        "git+https://github.com/user/repo#branch=develop@584894315b7a4fe4d7957d3c29dc4052b8012860");
+    ASSERT_TRUE(parsed.has_value());
+    EXPECT_EQ(parsed->url, "https://github.com/user/repo");
+    EXPECT_EQ(parsed->refKind, "branch");
+    EXPECT_EQ(parsed->ref, "develop");
+    ASSERT_TRUE(parsed->resolvedCommit.has_value());
+    EXPECT_EQ(parsed->resolvedCommit.value(),
+              "584894315b7a4fe4d7957d3c29dc4052b8012860");
+}
+
+TEST(PmLockIo, ParseGitBranchWithoutCommit) {
+    auto parsed = mcpp::pm::parse_git_source(
+        "git+https://github.com/user/repo#branch=develop");
+    ASSERT_TRUE(parsed.has_value());
+    EXPECT_EQ(parsed->url, "https://github.com/user/repo");
+    EXPECT_EQ(parsed->refKind, "branch");
+    EXPECT_EQ(parsed->ref, "develop");
+    EXPECT_FALSE(parsed->resolvedCommit.has_value());
+}
+
+TEST(PmLockIo, ParseGitTag) {
+    auto parsed = mcpp::pm::parse_git_source(
+        "git+https://github.com/user/repo#tag=v1.0.0");
+    ASSERT_TRUE(parsed.has_value());
+    EXPECT_EQ(parsed->url, "https://github.com/user/repo");
+    EXPECT_EQ(parsed->refKind, "tag");
+    EXPECT_EQ(parsed->ref, "v1.0.0");
+    EXPECT_FALSE(parsed->resolvedCommit.has_value());
+}
+
+TEST(PmLockIo, ParseGitRev) {
+    auto parsed = mcpp::pm::parse_git_source(
+        "git+https://github.com/user/repo#rev=584894315b7a4fe4d7957d3c29dc4052b8012860");
+    ASSERT_TRUE(parsed.has_value());
+    EXPECT_EQ(parsed->url, "https://github.com/user/repo");
+    EXPECT_EQ(parsed->refKind, "rev");
+    EXPECT_EQ(parsed->ref, "584894315b7a4fe4d7957d3c29dc4052b8012860");
+    EXPECT_FALSE(parsed->resolvedCommit.has_value());
+}
+
+TEST(PmLockIo, ParseNonGitSourceReturnsNullopt) {
+    EXPECT_FALSE(mcpp::pm::parse_git_source("index+mcpplibs@1.0.0").has_value());
+    EXPECT_FALSE(mcpp::pm::parse_git_source("").has_value());
+    EXPECT_FALSE(
+        mcpp::pm::parse_git_source("https://github.com/user/repo").has_value());
+    EXPECT_FALSE(mcpp::pm::parse_git_source("git+https://host/repo").has_value());
+    EXPECT_FALSE(
+        mcpp::pm::parse_git_source("git+https://host/repo#bad").has_value());
+}
