#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HandleKind {
pub sector: String,
pub kind: String,
pub handle: String,
pub declared: bool,
pub subject: Option<String>,
}
pub const KIND_SECTORS: &[(&str, &[&str])] = &[
(
"mcard",
&[
"content", "knowledge", "schema", "contract", "registry", "record", "projection",
"derived", "lifecycle",
"artifact", "commit", "design_decision", "feedback", "specification",
"sprint_status", "telemetry", "test_result",
"function",
],
),
("doc", &["vault", "document"]),
("pcard", &["program", "sprint", "fiber"]),
("vcard", &["seal", "execution", "contract"]),
("agent", &["root", "actor"]),
("node", &["did", "peer"]),
("key", &["pub", "rotate"]),
("execution", &["record", "trace", "migration"]),
("telemetry", &["event"]),
];
pub use crate::layer0::transition::CHANGE_CALCULUS;
fn split_handle(handle: &str) -> Option<(&str, &str, Option<&str>)> {
let lower = |s: &str| !s.is_empty() && s.bytes().all(|b| b.is_ascii_lowercase() || b == b'_');
if let Some(rest) = handle.strip_prefix("urn:pcard:") {
let (kind, subject) = match rest.split_once(':') {
Some((k, s)) => (k, Some(s)),
None => (rest, None),
};
if !lower(kind) {
return None;
}
return Some(("pcard", kind, subject));
}
if let Some(rest) = handle.strip_prefix("urn:vcard:") {
let (kind, subject) = match rest.split_once(':') {
Some((k, s)) => (k, Some(s)),
None => (rest, None),
};
if !lower(kind) {
return None;
}
return Some(("vcard", kind, subject));
}
let rest = handle.strip_prefix(crate::layer0::vocabulary::URI_SCHEME_URN_MCARD)?;
let (sector, rest) = rest.split_once(':')?;
let (kind, subject) = match rest.split_once(':') {
Some((k, s)) => (k, Some(s)),
None => (rest, None),
};
if !lower(sector) || !lower(kind) {
return None;
}
Some((sector, kind, subject))
}
pub fn kind_of(handle: &str) -> Option<HandleKind> {
let (sector, kind, subject) = split_handle(handle)?;
let declared = KIND_SECTORS
.iter()
.find(|(s, _)| *s == sector)
.map(|(_, kinds)| kinds.contains(&kind))
.unwrap_or(false);
Some(HandleKind {
sector: sector.to_string(),
kind: kind.to_string(),
handle: handle.to_string(),
declared,
subject: subject.map(str::to_string),
})
}
pub fn sector_of(handle: &str) -> Option<&str> {
split_handle(handle).map(|(s, _, _)| s)
}
pub fn kind_name_of(handle: &str) -> Option<&str> {
split_handle(handle).map(|(_, k, _)| k)
}
pub fn is_sector(handle: &str, sector: &str) -> bool {
sector_of(handle) == Some(sector)
}
pub fn is_declared(handle: &str) -> bool {
kind_of(handle).map(|k| k.declared).unwrap_or(false)
}
pub fn declared_kinds() -> Vec<String> {
let mut out: Vec<String> = KIND_SECTORS
.iter()
.flat_map(|(s, kinds)| kinds.iter().map(move |k| format!("{s}:{k}")))
.collect();
out.sort();
out
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parses_the_declared_sectors() {
let k = kind_of("urn:pcard:sprint:orc-02").expect("a handle");
assert_eq!(k.sector, "pcard");
assert_eq!(k.kind, "sprint");
assert_eq!(k.subject.as_deref(), Some("orc-02"));
assert!(k.declared);
let v = kind_of("urn:vcard:seal:9f2c").expect("a handle");
assert_eq!(v.sector, "vcard");
assert_eq!(v.kind, "seal");
assert_eq!(v.subject.as_deref(), Some("9f2c"));
assert!(v.declared);
}
#[test]
fn a_subject_may_contain_colons() {
let k = kind_of("urn:mcard:node:did:key:z6Mk").expect("a handle");
assert_eq!(k.sector, "node");
assert_eq!(k.kind, "did");
assert_eq!(k.subject.as_deref(), Some("key:z6Mk"));
}
#[test]
fn an_undeclared_kind_is_a_finding_not_a_null() {
let k = kind_of("urn:mcard:bogus:thing").expect("well formed");
assert!(!k.declared, "an undeclared kind must report declared:false");
}
#[test]
fn a_non_handle_is_none() {
assert!(kind_of("not-a-handle").is_none());
assert!(kind_of("urn:mcard:Pcard:Sprint").is_none(), "the grammar is lowercase");
assert!(kind_of("urn:mcard:pcard").is_none(), "no kind");
assert!(kind_of("urn:pcard").is_none(), "no kind");
assert!(kind_of("urn:vcard").is_none(), "no kind");
assert!(kind_of("").is_none());
}
#[test]
fn declared_kinds_matches_the_other_bindings() {
assert_eq!(declared_kinds().len(), 36);
}
}