Skip to main content

cortex_skills/
library.rs

1//! Importing a whole methodology library.
2//!
3//! The bundled skills exist so the editor is not empty. They are not a
4//! substitute for the libraries people already write: the portable `SKILL.md`
5//! format has a large public ecosystem, and a compiler that can only read its
6//! own fixtures is a compiler nobody needs.
7//!
8//! This module is pure. It takes documents that someone else read and returns
9//! validated graphs, collisions resolved, failures reported, and attribution
10//! carried alongside. Walking a directory is the caller's job, which keeps
11//! this crate free of filesystem and transport concerns.
12//!
13//! ## Attribution
14//!
15//! A library is someone else's work. [`LibraryImport::notices`] carries the
16//! licence and notice files found beside the skills so a consumer can show
17//! them before anything is stored, and every imported graph records where it
18//! came from in `metadata["library"]`. Nothing here decides whether a licence
19//! permits the use — that is a human decision, and the data exists so a human
20//! can make it.
21
22use std::collections::HashMap;
23
24use cortex_domain::GraphDocument;
25
26use crate::{SkillError, import_skill_markdown};
27
28/// Largest library this function will compile in one call.
29pub const MAX_LIBRARY_SKILLS: usize = 512;
30
31/// One candidate document, already read by the caller.
32#[derive(Debug, Clone, PartialEq, Eq)]
33pub struct LibraryEntry {
34    /// Provenance string, normally the path relative to the library root.
35    pub source: String,
36    pub markdown: String,
37}
38
39/// A licence or notice found beside the skills.
40#[derive(Debug, Clone, PartialEq, Eq)]
41pub struct LibraryNotice {
42    pub source: String,
43    pub text: String,
44}
45
46/// One skill that compiled.
47#[derive(Debug, Clone, PartialEq)]
48pub struct ImportedSkill {
49    pub source: String,
50    /// Set when the graph id collided and was disambiguated.
51    pub renamed_from: Option<String>,
52    pub graph: GraphDocument,
53}
54
55/// One document that did not compile, and why.
56#[derive(Debug, Clone, PartialEq, Eq)]
57pub struct SkippedDocument {
58    pub source: String,
59    pub reason: String,
60}
61
62/// The result of compiling a library.
63#[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    /// True when nothing compiled: a caller should say so rather than
72    /// silently storing an empty library.
73    #[must_use]
74    pub fn is_empty(&self) -> bool {
75        self.skills.is_empty()
76    }
77}
78
79/// Compile a library into validated graphs.
80///
81/// Entries are processed in the order given, so the result is deterministic
82/// for a deterministic walk. A document that fails to compile is skipped with
83/// its error rather than failing the whole library — one malformed file in
84/// somebody's repository must not cost the other ninety-nine.
85///
86/// Two skills with the same title produce the same graph id. Rather than drop
87/// the second, the id is suffixed (`-2`, `-3`, …) and
88/// [`ImportedSkill::renamed_from`] records it: a library that names two
89/// documents "Code Review" still imports both, and the report says what
90/// happened.
91#[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/// One line of the catalogue an agent keeps in context.
153///
154/// Everything here is cheap: what the workflow is called, when it applies,
155/// and how big it is. The steps themselves are not — they are fetched by id
156/// when a task actually matches.
157#[derive(Debug, Clone, PartialEq, Eq)]
158pub struct SkillIndexEntry {
159    pub id: String,
160    pub name: String,
161    pub description: String,
162    /// The trigger line. Falls back to the description when the author did
163    /// not write a `when-to-use` frontmatter key.
164    pub when_to_use: String,
165    pub steps: usize,
166    pub gates: usize,
167}
168
169/// Summarise one compiled skill graph for the catalogue.
170///
171/// Returns `None` for a graph this compiler did not produce: a catalogue of
172/// workflows must not advertise something `skill_read` cannot render.
173#[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/// Render the catalogue an agent keeps loaded.
221///
222/// This is the whole point of the two-tier surface: an agent that carries
223/// every workflow in its prompt pays for every workflow on every turn,
224/// whether or not the task is about any of them. It carries this instead —
225/// one line each — and calls `skill_read` for the one that matches.
226#[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        // The reason the two-tier surface exists, asserted rather than
355        // assumed: an agent that keeps the catalogue loaded must not be
356        // paying anything close to what keeping the workflows loaded costs.
357        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}