feat(dependencies): support pinning of tags / revs when using .gitmodules with foundry.lock

crates/cli/src/utils/mod.rs

@@ -1,18 +1,20 @@
 use alloy_json_abi::JsonAbi;
-use alloy_primitives::U256;
+use alloy_primitives::{map::HashMap, U256};
 use alloy_provider::{network::AnyNetwork, Provider};
 use eyre::{ContextCompat, Result};
 use foundry_common::{
     provider::{ProviderBuilder, RetryProvider},
     shell,
 };
 use foundry_config::{Chain, Config};
+use itertools::Itertools;
 use serde::de::DeserializeOwned;
 use std::{
     ffi::OsStr,
     future::Future,
     path::{Path, PathBuf},
     process::{Command, Output, Stdio},
+    str::FromStr,
     time::{Duration, SystemTime, UNIX_EPOCH},
 };
 use tracing_subscriber::prelude::*;
@@ -41,6 +43,13 @@ pub const STATIC_FUZZ_SEED: [u8; 32] = [
     0x5d, 0x64, 0x0b, 0x19, 0xad, 0xf0, 0xe3, 0x57, 0xb8, 0xd4, 0xbe, 0x7d, 0x49, 0xee, 0x70, 0xe6,
 ];
 
+/// Regex used to parse `.gitmodules` file and capture the submodule path and branch.
+const SUBMODULE_BRANCH_REGEX: &str = r#"\[submodule "([^"]+)"\](?:[^\[]*?branch = ([^\s]+))"#;
+/// Regex used to parse `git submodule status` output.
+const SUBMODULE_STATUS_REGEX: &str = r"^[\s+-]?([a-f0-9]+)\s+([^\s]+)(?:\s+\([^)]+\))?$";
+/// Capture the HEAD / default branch of the git repository from `git remote show origin`.
+const DEFAULT_BRANCH_REGEX: &str = r"HEAD branch: (.*)";
+
 /// Useful extensions to [`std::path::Path`].
 pub trait FoundryPathExt {
     /// Returns true if the [`Path`] ends with `.t.sol`
@@ -392,10 +401,21 @@ impl<'a> Git<'a> {
             .map(drop)
     }
 
+    pub fn checkout_at(self, tag: impl AsRef<OsStr>, at: &Path) -> Result<()> {
+        self.cmd_at(at).arg("checkout").arg(tag).exec().map(drop)
+    }
+
     pub fn init(self) -> Result<()> {
         self.cmd().arg("init").exec().map(drop)
     }
 
+    pub fn current_rev_branch(self, at: &Path) -> Result<(String, String)> {
+        let rev = self.cmd_at(at).args(["rev-parse", "HEAD"]).get_stdout_lossy()?;
+        let branch =
+            self.cmd_at(at).args(["rev-parse", "--abbrev-ref", "HEAD"]).get_stdout_lossy()?;
+        Ok((rev, branch))
+    }
+
     #[expect(clippy::should_implement_trait)] // this is not std::ops::Add clippy
     pub fn add<I, S>(self, paths: I) -> Result<()>
     where
@@ -469,6 +489,26 @@ impl<'a> Git<'a> {
             .map(|stdout| !stdout.is_empty())
     }
 
+    pub fn has_tag(self, tag: impl AsRef<OsStr>, at: &Path) -> Result<bool> {
+        self.cmd_at(at)
+            .args(["tag", "--list"])
+            .arg(tag)
+            .get_stdout_lossy()
+            .map(|stdout| !stdout.is_empty())
+    }
+
+    pub fn has_rev(self, rev: impl AsRef<OsStr>, at: &Path) -> Result<bool> {
+        self.cmd_at(at)
+            .args(["cat-file", "-t"])
+            .arg(rev)
+            .get_stdout_lossy()
+            .map(|stdout| &stdout == "commit")
+    }
+
+    pub fn get_rev(self, tag_or_branch: impl AsRef<OsStr>, at: &Path) -> Result<String> {
+        self.cmd_at(at).args(["rev-list", "-n", "1"]).arg(tag_or_branch).get_stdout_lossy()
+    }
+
     pub fn ensure_clean(self) -> Result<()> {
         if self.is_clean()? {
             Ok(())
@@ -497,6 +537,64 @@ ignore them in the `.gitignore` file."
         self.cmd().arg("tag").get_stdout_lossy()
     }
 
+    /// Returns the tag the commit first appeared in.
+    ///
+    /// E.g Take rev = `abc1234`. This commit can be found in multiple releases (tags).
+    /// Consider releases: `v0.1.0`, `v0.2.0`, `v0.3.0` in chronological order, `rev` first appeared
+    /// in `v0.2.0`.
+    ///
+    /// Hence, `tag_for_commit("abc1234")` will return `v0.2.0`.
+    pub fn tag_for_commit(self, rev: &str, at: &Path) -> Result<Option<String>> {
+        self.cmd_at(at)
+            .args(["tag", "--contains"])
+            .arg(rev)
+            .get_stdout_lossy()
+            .map(|stdout| stdout.lines().next().map(str::to_string))
+    }
+
+    /// Returns a list of tuples of submodule paths and their respective branches.
+    ///
+    /// This function reads the `.gitmodules` file and returns the paths of all submodules that have
+    /// a branch. The paths are relative to the Git::root_of(git.root) and not lib/ directory.
+    ///
+    /// `at` is the dir in which the `.gitmodules` file is located, this is the git root.
+    /// `lib` is name of the directory where the submodules are located.
+    pub fn read_submodules_with_branch(
+        self,
+        at: &Path,
+        lib: &OsStr,
+    ) -> Result<HashMap<PathBuf, String>> {
+        // Read the .gitmodules file
+        let gitmodules = foundry_common::fs::read_to_string(at.join(".gitmodules"))?;
+        let re = regex::Regex::new(SUBMODULE_BRANCH_REGEX)?;
+
+        let paths = re
+            .captures_iter(&gitmodules)
+            .map(|cap| {
+                let path_str = cap.get(1).unwrap().as_str();
+                let path = PathBuf::from_str(path_str).unwrap();
+                trace!(path = %path.display(), "unstripped path");
+
+                // Keep only the components that come after the lib directory.
+                // This needs to be done because the lockfile uses paths relative foundry project
+                // root whereas .gitmodules use paths relative to the git root which may not be the
+                // project root. e.g monorepo.
+                // Hence, if path is lib/solady, then `lib/solady` is kept. if path is
+                // packages/contract-bedrock/lib/solady, then `lib/solady` is kept.
+                let lib_pos = path.components().find_position(|c| c.as_os_str() == lib);
+                let path = path
+                    .components()
+                    .skip(lib_pos.map(|(i, _)| i).unwrap_or(0))
+                    .collect::<PathBuf>();
+
+                let branch = cap.get(2).unwrap().as_str().to_string();
+                (path, branch)
+            })
+            .collect::<HashMap<_, _>>();
+
+        Ok(paths)
+    }
+
     pub fn has_missing_dependencies<I, S>(self, paths: I) -> Result<bool>
     where
         I: IntoIterator<Item = S>,
@@ -574,10 +672,35 @@ ignore them in the `.gitignore` file."
             .map(drop)
     }
 
+    /// If the status is prefix with `-`, the submodule is not initialized.
+    ///
+    /// Ref: <https://git-scm.com/docs/git-submodule#Documentation/git-submodule.txt-status--cached--recursive--ltpathgt82308203>
+    pub fn submodules_unintialized(self) -> Result<bool> {
+        self.cmd()
+            .args(["submodule", "status"])
+            .get_stdout_lossy()
+            .map(|stdout| stdout.lines().any(|line| line.starts_with('-')))
+    }
+
+    /// Initializes the git submodules.
     pub fn submodule_init(self) -> Result<()> {
         self.cmd().stderr(self.stderr()).args(["submodule", "init"]).exec().map(drop)
     }
 
+    /// Gets the default branch of the git repository.
+    pub fn default_branch(&self, at: &Path) -> Result<String> {
+        self.cmd_at(at).args(["remote", "show", "origin"]).get_stdout_lossy().map(|stdout| {
+            let re = regex::Regex::new(DEFAULT_BRANCH_REGEX)?;
+            let caps =
+                re.captures(&stdout).ok_or_else(|| eyre::eyre!("Could not find HEAD branch"))?;
+            Ok(caps.get(1).unwrap().as_str().to_string())
+        })?
+    }
+
+    pub fn submodules(&self) -> Result<Submodules> {
+        self.cmd().args(["submodule", "status"]).get_stdout_lossy().map(|stdout| stdout.parse())?
+    }
+
     pub fn submodule_sync(self) -> Result<()> {
         self.cmd().stderr(self.stderr()).args(["submodule", "sync"]).exec().map(drop)
     }
@@ -610,13 +733,113 @@ ignore them in the `.gitignore` file."
     }
 }
 
+/// Deserialized `git submodule status lib/dep` output.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq)]
+pub struct Submodule {
+    /// Current commit hash the submodule is checked out at.
+    rev: String,
+    /// Relative path to the submodule.
+    path: PathBuf,
+}
+
+impl Submodule {
+    pub fn new(rev: String, path: PathBuf) -> Self {
+        Self { rev, path }
+    }
+
+    pub fn rev(&self) -> &str {
+        &self.rev
+    }
+
+    pub fn path(&self) -> &PathBuf {
+        &self.path
+    }
+}
+
+impl FromStr for Submodule {
+    type Err = eyre::Report;
+
+    fn from_str(s: &str) -> Result<Self> {
+        let re = regex::Regex::new(SUBMODULE_STATUS_REGEX)?;
+
+        let caps = re.captures(s).ok_or_else(|| eyre::eyre!("Invalid submodule status format"))?;
+
+        Ok(Self {
+            rev: caps.get(1).unwrap().as_str().to_string(),
+            path: PathBuf::from(caps.get(2).unwrap().as_str()),
+        })
+    }
+}
+
+/// Deserialized `git submodule status` output.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Submodules(pub Vec<Submodule>);
+
+impl Submodules {
+    pub fn len(&self) -> usize {
+        self.0.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.0.is_empty()
+    }
+}
+
+impl FromStr for Submodules {
+    type Err = eyre::Report;
+
+    fn from_str(s: &str) -> Result<Self> {
+        let subs = s.lines().map(str::parse).collect::<Result<Vec<Submodule>>>()?;
+        Ok(Self(subs))
+    }
+}
+
+impl<'a> IntoIterator for &'a Submodules {
+    type Item = &'a Submodule;
+    type IntoIter = std::slice::Iter<'a, Submodule>;
+
+    fn into_iter(self) -> Self::IntoIter {
+        self.0.iter()
+    }
+}
 #[cfg(test)]
 mod tests {
     use super::*;
     use foundry_common::fs;
     use std::{env, fs::File, io::Write};
     use tempfile::tempdir;
 
+    #[test]
+    fn parse_submodule_status() {
+        let s = "+8829465a08cac423dcf59852f21e448449c1a1a8 lib/openzeppelin-contracts (v4.8.0-791-g8829465a)";
+        let sub = Submodule::from_str(s).unwrap();
+        assert_eq!(sub.rev(), "8829465a08cac423dcf59852f21e448449c1a1a8");
+        assert_eq!(sub.path(), Path::new("lib/openzeppelin-contracts"));
+
+        let s = "-8829465a08cac423dcf59852f21e448449c1a1a8 lib/openzeppelin-contracts";
+        let sub = Submodule::from_str(s).unwrap();
+        assert_eq!(sub.rev(), "8829465a08cac423dcf59852f21e448449c1a1a8");
+        assert_eq!(sub.path(), Path::new("lib/openzeppelin-contracts"));
+
+        let s = "8829465a08cac423dcf59852f21e448449c1a1a8 lib/openzeppelin-contracts";
+        let sub = Submodule::from_str(s).unwrap();
+        assert_eq!(sub.rev(), "8829465a08cac423dcf59852f21e448449c1a1a8");
+        assert_eq!(sub.path(), Path::new("lib/openzeppelin-contracts"));
+    }
+
+    #[test]
+    fn parse_multiline_submodule_status() {
+        let s = r#"+d3db4ef90a72b7d24aa5a2e5c649593eaef7801d lib/forge-std (v1.9.4-6-gd3db4ef)
++8829465a08cac423dcf59852f21e448449c1a1a8 lib/openzeppelin-contracts (v4.8.0-791-g8829465a)
+"#;
+        let subs = Submodules::from_str(s).unwrap().0;
+        assert_eq!(subs.len(), 2);
+        assert_eq!(subs[0].rev(), "d3db4ef90a72b7d24aa5a2e5c649593eaef7801d");
+        assert_eq!(subs[0].path(), Path::new("lib/forge-std"));
+        assert_eq!(subs[1].rev(), "8829465a08cac423dcf59852f21e448449c1a1a8");
+        assert_eq!(subs[1].path(), Path::new("lib/openzeppelin-contracts"));
+    }
+
     #[test]
     fn foundry_path_ext_works() {
         let p = Path::new("contracts/MyTest.t.sol");
@@ -653,4 +876,92 @@ mod tests {
         assert_eq!(env::var("TESTCWDKEY").unwrap(), "cwd_val");
         assert_eq!(env::var("TESTPRJKEY").unwrap(), "prj_val");
     }
+
+    #[test]
+    fn test_read_gitmodules_regex() {
+        // Regex to read and return the paths of all submodules that have a branch
+        let re = regex::Regex::new(SUBMODULE_BRANCH_REGEX).unwrap();
+
+        let gitmodules = r#"
+        [submodule "lib/solady"]
+        path = lib/solady
+        url = ""
+        branch = v0.1.0
+        [submodule "lib/openzeppelin-contracts"]
+        path = lib/openzeppelin-contracts
+        url = ""
+        branch = v4.8.0-791-g8829465a
+        [submodule "lib/forge-std"]
+        path = lib/forge-std
+        url = ""
+"#;
+
+        let paths = re
+            .captures_iter(gitmodules)
+            .map(|cap| {
+                (
+                    PathBuf::from_str(cap.get(1).unwrap().as_str()).unwrap(),
+                    String::from(cap.get(2).unwrap().as_str()),
+                )
+            })
+            .collect::<HashMap<_, _>>();
+
+        assert_eq!(paths.get(Path::new("lib/solady")).unwrap(), "v0.1.0");
+        assert_eq!(
+            paths.get(Path::new("lib/openzeppelin-contracts")).unwrap(),
+            "v4.8.0-791-g8829465a"
+        );
+
+        let no_branch_gitmodules = r#"
+        [submodule "lib/solady"]
+        path = lib/solady
+        url = ""
+        [submodule "lib/openzeppelin-contracts"]
+        path = lib/openzeppelin-contracts
+        url = ""
+        [submodule "lib/forge-std"]
+        path = lib/forge-std
+        url = ""
+"#;
+        let paths = re
+            .captures_iter(no_branch_gitmodules)
+            .map(|cap| {
+                (
+                    PathBuf::from_str(cap.get(1).unwrap().as_str()).unwrap(),
+                    String::from(cap.get(2).unwrap().as_str()),
+                )
+            })
+            .collect::<HashMap<_, _>>();
+
+        assert!(paths.is_empty());
+
+        let branch_in_between = r#"
+        [submodule "lib/solady"]
+        path = lib/solady
+        url = ""
+        [submodule "lib/openzeppelin-contracts"]
+        path = lib/openzeppelin-contracts
+        url = ""
+        branch = v4.8.0-791-g8829465a
+        [submodule "lib/forge-std"]
+        path = lib/forge-std
+        url = ""
+        "#;
+
+        let paths = re
+            .captures_iter(branch_in_between)
+            .map(|cap| {
+                (
+                    PathBuf::from_str(cap.get(1).unwrap().as_str()).unwrap(),
+                    String::from(cap.get(2).unwrap().as_str()),
+                )
+            })
+            .collect::<HashMap<_, _>>();
+
+        assert_eq!(paths.len(), 1);
+        assert_eq!(
+            paths.get(Path::new("lib/openzeppelin-contracts")).unwrap(),
+            "v4.8.0-791-g8829465a"
+        );
+    }
 }