Skip to main content

foundry_cli/
lockfile.rs

1//! foundry.lock handler type.
2
3use crate::utils::{Git, SubmoduleCheckoutStatus};
4use alloy_primitives::map::HashMap;
5use eyre::{Context, OptionExt, Result};
6use foundry_common::fs::canonicalize_path;
7use serde::{Deserialize, Serialize};
8use std::{
9    collections::{BTreeMap, hash_map::Entry},
10    path::{Path, PathBuf},
11};
12
13pub const FOUNDRY_LOCK: &str = "foundry.lock";
14
15/// A type alias for a HashMap of dependencies keyed by relative path to the submodule dir.
16pub type DepMap = HashMap<PathBuf, DepIdentifier>;
17
18/// A difference between `foundry.lock` and an installed dependency submodule.
19#[derive(Debug, Clone, PartialEq, Eq)]
20pub enum LockfileMismatch {
21    /// An installed dependency is not recorded in the lockfile.
22    MissingLockEntry { path: PathBuf, actual: Option<String> },
23    /// A lockfile entry does not have a corresponding dependency submodule.
24    MissingSubmodule { path: PathBuf, expected: String },
25    /// The index contains a dependency gitlink without a `.gitmodules` mapping.
26    MissingSubmoduleMapping { path: PathBuf },
27    /// A dependency submodule has not been initialized.
28    Uninitialized { path: PathBuf, expected: Option<String> },
29    /// A dependency submodule has merge conflicts.
30    Conflicted { path: PathBuf },
31    /// The installed revision differs from the locked revision.
32    Revision { path: PathBuf, expected: String, actual: String },
33}
34
35impl LockfileMismatch {
36    /// Returns the dependency path associated with this mismatch.
37    pub fn path(&self) -> &Path {
38        match self {
39            Self::MissingLockEntry { path, .. }
40            | Self::MissingSubmodule { path, .. }
41            | Self::MissingSubmoduleMapping { path }
42            | Self::Uninitialized { path, .. }
43            | Self::Conflicted { path }
44            | Self::Revision { path, .. } => path,
45        }
46    }
47}
48
49impl std::fmt::Display for LockfileMismatch {
50    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
51        match self {
52            Self::MissingLockEntry { path, actual: Some(actual) } => {
53                write!(f, "{}: missing from foundry.lock (found {actual})", path.display())
54            }
55            Self::MissingLockEntry { path, actual: None } => {
56                write!(f, "{}: missing from foundry.lock", path.display())
57            }
58            Self::MissingSubmodule { path, expected } => write!(
59                f,
60                "{}: dependency submodule is missing (expected {expected})",
61                path.display()
62            ),
63            Self::MissingSubmoduleMapping { path } => {
64                write!(f, "{}: dependency submodule is missing from .gitmodules", path.display())
65            }
66            Self::Uninitialized { path, expected: Some(expected) } => write!(
67                f,
68                "{}: dependency submodule is not initialized (expected {expected})",
69                path.display()
70            ),
71            Self::Uninitialized { path, expected: None } => {
72                write!(f, "{}: dependency submodule is not initialized", path.display())
73            }
74            Self::Conflicted { path } => {
75                write!(f, "{}: dependency submodule has merge conflicts", path.display())
76            }
77            Self::Revision { path, expected, actual } => {
78                write!(f, "{}: expected {expected}, found {actual}", path.display())
79            }
80        }
81    }
82}
83
84/// A lockfile handler that keeps track of the dependencies and their current state.
85#[derive(Debug, Clone, Serialize, Deserialize)]
86pub struct Lockfile<'a> {
87    /// A map of the dependencies keyed by relative path to the submodule dir.
88    #[serde(flatten)]
89    deps: DepMap,
90    /// This is optional to handle no-git scencarios.
91    #[serde(skip)]
92    git: Option<&'a Git<'a>>,
93    /// Absolute path to the lockfile.
94    #[serde(skip)]
95    lockfile_path: PathBuf,
96}
97
98impl<'a> Lockfile<'a> {
99    /// Create a new [`Lockfile`] instance.
100    ///
101    /// `project_root` is the absolute path to the project root.
102    ///
103    /// You will need to call [`Lockfile::read`] or [`Lockfile::sync`] to load the lockfile.
104    pub fn new(project_root: &Path) -> Self {
105        Self { deps: HashMap::default(), git: None, lockfile_path: project_root.join(FOUNDRY_LOCK) }
106    }
107
108    /// Set the git instance to be used for submodule operations.
109    pub const fn with_git(mut self, git: &'a Git<'_>) -> Self {
110        self.git = Some(git);
111        self
112    }
113
114    /// Sync the foundry.lock file with the current state of `git submodules`.
115    ///
116    /// If the lockfile and git submodules are out of sync, it returns a [`DepMap`] consisting of
117    /// _only_ the out-of-sync dependencies.
118    ///
119    /// This method writes the lockfile to project root if:
120    /// - The lockfile does not exist.
121    /// - The lockfile is out of sync with the git submodules.
122    pub fn sync(&mut self, lib: &Path) -> Result<Option<DepMap>> {
123        if self.exists() {
124            self.read()?;
125        }
126
127        if let Some(git) = &self.git {
128            let submodules = git.submodules()?;
129
130            if submodules.is_empty() {
131                trace!("No submodules found. Skipping sync.");
132                return Ok(None);
133            }
134
135            let modules_with_branch = git
136                .read_submodules_with_branch(&Git::root_of(git.root)?, lib.file_name().unwrap())?;
137
138            let mut out_of_sync: DepMap = HashMap::default();
139            for sub in &submodules {
140                let rel_path = sub.path();
141                let rev = sub.rev();
142
143                let entry = self.deps.entry(rel_path.clone());
144
145                match entry {
146                    Entry::Occupied(e) if e.get().rev() != rev => {
147                        out_of_sync.insert(rel_path.clone(), e.get().clone());
148                    }
149                    Entry::Vacant(e) => {
150                        // Check if there is branch specified for the submodule at rel_path in
151                        // .gitmodules
152                        let maybe_branch = modules_with_branch.get(rel_path).cloned();
153
154                        trace!(?maybe_branch, submodule = ?rel_path, "submodule branch");
155                        if let Some(branch) = maybe_branch {
156                            let dep_id = DepIdentifier::Branch {
157                                name: branch,
158                                rev: rev.to_string(),
159                                r#override: false,
160                            };
161                            e.insert(dep_id.clone());
162                            out_of_sync.insert(rel_path.clone(), dep_id);
163                            continue;
164                        }
165
166                        let dep_id = DepIdentifier::Rev { rev: rev.to_string(), r#override: false };
167                        trace!(submodule=?rel_path, ?dep_id, "submodule dep_id");
168                        e.insert(dep_id.clone());
169                        out_of_sync.insert(rel_path.clone(), dep_id);
170                    }
171                    _ => {}
172                }
173            }
174
175            return Ok(if out_of_sync.is_empty() { None } else { Some(out_of_sync) });
176        }
177
178        Ok(None)
179    }
180
181    /// Checks whether the lockfile matches dependency submodules without modifying either.
182    pub fn check(&mut self) -> Result<Vec<LockfileMismatch>> {
183        let lockfile_exists = self.exists();
184        if lockfile_exists {
185            self.read().wrap_err("Failed to read foundry.lock")?;
186        } else {
187            self.deps.clear();
188        }
189
190        let git = self.git.ok_or_eyre("Git is required to check foundry.lock")?;
191        let project_root =
192            canonicalize_path(self.lockfile_path.parent().expect("lockfile path has a parent"))?;
193        let git_root = match Git::root_of(git.root) {
194            Ok(root) => root,
195            Err(_)
196                if !lockfile_exists
197                    && !project_root.ancestors().any(|root| root.join(".git").exists()) =>
198            {
199                return Ok(Vec::new());
200            }
201            Err(err) => return Err(err),
202        };
203        let project_prefix = project_root.strip_prefix(&git_root).map_err(|_| {
204            eyre::eyre!("Project root is not contained in Git root {}", git_root.display())
205        })?;
206
207        let repository_path = relative_path(&git_root, &project_root);
208        let git_submodules =
209            git.submodules_in_worktree(&repository_path, &git_root, project_prefix)?;
210        let mut submodules = BTreeMap::new();
211        for submodule in &git_submodules {
212            submodules.insert(submodule.path().clone(), submodule);
213        }
214
215        let mut mismatches = Vec::new();
216        for (path, dep) in &self.deps {
217            let expected = dep.rev();
218            let Some(submodule) = submodules.remove(path) else {
219                mismatches.push(LockfileMismatch::MissingSubmodule {
220                    path: path.clone(),
221                    expected: expected.to_string(),
222                });
223                continue;
224            };
225            match submodule.status() {
226                SubmoduleCheckoutStatus::Uninitialized => {
227                    mismatches.push(LockfileMismatch::Uninitialized {
228                        path: path.clone(),
229                        expected: Some(expected.to_string()),
230                    });
231                }
232                SubmoduleCheckoutStatus::Conflicted => {
233                    mismatches.push(LockfileMismatch::Conflicted { path: path.clone() });
234                }
235                SubmoduleCheckoutStatus::MissingMapping => {
236                    mismatches
237                        .push(LockfileMismatch::MissingSubmoduleMapping { path: path.clone() });
238                }
239                SubmoduleCheckoutStatus::Current | SubmoduleCheckoutStatus::Modified
240                    if submodule.rev() != expected =>
241                {
242                    mismatches.push(LockfileMismatch::Revision {
243                        path: path.clone(),
244                        expected: expected.to_string(),
245                        actual: submodule.rev().to_string(),
246                    });
247                }
248                SubmoduleCheckoutStatus::Current | SubmoduleCheckoutStatus::Modified => {}
249            }
250        }
251        for (path, submodule) in submodules {
252            match submodule.status() {
253                SubmoduleCheckoutStatus::MissingMapping => {
254                    mismatches.push(LockfileMismatch::MissingSubmoduleMapping { path });
255                }
256                SubmoduleCheckoutStatus::Uninitialized => {
257                    mismatches.push(LockfileMismatch::MissingLockEntry {
258                        path: path.clone(),
259                        actual: None,
260                    });
261                    mismatches.push(LockfileMismatch::Uninitialized { path, expected: None });
262                }
263                SubmoduleCheckoutStatus::Conflicted => {
264                    mismatches.push(LockfileMismatch::MissingLockEntry {
265                        path: path.clone(),
266                        actual: None,
267                    });
268                    mismatches.push(LockfileMismatch::Conflicted { path });
269                }
270                SubmoduleCheckoutStatus::Current | SubmoduleCheckoutStatus::Modified => {
271                    mismatches.push(LockfileMismatch::MissingLockEntry {
272                        path,
273                        actual: Some(submodule.rev().to_string()),
274                    });
275                }
276            }
277        }
278        mismatches.sort_by(|a, b| a.path().cmp(b.path()));
279        Ok(mismatches)
280    }
281
282    /// Loads the lockfile from the project root.
283    ///
284    /// Throws an error if the lockfile does not exist.
285    pub fn read(&mut self) -> Result<()> {
286        if !self.lockfile_path.exists() {
287            return Err(eyre::eyre!("Lockfile not found at {}", self.lockfile_path.display()));
288        }
289
290        let lockfile_str = foundry_common::fs::read_to_string(&self.lockfile_path)?;
291
292        self.deps = serde_json::from_str(&lockfile_str)?;
293
294        trace!(lockfile = ?self.deps, "loaded lockfile");
295
296        Ok(())
297    }
298
299    /// Writes the lockfile to the project root.
300    pub fn write(&self) -> Result<()> {
301        let ordered_deps: BTreeMap<_, _> = self.deps.clone().into_iter().collect();
302        let mut contents = serde_json::to_string_pretty(&ordered_deps)?;
303        // End the file with a newline, as editors and formatters expect for text files.
304        contents.push('\n');
305        foundry_common::fs::write(&self.lockfile_path, contents)?;
306        trace!(at= ?self.lockfile_path, "wrote lockfile");
307
308        Ok(())
309    }
310
311    /// Insert a dependency into the lockfile.
312    /// If the dependency already exists, it will be updated.
313    ///
314    /// Note: This does not write the updated lockfile to disk, only inserts the dep in-memory.
315    pub fn insert(&mut self, path: PathBuf, dep_id: DepIdentifier) {
316        self.deps.insert(path, dep_id);
317    }
318
319    /// Get the [`DepIdentifier`] for a submodule at a given path.
320    pub fn get(&self, path: &Path) -> Option<&DepIdentifier> {
321        self.deps.get(path)
322    }
323
324    /// Removes a dependency from the lockfile.
325    ///
326    /// Note: This does not write the updated lockfile to disk, only removes the dep in-memory.
327    pub fn remove(&mut self, path: &Path) -> Option<DepIdentifier> {
328        self.deps.remove(path)
329    }
330
331    /// Override a dependency in the lockfile.
332    ///
333    /// Returns the overridden/previous [`DepIdentifier`].
334    /// This is used in `forge update` to decide whether a dep's tag/branch/rev should be updated.
335    ///
336    /// Throws an error if the dependency is not found in the lockfile.
337    pub fn override_dep(
338        &mut self,
339        dep: &Path,
340        mut new_dep_id: DepIdentifier,
341    ) -> Result<DepIdentifier> {
342        let prev = self
343            .deps
344            .get_mut(dep)
345            .map(|d| {
346                new_dep_id.mark_override();
347                std::mem::replace(d, new_dep_id)
348            })
349            .ok_or_eyre(format!("Dependency not found in lockfile: {}", dep.display()))?;
350
351        Ok(prev)
352    }
353
354    /// Returns the num of dependencies in the lockfile.
355    pub fn len(&self) -> usize {
356        self.deps.len()
357    }
358
359    /// Returns whether the lockfile is empty.
360    pub fn is_empty(&self) -> bool {
361        self.deps.is_empty()
362    }
363
364    /// Returns an iterator over the lockfile.
365    pub fn iter(&self) -> impl Iterator<Item = (&PathBuf, &DepIdentifier)> {
366        self.deps.iter()
367    }
368
369    /// Returns an mutable iterator over the lockfile.
370    pub fn iter_mut(&mut self) -> impl Iterator<Item = (&PathBuf, &mut DepIdentifier)> {
371        self.deps.iter_mut()
372    }
373
374    pub fn exists(&self) -> bool {
375        self.lockfile_path.exists()
376    }
377}
378
379fn relative_path(path: &Path, base: &Path) -> PathBuf {
380    let common =
381        path.components().zip(base.components()).take_while(|(path, base)| path == base).count();
382    let mut relative = PathBuf::new();
383    for _ in common..base.components().count() {
384        relative.push("..");
385    }
386    relative.extend(path.components().skip(common));
387    relative
388}
389
390// Implement .iter() for &LockFile
391
392/// Identifies whether a dependency (submodule) is referenced by a branch,
393/// tag or rev (commit hash).
394///
395/// Each enum variant consists of an `r#override` flag which is used in `forge update` to decide
396/// whether to update a dep or not. This flag is skipped during serialization.
397#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
398pub enum DepIdentifier {
399    /// `name` of the branch and the `rev`  it is currently pointing to.
400    /// Running `forge update`, will update the `name` branch to the latest `rev`.
401    #[serde(rename = "branch")]
402    Branch {
403        name: String,
404        rev: String,
405        #[serde(skip)]
406        r#override: bool,
407    },
408    /// Release tag `name` and the `rev` it is currently pointing to.
409    /// Running `forge update` does not update the tag/rev.
410    /// Dependency will remain pinned to the existing tag/rev unless r#override like so `forge
411    /// update owner/dep@tag=different_tag`.
412    #[serde(rename = "tag")]
413    Tag {
414        name: String,
415        rev: String,
416        #[serde(skip)]
417        r#override: bool,
418    },
419    /// Commit hash `rev` the submodule is currently pointing to.
420    /// Running `forge update` does not update the rev.
421    /// Dependency will remain pinned to the existing rev unless r#override.
422    #[serde(rename = "rev", untagged)]
423    Rev {
424        rev: String,
425        #[serde(skip)]
426        r#override: bool,
427    },
428}
429
430impl DepIdentifier {
431    /// Resolves the [`DepIdentifier`] for a submodule at a given path.
432    /// `lib_path` is the absolute path to the submodule.
433    pub fn resolve_type(git: &Git<'_>, lib_path: &Path, s: &str) -> Result<Self> {
434        trace!(lib_path = ?lib_path, resolving_type = ?s, "resolving submodule identifier");
435        // Get the tags for the submodule
436        if git.has_tag(s, lib_path)? {
437            let rev = git.get_rev(s, lib_path)?;
438            return Ok(Self::Tag { name: String::from(s), rev, r#override: false });
439        }
440
441        if git.has_branch(s, lib_path)? {
442            let rev = git.get_rev(s, lib_path)?;
443            return Ok(Self::Branch { name: String::from(s), rev, r#override: false });
444        }
445
446        if git.has_rev(s, lib_path)? {
447            return Ok(Self::Rev { rev: String::from(s), r#override: false });
448        }
449
450        Err(eyre::eyre!("Could not resolve tag type for submodule at path {}", lib_path.display()))
451    }
452
453    /// Get the commit hash of the dependency.
454    pub fn rev(&self) -> &str {
455        match self {
456            Self::Branch { rev, .. } => rev,
457            Self::Tag { rev, .. } => rev,
458            Self::Rev { rev, .. } => rev,
459        }
460    }
461
462    /// Get the name of the dependency.
463    ///
464    /// In case of a Rev, this will return the commit hash.
465    pub fn name(&self) -> &str {
466        match self {
467            Self::Branch { name, .. } => name,
468            Self::Tag { name, .. } => name,
469            Self::Rev { rev, .. } => rev,
470        }
471    }
472
473    /// Get the name/rev to checkout at.
474    ///
475    /// Tags are checked out at their locked revision, since a tag name can be shadowed by a
476    /// branch with the same name.
477    pub fn checkout_id(&self) -> &str {
478        match self {
479            Self::Branch { name, .. } => name,
480            Self::Tag { rev, .. } | Self::Rev { rev, .. } => rev,
481        }
482    }
483
484    /// Marks as dependency as overridden.
485    pub const fn mark_override(&mut self) {
486        match self {
487            Self::Branch { r#override, .. } => *r#override = true,
488            Self::Tag { r#override, .. } => *r#override = true,
489            Self::Rev { r#override, .. } => *r#override = true,
490        }
491    }
492
493    /// Returns whether the dependency has been overridden.
494    pub const fn overridden(&self) -> bool {
495        match self {
496            Self::Branch { r#override, .. } => *r#override,
497            Self::Tag { r#override, .. } => *r#override,
498            Self::Rev { r#override, .. } => *r#override,
499        }
500    }
501
502    /// Returns whether the dependency is a branch.
503    pub const fn is_branch(&self) -> bool {
504        matches!(self, Self::Branch { .. })
505    }
506}
507
508impl std::fmt::Display for DepIdentifier {
509    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
510        match self {
511            Self::Branch { name, rev, .. } => write!(f, "branch={name}@{rev}"),
512            Self::Tag { name, rev, .. } => write!(f, "tag={name}@{rev}"),
513            Self::Rev { rev, .. } => write!(f, "rev={rev}"),
514        }
515    }
516}
517
518#[cfg(test)]
519mod tests {
520    use super::*;
521    use std::fs;
522    use tempfile::tempdir;
523
524    #[test]
525    fn serde_dep_identifier() {
526        let branch = DepIdentifier::Branch {
527            name: "main".to_string(),
528            rev: "b7954c3e9ce1d487b49489f5800f52f4b77b7351".to_string(),
529            r#override: false,
530        };
531
532        let tag = DepIdentifier::Tag {
533            name: "v0.1.0".to_string(),
534            rev: "b7954c3e9ce1d487b49489f5800f52f4b77b7351".to_string(),
535            r#override: false,
536        };
537
538        let rev = DepIdentifier::Rev {
539            rev: "b7954c3e9ce1d487b49489f5800f52f4b77b7351".to_string(),
540            r#override: false,
541        };
542
543        let branch_str = serde_json::to_string(&branch).unwrap();
544        let tag_str = serde_json::to_string(&tag).unwrap();
545        let rev_str = serde_json::to_string(&rev).unwrap();
546
547        assert_eq!(
548            branch_str,
549            r#"{"branch":{"name":"main","rev":"b7954c3e9ce1d487b49489f5800f52f4b77b7351"}}"#
550        );
551        assert_eq!(
552            tag_str,
553            r#"{"tag":{"name":"v0.1.0","rev":"b7954c3e9ce1d487b49489f5800f52f4b77b7351"}}"#
554        );
555        assert_eq!(rev_str, r#"{"rev":"b7954c3e9ce1d487b49489f5800f52f4b77b7351"}"#);
556
557        let branch_de: DepIdentifier = serde_json::from_str(&branch_str).unwrap();
558        let tag_de: DepIdentifier = serde_json::from_str(&tag_str).unwrap();
559        let rev_de: DepIdentifier = serde_json::from_str(&rev_str).unwrap();
560
561        assert_eq!(branch, branch_de);
562        assert_eq!(tag, tag_de);
563        assert_eq!(rev, rev_de);
564    }
565
566    #[test]
567    fn test_write_ordered_deps() {
568        let dir = tempdir().unwrap();
569        let mut lockfile = Lockfile::new(dir.path());
570        lockfile.insert(
571            PathBuf::from("z_dep"),
572            DepIdentifier::Rev { rev: "3".to_string(), r#override: false },
573        );
574        lockfile.insert(
575            PathBuf::from("a_dep"),
576            DepIdentifier::Rev { rev: "1".to_string(), r#override: false },
577        );
578        lockfile.insert(
579            PathBuf::from("c_dep"),
580            DepIdentifier::Rev { rev: "2".to_string(), r#override: false },
581        );
582        let _ = lockfile.write();
583        let contents = fs::read_to_string(lockfile.lockfile_path).unwrap();
584        let expected = r#"{
585  "a_dep": {
586    "rev": "1"
587  },
588  "c_dep": {
589    "rev": "2"
590  },
591  "z_dep": {
592    "rev": "3"
593  }
594}
595"#;
596        assert_eq!(contents, expected);
597
598        let mut lockfile = Lockfile::new(dir.path());
599        lockfile.read().unwrap();
600        lockfile.insert(
601            PathBuf::from("x_dep"),
602            DepIdentifier::Rev { rev: "4".to_string(), r#override: false },
603        );
604        let _ = lockfile.write();
605        let contents = fs::read_to_string(lockfile.lockfile_path).unwrap();
606        let expected = r#"{
607  "a_dep": {
608    "rev": "1"
609  },
610  "c_dep": {
611    "rev": "2"
612  },
613  "x_dep": {
614    "rev": "4"
615  },
616  "z_dep": {
617    "rev": "3"
618  }
619}
620"#;
621        assert_eq!(contents, expected);
622    }
623
624    #[test]
625    fn sync_propagates_errors_containing_missing_lockfile_message() {
626        let dir = tempdir().unwrap();
627        fs::write(dir.path().join(FOUNDRY_LOCK), r#""Lockfile not found""#).unwrap();
628        let mut lockfile = Lockfile::new(dir.path());
629
630        let err = lockfile.sync(Path::new("lib")).unwrap_err();
631        assert!(err.downcast_ref::<serde_json::Error>().is_some());
632    }
633
634    #[test]
635    fn sync_preserves_dependencies_without_lockfile() {
636        let dir = tempdir().unwrap();
637        let mut lockfile = Lockfile::new(dir.path());
638        let dep = DepIdentifier::Rev { rev: "1".to_string(), r#override: false };
639        lockfile.insert(PathBuf::from("lib/dep"), dep.clone());
640
641        assert_eq!(lockfile.sync(Path::new("lib")).unwrap(), None);
642        assert_eq!(lockfile.get(Path::new("lib/dep")), Some(&dep));
643        assert!(!lockfile.exists());
644    }
645}