use core::{
fmt,
str::FromStr,
};
use serde::{
Deserialize,
Deserializer,
Serialize,
Serializer,
};
use crate::{
data::catalog::error::{
CatalogErrorExt,
CatalogRule,
catalog_error,
},
errors::{
BunsenError,
BunsenResult,
},
};
const YAML_WORDS: [&str; 12] = [
"true", "false", "null", "yes", "no", "on", "off", "y", "n", "nan", "inf", "infinity",
];
pub fn is_segment(segment: &str) -> bool {
let mut chars = segment.chars();
chars
.next()
.is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
&& chars.all(|c| c.is_ascii_alphanumeric() || matches!(c, '_' | '-' | '.'))
&& !YAML_WORDS.iter().any(|w| w.eq_ignore_ascii_case(segment))
}
pub const HUB_ROOT: &str = "hf";
pub fn is_hub_segment(segment: &str) -> bool {
!segment.is_empty()
&& segment != "."
&& segment != ".."
&& segment
.chars()
.all(|c| c.is_ascii_alphanumeric() || matches!(c, '_' | '-' | '.'))
}
pub fn check_segment(segment: &str) -> BunsenResult<()> {
if is_segment(segment) {
Ok(())
} else {
Err(catalog_error(
CatalogRule::Name,
format!(
"`{segment}` is not a name segment: it must start with an ASCII letter or `_`, \
continue with ASCII letters, digits, `_`, `-` or `.`, and not be a YAML word"
),
))
}
}
pub const CONTRACTS: &str = "$contracts";
#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct CatalogName(Vec<String>);
impl PartialEq<str> for CatalogName {
fn eq(
&self,
other: &str,
) -> bool {
let mut parts = other.split('/');
self.0.iter().all(|s| parts.next() == Some(s.as_str())) && parts.next().is_none()
}
}
impl PartialEq<&str> for CatalogName {
fn eq(
&self,
other: &&str,
) -> bool {
self == *other
}
}
impl PartialEq<String> for CatalogName {
fn eq(
&self,
other: &String,
) -> bool {
self == other.as_str()
}
}
impl CatalogName {
pub fn parse(name: &str) -> BunsenResult<Self> {
if name.is_empty() {
return Err(catalog_error(CatalogRule::Name, "a name is empty"));
}
let segments: Vec<String> = name.split('/').map(str::to_string).collect();
let named = match segments.split_first() {
Some((first, rest)) if first == CONTRACTS => rest,
Some((first, rest)) if first == HUB_ROOT => {
if let Some(bad) = rest.iter().find(|s| !is_hub_segment(s)) {
return Err(catalog_error(
CatalogRule::Name,
format!("in `{name}`: `{bad}` is not a Hub name segment"),
));
}
&[][..]
}
_ => &segments[..],
};
for segment in named {
check_segment(segment).map_err(|e| {
catalog_error(
CatalogRule::Name,
format!("in `{name}`: {}", e.problem_message()),
)
})?;
}
Ok(Self(segments))
}
pub fn contracts_root() -> Self {
Self(vec![CONTRACTS.to_string()])
}
pub fn in_contracts(&self) -> bool {
self.0.first().is_some_and(|s| s == CONTRACTS)
}
pub fn contract_path(&self) -> Option<String> {
self.in_contracts()
.then(|| self.0[1..].join("/"))
.filter(|path| !path.is_empty())
}
pub fn root(segment: &str) -> BunsenResult<Self> {
check_segment(segment)?;
Ok(Self(vec![segment.to_string()]))
}
pub fn child(
&self,
segment: &str,
) -> BunsenResult<Self> {
check_segment(segment)?;
let mut segments = self.0.clone();
segments.push(segment.to_string());
Ok(Self(segments))
}
pub fn under(
scope: Option<&CatalogName>,
segment: &str,
) -> BunsenResult<Self> {
match scope {
Some(scope) => scope.child(segment),
None => Self::root(segment),
}
}
pub fn segments(&self) -> &[String] {
&self.0
}
pub fn leaf(&self) -> &str {
self.0.last().expect("a name has a segment")
}
pub fn scope(&self) -> Option<CatalogName> {
(self.0.len() > 1).then(|| Self(self.0[..self.0.len() - 1].to_vec()))
}
pub fn is_within(
&self,
ancestor: &CatalogName,
) -> bool {
self.0.starts_with(&ancestor.0)
}
pub fn common_scope(
&self,
other: &CatalogName,
) -> Option<CatalogName> {
let n = self
.0
.iter()
.zip(&other.0)
.take_while(|(a, b)| a == b)
.count();
(n > 0).then(|| Self(self.0[..n].to_vec()))
}
}
impl fmt::Display for CatalogName {
fn fmt(
&self,
f: &mut fmt::Formatter<'_>,
) -> fmt::Result {
f.write_str(&self.0.join("/"))
}
}
impl fmt::Debug for CatalogName {
fn fmt(
&self,
f: &mut fmt::Formatter<'_>,
) -> fmt::Result {
write!(f, "`{self}`")
}
}
impl FromStr for CatalogName {
type Err = BunsenError;
fn from_str(s: &str) -> BunsenResult<Self> {
Self::parse(s)
}
}
impl Serialize for CatalogName {
fn serialize<S: Serializer>(
&self,
serializer: S,
) -> Result<S::Ok, S::Error> {
serializer.collect_str(self)
}
}
impl<'de> Deserialize<'de> for CatalogName {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
let s = String::deserialize(deserializer)?;
Self::parse(&s).map_err(serde::de::Error::custom)
}
}
impl CatalogName {
pub fn join(
&self,
other: &CatalogName,
) -> CatalogName {
let mut segments = self.0.clone();
segments.extend(other.0.iter().cloned());
Self(segments)
}
}
#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct CatalogRef {
absolute: bool,
path: CatalogName,
}
impl CatalogRef {
pub fn parse(reference: &str) -> BunsenResult<Self> {
let (absolute, rest) = match reference.strip_prefix('/') {
Some(rest) => (true, rest),
None => (false, reference),
};
Ok(Self {
absolute,
path: CatalogName::parse(rest)?,
})
}
pub fn absolute(name: CatalogName) -> Self {
Self {
absolute: true,
path: name,
}
}
pub fn is_absolute(&self) -> bool {
self.absolute
}
pub fn path(&self) -> &CatalogName {
&self.path
}
pub fn candidates(
&self,
from: Option<&CatalogName>,
) -> Vec<CatalogName> {
let mut out = Vec::new();
if !self.absolute {
let mut scope = from.cloned();
while let Some(s) = scope {
out.push(s.join(&self.path));
scope = s.scope();
}
}
out.push(self.path.clone());
out
}
}
impl fmt::Display for CatalogRef {
fn fmt(
&self,
f: &mut fmt::Formatter<'_>,
) -> fmt::Result {
if self.absolute {
f.write_str("/")?;
}
write!(f, "{}", self.path)
}
}
impl fmt::Debug for CatalogRef {
fn fmt(
&self,
f: &mut fmt::Formatter<'_>,
) -> fmt::Result {
write!(f, "`{self}`")
}
}
impl FromStr for CatalogRef {
type Err = BunsenError;
fn from_str(s: &str) -> BunsenResult<Self> {
Self::parse(s)
}
}
impl Serialize for CatalogRef {
fn serialize<S: Serializer>(
&self,
serializer: S,
) -> Result<S::Ok, S::Error> {
serializer.collect_str(self)
}
}
impl<'de> Deserialize<'de> for CatalogRef {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
let s = String::deserialize(deserializer)?;
Self::parse(&s).map_err(serde::de::Error::custom)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_segments_are_plain_yaml_keys() {
for ok in ["qwen3", "qwen3-0.6b", "tiny.en", "_x", "qwen3.5", "a-b_c.d"] {
assert!(is_segment(ok), "{ok}");
}
for bad in [
"", "0x", "-a", ".", "..", "a/b", "a b", "yes", "No", "NULL", "inf", "ü", "a:b",
] {
assert!(!is_segment(bad), "{bad}");
}
}
#[test]
fn test_parse_and_display_round_trip() {
let name = CatalogName::parse("qwen/qwen3/qwen3-4b").unwrap();
assert_eq!(name.segments(), ["qwen", "qwen3", "qwen3-4b"]);
assert_eq!(name.leaf(), "qwen3-4b");
assert_eq!(name.to_string(), "qwen/qwen3/qwen3-4b");
assert_eq!(
name, "qwen/qwen3/qwen3-4b",
"a name equals its written form"
);
assert_ne!(name, "qwen/qwen3");
assert_ne!(name, "qwen/qwen3/qwen3-4b/x");
assert_eq!(name.scope().unwrap().to_string(), "qwen/qwen3");
assert_eq!(CatalogName::root("qwen").unwrap().scope(), None);
}
#[test]
fn test_hub_names_keep_the_hubs_spelling() {
let name = CatalogName::parse("hf/01-ai/Yi-6B").unwrap();
assert_eq!(name.segments(), ["hf", "01-ai", "Yi-6B"]);
assert_eq!(name.to_string(), "hf/01-ai/Yi-6B");
for bad in ["hf/a b/c", "hf//c", "hf/../c", "hf/a:b"] {
assert!(CatalogName::parse(bad).is_err(), "{bad}");
}
assert!(
CatalogName::parse("other/01-ai").is_err(),
"only under `hf`"
);
}
#[test]
fn test_parse_rejects_bad_names() {
for bad in ["", "/a", "a/", "a//b", "a/yes", "a/0b"] {
let err = CatalogName::parse(bad).unwrap_err();
assert_eq!(err.rule(), Some(CatalogRule::Name), "{bad}");
}
}
#[test]
fn test_within_and_common_scope() {
let a = CatalogName::parse("qwen/qwen3/a").unwrap();
let b = CatalogName::parse("qwen/qwen3/b").unwrap();
let c = CatalogName::parse("openai/whisper").unwrap();
let qwen3 = CatalogName::parse("qwen/qwen3").unwrap();
assert!(a.is_within(&qwen3));
assert!(qwen3.is_within(&qwen3));
assert!(!c.is_within(&qwen3));
assert_eq!(a.common_scope(&b), Some(qwen3));
assert_eq!(a.common_scope(&c), None);
}
#[test]
fn test_serde_as_a_string() {
let name: CatalogName = serde_json::from_str("\"qwen/qwen3\"").unwrap();
assert_eq!(serde_json::to_string(&name).unwrap(), "\"qwen/qwen3\"");
assert!(serde_json::from_str::<CatalogName>("\"qwen/yes\"").is_err());
}
#[test]
fn test_references_climb_to_the_root() {
let from = CatalogName::parse("openai/whisper/large/large-v1").unwrap();
let relative = CatalogRef::parse("release").unwrap();
let shown: Vec<String> = relative
.candidates(Some(&from))
.iter()
.map(ToString::to_string)
.collect();
assert_eq!(
shown,
[
"openai/whisper/large/large-v1/release",
"openai/whisper/large/release",
"openai/whisper/release",
"openai/release",
"release",
]
);
let absolute = CatalogRef::parse("/release").unwrap();
assert!(absolute.is_absolute());
assert_eq!(absolute.to_string(), "/release");
assert_eq!(
absolute.candidates(Some(&from)),
[CatalogName::parse("release").unwrap()]
);
assert!(CatalogRef::parse("//x").is_err());
assert!(CatalogRef::parse("/").is_err());
}
}