use std::collections::BTreeSet;
use std::path::Path;
use include_dir::{Dir, include_dir};
pub use crate::payload_roots::PAYLOAD_ROOTS;
pub static SPECS: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/_docs/specs");
pub static TEMPLATES: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/templates");
pub static MARKDOWNLINT: &[u8] = include_bytes!("../_docs/.markdownlint-cli2.jsonc");
pub static INSTANCE: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/instance");
pub static METHOD: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/method");
pub static SKILLS: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/skills");
pub static SKILL_SHARED: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/skill-shared");
pub static COMPARISON_DOCS: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/comparison-docs");
pub static PRIOR_ART: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/reference/prior-art");
pub static TRACKER_MARKUP: Dir<'static> =
include_dir!("$CARGO_MANIFEST_DIR/reference/tracker-markup");
pub static LICENSE: &str = include_str!("../LICENSE");
pub static LICENSE_MIT: &str = include_str!("../LICENSE-MIT");
pub static LICENSE_CC_BY: &str = include_str!("../LICENSE-CC-BY-4.0");
pub static THIRD_PARTY_NOTICES: &str = include_str!("../THIRD_PARTY_NOTICES.md");
pub static CHANGELOG: &str = include_str!("../CHANGELOG.md");
const EMBEDDED_ROOTS: &[(&str, &Dir<'static>)] = &[
("_docs/specs", &SPECS),
("templates", &TEMPLATES),
("instance", &INSTANCE),
("method", &METHOD),
("skills", &SKILLS),
("skill-shared", &SKILL_SHARED),
("comparison-docs", &COMPARISON_DOCS),
("reference/prior-art", &PRIOR_ART),
("reference/tracker-markup", &TRACKER_MARKUP),
];
const EMBEDDED_FILES: &[(&str, &[u8])] = &[("_docs/.markdownlint-cli2.jsonc", MARKDOWNLINT)];
#[must_use]
pub const fn roots() -> &'static [(&'static str, &'static Dir<'static>)] {
EMBEDDED_ROOTS
}
#[must_use]
pub fn skill_names() -> Vec<&'static str> {
let mut names: Vec<&'static str> = SKILLS
.dirs()
.filter_map(|dir| dir.path().as_os_str().to_str())
.collect();
names.sort_unstable();
names
}
#[must_use]
pub fn skill(name: &str) -> Option<&'static str> {
SKILLS
.get_file(format!("{name}/SKILL.md"))
.and_then(include_dir::File::contents_utf8)
}
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum PackageError {
#[error("the payload carries no skill named {0}")]
Unknown(String),
#[error(
"{skill}: {path} is claimed by the skill and by the shared source; author it once (skill-format:shared-content-is-authored-once)"
)]
Collision {
skill: String,
path: String,
},
#[error(
"{skill}: {path} is neither SKILL.md nor a file under references/ (skill-format:a-package-holds-the-manual-and-its-references)"
)]
Unlisted {
skill: String,
path: String,
},
}
pub fn skill_package(name: &str) -> Result<Vec<(String, &'static [u8])>, PackageError> {
let dir = SKILLS
.get_dir(name)
.ok_or_else(|| PackageError::Unknown(name.to_string()))?;
compose_package(name, dir, &SKILL_SHARED)
}
pub fn compose_package(
name: &str,
skill: &'static Dir<'static>,
shared: &'static Dir<'static>,
) -> Result<Vec<(String, &'static [u8])>, PackageError> {
use crate::domain::paths::{SKILL_FILE, SKILL_REFERENCES_DIR};
let mut files = Vec::new();
for (relative, bytes) in files_relative_to(skill) {
let allowed = relative == SKILL_FILE
|| relative
.strip_prefix(&format!("{SKILL_REFERENCES_DIR}/"))
.is_some_and(|file| !file.is_empty() && !file.contains('/'));
if !allowed {
return Err(PackageError::Unlisted {
skill: name.to_string(),
path: relative,
});
}
files.push((relative, bytes));
}
if !files.iter().any(|(path, _)| path == SKILL_FILE) {
return Err(PackageError::Unknown(name.to_string()));
}
for (path, bytes) in files_relative_to(shared) {
let relative = format!("{SKILL_REFERENCES_DIR}/{path}");
if files.iter().any(|(claimed, _)| *claimed == relative) {
return Err(PackageError::Collision {
skill: name.to_string(),
path: relative,
});
}
files.push((relative, bytes));
}
files.sort_by(|left, right| left.0.cmp(&right.0));
Ok(files)
}
fn files_relative_to(dir: &'static Dir<'static>) -> Vec<(String, &'static [u8])> {
fn walk(base: &Path, dir: &'static Dir<'static>, out: &mut Vec<(String, &'static [u8])>) {
for file in dir.files() {
let relative = file
.path()
.strip_prefix(base)
.unwrap_or_else(|_| file.path());
if let Some(relative) = relative.to_str() {
out.push((relative.to_string(), file.contents()));
}
}
for sub in dir.dirs() {
walk(base, sub, out);
}
}
let mut out = Vec::new();
walk(dir.path(), dir, &mut out);
out
}
#[must_use]
pub fn shared_artifacts() -> Vec<(String, &'static [u8])> {
let mut out = files_relative_to(&SKILL_SHARED);
out.sort_by(|a, b| a.0.cmp(&b.0));
out
}
#[must_use]
pub fn asset(source: &str) -> Option<&'static [u8]> {
EMBEDDED_FILES
.iter()
.find_map(|(path, bytes)| (*path == source).then_some(*bytes))
.or_else(|| {
EMBEDDED_ROOTS.iter().find_map(|(root, dir)| {
let rest = source.strip_prefix(root)?.strip_prefix('/')?;
dir.get_file(rest).map(include_dir::File::contents)
})
})
}
#[must_use]
pub fn assets_under(root: &str) -> Vec<(String, &'static [u8])> {
if let Some((path, bytes)) = EMBEDDED_FILES.iter().find(|(path, _)| *path == root) {
return vec![((*path).to_string(), *bytes)];
}
let Some((name, dir)) = EMBEDDED_ROOTS.iter().find(|(name, _)| *name == root) else {
return Vec::new();
};
let mut out = Vec::new();
collect_under(name, dir, &mut out);
out.sort_by(|a, b| a.0.cmp(&b.0));
out
}
fn collect_under(root: &str, dir: &'static Dir<'static>, out: &mut Vec<(String, &'static [u8])>) {
for file in dir.files() {
if let Some(rest) = file.path().to_str() {
out.push((format!("{root}/{rest}"), file.contents()));
}
}
for sub in dir.dirs() {
collect_under(root, sub, out);
}
}
#[must_use]
pub fn spec_rule_ids() -> BTreeSet<String> {
let mut ids = BTreeSet::new();
for file in SPECS.files() {
let Some(text) = file.contents_utf8() else {
continue;
};
ids.extend(rule_ids_in(text));
}
ids
}
pub fn spec_texts() -> impl Iterator<Item = &'static str> {
SPECS.files().filter_map(include_dir::File::contents_utf8)
}
pub fn rule_ids_in(text: &str) -> impl Iterator<Item = String> + '_ {
text.lines().filter_map(|line| {
let candidate = line.strip_prefix("### `")?;
let (id, _) = candidate.split_once('`')?;
let (domain, rule) = id.split_once(':')?;
let is_slug = |part: &str| {
!part.is_empty()
&& part
.bytes()
.all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
};
(is_slug(domain) && is_slug(rule)).then(|| id.to_string())
})
}
#[cfg(test)]
mod tests {
use super::*;
use crate::domain::profile::ProfileId;
use crate::domain::rule_id::RuleId;
#[test]
fn rule_id_enum_matches_the_embedded_specs() {
let from_specs = spec_rule_ids();
let from_enum: BTreeSet<String> = RuleId::ALL
.iter()
.map(|rule| rule.as_str().to_string())
.collect();
assert_eq!(
from_specs, from_enum,
"RuleId and the specs disagree; update the enum and the specs together"
);
}
#[test]
fn the_embedded_roots_are_the_declared_payload_roots() {
let mut embedded: Vec<&str> = EMBEDDED_ROOTS
.iter()
.map(|(root, _)| *root)
.chain(EMBEDDED_FILES.iter().map(|(path, _)| *path))
.collect();
embedded.sort_unstable();
let mut declared = PAYLOAD_ROOTS.to_vec();
declared.sort_unstable();
assert_eq!(
embedded, declared,
"payload_roots.rs and the embedded statics disagree; a root missing from the declaration ships unscanned"
);
}
#[test]
fn a_single_file_root_resolves_through_both_readers() {
for (path, bytes) in EMBEDDED_FILES {
assert_eq!(asset(path), Some(*bytes), "{path}");
assert_eq!(assets_under(path), vec![((*path).to_string(), *bytes)]);
}
assert!(asset("_docs/.markdownlint-cli2.jsonc/x").is_none());
}
#[test]
fn every_profile_projection_resolves_to_an_embedded_asset() {
for id in [ProfileId::Codebase, ProfileId::KnowledgeBase] {
let profile = id.profile();
for entry in profile.managed.iter().chain(profile.adopted) {
assert!(
asset(&entry.source).is_some(),
"{id}: {} is not embedded",
entry.source
);
}
}
}
#[test]
fn the_method_and_licenses_are_carried() {
assert!(METHOD.get_file("glossary.md").is_some());
assert!(METHOD.files().count() >= 15);
assert!(LICENSE.contains("LICENSE-MIT") && LICENSE.contains("LICENSE-CC-BY-4.0"));
}
use include_dir::{DirEntry, File};
static SHARED: Dir<'static> = Dir::new(
"",
&[DirEntry::File(File::new("plan-gate.md", b"shared gate"))],
);
static OWN_REFERENCE: Dir<'static> = Dir::new(
"demo",
&[
DirEntry::File(File::new("demo/SKILL.md", b"manual")),
DirEntry::Dir(Dir::new(
"demo/references",
&[DirEntry::File(File::new(
"demo/references/land.md",
b"task",
))],
)),
],
);
static CLAIMED_TWICE: Dir<'static> = Dir::new(
"demo",
&[
DirEntry::File(File::new("demo/SKILL.md", b"manual")),
DirEntry::Dir(Dir::new(
"demo/references",
&[DirEntry::File(File::new(
"demo/references/plan-gate.md",
b"a copy",
))],
)),
],
);
static UNLISTED: Dir<'static> = Dir::new(
"demo",
&[
DirEntry::File(File::new("demo/SKILL.md", b"manual")),
DirEntry::Dir(Dir::new(
"demo/scripts",
&[DirEntry::File(File::new("demo/scripts/check.sh", b"echo"))],
)),
],
);
#[test]
fn a_skill_reference_lands_beside_the_shared_artifacts() {
let package = compose_package("demo", &OWN_REFERENCE, &SHARED).unwrap();
let paths: Vec<&str> = package.iter().map(|(path, _)| path.as_str()).collect();
assert_eq!(
paths,
["SKILL.md", "references/land.md", "references/plan-gate.md"]
);
}
#[test]
fn a_name_both_sources_claim_fails_the_package() {
let error = compose_package("demo", &CLAIMED_TWICE, &SHARED).unwrap_err();
assert_eq!(
error,
PackageError::Collision {
skill: "demo".to_string(),
path: "references/plan-gate.md".to_string(),
}
);
assert!(
error
.to_string()
.contains("skill-format:shared-content-is-authored-once")
);
}
#[test]
fn a_file_outside_the_allowlist_fails_the_package() {
let error = compose_package("demo", &UNLISTED, &SHARED).unwrap_err();
assert_eq!(
error,
PackageError::Unlisted {
skill: "demo".to_string(),
path: "scripts/check.sh".to_string(),
}
);
}
#[test]
fn a_name_the_payload_lacks_is_unknown() {
assert_eq!(
skill_package("no-such-skill"),
Err(PackageError::Unknown("no-such-skill".to_string()))
);
}
#[test]
fn rule_id_parser_matches_heading_shape_only() {
let text = "### `a-b:c-d` — Title\n### `Bad:Id`\nplain ### `x:y`\n### `no-colon`\n";
let ids: Vec<String> = rule_ids_in(text).collect();
assert_eq!(ids, vec!["a-b:c-d".to_string()]);
}
}