use std::io::Write;
use super::{Cli, Failure, Fallible, Outcome, write_envelope};
const SKILL: &str = include_str!("../../skills/matra/SKILL.md");
const SKILL_NAME: &str = "SKILL";
const REFERENCES: &[(&str, &str)] = &[
(
"errors",
include_str!("../../skills/matra/references/errors.md"),
),
(
"json",
include_str!("../../skills/matra/references/json.md"),
),
(
"metrics",
include_str!("../../skills/matra/references/metrics.md"),
),
(
"python",
include_str!("../../skills/matra/references/python.md"),
),
(
"semantic",
include_str!("../../skills/matra/references/semantic.md"),
),
(
"structure",
include_str!("../../skills/matra/references/structure.md"),
),
];
#[derive(serde::Serialize)]
struct Entry<'a> {
name: &'a str,
summary: &'a str,
}
#[derive(serde::Serialize)]
struct Text<'a> {
name: &'a str,
body: &'a str,
}
#[derive(serde::Serialize)]
struct List<'a> {
references: Vec<Entry<'a>>,
}
pub(super) fn run(cli: &Cli, out: &mut dyn Write) -> Fallible<Outcome> {
match cli.reference.as_ref() {
None => text(cli, out, SKILL_NAME, SKILL),
Some(None) => list(cli, out),
Some(Some(name)) => {
let body = lookup(name)?;
text(cli, out, name, body)
}
}
}
fn text(cli: &Cli, out: &mut dyn Write, name: &str, body: &str) -> Fallible<Outcome> {
if cli.json {
write_envelope(out, "skill", None, Text { name, body })?;
} else {
out.write_all(body.as_bytes())?;
}
Ok(Outcome::Found)
}
fn list(cli: &Cli, out: &mut dyn Write) -> Fallible<Outcome> {
let mut entries = Vec::with_capacity(REFERENCES.len());
for (name, body) in REFERENCES {
entries.push(Entry {
name,
summary: summary_of(name, body)?,
});
}
if cli.json {
write_envelope(
out,
"skill",
None,
List {
references: entries,
},
)?;
return Ok(Outcome::Found);
}
let width = entries.iter().map(|e| e.name.len()).max().unwrap_or(0);
for entry in &entries {
writeln!(out, "{:<width$} {}", entry.name, entry.summary)?;
}
Ok(Outcome::Found)
}
fn lookup(name: &str) -> Fallible<&'static str> {
match REFERENCES.iter().find(|(known, _)| *known == name) {
Some((_, body)) => Ok(body),
None => Err(Failure::refused(
"reference_unknown",
format!("no reference named `{name}`; known references: {}", names()),
)),
}
}
fn names() -> String {
REFERENCES
.iter()
.map(|(name, _)| *name)
.collect::<Vec<_>>()
.join(", ")
}
fn summary_of<'a>(name: &str, body: &'a str) -> Fallible<&'a str> {
let mut lines = body.lines();
if lines.next() != Some("---") {
return Err(Failure::refused(
"embedded_file_malformed",
format!("reference `{name}` does not open with frontmatter"),
));
}
for line in lines {
if line == "---" {
break;
}
if let Some(summary) = line.strip_prefix("summary:") {
let summary = summary.trim();
if summary.is_empty() {
break;
}
return Ok(summary);
}
}
Err(Failure::refused(
"embedded_file_malformed",
format!("reference `{name}` declares no summary in its frontmatter"),
))
}
#[cfg(test)]
mod tests {
use super::*;
use std::path::Path;
#[test]
fn the_table_is_the_directory() {
let dir = Path::new(env!("CARGO_MANIFEST_DIR")).join("skills/matra/references");
let mut on_disk: Vec<String> = std::fs::read_dir(&dir)
.unwrap_or_else(|e| panic!("read {}: {e}", dir.display()))
.map(|entry| entry.expect("dir entry").path())
.filter(|path| path.extension().is_some_and(|e| e == "md"))
.map(|path| {
path.file_stem()
.and_then(|s| s.to_str())
.expect("utf8 file name")
.to_string()
})
.collect();
on_disk.sort();
let embedded: Vec<String> = REFERENCES.iter().map(|(n, _)| (*n).to_string()).collect();
assert_eq!(
embedded,
on_disk,
"the embedded reference table and {} disagree",
dir.display()
);
for (name, body) in REFERENCES {
let path = dir.join(format!("{name}.md"));
let on_disk =
std::fs::read_to_string(&path).unwrap_or_else(|e| panic!("read {name}: {e}"));
assert_eq!(*body, on_disk, "`{name}` is embedded from the wrong file");
}
}
#[test]
fn every_reference_declares_a_summary() {
for (name, body) in REFERENCES {
let summary = summary_of(name, body).unwrap_or_else(|e| panic!("{e}"));
assert!(!summary.is_empty(), "`{name}` has an empty summary");
}
}
#[test]
fn the_top_level_is_the_file() {
let path = Path::new(env!("CARGO_MANIFEST_DIR")).join("skills/matra/SKILL.md");
let on_disk = std::fs::read_to_string(&path).expect("read SKILL.md");
assert_eq!(SKILL, on_disk);
}
#[test]
fn a_reference_without_a_summary_is_refused() {
let err = summary_of("x", "---\nname: x\n---\n\n# X\n").expect_err("no summary");
assert!(err.to_string().contains("declares no summary"), "{err}");
let err = summary_of("x", "# X\n").expect_err("no frontmatter");
assert!(err.to_string().contains("frontmatter"), "{err}");
}
#[test]
fn an_unknown_name_names_the_known_ones() {
let err = lookup("jsn").expect_err("no such reference");
let message = err.to_string();
assert!(message.contains("jsn"), "{message}");
for (name, _) in REFERENCES {
assert!(message.contains(name), "{message} omits `{name}`");
}
}
}