1use crate::layer0::vocabulary::{HANDLE_MCARD, URI_SCHEME_MCARD};
4use serde::{Deserialize, Serialize};
5
6#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
7pub enum McardUriType {
8 Hash,
9 Handle,
10}
11
12pub type McardUriKind = McardUriType;
13
14#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
15pub struct ParsedMcardUri {
16 pub uri_type: McardUriType,
17 pub target: String,
18 pub fragment: Option<String>,
19 pub original: String,
20}
21
22pub type McardUri = ParsedMcardUri;
23
24#[derive(Debug, Clone, PartialEq, Eq)]
25pub struct TransclusionCycleError {
26 pub cycle_path: Vec<String>,
27}
28
29impl std::fmt::Display for TransclusionCycleError {
30 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
31 write!(f, "Transclusion cycle detected: {}", self.cycle_path.join(" -> "))
32 }
33}
34
35impl std::error::Error for TransclusionCycleError {}
36
37pub fn canonicalize_mcard_uri(path: &str, context_prefix: &str) -> String {
38 let clean = path.trim_start_matches('/');
39 let mut prefix = context_prefix.trim_matches('/');
40 if prefix == "mcard" {
41 prefix = "";
42 }
43 if let Some(rest) = clean.strip_prefix(crate::layer0::vocabulary::HANDLE_MCARD) {
44 let rest = rest.trim_start_matches('/');
45 if prefix.is_empty() || rest == prefix || rest.starts_with(&format!("{prefix}/")) {
46 return format!("{HANDLE_MCARD}{rest}");
47 }
48 return format!("{HANDLE_MCARD}{prefix}/{rest}");
49 }
50 if prefix.is_empty() {
51 format!("{HANDLE_MCARD}{clean}")
52 } else {
53 format!("{HANDLE_MCARD}{prefix}/{clean}")
54 }
55}
56
57const DIGEST_HEX_LENGTH: [(&str, usize); 8] = [
58 (crate::layer0::vocabulary::HASH_ALGORITHM_BLAKE3, 64),
59 (crate::layer0::vocabulary::HASH_ALGORITHM_SHA256, 64),
60 (crate::layer0::vocabulary::HASH_ALGORITHM_SHA3_256, 64),
61 (crate::layer0::vocabulary::HASH_ALGORITHM_SHA384, 96),
62 (crate::layer0::vocabulary::HASH_ALGORITHM_SHA512, 128),
63 (crate::layer0::vocabulary::HASH_ALGORITHM_SHA224, 56),
64 (crate::layer0::vocabulary::HASH_ALGORITHM_SHA1, 40),
65 (crate::layer0::vocabulary::HASH_ALGORITHM_MD5, 32),
66];
67
68pub fn digest_target(value: &str) -> Option<String> {
70 let (algo, hex) = value.split_once(':')?;
71 let algo = algo.to_ascii_lowercase();
72 let hex = hex.to_ascii_lowercase();
73 let expected = DIGEST_HEX_LENGTH
74 .iter()
75 .find(|(name, _)| *name == algo.as_str())
76 .map(|(_, len)| *len)?;
77 if hex.len() != expected || !hex.chars().all(|c| c.is_ascii_hexdigit()) {
78 return None;
79 }
80 Some(format!("{algo}:{hex}"))
81}
82
83pub fn is_qualified_hash(value: &str) -> bool {
84 digest_target(value).is_some()
85}
86
87pub fn format_mcard_uri(parsed: &ParsedMcardUri) -> String {
88 let frag = parsed
89 .fragment
90 .as_ref()
91 .map(|f| format!("#{}", f.trim_start_matches('#')))
92 .unwrap_or_default();
93 let kind = match parsed.uri_type {
94 McardUriType::Hash => "hash",
95 McardUriType::Handle => "handle",
96 };
97 format!("{URI_SCHEME_MCARD}{kind}/{}{frag}", parsed.target)
98}
99
100pub fn parse_mcard_uri(uri: &str) -> std::result::Result<ParsedMcardUri, String> {
101 if uri.is_empty() {
102 return Err("Invalid MCard URI: expected non-empty string".to_string());
103 }
104 let (base, fragment) = match uri.split_once('#') {
105 Some((base, frag)) => (base, Some(frag.to_string())),
106 None => (uri, None),
107 };
108 if let Some(target) = base.strip_prefix(crate::layer0::vocabulary::HANDLE_MCARD_HASH_2) {
109 let target = target.trim_end_matches('/');
110 if !target.contains(':') {
111 return Err(format!("Malformed hash URI: expected '<algorithm>:<hex>', got '{target}'"));
112 }
113 return Ok(ParsedMcardUri {
114 uri_type: McardUriType::Hash,
115 target: target.to_string(),
116 fragment,
117 original: uri.to_string(),
118 });
119 }
120 if let Some(rest) = base.strip_prefix(crate::layer0::vocabulary::HANDLE_MCARD_HANDLE) {
121 let raw = rest.split('?').next().unwrap_or(rest).trim_end_matches('/');
122 return Ok(ParsedMcardUri {
123 uri_type: McardUriType::Handle,
124 target: canonicalize_mcard_uri(raw, ""),
125 fragment,
126 original: uri.to_string(),
127 });
128 }
129 if base.starts_with(crate::layer0::vocabulary::HANDLE_MCARD_RECEIPTS) || base.starts_with(crate::layer0::vocabulary::HANDLE_MCARD_SCHEMAS) {
130 let raw = base.trim_start_matches(crate::layer0::vocabulary::URI_SCHEME_MCARD).trim_end_matches('/');
131 return Ok(ParsedMcardUri {
132 uri_type: McardUriType::Handle,
133 target: canonicalize_mcard_uri(raw, ""),
134 fragment,
135 original: uri.to_string(),
136 });
137 }
138 if let Some(raw) = base.strip_prefix(crate::layer0::vocabulary::URI_SCHEME_MCARD) {
139 let raw = raw.trim_end_matches('/');
140 if let Some(target) = digest_target(raw) {
141 return Ok(ParsedMcardUri {
142 uri_type: McardUriType::Hash,
143 target,
144 fragment,
145 original: uri.to_string(),
146 });
147 }
148 return Ok(ParsedMcardUri {
149 uri_type: McardUriType::Handle,
150 target: canonicalize_mcard_uri(raw, ""),
151 fragment,
152 original: uri.to_string(),
153 });
154 }
155 let candidate = match base.get(..6) {
156 Some(prefix) if prefix.eq_ignore_ascii_case(crate::layer0::vocabulary::HANDLE_MCARD) => &base[6..],
157 _ => base,
158 };
159 if let Some(target) = digest_target(candidate) {
160 return Ok(ParsedMcardUri {
161 uri_type: McardUriType::Hash,
162 target,
163 fragment,
164 original: uri.to_string(),
165 });
166 }
167 Ok(ParsedMcardUri {
168 uri_type: McardUriType::Handle,
169 target: canonicalize_mcard_uri(base, ""),
170 fragment,
171 original: uri.to_string(),
172 })
173}
174
175pub fn validate_transclusion_chain(
176 chain: &[String],
177 next_ref: &str,
178) -> std::result::Result<(), TransclusionCycleError> {
179 let next = next_ref.to_lowercase();
180 if chain.iter().any(|ref_| ref_.to_lowercase() == next) {
181 let mut cycle_path = chain.to_vec();
182 cycle_path.push(next_ref.to_string());
183 return Err(TransclusionCycleError { cycle_path });
184 }
185 Ok(())
186}