1#[derive(Debug, Clone, PartialEq, Eq)]
27pub struct HandleKind {
28 pub sector: String,
29 pub kind: String,
30 pub handle: String,
31 pub declared: bool,
32 pub subject: Option<String>,
33}
34
35pub const KIND_SECTORS: &[(&str, &[&str])] = &[
37 (
39 "mcard",
40 &[
41 "content", "knowledge", "schema", "contract", "registry", "record", "projection",
42 "derived", "lifecycle",
43 "artifact", "commit", "design_decision", "feedback", "specification",
46 "sprint_status", "telemetry", "test_result",
47 ],
48 ),
49 ("doc", &["vault", "document"]),
50 ("pcard", &["program", "sprint"]),
51 ("vcard", &["seal", "execution", "contract"]),
52 ("agent", &["root", "actor"]),
54 ("node", &["did", "peer"]),
55 ("key", &["pub", "rotate"]),
56 ("execution", &["record", "trace", "migration"]),
58 ("telemetry", &["event"]),
59];
60
61pub const CHANGE_CALCULUS: &[&str] = &[
64 "CREATE", "UPDATE", "SEAL", "RELOCATE", "ROTATE", "TOMBSTONE",
65];
66
67fn split_handle(handle: &str) -> Option<(&str, &str, Option<&str>)> {
72 let rest = handle.strip_prefix("urn:mcard:")?;
75 let (sector, rest) = rest.split_once(':')?;
76 let (kind, subject) = match rest.split_once(':') {
77 Some((k, s)) => (k, Some(s)),
78 None => (rest, None),
79 };
80 let lower = |s: &str| !s.is_empty() && s.bytes().all(|b| b.is_ascii_lowercase() || b == b'_');
81 if !lower(sector) || !lower(kind) {
82 return None;
83 }
84 Some((sector, kind, subject))
85}
86
87pub fn kind_of(handle: &str) -> Option<HandleKind> {
89 let (sector, kind, subject) = split_handle(handle)?;
90 let declared = KIND_SECTORS
91 .iter()
92 .find(|(s, _)| *s == sector)
93 .map(|(_, kinds)| kinds.contains(&kind))
94 .unwrap_or(false);
95 Some(HandleKind {
96 sector: sector.to_string(),
97 kind: kind.to_string(),
98 handle: handle.to_string(),
99 declared,
100 subject: subject.map(str::to_string),
101 })
102}
103
104pub fn sector_of(handle: &str) -> Option<&str> {
106 split_handle(handle).map(|(s, _, _)| s)
107}
108
109pub fn kind_name_of(handle: &str) -> Option<&str> {
111 split_handle(handle).map(|(_, k, _)| k)
112}
113
114pub fn is_sector(handle: &str, sector: &str) -> bool {
116 sector_of(handle) == Some(sector)
117}
118
119pub fn is_declared(handle: &str) -> bool {
121 kind_of(handle).map(|k| k.declared).unwrap_or(false)
122}
123
124pub fn declared_kinds() -> Vec<String> {
126 let mut out: Vec<String> = KIND_SECTORS
127 .iter()
128 .flat_map(|(s, kinds)| kinds.iter().map(move |k| format!("{s}:{k}")))
129 .collect();
130 out.sort();
131 out
132}
133
134#[cfg(test)]
135mod tests {
136 use super::*;
137
138 #[test]
139 fn parses_the_declared_sectors() {
140 let k = kind_of("urn:mcard:pcard:sprint:orc-02").expect("a handle");
141 assert_eq!(k.sector, "pcard");
142 assert_eq!(k.kind, "sprint");
143 assert_eq!(k.subject.as_deref(), Some("orc-02"));
144 assert!(k.declared);
145 }
146
147 #[test]
148 fn a_subject_may_contain_colons() {
149 let k = kind_of("urn:mcard:node:did:key:z6Mk").expect("a handle");
150 assert_eq!(k.sector, "node");
151 assert_eq!(k.kind, "did");
152 assert_eq!(k.subject.as_deref(), Some("key:z6Mk"));
153 }
154
155 #[test]
156 fn an_undeclared_kind_is_a_finding_not_a_null() {
157 let k = kind_of("urn:mcard:bogus:thing").expect("well formed");
158 assert!(!k.declared, "an undeclared kind must report declared:false");
159 }
160
161 #[test]
162 fn a_non_handle_is_none() {
163 assert!(kind_of("not-a-handle").is_none());
164 assert!(kind_of("urn:mcard:Pcard:Sprint").is_none(), "the grammar is lowercase");
165 assert!(kind_of("urn:mcard:pcard").is_none(), "no kind");
166 assert!(kind_of("").is_none());
167 }
168
169 #[test]
170 fn declared_kinds_matches_the_other_bindings() {
171 assert_eq!(declared_kinds().len(), 34);
174 }
175}