Skip to main content

cortex_skills/
lib.rs

1#![doc = include_str!("../README.md")]
2
3mod export;
4mod import;
5mod import_helpers;
6pub mod library;
7
8use std::fmt::{Display, Formatter};
9
10use cortex_domain::{GraphDocument, GraphError};
11
12pub use export::export_skill_markdown;
13pub use import::import_skill_markdown;
14pub use library::{
15    ImportedSkill, LibraryEntry, LibraryImport, LibraryNotice, SkillIndexEntry, import_library,
16    index_entry, render_index,
17};
18
19/// A failure to parse, validate, or export a skill workflow.
20///
21/// Marked `#[non_exhaustive]` so new failure modes can be reported without a
22/// breaking release; match with a wildcard arm.
23#[derive(Debug, Clone, PartialEq, Eq)]
24#[non_exhaustive]
25pub enum SkillError {
26    /// The `---` frontmatter block is malformed.
27    InvalidFrontmatter(String),
28    /// The compiled graph failed [`cortex_domain`] validation.
29    InvalidGraph(String),
30    /// The graph was not produced by this compiler and cannot be exported.
31    UnsupportedGraph(String),
32}
33
34impl Display for SkillError {
35    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
36        match self {
37            Self::InvalidFrontmatter(message) => {
38                write!(formatter, "invalid frontmatter: {message}")
39            }
40            Self::InvalidGraph(message) => write!(formatter, "invalid skill graph: {message}"),
41            Self::UnsupportedGraph(message) => {
42                write!(formatter, "unsupported skill graph: {message}")
43            }
44        }
45    }
46}
47
48impl std::error::Error for SkillError {}
49
50impl From<GraphError> for SkillError {
51    fn from(error: GraphError) -> Self {
52        Self::InvalidGraph(error.to_string())
53    }
54}
55
56/// One methodology skill shipped with this crate.
57///
58/// The library exists so a consumer starts with working methodology instead
59/// of an empty editor: compile a bundled skill with
60/// [`import_skill_markdown`], edit the graph, and export it back to Markdown.
61#[derive(Debug, Clone, Copy, PartialEq, Eq)]
62pub struct BundledSkill {
63    /// Stable identifier, matching the file stem.
64    pub id: &'static str,
65    /// Provenance string to pass to [`import_skill_markdown`].
66    pub source: &'static str,
67    /// The `SKILL.md` document.
68    pub markdown: &'static str,
69}
70
71/// The methodology skills shipped with this crate.
72///
73/// ```
74/// for skill in cortex_skills::bundled_skills() {
75///     let graph = cortex_skills::import_skill_markdown(skill.source, skill.markdown)?;
76///     assert!(!graph.nodes.is_empty());
77/// }
78/// # Ok::<(), cortex_skills::SkillError>(())
79/// ```
80#[must_use]
81#[allow(clippy::too_many_lines)] // static table of methodology fixtures
82pub const fn bundled_skills() -> &'static [BundledSkill] {
83    &[
84        BundledSkill {
85            id: "test-driven-development",
86            source: "cortex-skills/fixtures/test-driven-development.md",
87            markdown: include_str!("../fixtures/test-driven-development.md"),
88        },
89        BundledSkill {
90            id: "systematic-debugging",
91            source: "cortex-skills/fixtures/systematic-debugging.md",
92            markdown: include_str!("../fixtures/systematic-debugging.md"),
93        },
94        BundledSkill {
95            id: "grounded-review",
96            source: "cortex-skills/fixtures/grounded-review.md",
97            markdown: include_str!("../fixtures/grounded-review.md"),
98        },
99        BundledSkill {
100            id: "evidence-first-change",
101            source: "cortex-skills/fixtures/evidence-first-change.md",
102            markdown: include_str!("../fixtures/evidence-first-change.md"),
103        },
104        BundledSkill {
105            id: "verification-before-completion",
106            source: "cortex-skills/fixtures/verification-before-completion.md",
107            markdown: include_str!("../fixtures/verification-before-completion.md"),
108        },
109        BundledSkill {
110            id: "blast-radius-analysis",
111            source: "cortex-skills/fixtures/blast-radius-analysis.md",
112            markdown: include_str!("../fixtures/blast-radius-analysis.md"),
113        },
114        BundledSkill {
115            id: "interface-contract-change",
116            source: "cortex-skills/fixtures/interface-contract-change.md",
117            markdown: include_str!("../fixtures/interface-contract-change.md"),
118        },
119        BundledSkill {
120            id: "dependency-upgrade",
121            source: "cortex-skills/fixtures/dependency-upgrade.md",
122            markdown: include_str!("../fixtures/dependency-upgrade.md"),
123        },
124        BundledSkill {
125            id: "performance-investigation",
126            source: "cortex-skills/fixtures/performance-investigation.md",
127            markdown: include_str!("../fixtures/performance-investigation.md"),
128        },
129        BundledSkill {
130            id: "incident-response",
131            source: "cortex-skills/fixtures/incident-response.md",
132            markdown: include_str!("../fixtures/incident-response.md"),
133        },
134        BundledSkill {
135            id: "migration-cutover",
136            source: "cortex-skills/fixtures/migration-cutover.md",
137            markdown: include_str!("../fixtures/migration-cutover.md"),
138        },
139        BundledSkill {
140            id: "api-versioning",
141            source: "cortex-skills/fixtures/api-versioning.md",
142            markdown: include_str!("../fixtures/api-versioning.md"),
143        },
144        BundledSkill {
145            id: "flaky-test-quarantine",
146            source: "cortex-skills/fixtures/flaky-test-quarantine.md",
147            markdown: include_str!("../fixtures/flaky-test-quarantine.md"),
148        },
149        BundledSkill {
150            id: "security-threat-model",
151            source: "cortex-skills/fixtures/security-threat-model.md",
152            markdown: include_str!("../fixtures/security-threat-model.md"),
153        },
154        BundledSkill {
155            id: "observability-first",
156            source: "cortex-skills/fixtures/observability-first.md",
157            markdown: include_str!("../fixtures/observability-first.md"),
158        },
159        BundledSkill {
160            id: "data-migration",
161            source: "cortex-skills/fixtures/data-migration.md",
162            markdown: include_str!("../fixtures/data-migration.md"),
163        },
164        BundledSkill {
165            id: "feature-flag-rollout",
166            source: "cortex-skills/fixtures/feature-flag-rollout.md",
167            markdown: include_str!("../fixtures/feature-flag-rollout.md"),
168        },
169        BundledSkill {
170            id: "documentation-sync",
171            source: "cortex-skills/fixtures/documentation-sync.md",
172            markdown: include_str!("../fixtures/documentation-sync.md"),
173        },
174        BundledSkill {
175            id: "release-checklist",
176            source: "cortex-skills/fixtures/release-checklist.md",
177            markdown: include_str!("../fixtures/release-checklist.md"),
178        },
179        BundledSkill {
180            id: "backlog-triage",
181            source: "cortex-skills/fixtures/backlog-triage.md",
182            markdown: include_str!("../fixtures/backlog-triage.md"),
183        },
184        BundledSkill {
185            id: "accessibility-audit",
186            source: "cortex-skills/fixtures/accessibility-audit.md",
187            markdown: include_str!("../fixtures/accessibility-audit.md"),
188        },
189        BundledSkill {
190            id: "configuration-drift",
191            source: "cortex-skills/fixtures/configuration-drift.md",
192            markdown: include_str!("../fixtures/configuration-drift.md"),
193        },
194        BundledSkill {
195            id: "cache-invalidation",
196            source: "cortex-skills/fixtures/cache-invalidation.md",
197            markdown: include_str!("../fixtures/cache-invalidation.md"),
198        },
199        BundledSkill {
200            id: "concurrency-bug-hunt",
201            source: "cortex-skills/fixtures/concurrency-bug-hunt.md",
202            markdown: include_str!("../fixtures/concurrency-bug-hunt.md"),
203        },
204        BundledSkill {
205            id: "schema-evolution",
206            source: "cortex-skills/fixtures/schema-evolution.md",
207            markdown: include_str!("../fixtures/schema-evolution.md"),
208        },
209        BundledSkill {
210            id: "dependency-audit",
211            source: "cortex-skills/fixtures/dependency-audit.md",
212            markdown: include_str!("../fixtures/dependency-audit.md"),
213        },
214        BundledSkill {
215            id: "error-budget-review",
216            source: "cortex-skills/fixtures/error-budget-review.md",
217            markdown: include_str!("../fixtures/error-budget-review.md"),
218        },
219        BundledSkill {
220            id: "capacity-planning",
221            source: "cortex-skills/fixtures/capacity-planning.md",
222            markdown: include_str!("../fixtures/capacity-planning.md"),
223        },
224        BundledSkill {
225            id: "rollback-drill",
226            source: "cortex-skills/fixtures/rollback-drill.md",
227            markdown: include_str!("../fixtures/rollback-drill.md"),
228        },
229        BundledSkill {
230            id: "contract-testing",
231            source: "cortex-skills/fixtures/contract-testing.md",
232            markdown: include_str!("../fixtures/contract-testing.md"),
233        },
234        BundledSkill {
235            id: "postmortem-writeup",
236            source: "cortex-skills/fixtures/postmortem-writeup.md",
237            markdown: include_str!("../fixtures/postmortem-writeup.md"),
238        },
239    ]
240}
241
242/// A single-line rendering of a skill name for the Markdown `# ` title.
243///
244/// Frontmatter carries the exact name; the title must stay on one line.
245/// Writing a multi-line name straight into the heading would spill the
246/// remainder into the body, where the next import reads it as extra nodes —
247/// so the document would grow on every round trip instead of reaching a
248/// fixpoint. Import and export both compare through this function.
249pub(crate) fn heading_text(name: &str) -> String {
250    name.split_whitespace().collect::<Vec<_>>().join(" ")
251}
252
253/// Short alias for [`import_skill_markdown`].
254pub fn import_skill(source: &str, markdown: &str) -> Result<GraphDocument, SkillError> {
255    import_skill_markdown(source, markdown)
256}
257
258/// Short alias for [`export_skill_markdown`].
259pub fn export_skill(graph: &GraphDocument) -> Result<String, SkillError> {
260    export_skill_markdown(graph)
261}
262
263#[cfg(test)]
264mod tests;
265#[cfg(test)]
266mod tests_roundtrip;