foundry_cli/opts/
dependency.rs

1//! CLI dependency parsing
2
3use eyre::Result;
4use regex::Regex;
5use std::{str::FromStr, sync::LazyLock};
6
7static GH_REPO_REGEX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"[\w-]+/[\w.-]+").unwrap());
8
9/// Git repo prefix regex
10pub static GH_REPO_PREFIX_REGEX: LazyLock<Regex> = LazyLock::new(|| {
11    Regex::new(r"((git@)|(git\+https://)|(https://)|https://(?P<token>[^@]+)@|(org-([A-Za-z0-9-])+@))?(?P<brand>[A-Za-z0-9-]+)\.(?P<tld>[A-Za-z0-9-]+)(/|:)")
12        .unwrap()
13});
14
15static VERSION_PREFIX_REGEX: LazyLock<Regex> =
16    LazyLock::new(|| Regex::new(r#"@(tag|branch|rev)="#).unwrap());
17
18const GITHUB: &str = "github.com";
19const VERSION_SEPARATOR: char = '@';
20const ALIAS_SEPARATOR: char = '=';
21
22/// Commonly used aliases for solidity repos,
23///
24/// These will be autocorrected when used in place of the `org`
25const COMMON_ORG_ALIASES: &[(&str, &str); 2] =
26    &[("@openzeppelin", "openzeppelin"), ("@aave", "aave")];
27
28/// A git dependency which will be installed as a submodule
29///
30/// A dependency can be provided as a raw URL, or as a path to a Github repository
31/// e.g. `org-name/repo-name`
32///
33/// Providing a ref can be done in the following 3 ways:
34/// * branch: master
35/// * tag: v0.1.1
36/// * commit: 8e8128
37///
38/// Non Github URLs must be provided with an https:// prefix.
39/// Adding dependencies as local paths is not supported yet.
40#[derive(Clone, Debug, PartialEq, Eq)]
41pub struct Dependency {
42    /// The name of the dependency
43    pub name: String,
44    /// The url to the git repository corresponding to the dependency
45    pub url: Option<String>,
46    /// Optional tag corresponding to a Git SHA, tag, or branch.
47    pub tag: Option<String>,
48    /// Optional alias of the dependency
49    pub alias: Option<String>,
50}
51
52impl FromStr for Dependency {
53    type Err = eyre::Error;
54    fn from_str(dependency: &str) -> Result<Self, Self::Err> {
55        // Handle dependency exact ref type (`@tag=`, `@branch=` or `@rev=`)`.
56        // Only extract version for first tag/branch/commit specified.
57        let url_and_version: Vec<&str> = VERSION_PREFIX_REGEX.split(dependency).collect();
58        let dependency = url_and_version[0];
59        let mut tag_or_branch = url_and_version.get(1).map(|version| version.to_string());
60
61        // everything before "=" should be considered the alias
62        let (mut alias, dependency) = if let Some(split) = dependency.split_once(ALIAS_SEPARATOR) {
63            (Some(String::from(split.0)), split.1.to_string())
64        } else {
65            let mut dependency = dependency.to_string();
66            // this will autocorrect wrong conventional aliases for tag, but only autocorrect if
67            // it's not used as alias
68            for (alias, real_org) in COMMON_ORG_ALIASES {
69                if dependency.starts_with(alias) {
70                    dependency = dependency.replacen(alias, real_org, 1);
71                    break;
72                }
73            }
74
75            (None, dependency)
76        };
77
78        let dependency = dependency.as_str();
79
80        let url_with_version = if let Some(captures) = GH_REPO_PREFIX_REGEX.captures(dependency) {
81            let brand = captures.name("brand").unwrap().as_str();
82            let tld = captures.name("tld").unwrap().as_str();
83            let project = GH_REPO_PREFIX_REGEX.replace(dependency, "");
84            if let Some(token) = captures.name("token") {
85                Some(format!(
86                    "https://{}@{brand}.{tld}/{}",
87                    token.as_str(),
88                    project.trim_end_matches(".git")
89                ))
90            } else if dependency.starts_with("git@") {
91                Some(format!("git@{brand}.{tld}:{}", project.trim_end_matches(".git")))
92            } else {
93                Some(format!("https://{brand}.{tld}/{}", project.trim_end_matches(".git")))
94            }
95        } else {
96            // If we don't have a URL and we don't have a valid
97            // GitHub repository name, then we assume this is the alias.
98            //
99            // This is to allow for conveniently removing aliased dependencies
100            // using `forge remove <alias>`
101            if GH_REPO_REGEX.is_match(dependency) {
102                Some(format!("https://{GITHUB}/{dependency}"))
103            } else {
104                alias = Some(dependency.to_string());
105                None
106            }
107        };
108
109        // everything after the last "@" should be considered the version if there are no path
110        // segments
111        let (url, name, tag) = if let Some(url_with_version) = url_with_version {
112            // `@`s are actually valid github project name chars but we assume this is unlikely and
113            // treat everything after the last `@` as the version tag there's still the
114            // case that the user tries to use `@<org>/<project>`, so we need to check that the
115            // `tag` does not contain a slash
116            let mut split = url_with_version.rsplit(VERSION_SEPARATOR);
117
118            let mut url = url_with_version.as_str();
119
120            if tag_or_branch.is_none() {
121                let maybe_tag_or_branch = split.next().unwrap();
122                if let Some(actual_url) = split.next()
123                    && !maybe_tag_or_branch.contains('/')
124                {
125                    tag_or_branch = Some(maybe_tag_or_branch.to_string());
126                    url = actual_url;
127                }
128            }
129
130            let url = url.to_string();
131            let name = url
132                .split('/')
133                .next_back()
134                .ok_or_else(|| eyre::eyre!("no dependency name found"))?
135                .to_string();
136
137            (Some(url), Some(name), tag_or_branch)
138        } else {
139            (None, None, None)
140        };
141
142        Ok(Self { name: name.or_else(|| alias.clone()).unwrap(), url, tag, alias })
143    }
144}
145
146impl Dependency {
147    /// Returns the name of the dependency, prioritizing the alias if it exists.
148    pub fn name(&self) -> &str {
149        self.alias.as_deref().unwrap_or(self.name.as_str())
150    }
151
152    /// Returns the URL of the dependency if it exists, or an error if not.
153    pub fn require_url(&self) -> Result<&str> {
154        self.url.as_deref().ok_or_else(|| eyre::eyre!("dependency {} has no url", self.name()))
155    }
156}
157
158#[cfg(test)]
159mod tests {
160    use super::*;
161    use foundry_compilers::info::ContractInfo;
162
163    #[test]
164    fn parses_dependencies() {
165        for (input, expected_path, expected_tag, expected_alias) in [
166            ("gakonst/lootloose", "https://github.com/gakonst/lootloose", None, None),
167            ("github.com/gakonst/lootloose", "https://github.com/gakonst/lootloose", None, None),
168            (
169                "https://github.com/gakonst/lootloose",
170                "https://github.com/gakonst/lootloose",
171                None,
172                None,
173            ),
174            (
175                "git+https://github.com/gakonst/lootloose",
176                "https://github.com/gakonst/lootloose",
177                None,
178                None,
179            ),
180            (
181                "git@github.com:gakonst/lootloose@tag=v1",
182                "git@github.com:gakonst/lootloose",
183                Some("v1"),
184                None,
185            ),
186            ("git@github.com:gakonst/lootloose", "git@github.com:gakonst/lootloose", None, None),
187            (
188                "https://gitlab.com/gakonst/lootloose",
189                "https://gitlab.com/gakonst/lootloose",
190                None,
191                None,
192            ),
193            (
194                "https://github.xyz/gakonst/lootloose",
195                "https://github.xyz/gakonst/lootloose",
196                None,
197                None,
198            ),
199            (
200                "gakonst/lootloose@0.1.0",
201                "https://github.com/gakonst/lootloose",
202                Some("0.1.0"),
203                None,
204            ),
205            (
206                "gakonst/lootloose@develop",
207                "https://github.com/gakonst/lootloose",
208                Some("develop"),
209                None,
210            ),
211            (
212                "gakonst/lootloose@98369d0edc900c71d0ec33a01dfba1d92111deed",
213                "https://github.com/gakonst/lootloose",
214                Some("98369d0edc900c71d0ec33a01dfba1d92111deed"),
215                None,
216            ),
217            ("loot=gakonst/lootloose", "https://github.com/gakonst/lootloose", None, Some("loot")),
218            (
219                "loot=github.com/gakonst/lootloose",
220                "https://github.com/gakonst/lootloose",
221                None,
222                Some("loot"),
223            ),
224            (
225                "loot=https://github.com/gakonst/lootloose",
226                "https://github.com/gakonst/lootloose",
227                None,
228                Some("loot"),
229            ),
230            (
231                "loot=git+https://github.com/gakonst/lootloose",
232                "https://github.com/gakonst/lootloose",
233                None,
234                Some("loot"),
235            ),
236            (
237                "loot=git@github.com:gakonst/lootloose@tag=v1",
238                "git@github.com:gakonst/lootloose",
239                Some("v1"),
240                Some("loot"),
241            ),
242        ] {
243            let dep = Dependency::from_str(input).unwrap();
244            assert_eq!(dep.url, Some(expected_path.to_string()));
245            assert_eq!(dep.tag, expected_tag.map(ToString::to_string));
246            assert_eq!(dep.name, "lootloose");
247            assert_eq!(dep.alias, expected_alias.map(ToString::to_string));
248        }
249    }
250
251    #[test]
252    fn can_parse_alias_only() {
253        let dep = Dependency::from_str("foo").unwrap();
254        assert_eq!(dep.name, "foo");
255        assert_eq!(dep.url, None);
256        assert_eq!(dep.tag, None);
257        assert_eq!(dep.alias, Some("foo".to_string()));
258    }
259
260    #[test]
261    fn test_invalid_github_repo_dependency() {
262        let dep = Dependency::from_str("solmate").unwrap();
263        assert_eq!(dep.url, None);
264    }
265
266    #[test]
267    fn parses_contract_info() {
268        for (input, expected_path, expected_name) in [
269            (
270                "src/contracts/Contracts.sol:Contract",
271                Some("src/contracts/Contracts.sol"),
272                "Contract",
273            ),
274            ("Contract", None, "Contract"),
275        ] {
276            let contract = ContractInfo::from_str(input).unwrap();
277            assert_eq!(contract.path, expected_path.map(ToString::to_string));
278            assert_eq!(contract.name, expected_name.to_string());
279        }
280    }
281
282    #[test]
283    fn contract_info_should_reject_without_name() {
284        for input in ["src/contracts/", "src/contracts/Contracts.sol"] {
285            let contract = ContractInfo::from_str(input);
286            assert!(contract.is_err());
287        }
288    }
289
290    #[test]
291    fn can_parse_oz_dep() {
292        let dep = Dependency::from_str("@openzeppelin/contracts-upgradeable").unwrap();
293        assert_eq!(dep.name, "contracts-upgradeable");
294        assert_eq!(
295            dep.url,
296            Some("https://github.com/openzeppelin/contracts-upgradeable".to_string())
297        );
298        assert_eq!(dep.tag, None);
299        assert_eq!(dep.alias, None);
300    }
301
302    #[test]
303    fn can_parse_oz_dep_tag() {
304        let dep = Dependency::from_str("@openzeppelin/contracts-upgradeable@v1").unwrap();
305        assert_eq!(dep.name, "contracts-upgradeable");
306        assert_eq!(
307            dep.url,
308            Some("https://github.com/openzeppelin/contracts-upgradeable".to_string())
309        );
310        assert_eq!(dep.tag, Some("v1".to_string()));
311        assert_eq!(dep.alias, None);
312    }
313
314    #[test]
315    fn can_parse_oz_with_tag() {
316        let dep = Dependency::from_str("OpenZeppelin/openzeppelin-contracts@v4.7.0").unwrap();
317        assert_eq!(dep.name, "openzeppelin-contracts");
318        assert_eq!(
319            dep.url,
320            Some("https://github.com/OpenZeppelin/openzeppelin-contracts".to_string())
321        );
322        assert_eq!(dep.tag, Some("v4.7.0".to_string()));
323        assert_eq!(dep.alias, None);
324
325        let dep = Dependency::from_str("OpenZeppelin/openzeppelin-contracts@4.7.0").unwrap();
326        assert_eq!(dep.name, "openzeppelin-contracts");
327        assert_eq!(
328            dep.url,
329            Some("https://github.com/OpenZeppelin/openzeppelin-contracts".to_string())
330        );
331        assert_eq!(dep.tag, Some("4.7.0".to_string()));
332        assert_eq!(dep.alias, None);
333    }
334
335    // <https://github.com/foundry-rs/foundry/pull/3130>
336    #[test]
337    fn can_parse_oz_with_alias() {
338        let dep =
339            Dependency::from_str("@openzeppelin=OpenZeppelin/openzeppelin-contracts").unwrap();
340        assert_eq!(dep.name, "openzeppelin-contracts");
341        assert_eq!(dep.alias, Some("@openzeppelin".to_string()));
342        assert_eq!(
343            dep.url,
344            Some("https://github.com/OpenZeppelin/openzeppelin-contracts".to_string())
345        );
346    }
347
348    #[test]
349    fn can_parse_aave() {
350        let dep = Dependency::from_str("@aave/aave-v3-core").unwrap();
351        assert_eq!(dep.name, "aave-v3-core");
352        assert_eq!(dep.url, Some("https://github.com/aave/aave-v3-core".to_string()));
353    }
354
355    #[test]
356    fn can_parse_aave_with_alias() {
357        let dep = Dependency::from_str("@aave=aave/aave-v3-core").unwrap();
358        assert_eq!(dep.name, "aave-v3-core");
359        assert_eq!(dep.alias, Some("@aave".to_string()));
360        assert_eq!(dep.url, Some("https://github.com/aave/aave-v3-core".to_string()));
361    }
362
363    #[test]
364    fn can_parse_org_ssh_url() {
365        let org_url = "org-git12345678@github.com:my-org/my-repo.git";
366        assert!(GH_REPO_PREFIX_REGEX.is_match(org_url));
367    }
368
369    #[test]
370    fn can_parse_org_shh_url_dependency() {
371        let dep: Dependency = "org-git12345678@github.com:my-org/my-repo.git".parse().unwrap();
372        assert_eq!(dep.url.unwrap(), "https://github.com/my-org/my-repo");
373    }
374
375    #[test]
376    fn can_parse_with_explicit_ref_type() {
377        let dep = Dependency::from_str("smartcontractkit/ccip@tag=contracts-ccip/v1.2.1").unwrap();
378        assert_eq!(dep.name, "ccip");
379        assert_eq!(dep.url, Some("https://github.com/smartcontractkit/ccip".to_string()));
380        assert_eq!(dep.tag, Some("contracts-ccip/v1.2.1".to_string()));
381        assert_eq!(dep.alias, None);
382
383        let dep =
384            Dependency::from_str("smartcontractkit/ccip@branch=contracts-ccip/v1.2.1").unwrap();
385        assert_eq!(dep.name, "ccip");
386        assert_eq!(dep.url, Some("https://github.com/smartcontractkit/ccip".to_string()));
387        assert_eq!(dep.tag, Some("contracts-ccip/v1.2.1".to_string()));
388        assert_eq!(dep.alias, None);
389
390        let dep = Dependency::from_str("smartcontractkit/ccip@rev=80eb41b").unwrap();
391        assert_eq!(dep.name, "ccip");
392        assert_eq!(dep.url, Some("https://github.com/smartcontractkit/ccip".to_string()));
393        assert_eq!(dep.tag, Some("80eb41b".to_string()));
394        assert_eq!(dep.alias, None);
395    }
396
397    #[test]
398    fn can_parse_https_with_github_token() {
399        // <https://github.com/foundry-rs/foundry/issues/9717>
400        let dep = Dependency::from_str(
401            "https://ghp_mytoken@github.com/private-org/precompiles-solidity.git",
402        )
403        .unwrap();
404        assert_eq!(dep.name, "precompiles-solidity");
405        assert_eq!(
406            dep.url,
407            Some("https://ghp_mytoken@github.com/private-org/precompiles-solidity".to_string())
408        );
409    }
410}
foundry_cli/opts/dependency.rs

foundry_cli/opts/
dependency.rs
