use std::path::{Path, PathBuf};
use anyhow::{bail, Result};
use crate::http::HttpClient;
use crate::lockfiles::npm_ecosystem_read;
use crate::resolvers::get_resolver;
use crate::sources::github::{self, GithubOptions};
use crate::sources::FetchResult;
use crate::spec::{parse_spec, split_explicit_version, ParsedSpec};
use crate::store::{github_store_path, resolve_ask_home};
const DEFAULT_GITHUB_HOST: &str = "github.com";
#[derive(Debug, Clone)]
pub struct EnsureCheckoutOptions {
pub spec: String,
pub project_dir: PathBuf,
pub no_fetch: bool,
}
#[derive(Debug, Clone)]
pub struct EnsureCheckoutResult {
pub parsed: ParsedSpec,
pub owner: String,
pub repo: String,
pub reference: String,
pub resolved_version: String,
pub checkout_dir: PathBuf,
pub npm_package_name: Option<String>,
pub from_cache: bool,
}
#[derive(Debug, thiserror::Error)]
#[error("no cached checkout for {spec} (expected at {checkout_dir})")]
pub struct NoCacheError {
pub checkout_dir: PathBuf,
pub spec: String,
}
pub trait CheckoutFetcher {
fn fetch(
&self,
client: &dyn HttpClient,
opts: &GithubOptions,
ask_home: &Path,
) -> Result<Option<FetchResult>>;
}
pub struct GithubCheckoutFetcher;
impl CheckoutFetcher for GithubCheckoutFetcher {
fn fetch(
&self,
client: &dyn HttpClient,
opts: &GithubOptions,
ask_home: &Path,
) -> Result<Option<FetchResult>> {
github::fetch(client, opts, ask_home).map(Some)
}
}
#[derive(Default)]
pub struct EnsureCheckoutDeps<'a> {
pub ask_home: Option<PathBuf>,
pub fetcher: Option<&'a dyn CheckoutFetcher>,
}
pub fn ensure_checkout(
client: &dyn HttpClient,
options: &EnsureCheckoutOptions,
deps: &EnsureCheckoutDeps,
) -> Result<EnsureCheckoutResult> {
let ask_home = deps.ask_home.clone().unwrap_or_else(resolve_ask_home);
let default_fetcher = GithubCheckoutFetcher;
let fetcher: &dyn CheckoutFetcher = deps.fetcher.unwrap_or(&default_fetcher);
let (spec_body, explicit_version) = split_explicit_version(&options.spec);
let parsed = parse_spec(spec_body);
let owner: String;
let repo: String;
let reference: String;
let resolved_version: String;
let mut npm_package_name: Option<String> = None;
let mut fallback_refs: Vec<String> = Vec::new();
let mut is_from_branch = false;
let mut is_implicit_default_ref = false;
match &parsed {
ParsedSpec::Github {
owner: o, repo: r, ..
} => {
owner = o.clone();
repo = r.clone();
reference = explicit_version.unwrap_or("main").to_string();
resolved_version = reference.clone();
is_from_branch = explicit_version.is_none(); is_implicit_default_ref = explicit_version.is_none();
}
_ => {
let ecosystem = match &parsed {
ParsedSpec::Npm { .. } => "npm",
ParsedSpec::Unknown { ecosystem, .. } if ecosystem.is_empty() => "npm", ParsedSpec::Unknown { ecosystem, .. } => ecosystem.as_str(),
ParsedSpec::Github { .. } => unreachable!(),
};
let pkg_name = match &parsed {
ParsedSpec::Npm { pkg, .. } => pkg.clone(),
ParsedSpec::Unknown { payload, .. } => payload.clone(),
ParsedSpec::Github { .. } => unreachable!(),
};
if ecosystem == "npm" {
npm_package_name = Some(pkg_name.clone());
}
let Some(resolver) = get_resolver(ecosystem) else {
bail!(
"unsupported ecosystem '{ecosystem}' for spec '{}'. \
Supported ecosystems: npm, pypi, pub, maven",
options.spec
);
};
let query_version = match explicit_version {
Some(v) => v.to_string(),
None => {
let from_lock = if ecosystem == "npm" {
npm_ecosystem_read(&pkg_name, &options.project_dir).map(|h| h.version)
} else {
None
};
from_lock.unwrap_or_else(|| "latest".to_string())
}
};
let result = resolver(client, &pkg_name, &query_version)?;
let Some((o, r)) = result.repo.split_once('/') else {
bail!(
"resolver returned malformed repo '{}' for spec '{}'",
result.repo,
options.spec
);
};
owner = o.to_string();
repo = r.to_string();
reference = result.ref_;
resolved_version = result.resolved_version;
fallback_refs = result.fallback_refs;
}
}
let checkout_dir =
github_store_path(&ask_home, DEFAULT_GITHUB_HOST, &owner, &repo, &reference)?;
if checkout_dir.exists() {
return Ok(EnsureCheckoutResult {
parsed,
owner,
repo,
reference,
resolved_version,
checkout_dir,
npm_package_name,
from_cache: true,
});
}
if options.no_fetch {
return Err(NoCacheError {
checkout_dir,
spec: options.spec.clone(),
}
.into());
}
let (branch, tag) = if is_implicit_default_ref {
(None, None)
} else if is_from_branch {
(Some(reference.clone()), None)
} else {
(None, Some(reference.clone()))
};
let opts = GithubOptions {
name: parsed.name().to_string(),
version: resolved_version.clone(),
repo: format!("{owner}/{repo}"),
branch,
tag,
docs_path: None,
fallback_refs,
remote_url: None,
skip_doc_extraction: true,
};
let fetch_result = fetcher.fetch(client, &opts, &ask_home)?;
let resolved_checkout_dir = fetch_result
.as_ref()
.and_then(|r| r.store_path.clone())
.unwrap_or_else(|| checkout_dir.clone());
let actual_ref = if resolved_checkout_dir == checkout_dir {
reference
} else {
resolved_checkout_dir
.file_name()
.map(|n| n.to_string_lossy().into_owned())
.unwrap_or(reference)
};
Ok(EnsureCheckoutResult {
parsed,
owner,
repo,
reference: actual_ref,
resolved_version,
checkout_dir: resolved_checkout_dir,
npm_package_name,
from_cache: fetch_result
.as_ref()
.map(|r| r.from_store_cache)
.unwrap_or(false),
})
}
#[cfg(test)]
mod tests {
use super::*;
use crate::http::mock::MockClient;
fn no_http() -> MockClient {
MockClient::new()
}
fn opts(spec: &str, project_dir: &Path, no_fetch: bool) -> EnsureCheckoutOptions {
EnsureCheckoutOptions {
spec: spec.to_string(),
project_dir: project_dir.to_path_buf(),
no_fetch,
}
}
struct MkdirFetcher {
from_store_cache: bool,
}
impl CheckoutFetcher for MkdirFetcher {
fn fetch(
&self,
_client: &dyn HttpClient,
o: &GithubOptions,
ask_home: &Path,
) -> Result<Option<FetchResult>> {
let (owner, repo) = o.repo.split_once('/').unwrap();
let reference = o
.tag
.clone()
.or_else(|| o.branch.clone())
.unwrap_or_else(|| "main".into());
let dir = github_store_path(ask_home, DEFAULT_GITHUB_HOST, owner, repo, &reference)?;
std::fs::create_dir_all(&dir)?;
Ok(Some(FetchResult {
files: Vec::new(),
resolved_version: o.version.clone(),
store_path: Some(dir),
store_subpath: None,
from_store_cache: self.from_store_cache,
meta: Default::default(),
}))
}
}
#[test]
fn github_direct_spec_cache_hit() {
let home = tempfile::tempdir().unwrap();
let proj = tempfile::tempdir().unwrap();
let dir = github_store_path(
home.path(),
DEFAULT_GITHUB_HOST,
"facebook",
"react",
"v18.2.0",
)
.unwrap();
std::fs::create_dir_all(&dir).unwrap();
let deps = EnsureCheckoutDeps {
ask_home: Some(home.path().to_path_buf()),
fetcher: None,
};
let res = ensure_checkout(
&no_http(),
&opts("github:facebook/react@v18.2.0", proj.path(), false),
&deps,
)
.unwrap();
assert_eq!(res.owner, "facebook");
assert_eq!(res.repo, "react");
assert_eq!(res.reference, "v18.2.0");
assert_eq!(res.checkout_dir, dir);
assert!(res.from_cache);
assert!(res.npm_package_name.is_none());
}
#[test]
fn github_bare_spec_defaults_to_main() {
let home = tempfile::tempdir().unwrap();
let proj = tempfile::tempdir().unwrap();
let dir =
github_store_path(home.path(), DEFAULT_GITHUB_HOST, "owner", "repo", "main").unwrap();
std::fs::create_dir_all(&dir).unwrap();
let deps = EnsureCheckoutDeps {
ask_home: Some(home.path().to_path_buf()),
fetcher: None,
};
let res = ensure_checkout(
&no_http(),
&opts("github:owner/repo", proj.path(), false),
&deps,
)
.unwrap();
assert_eq!(res.reference, "main");
assert_eq!(res.resolved_version, "main");
assert!(res.from_cache);
}
#[test]
fn no_fetch_miss_raises_no_cache_error() {
let home = tempfile::tempdir().unwrap();
let proj = tempfile::tempdir().unwrap();
let deps = EnsureCheckoutDeps {
ask_home: Some(home.path().to_path_buf()),
fetcher: None,
};
let err = ensure_checkout(
&no_http(),
&opts("github:owner/repo@v1.2.3", proj.path(), true),
&deps,
)
.unwrap_err();
let nce = err.downcast_ref::<NoCacheError>().expect("NoCacheError");
assert_eq!(nce.spec, "github:owner/repo@v1.2.3");
assert!(nce
.checkout_dir
.ends_with("github/github.com/owner/repo/v1.2.3"));
}
#[test]
fn npm_spec_resolves_via_registry_then_cache_hit() {
let home = tempfile::tempdir().unwrap();
let proj = tempfile::tempdir().unwrap();
let client = MockClient::new().with(
"https://registry.npmjs.org/react",
200,
r#"{"dist-tags":{},"versions":{"18.3.1":{}},"repository":{"url":"https://github.com/facebook/react.git"}}"#,
);
let dir = github_store_path(
home.path(),
DEFAULT_GITHUB_HOST,
"facebook",
"react",
"v18.3.1",
)
.unwrap();
std::fs::create_dir_all(&dir).unwrap();
let deps = EnsureCheckoutDeps {
ask_home: Some(home.path().to_path_buf()),
fetcher: None,
};
let res = ensure_checkout(
&client,
&opts("npm:react@18.3.1", proj.path(), false),
&deps,
)
.unwrap();
assert_eq!(res.owner, "facebook");
assert_eq!(res.repo, "react");
assert_eq!(res.reference, "v18.3.1");
assert_eq!(res.resolved_version, "18.3.1");
assert_eq!(res.npm_package_name.as_deref(), Some("react"));
assert!(res.from_cache);
}
#[test]
fn cache_miss_triggers_fetch_and_reports_store_path() {
let home = tempfile::tempdir().unwrap();
let proj = tempfile::tempdir().unwrap();
let fetcher = MkdirFetcher {
from_store_cache: false,
};
let deps = EnsureCheckoutDeps {
ask_home: Some(home.path().to_path_buf()),
fetcher: Some(&fetcher),
};
let res = ensure_checkout(
&no_http(),
&opts("github:owner/repo@v9.9.9", proj.path(), false),
&deps,
)
.unwrap();
assert_eq!(res.reference, "v9.9.9");
assert!(res.checkout_dir.exists());
assert!(res
.checkout_dir
.ends_with("github/github.com/owner/repo/v9.9.9"));
assert!(!res.from_cache);
}
#[test]
fn npm_bare_name_treated_as_npm_ecosystem() {
let home = tempfile::tempdir().unwrap();
let proj = tempfile::tempdir().unwrap();
let client = MockClient::new().with(
"https://registry.npmjs.org/react",
200,
r#"{"dist-tags":{},"versions":{"18.3.1":{}},"repository":{"url":"https://github.com/facebook/react.git"}}"#,
);
let dir = github_store_path(
home.path(),
DEFAULT_GITHUB_HOST,
"facebook",
"react",
"v18.3.1",
)
.unwrap();
std::fs::create_dir_all(&dir).unwrap();
let deps = EnsureCheckoutDeps {
ask_home: Some(home.path().to_path_buf()),
fetcher: None,
};
let res =
ensure_checkout(&client, &opts("react@18.3.1", proj.path(), false), &deps).unwrap();
assert_eq!(res.npm_package_name.as_deref(), Some("react"));
assert_eq!(res.reference, "v18.3.1");
}
}