pub mod api;
pub use api::{
fetch_registry_entry, resolve_from_registry, RegistryApiPackage, RegistryApiResponse,
RegistryResolution, RegistrySource,
};
use std::path::Path;
pub const REGISTRY_BASE_URL: &str = "https://ask-registry.pages.dev";
pub fn parse_ecosystem(input: &str) -> (Option<&str>, &str) {
let colon = input.find(':');
let slash = input.find('/');
if let Some(c) = colon {
if c > 0 && slash.is_none_or(|s| c < s) {
return (Some(&input[..c]), &input[c + 1..]);
}
}
(None, input)
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ParsedDocSpec {
Github {
owner: String,
repo: String,
ref_: Option<String>,
},
Ecosystem {
ecosystem: String,
name: String,
version: String,
},
Name {
name: String,
version: String,
},
}
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum DocSpecError {
#[error("docs spec is empty — expected `owner/repo`, `ecosystem:name`, or `name`")]
Empty,
#[error(
"invalid docs spec '{0}': github shorthand must contain exactly one slash (owner/repo)"
)]
NotExactlyOneSlash(String),
#[error("invalid docs spec '{0}': owner segment is empty")]
EmptyOwner(String),
#[error("invalid docs spec '{0}': repo segment is empty")]
EmptyRepo(String),
}
fn split_name_version(spec: &str) -> (String, String) {
match spec.rfind('@') {
Some(idx) if idx > 0 => (spec[..idx].to_string(), spec[idx + 1..].to_string()),
_ => (spec.to_string(), "latest".to_string()),
}
}
pub fn parse_doc_spec(input: &str) -> Result<ParsedDocSpec, DocSpecError> {
if input.is_empty() {
return Err(DocSpecError::Empty);
}
if input.contains('/') && !input.contains(':') {
let parts: Vec<&str> = input.split('/').collect();
if parts.len() != 2 {
return Err(DocSpecError::NotExactlyOneSlash(input.to_string()));
}
let owner = parts[0];
let repo_and_ref = parts[1];
if owner.is_empty() {
return Err(DocSpecError::EmptyOwner(input.to_string()));
}
if repo_and_ref.is_empty() {
return Err(DocSpecError::EmptyRepo(input.to_string()));
}
if let Some(at) = repo_and_ref.find('@') {
let repo = &repo_and_ref[..at];
let ref_ = &repo_and_ref[at + 1..];
if repo.is_empty() {
return Err(DocSpecError::EmptyRepo(input.to_string()));
}
return Ok(ParsedDocSpec::Github {
owner: owner.to_string(),
repo: repo.to_string(),
ref_: (!ref_.is_empty()).then(|| ref_.to_string()),
});
}
return Ok(ParsedDocSpec::Github {
owner: owner.to_string(),
repo: repo_and_ref.to_string(),
ref_: None,
});
}
if let Some(colon) = input.find(':') {
if colon > 0 {
let ecosystem = &input[..colon];
let (name, version) = split_name_version(&input[colon + 1..]);
return Ok(ParsedDocSpec::Ecosystem {
ecosystem: ecosystem.to_string(),
name,
version,
});
}
}
let (name, version) = split_name_version(input);
Ok(ParsedDocSpec::Name { name, version })
}
pub fn detect_ecosystem(project_dir: &Path) -> &'static str {
const CHECKS: &[(&str, &str)] = &[
("package.json", "npm"),
("pubspec.yaml", "pub"),
("pyproject.toml", "pypi"),
("requirements.txt", "pypi"),
("go.mod", "go"),
("Cargo.toml", "crates"),
("mix.exs", "hex"),
("pom.xml", "maven"),
("build.gradle", "maven"),
("build.gradle.kts", "maven"),
];
for (file, ecosystem) in CHECKS {
if project_dir.join(file).exists() {
return ecosystem;
}
}
"npm"
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parse_ecosystem_cases() {
assert_eq!(
parse_ecosystem("npm:next@canary"),
(Some("npm"), "next@canary")
);
assert_eq!(parse_ecosystem("next@canary"), (None, "next@canary"));
assert_eq!(
parse_ecosystem("npm:@mastra/client-js"),
(Some("npm"), "@mastra/client-js")
);
assert_eq!(parse_ecosystem("owner/repo"), (None, "owner/repo"));
assert_eq!(parse_ecosystem(":x"), (None, ":x"));
}
#[test]
fn parse_doc_spec_github_shapes() {
assert_eq!(
parse_doc_spec("vercel/next.js").unwrap(),
ParsedDocSpec::Github {
owner: "vercel".into(),
repo: "next.js".into(),
ref_: None
}
);
assert_eq!(
parse_doc_spec("vercel/next.js@v14").unwrap(),
ParsedDocSpec::Github {
owner: "vercel".into(),
repo: "next.js".into(),
ref_: Some("v14".into()),
}
);
assert_eq!(
parse_doc_spec("vercel/next.js@").unwrap(),
ParsedDocSpec::Github {
owner: "vercel".into(),
repo: "next.js".into(),
ref_: None
}
);
}
#[test]
fn parse_doc_spec_github_errors() {
assert_eq!(parse_doc_spec("").unwrap_err(), DocSpecError::Empty);
assert_eq!(
parse_doc_spec("a/b/c").unwrap_err(),
DocSpecError::NotExactlyOneSlash("a/b/c".into())
);
assert_eq!(
parse_doc_spec("/repo").unwrap_err(),
DocSpecError::EmptyOwner("/repo".into())
);
assert_eq!(
parse_doc_spec("owner/").unwrap_err(),
DocSpecError::EmptyRepo("owner/".into())
);
}
#[test]
fn parse_doc_spec_ecosystem_and_name() {
assert_eq!(
parse_doc_spec("npm:next@canary").unwrap(),
ParsedDocSpec::Ecosystem {
ecosystem: "npm".into(),
name: "next".into(),
version: "canary".into(),
}
);
assert_eq!(
parse_doc_spec("next").unwrap(),
ParsedDocSpec::Name {
name: "next".into(),
version: "latest".into()
}
);
assert_eq!(
parse_doc_spec("next@14").unwrap(),
ParsedDocSpec::Name {
name: "next".into(),
version: "14".into()
}
);
assert_eq!(
parse_doc_spec("npm:@scope/pkg@1.0").unwrap(),
ParsedDocSpec::Ecosystem {
ecosystem: "npm".into(),
name: "@scope/pkg".into(),
version: "1.0".into(),
}
);
}
#[test]
fn detect_ecosystem_from_marker_files() {
let dir = tempfile::tempdir().unwrap();
assert_eq!(detect_ecosystem(dir.path()), "npm");
std::fs::write(dir.path().join("Cargo.toml"), "").unwrap();
assert_eq!(detect_ecosystem(dir.path()), "crates");
std::fs::write(dir.path().join("package.json"), "{}").unwrap();
assert_eq!(detect_ecosystem(dir.path()), "npm");
}
}