1use std::collections::HashMap;
23
24use cortex_domain::GraphDocument;
25
26use crate::{SkillError, import_skill_markdown};
27
28pub const MAX_LIBRARY_SKILLS: usize = 512;
30
31#[derive(Debug, Clone, PartialEq, Eq)]
33pub struct LibraryEntry {
34 pub source: String,
36 pub markdown: String,
37}
38
39#[derive(Debug, Clone, PartialEq, Eq)]
41pub struct LibraryNotice {
42 pub source: String,
43 pub text: String,
44}
45
46#[derive(Debug, Clone, PartialEq)]
48pub struct ImportedSkill {
49 pub source: String,
50 pub renamed_from: Option<String>,
52 pub graph: GraphDocument,
53}
54
55#[derive(Debug, Clone, PartialEq, Eq)]
57pub struct SkippedDocument {
58 pub source: String,
59 pub reason: String,
60}
61
62#[derive(Debug, Clone, Default, PartialEq)]
64pub struct LibraryImport {
65 pub skills: Vec<ImportedSkill>,
66 pub skipped: Vec<SkippedDocument>,
67 pub notices: Vec<LibraryNotice>,
68}
69
70impl LibraryImport {
71 #[must_use]
74 pub fn is_empty(&self) -> bool {
75 self.skills.is_empty()
76 }
77}
78
79#[must_use]
92pub fn import_library(
93 entries: impl IntoIterator<Item = LibraryEntry>,
94 notices: Vec<LibraryNotice>,
95 library: &str,
96) -> LibraryImport {
97 let mut result = LibraryImport {
98 notices,
99 ..LibraryImport::default()
100 };
101 let mut seen: HashMap<String, usize> = HashMap::new();
102 for entry in entries {
103 if result.skills.len() >= MAX_LIBRARY_SKILLS {
104 result.skipped.push(SkippedDocument {
105 source: entry.source,
106 reason: format!("library exceeds {MAX_LIBRARY_SKILLS} skills"),
107 });
108 continue;
109 }
110 match import_skill_markdown(&entry.source, &entry.markdown) {
111 Ok(graph) => result
112 .skills
113 .push(disambiguate(graph, &entry.source, library, &mut seen)),
114 Err(error) => result.skipped.push(SkippedDocument {
115 source: entry.source,
116 reason: describe(&error),
117 }),
118 }
119 }
120 result
121}
122
123fn disambiguate(
124 mut graph: GraphDocument,
125 source: &str,
126 library: &str,
127 seen: &mut HashMap<String, usize>,
128) -> ImportedSkill {
129 graph
130 .metadata
131 .insert("library".to_owned(), library.to_owned());
132 let original = graph.id.clone();
133 let count = seen.entry(original.clone()).or_insert(0);
134 *count += 1;
135 let renamed_from = if *count == 1 {
136 None
137 } else {
138 graph.id = format!("{original}-{count}");
139 Some(original)
140 };
141 ImportedSkill {
142 source: source.to_owned(),
143 renamed_from,
144 graph,
145 }
146}
147
148fn describe(error: &SkillError) -> String {
149 error.to_string()
150}
151
152#[derive(Debug, Clone, PartialEq, Eq)]
158pub struct SkillIndexEntry {
159 pub id: String,
160 pub name: String,
161 pub description: String,
162 pub when_to_use: String,
165 pub steps: usize,
166 pub gates: usize,
167}
168
169#[must_use]
174pub fn index_entry(graph: &GraphDocument) -> Option<SkillIndexEntry> {
175 if graph.metadata.get("compiler").map(String::as_str) != Some("cortex-skills") {
176 return None;
177 }
178 let description = graph
179 .metadata
180 .get("description")
181 .cloned()
182 .unwrap_or_default();
183 let when_to_use = graph
184 .metadata
185 .get("frontmatter.when-to-use")
186 .or_else(|| graph.metadata.get("frontmatter.when_to_use"))
187 .cloned()
188 .unwrap_or_else(|| description.clone());
189 let steps = graph
190 .nodes
191 .iter()
192 .filter(|node| {
193 node.config.get("role").and_then(serde_json::Value::as_str) == Some("workflow_step")
194 })
195 .count();
196 let gates = graph
197 .nodes
198 .iter()
199 .filter(|node| {
200 matches!(
201 node.kind,
202 cortex_domain::NodeKind::QualityGate
203 | cortex_domain::NodeKind::HumanGate
204 | cortex_domain::NodeKind::TestGate
205 | cortex_domain::NodeKind::ReviewGate
206 | cortex_domain::NodeKind::EvidenceGate
207 )
208 })
209 .count();
210 Some(SkillIndexEntry {
211 id: graph.id.clone(),
212 name: graph.name.clone(),
213 description,
214 when_to_use,
215 steps,
216 gates,
217 })
218}
219
220#[must_use]
227pub fn render_index(entries: &[SkillIndexEntry]) -> String {
228 use std::fmt::Write as _;
229
230 let mut output = String::new();
231 output.push_str(
232 "# Cortex Loom workflow catalogue\n\n\
233 Pick at most one workflow, then fetch it with `skill_read { id }`. \
234 Do not load a workflow you are not about to follow: the catalogue is \
235 cheap and the workflows are not.\n\n",
236 );
237 for entry in entries {
238 let _ = writeln!(
239 output,
240 "- `{}` — **{}**. {} ({} steps, {} gate{})",
241 entry.id,
242 entry.name,
243 entry.when_to_use,
244 entry.steps,
245 entry.gates,
246 if entry.gates == 1 { "" } else { "s" }
247 );
248 }
249 if entries.is_empty() {
250 output.push_str("- (no workflows stored)\n");
251 }
252 output
253}
254
255#[cfg(test)]
256mod tests {
257 use super::{LibraryEntry, LibraryNotice, import_library};
258
259 fn entry(source: &str, name: &str) -> LibraryEntry {
260 LibraryEntry {
261 source: source.to_owned(),
262 markdown: format!(
263 "---\nname: {name}\ndescription: imported\n---\n# {name}\n\n\
264 ## Steps\n\n1. Do the first thing.\n2. Do the second. [depends: 1]\n"
265 ),
266 }
267 }
268
269 #[test]
270 fn a_malformed_document_costs_only_itself() {
271 let import = import_library(
272 vec![
273 entry("skills/alpha/SKILL.md", "Alpha"),
274 LibraryEntry {
275 source: "skills/broken/SKILL.md".to_owned(),
276 markdown: "---\nname: Broken\n# no closing delimiter\n".to_owned(),
277 },
278 entry("skills/beta/SKILL.md", "Beta"),
279 ],
280 Vec::new(),
281 "/checkout/superpowers",
282 );
283 assert_eq!(import.skills.len(), 2, "the good documents still import");
284 assert_eq!(import.skipped.len(), 1);
285 assert_eq!(import.skipped[0].source, "skills/broken/SKILL.md");
286 assert!(import.skipped[0].reason.contains("frontmatter"));
287 }
288
289 #[test]
290 fn colliding_titles_are_disambiguated_rather_than_dropped() {
291 let import = import_library(
292 vec![
293 entry("skills/one/SKILL.md", "Code Review"),
294 entry("skills/two/SKILL.md", "Code Review"),
295 entry("skills/three/SKILL.md", "Code Review"),
296 ],
297 Vec::new(),
298 "/checkout/library",
299 );
300 let ids: Vec<&str> = import
301 .skills
302 .iter()
303 .map(|skill| skill.graph.id.as_str())
304 .collect();
305 assert_eq!(
306 ids,
307 [
308 "code-review-skill",
309 "code-review-skill-2",
310 "code-review-skill-3"
311 ]
312 );
313 assert_eq!(import.skills[0].renamed_from, None);
314 assert_eq!(
315 import.skills[2].renamed_from.as_deref(),
316 Some("code-review-skill")
317 );
318 assert!(import.skipped.is_empty());
319 }
320
321 #[test]
322 fn provenance_and_attribution_travel_with_the_import() {
323 let notice = LibraryNotice {
324 source: "LICENSE".to_owned(),
325 text: "MIT License\n\nCopyright (c) someone".to_owned(),
326 };
327 let import = import_library(
328 vec![entry("skills/alpha/SKILL.md", "Alpha")],
329 vec![notice.clone()],
330 "/checkout/superpowers",
331 );
332 let graph = &import.skills[0].graph;
333 assert_eq!(
334 graph.metadata.get("library").map(String::as_str),
335 Some("/checkout/superpowers")
336 );
337 assert_eq!(
338 graph.metadata.get("source").map(String::as_str),
339 Some("skills/alpha/SKILL.md"),
340 "the per-document provenance the compiler wrote is untouched"
341 );
342 assert_eq!(import.notices, [notice], "attribution is carried, not lost");
343 assert_eq!(graph.revision, 0, "an import is unsaved until stored");
344 }
345
346 #[test]
347 fn an_empty_library_reports_itself_as_empty() {
348 let import = import_library(Vec::new(), Vec::new(), "/checkout/empty");
349 assert!(import.is_empty());
350 }
351
352 #[test]
353 fn the_catalogue_costs_a_fraction_of_the_workflows_it_lists() {
354 let skills: Vec<_> = crate::bundled_skills()
358 .iter()
359 .map(|skill| crate::import_skill_markdown(skill.source, skill.markdown).unwrap())
360 .collect();
361 let entries: Vec<_> = skills
362 .iter()
363 .map(|graph| super::index_entry(graph).expect("bundled graphs are skill graphs"))
364 .collect();
365 assert_eq!(entries.len(), skills.len());
366
367 let catalogue = super::render_index(&entries).chars().count();
368 let bodies: usize = crate::bundled_skills()
369 .iter()
370 .map(|skill| skill.markdown.chars().count())
371 .sum();
372 assert!(
373 catalogue * 4 < bodies,
374 "catalogue {catalogue} chars vs {bodies} chars of workflows: not worth the indirection"
375 );
376 }
377
378 #[test]
379 fn a_graph_this_compiler_did_not_produce_is_not_advertised() {
380 let foreign = cortex_domain::default_control_plane();
381 assert_eq!(super::index_entry(&foreign), None);
382 }
383}