Skip to main content

spec_driven_docs/
embedded.rs

1//! Compile-time embedded assets: the payload and the method, in the binary.
2//!
3//! Every `include_dir!`/`include_str!` in the crate lives here, and each
4//! embeds from its canonical authored path, so the repository file and the
5//! shipped copy cannot diverge — the build reads the real thing. This module
6//! only holds bytes and typed accessors; deciding where an asset lands in an
7//! instance is the profiles' and installer's business.
8
9use std::collections::BTreeSet;
10use std::path::Path;
11
12use include_dir::{Dir, include_dir};
13
14pub use crate::payload_roots::PAYLOAD_ROOTS;
15
16/// This repository's own specs: the canon-only ones and its adopted copies.
17///
18/// A reader takes the specs through [`spec_files`], where a payload spec
19/// wins by name, so an adopted copy is never served.
20pub static SPECS: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/_docs/specs");
21/// The stable document templates.
22pub static TEMPLATES: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/templates");
23/// What a release says about itself, plus what it seeds and splices.
24///
25/// One root rather than a root per subdirectory: the projection
26/// declaration sits beside the seeds it describes, and a root per
27/// subdirectory would make the declaration a one-file exception to the
28/// payload inventory.
29pub static INSTANCE: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/instance");
30/// The method chapters and glossary.
31pub static METHOD: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/method");
32/// The cross-agent skills, one `SKILL.md` per directory.
33pub static SKILLS: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/skills");
34/// The artifacts every skill shares, materialized into every package.
35pub static SKILL_SHARED: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/skill-shared");
36/// The comparison documents, which a stage carries as reference material.
37pub static COMPARISON_DOCS: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/comparison-docs");
38/// The prior-art shelf, which a stage carries as reference material.
39pub static PRIOR_ART: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/reference/prior-art");
40/// The tracker-markup shelf, which the format chapter routes a reader to.
41pub static TRACKER_MARKUP: Dir<'static> =
42    include_dir!("$CARGO_MANIFEST_DIR/reference/tracker-markup");
43
44/// The combined license statement naming both halves.
45pub static LICENSE: &str = include_str!("../LICENSE");
46/// The MIT license covering the distribution.
47pub static LICENSE_MIT: &str = include_str!("../LICENSE-MIT");
48/// The CC BY 4.0 license covering the method.
49pub static LICENSE_CC_BY: &str = include_str!("../LICENSE-CC-BY-4.0");
50/// The attribution notice for every third-party source the payload derives from.
51pub static THIRD_PARTY_NOTICES: &str = include_str!("../THIRD_PARTY_NOTICES.md");
52/// The release notes, which a stage carries as this version's own history.
53pub static CHANGELOG: &str = include_str!("../CHANGELOG.md");
54
55/// Every embedded directory root paired with the authored path it came
56/// from. With [`EMBEDDED_FILES`] it is [`PAYLOAD_ROOTS`] in order: a unit test
57/// holds the union equal to the declaration, so a root embedded here but
58/// missing from the declaration — or the reverse — fails the build rather
59/// than shipping unscanned.
60const EMBEDDED_ROOTS: &[(&str, &Dir<'static>)] = &[
61    ("_docs/specs", &SPECS),
62    ("templates", &TEMPLATES),
63    ("instance", &INSTANCE),
64    ("method", &METHOD),
65    ("skills", &SKILLS),
66    ("skill-shared", &SKILL_SHARED),
67    ("comparison-docs", &COMPARISON_DOCS),
68    ("reference/prior-art", &PRIOR_ART),
69    ("reference/tracker-markup", &TRACKER_MARKUP),
70];
71
72/// Every payload root that is one file, paired with its bytes.
73///
74/// A directory static cannot hold a file that sits beside other authored
75/// content, such as a configuration at the top of the documentation root,
76/// so such a root is embedded by itself.
77const EMBEDDED_FILES: &[(&str, &[u8])] = &[];
78
79/// Where the payload keeps the sources that an instance's own paths would
80/// otherwise share with this repository's instance, under the `instance`
81/// root.
82pub const PAYLOAD_DIR: &str = "instance/payload";
83
84/// An empty directory, for a payload folder this build does not carry.
85static EMPTY: Dir<'static> = Dir::new("", &[]);
86
87/// The specs an instance adopts, as the payload carries them.
88#[must_use]
89pub fn payload_specs() -> &'static Dir<'static> {
90    INSTANCE.get_dir("payload/_docs/specs").unwrap_or(&EMPTY)
91}
92
93/// Every spec this binary serves, by file name, sorted: each payload spec,
94/// then each canon-only spec whose name the payload does not carry.
95#[must_use]
96pub fn spec_files() -> Vec<(&'static str, &'static include_dir::File<'static>)> {
97    let named = |dir: &'static Dir<'static>| {
98        dir.files()
99            .filter_map(|file| {
100                let name = file.path().file_name()?.to_str()?;
101                Some((name, file))
102            })
103            .collect::<Vec<_>>()
104    };
105    let mut files = named(payload_specs());
106    for (name, file) in named(&SPECS) {
107        if !files.iter().any(|(held, _)| *held == name) {
108            files.push((name, file));
109        }
110    }
111    files.sort_by(|left, right| left.0.cmp(right.0));
112    files
113}
114
115/// Every embedded root paired with the authored path it came from.
116///
117/// The candidate reads its sources through this, so a root added to the
118/// declaration reaches the projection without a second list.
119#[must_use]
120pub const fn roots() -> &'static [(&'static str, &'static Dir<'static>)] {
121    EMBEDDED_ROOTS
122}
123
124/// Every skill name, sorted; a name is the skill's directory.
125#[must_use]
126pub fn skill_names() -> Vec<&'static str> {
127    let mut names: Vec<&'static str> = SKILLS
128        .dirs()
129        .filter_map(|dir| dir.path().as_os_str().to_str())
130        .collect();
131    names.sort_unstable();
132    names
133}
134
135/// One skill's `SKILL.md` text, by skill name.
136#[must_use]
137pub fn skill(name: &str) -> Option<&'static str> {
138    SKILLS
139        .get_file(format!("{name}/SKILL.md"))
140        .and_then(include_dir::File::contents_utf8)
141}
142
143/// Why a skill package cannot be composed.
144#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
145pub enum PackageError {
146    /// The payload carries no skill by this name.
147    #[error("the payload carries no skill named {0}")]
148    Unknown(String),
149    /// The skill and the shared source both claim one reference name.
150    #[error(
151        "{skill}: {path} is claimed by the skill and by the shared source; author it once (skill-format:shared-content-is-authored-once)"
152    )]
153    Collision {
154        /// The skill whose package was being composed.
155        skill: String,
156        /// The package-relative path both sources claim.
157        path: String,
158    },
159    /// The skill directory holds a file the package does not carry.
160    #[error(
161        "{skill}: {path} is neither SKILL.md nor a file under references/ (skill-format:a-package-holds-the-manual-and-its-references)"
162    )]
163    Unlisted {
164        /// The skill whose package was being composed.
165        skill: String,
166        /// The skill-relative path outside the package closure.
167        path: String,
168    },
169}
170
171/// Every file of one installed skill package, as `(path relative to the
172/// package root, bytes)`, sorted by path.
173///
174/// A package is the unit the Agent Skills format and every documented host
175/// resolve against: one directory holding `SKILL.md` and supporting files
176/// beside it. A skill's own reference files are authored in its directory,
177/// and the shared artifacts are authored once under `skill-shared/` and
178/// materialized here into every package, so a fix lands in one file and
179/// reaches every root the installer writes.
180///
181/// # Errors
182///
183/// [`PackageError::Unknown`] for a name the payload does not carry, and the
184/// composition errors of [`compose_package`].
185pub fn skill_package(name: &str) -> Result<Vec<(String, &'static [u8])>, PackageError> {
186    let dir = SKILLS
187        .get_dir(name)
188        .ok_or_else(|| PackageError::Unknown(name.to_string()))?;
189    compose_package(name, dir, &SKILL_SHARED)
190}
191
192/// One file the landing writes for a skill package.
193#[derive(Debug, Clone, PartialEq, Eq)]
194pub struct SkillFile {
195    /// The payload path the bytes come from, as [`asset`] resolves it.
196    pub source: String,
197    /// Where the instance holds it, relative to the target root.
198    pub destination: String,
199    /// The package bytes, unchanged.
200    pub bytes: &'static [u8],
201}
202
203/// Every file of every skill package, under each skill root an instance
204/// carries, in a fixed order.
205///
206/// The one inventory: the candidate projects these rows and the verifier
207/// expects them, so the two cannot disagree on which skill entries an
208/// instance owes.
209///
210/// SATISFIES distribution:an-instance-carries-the-skills
211///
212/// # Errors
213///
214/// The composition errors of [`skill_package`].
215pub fn skill_inventory() -> Result<Vec<SkillFile>, PackageError> {
216    use crate::domain::paths::SKILL_REFERENCES_DIR;
217
218    let mut out = Vec::new();
219    for root in SKILL_ROOTS {
220        for name in skill_names() {
221            for (relative, bytes) in skill_package(name)? {
222                let own = format!("skills/{name}/{relative}");
223                let source = if asset(&own).is_some() {
224                    own
225                } else {
226                    let shared = relative
227                        .strip_prefix(&format!("{SKILL_REFERENCES_DIR}/"))
228                        .unwrap_or(&relative);
229                    format!("skill-shared/{shared}")
230                };
231                out.push(SkillFile {
232                    source,
233                    destination: format!("{root}/{name}/{relative}"),
234                    bytes,
235                });
236            }
237        }
238    }
239    Ok(out)
240}
241
242/// The skill roots an instance carries, relative to its root.
243pub const SKILL_ROOTS: [&str; 2] = [
244    crate::domain::paths::CLAUDE_ROOT,
245    crate::domain::paths::AGENTS_ROOT,
246];
247
248/// Every package folder the inventory lands, as `<root>/<name>`.
249#[must_use]
250pub fn skill_package_folders() -> Vec<String> {
251    SKILL_ROOTS
252        .iter()
253        .flat_map(|root| {
254            skill_names()
255                .into_iter()
256                .map(move |name| format!("{root}/{name}"))
257        })
258        .collect()
259}
260
261/// Compose one package from a skill directory and the shared source.
262///
263/// The closure is an allowlist: `SKILL.md` and the files directly under the
264/// skill's `references/`, then every shared artifact under `references/`.
265/// A file outside the allowlist, or a reference name both sources claim, is
266/// refused rather than dropped or shadowed, because either would ship a
267/// package that differs from what its author wrote.
268///
269/// # Errors
270///
271/// [`PackageError::Unknown`] where the directory holds no `SKILL.md`,
272/// [`PackageError::Unlisted`] for a file outside the allowlist, and
273/// [`PackageError::Collision`] for a name both sources claim.
274pub fn compose_package(
275    name: &str,
276    skill: &'static Dir<'static>,
277    shared: &'static Dir<'static>,
278) -> Result<Vec<(String, &'static [u8])>, PackageError> {
279    use crate::domain::paths::{SKILL_FILE, SKILL_REFERENCES_DIR};
280
281    let mut files = Vec::new();
282    for (relative, bytes) in files_relative_to(skill) {
283        let allowed = relative == SKILL_FILE
284            || relative
285                .strip_prefix(&format!("{SKILL_REFERENCES_DIR}/"))
286                .is_some_and(|file| !file.is_empty() && !file.contains('/'));
287        if !allowed {
288            return Err(PackageError::Unlisted {
289                skill: name.to_string(),
290                path: relative,
291            });
292        }
293        files.push((relative, bytes));
294    }
295    if !files.iter().any(|(path, _)| path == SKILL_FILE) {
296        return Err(PackageError::Unknown(name.to_string()));
297    }
298    for (path, bytes) in files_relative_to(shared) {
299        let relative = format!("{SKILL_REFERENCES_DIR}/{path}");
300        if files.iter().any(|(claimed, _)| *claimed == relative) {
301            return Err(PackageError::Collision {
302                skill: name.to_string(),
303                path: relative,
304            });
305        }
306        files.push((relative, bytes));
307    }
308    files.sort_by(|left, right| left.0.cmp(&right.0));
309    Ok(files)
310}
311
312/// Every file under `dir`, at any depth, by its path relative to `dir`.
313fn files_relative_to(dir: &'static Dir<'static>) -> Vec<(String, &'static [u8])> {
314    fn walk(base: &Path, dir: &'static Dir<'static>, out: &mut Vec<(String, &'static [u8])>) {
315        for file in dir.files() {
316            let relative = file
317                .path()
318                .strip_prefix(base)
319                .unwrap_or_else(|_| file.path());
320            if let Some(relative) = relative.to_str() {
321                out.push((relative.to_string(), file.contents()));
322            }
323        }
324        for sub in dir.dirs() {
325            walk(base, sub, out);
326        }
327    }
328    let mut out = Vec::new();
329    walk(dir.path(), dir, &mut out);
330    out
331}
332
333/// Every artifact the skills share, as `(path under the root, bytes)`,
334/// sorted by path.
335///
336/// This is the authored view. What lands is [`skill_package`], which copies
337/// each of these into every package as a reference relative to the skill's
338/// own root.
339#[must_use]
340pub fn shared_artifacts() -> Vec<(String, &'static [u8])> {
341    let mut out = files_relative_to(&SKILL_SHARED);
342    out.sort_by(|a, b| a.0.cmp(&b.0));
343    out
344}
345
346/// Resolve a payload source path — as a profile projection names it — to its
347/// embedded bytes.
348#[must_use]
349pub fn asset(source: &str) -> Option<&'static [u8]> {
350    EMBEDDED_FILES
351        .iter()
352        .find_map(|(path, bytes)| (*path == source).then_some(*bytes))
353        .or_else(|| {
354            EMBEDDED_ROOTS.iter().find_map(|(root, dir)| {
355                let rest = source.strip_prefix(root)?.strip_prefix('/')?;
356                dir.get_file(rest).map(include_dir::File::contents)
357            })
358        })
359}
360
361/// Every file under one embedded root, by the logical path that names it.
362///
363/// A root that is one file yields that file alone. The paths come back
364/// sorted, so a caller that copies them writes the same tree every time.
365#[must_use]
366pub fn assets_under(root: &str) -> Vec<(String, &'static [u8])> {
367    if let Some((path, bytes)) = EMBEDDED_FILES.iter().find(|(path, _)| *path == root) {
368        return vec![((*path).to_string(), *bytes)];
369    }
370    let Some((name, dir)) = EMBEDDED_ROOTS.iter().find(|(name, _)| *name == root) else {
371        return Vec::new();
372    };
373    let mut out = Vec::new();
374    collect_under(name, dir, &mut out);
375    out.sort_by(|a, b| a.0.cmp(&b.0));
376    out
377}
378
379fn collect_under(root: &str, dir: &'static Dir<'static>, out: &mut Vec<(String, &'static [u8])>) {
380    for file in dir.files() {
381        if let Some(rest) = file.path().to_str() {
382            out.push((format!("{root}/{rest}"), file.contents()));
383        }
384    }
385    for sub in dir.dirs() {
386        collect_under(root, sub, out);
387    }
388}
389
390/// Every `` ### `domain:rule` `` requirement address the embedded specs define.
391#[must_use]
392pub fn spec_rule_ids() -> BTreeSet<String> {
393    let mut ids = BTreeSet::new();
394    for (_, file) in spec_files() {
395        let Some(text) = file.contents_utf8() else {
396            continue;
397        };
398        ids.extend(rule_ids_in(text));
399    }
400    ids
401}
402
403/// The text of every spec this binary carries.
404pub fn spec_texts() -> impl Iterator<Item = &'static str> {
405    spec_files()
406        .into_iter()
407        .filter_map(|(_, file)| file.contents_utf8())
408}
409
410/// The requirement addresses one spec document defines.
411pub fn rule_ids_in(text: &str) -> impl Iterator<Item = String> + '_ {
412    text.lines().filter_map(|line| {
413        let candidate = line.strip_prefix("### `")?;
414        let (id, _) = candidate.split_once('`')?;
415        let (domain, rule) = id.split_once(':')?;
416        let is_slug = |part: &str| {
417            !part.is_empty()
418                && part
419                    .bytes()
420                    .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
421        };
422        (is_slug(domain) && is_slug(rule)).then(|| id.to_string())
423    })
424}
425
426#[cfg(test)]
427mod tests {
428    use super::*;
429    use crate::domain::profile::ProfileId;
430    use crate::domain::rule_id::RuleId;
431
432    #[test]
433    fn rule_id_enum_matches_the_embedded_specs() {
434        let from_specs = spec_rule_ids();
435        let from_enum: BTreeSet<String> = RuleId::ALL
436            .iter()
437            .map(|rule| rule.as_str().to_string())
438            .collect();
439        assert_eq!(
440            from_specs, from_enum,
441            "RuleId and the specs disagree; update the enum and the specs together"
442        );
443    }
444
445    #[test]
446    fn the_embedded_roots_are_the_declared_payload_roots() {
447        let mut embedded: Vec<&str> = EMBEDDED_ROOTS
448            .iter()
449            .map(|(root, _)| *root)
450            .chain(EMBEDDED_FILES.iter().map(|(path, _)| *path))
451            .collect();
452        embedded.sort_unstable();
453        let mut declared = PAYLOAD_ROOTS.to_vec();
454        declared.sort_unstable();
455        assert_eq!(
456            embedded, declared,
457            "payload_roots.rs and the embedded statics disagree; a root missing from the declaration ships unscanned"
458        );
459    }
460
461    #[test]
462    fn a_single_file_root_resolves_through_both_readers() {
463        for (path, bytes) in EMBEDDED_FILES {
464            assert_eq!(asset(path), Some(*bytes), "{path}");
465            assert_eq!(assets_under(path), vec![((*path).to_string(), *bytes)]);
466        }
467        assert!(asset("instance/payload/_docs/.markdownlint-cli2.jsonc/x").is_none());
468    }
469
470    #[test]
471    fn every_profile_projection_resolves_to_an_embedded_asset() {
472        for id in [ProfileId::Codebase, ProfileId::KnowledgeBase] {
473            let profile = id.profile();
474            for entry in profile.managed.iter().chain(profile.adopted) {
475                assert!(
476                    asset(&entry.source).is_some(),
477                    "{id}: {} is not embedded",
478                    entry.source
479                );
480            }
481        }
482    }
483
484    #[test]
485    fn the_method_and_licenses_are_carried() {
486        assert!(METHOD.get_file("glossary.md").is_some());
487        assert!(METHOD.files().count() >= 15);
488        assert!(LICENSE.contains("LICENSE-MIT") && LICENSE.contains("LICENSE-CC-BY-4.0"));
489    }
490
491    use include_dir::{DirEntry, File};
492
493    static SHARED: Dir<'static> = Dir::new(
494        "",
495        &[DirEntry::File(File::new("plan-gate.md", b"shared gate"))],
496    );
497    static OWN_REFERENCE: Dir<'static> = Dir::new(
498        "demo",
499        &[
500            DirEntry::File(File::new("demo/SKILL.md", b"manual")),
501            DirEntry::Dir(Dir::new(
502                "demo/references",
503                &[DirEntry::File(File::new(
504                    "demo/references/land.md",
505                    b"task",
506                ))],
507            )),
508        ],
509    );
510    static CLAIMED_TWICE: Dir<'static> = Dir::new(
511        "demo",
512        &[
513            DirEntry::File(File::new("demo/SKILL.md", b"manual")),
514            DirEntry::Dir(Dir::new(
515                "demo/references",
516                &[DirEntry::File(File::new(
517                    "demo/references/plan-gate.md",
518                    b"a copy",
519                ))],
520            )),
521        ],
522    );
523    static UNLISTED: Dir<'static> = Dir::new(
524        "demo",
525        &[
526            DirEntry::File(File::new("demo/SKILL.md", b"manual")),
527            DirEntry::Dir(Dir::new(
528                "demo/scripts",
529                &[DirEntry::File(File::new("demo/scripts/check.sh", b"echo"))],
530            )),
531        ],
532    );
533
534    /// SATISFIES distribution:a-skill-package-is-self-contained
535    #[test]
536    fn a_skill_reference_lands_beside_the_shared_artifacts() {
537        let package = compose_package("demo", &OWN_REFERENCE, &SHARED).unwrap();
538        let paths: Vec<&str> = package.iter().map(|(path, _)| path.as_str()).collect();
539        assert_eq!(
540            paths,
541            ["SKILL.md", "references/land.md", "references/plan-gate.md"]
542        );
543    }
544
545    /// VERIFIES skill-format:shared-content-is-authored-once
546    #[test]
547    fn a_name_both_sources_claim_fails_the_package() {
548        let error = compose_package("demo", &CLAIMED_TWICE, &SHARED).unwrap_err();
549        assert_eq!(
550            error,
551            PackageError::Collision {
552                skill: "demo".to_string(),
553                path: "references/plan-gate.md".to_string(),
554            }
555        );
556        assert!(
557            error
558                .to_string()
559                .contains("skill-format:shared-content-is-authored-once")
560        );
561    }
562
563    /// VERIFIES skill-format:a-package-holds-the-manual-and-its-references
564    #[test]
565    fn a_file_outside_the_allowlist_fails_the_package() {
566        let error = compose_package("demo", &UNLISTED, &SHARED).unwrap_err();
567        assert_eq!(
568            error,
569            PackageError::Unlisted {
570                skill: "demo".to_string(),
571                path: "scripts/check.sh".to_string(),
572            }
573        );
574    }
575
576    #[test]
577    fn a_name_the_payload_lacks_is_unknown() {
578        assert_eq!(
579            skill_package("no-such-skill"),
580            Err(PackageError::Unknown("no-such-skill".to_string()))
581        );
582    }
583
584    #[test]
585    fn rule_id_parser_matches_heading_shape_only() {
586        let text = "### `a-b:c-d` — Title\n### `Bad:Id`\nplain ### `x:y`\n### `no-colon`\n";
587        let ids: Vec<String> = rule_ids_in(text).collect();
588        assert_eq!(ids, vec!["a-b:c-d".to_string()]);
589    }
590}