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/// The spec seeds an instance adopts, and the canon-only specs beside them.
17pub static SPECS: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/_docs/specs");
18/// The stable document templates.
19pub static TEMPLATES: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/templates");
20/// The documentation root's lint configuration, which an instance receives
21/// managed.
22pub static MARKDOWNLINT: &[u8] = include_bytes!("../_docs/.markdownlint-cli2.jsonc");
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])] = &[("_docs/.markdownlint-cli2.jsonc", MARKDOWNLINT)];
78
79/// Every embedded root paired with the authored path it came from.
80///
81/// The candidate reads its sources through this, so a root added to the
82/// declaration reaches the projection without a second list.
83#[must_use]
84pub const fn roots() -> &'static [(&'static str, &'static Dir<'static>)] {
85    EMBEDDED_ROOTS
86}
87
88/// Every skill name, sorted; a name is the skill's directory.
89#[must_use]
90pub fn skill_names() -> Vec<&'static str> {
91    let mut names: Vec<&'static str> = SKILLS
92        .dirs()
93        .filter_map(|dir| dir.path().as_os_str().to_str())
94        .collect();
95    names.sort_unstable();
96    names
97}
98
99/// One skill's `SKILL.md` text, by skill name.
100#[must_use]
101pub fn skill(name: &str) -> Option<&'static str> {
102    SKILLS
103        .get_file(format!("{name}/SKILL.md"))
104        .and_then(include_dir::File::contents_utf8)
105}
106
107/// Why a skill package cannot be composed.
108#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
109pub enum PackageError {
110    /// The payload carries no skill by this name.
111    #[error("the payload carries no skill named {0}")]
112    Unknown(String),
113    /// The skill and the shared source both claim one reference name.
114    #[error(
115        "{skill}: {path} is claimed by the skill and by the shared source; author it once (skill-format:shared-content-is-authored-once)"
116    )]
117    Collision {
118        /// The skill whose package was being composed.
119        skill: String,
120        /// The package-relative path both sources claim.
121        path: String,
122    },
123    /// The skill directory holds a file the package does not carry.
124    #[error(
125        "{skill}: {path} is neither SKILL.md nor a file under references/ (skill-format:a-package-holds-the-manual-and-its-references)"
126    )]
127    Unlisted {
128        /// The skill whose package was being composed.
129        skill: String,
130        /// The skill-relative path outside the package closure.
131        path: String,
132    },
133}
134
135/// Every file of one installed skill package, as `(path relative to the
136/// package root, bytes)`, sorted by path.
137///
138/// A package is the unit the Agent Skills format and every documented host
139/// resolve against: one directory holding `SKILL.md` and supporting files
140/// beside it. A skill's own reference files are authored in its directory,
141/// and the shared artifacts are authored once under `skill-shared/` and
142/// materialized here into every package, so a fix lands in one file and
143/// reaches every root the installer writes.
144///
145/// # Errors
146///
147/// [`PackageError::Unknown`] for a name the payload does not carry, and the
148/// composition errors of [`compose_package`].
149pub fn skill_package(name: &str) -> Result<Vec<(String, &'static [u8])>, PackageError> {
150    let dir = SKILLS
151        .get_dir(name)
152        .ok_or_else(|| PackageError::Unknown(name.to_string()))?;
153    compose_package(name, dir, &SKILL_SHARED)
154}
155
156/// Compose one package from a skill directory and the shared source.
157///
158/// The closure is an allowlist: `SKILL.md` and the files directly under the
159/// skill's `references/`, then every shared artifact under `references/`.
160/// A file outside the allowlist, or a reference name both sources claim, is
161/// refused rather than dropped or shadowed, because either would ship a
162/// package that differs from what its author wrote.
163///
164/// # Errors
165///
166/// [`PackageError::Unknown`] where the directory holds no `SKILL.md`,
167/// [`PackageError::Unlisted`] for a file outside the allowlist, and
168/// [`PackageError::Collision`] for a name both sources claim.
169pub fn compose_package(
170    name: &str,
171    skill: &'static Dir<'static>,
172    shared: &'static Dir<'static>,
173) -> Result<Vec<(String, &'static [u8])>, PackageError> {
174    use crate::domain::paths::{SKILL_FILE, SKILL_REFERENCES_DIR};
175
176    let mut files = Vec::new();
177    for (relative, bytes) in files_relative_to(skill) {
178        let allowed = relative == SKILL_FILE
179            || relative
180                .strip_prefix(&format!("{SKILL_REFERENCES_DIR}/"))
181                .is_some_and(|file| !file.is_empty() && !file.contains('/'));
182        if !allowed {
183            return Err(PackageError::Unlisted {
184                skill: name.to_string(),
185                path: relative,
186            });
187        }
188        files.push((relative, bytes));
189    }
190    if !files.iter().any(|(path, _)| path == SKILL_FILE) {
191        return Err(PackageError::Unknown(name.to_string()));
192    }
193    for (path, bytes) in files_relative_to(shared) {
194        let relative = format!("{SKILL_REFERENCES_DIR}/{path}");
195        if files.iter().any(|(claimed, _)| *claimed == relative) {
196            return Err(PackageError::Collision {
197                skill: name.to_string(),
198                path: relative,
199            });
200        }
201        files.push((relative, bytes));
202    }
203    files.sort_by(|left, right| left.0.cmp(&right.0));
204    Ok(files)
205}
206
207/// Every file under `dir`, at any depth, by its path relative to `dir`.
208fn files_relative_to(dir: &'static Dir<'static>) -> Vec<(String, &'static [u8])> {
209    fn walk(base: &Path, dir: &'static Dir<'static>, out: &mut Vec<(String, &'static [u8])>) {
210        for file in dir.files() {
211            let relative = file
212                .path()
213                .strip_prefix(base)
214                .unwrap_or_else(|_| file.path());
215            if let Some(relative) = relative.to_str() {
216                out.push((relative.to_string(), file.contents()));
217            }
218        }
219        for sub in dir.dirs() {
220            walk(base, sub, out);
221        }
222    }
223    let mut out = Vec::new();
224    walk(dir.path(), dir, &mut out);
225    out
226}
227
228/// Every artifact the skills share, as `(path under the root, bytes)`,
229/// sorted by path.
230///
231/// This is the authored view. What lands is [`skill_package`], which copies
232/// each of these into every package as a reference relative to the skill's
233/// own root.
234#[must_use]
235pub fn shared_artifacts() -> Vec<(String, &'static [u8])> {
236    let mut out = files_relative_to(&SKILL_SHARED);
237    out.sort_by(|a, b| a.0.cmp(&b.0));
238    out
239}
240
241/// Resolve a payload source path — as a profile projection names it — to its
242/// embedded bytes.
243#[must_use]
244pub fn asset(source: &str) -> Option<&'static [u8]> {
245    EMBEDDED_FILES
246        .iter()
247        .find_map(|(path, bytes)| (*path == source).then_some(*bytes))
248        .or_else(|| {
249            EMBEDDED_ROOTS.iter().find_map(|(root, dir)| {
250                let rest = source.strip_prefix(root)?.strip_prefix('/')?;
251                dir.get_file(rest).map(include_dir::File::contents)
252            })
253        })
254}
255
256/// Every file under one embedded root, by the logical path that names it.
257///
258/// A root that is one file yields that file alone. The paths come back
259/// sorted, so a caller that copies them writes the same tree every time.
260#[must_use]
261pub fn assets_under(root: &str) -> Vec<(String, &'static [u8])> {
262    if let Some((path, bytes)) = EMBEDDED_FILES.iter().find(|(path, _)| *path == root) {
263        return vec![((*path).to_string(), *bytes)];
264    }
265    let Some((name, dir)) = EMBEDDED_ROOTS.iter().find(|(name, _)| *name == root) else {
266        return Vec::new();
267    };
268    let mut out = Vec::new();
269    collect_under(name, dir, &mut out);
270    out.sort_by(|a, b| a.0.cmp(&b.0));
271    out
272}
273
274fn collect_under(root: &str, dir: &'static Dir<'static>, out: &mut Vec<(String, &'static [u8])>) {
275    for file in dir.files() {
276        if let Some(rest) = file.path().to_str() {
277            out.push((format!("{root}/{rest}"), file.contents()));
278        }
279    }
280    for sub in dir.dirs() {
281        collect_under(root, sub, out);
282    }
283}
284
285/// Every `` ### `domain:rule` `` requirement address the embedded specs define.
286#[must_use]
287pub fn spec_rule_ids() -> BTreeSet<String> {
288    let mut ids = BTreeSet::new();
289    for file in SPECS.files() {
290        let Some(text) = file.contents_utf8() else {
291            continue;
292        };
293        ids.extend(rule_ids_in(text));
294    }
295    ids
296}
297
298/// The text of every spec this binary carries.
299pub fn spec_texts() -> impl Iterator<Item = &'static str> {
300    SPECS.files().filter_map(include_dir::File::contents_utf8)
301}
302
303/// The requirement addresses one spec document defines.
304pub fn rule_ids_in(text: &str) -> impl Iterator<Item = String> + '_ {
305    text.lines().filter_map(|line| {
306        let candidate = line.strip_prefix("### `")?;
307        let (id, _) = candidate.split_once('`')?;
308        let (domain, rule) = id.split_once(':')?;
309        let is_slug = |part: &str| {
310            !part.is_empty()
311                && part
312                    .bytes()
313                    .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
314        };
315        (is_slug(domain) && is_slug(rule)).then(|| id.to_string())
316    })
317}
318
319#[cfg(test)]
320mod tests {
321    use super::*;
322    use crate::domain::profile::ProfileId;
323    use crate::domain::rule_id::RuleId;
324
325    #[test]
326    fn rule_id_enum_matches_the_embedded_specs() {
327        let from_specs = spec_rule_ids();
328        let from_enum: BTreeSet<String> = RuleId::ALL
329            .iter()
330            .map(|rule| rule.as_str().to_string())
331            .collect();
332        assert_eq!(
333            from_specs, from_enum,
334            "RuleId and the specs disagree; update the enum and the specs together"
335        );
336    }
337
338    #[test]
339    fn the_embedded_roots_are_the_declared_payload_roots() {
340        let mut embedded: Vec<&str> = EMBEDDED_ROOTS
341            .iter()
342            .map(|(root, _)| *root)
343            .chain(EMBEDDED_FILES.iter().map(|(path, _)| *path))
344            .collect();
345        embedded.sort_unstable();
346        let mut declared = PAYLOAD_ROOTS.to_vec();
347        declared.sort_unstable();
348        assert_eq!(
349            embedded, declared,
350            "payload_roots.rs and the embedded statics disagree; a root missing from the declaration ships unscanned"
351        );
352    }
353
354    #[test]
355    fn a_single_file_root_resolves_through_both_readers() {
356        for (path, bytes) in EMBEDDED_FILES {
357            assert_eq!(asset(path), Some(*bytes), "{path}");
358            assert_eq!(assets_under(path), vec![((*path).to_string(), *bytes)]);
359        }
360        assert!(asset("_docs/.markdownlint-cli2.jsonc/x").is_none());
361    }
362
363    #[test]
364    fn every_profile_projection_resolves_to_an_embedded_asset() {
365        for id in [ProfileId::Codebase, ProfileId::KnowledgeBase] {
366            let profile = id.profile();
367            for entry in profile.managed.iter().chain(profile.adopted) {
368                assert!(
369                    asset(&entry.source).is_some(),
370                    "{id}: {} is not embedded",
371                    entry.source
372                );
373            }
374        }
375    }
376
377    #[test]
378    fn the_method_and_licenses_are_carried() {
379        assert!(METHOD.get_file("glossary.md").is_some());
380        assert!(METHOD.files().count() >= 15);
381        assert!(LICENSE.contains("LICENSE-MIT") && LICENSE.contains("LICENSE-CC-BY-4.0"));
382    }
383
384    use include_dir::{DirEntry, File};
385
386    static SHARED: Dir<'static> = Dir::new(
387        "",
388        &[DirEntry::File(File::new("plan-gate.md", b"shared gate"))],
389    );
390    static OWN_REFERENCE: Dir<'static> = Dir::new(
391        "demo",
392        &[
393            DirEntry::File(File::new("demo/SKILL.md", b"manual")),
394            DirEntry::Dir(Dir::new(
395                "demo/references",
396                &[DirEntry::File(File::new(
397                    "demo/references/land.md",
398                    b"task",
399                ))],
400            )),
401        ],
402    );
403    static CLAIMED_TWICE: Dir<'static> = Dir::new(
404        "demo",
405        &[
406            DirEntry::File(File::new("demo/SKILL.md", b"manual")),
407            DirEntry::Dir(Dir::new(
408                "demo/references",
409                &[DirEntry::File(File::new(
410                    "demo/references/plan-gate.md",
411                    b"a copy",
412                ))],
413            )),
414        ],
415    );
416    static UNLISTED: Dir<'static> = Dir::new(
417        "demo",
418        &[
419            DirEntry::File(File::new("demo/SKILL.md", b"manual")),
420            DirEntry::Dir(Dir::new(
421                "demo/scripts",
422                &[DirEntry::File(File::new("demo/scripts/check.sh", b"echo"))],
423            )),
424        ],
425    );
426
427    /// SATISFIES distribution:a-skill-package-is-self-contained
428    #[test]
429    fn a_skill_reference_lands_beside_the_shared_artifacts() {
430        let package = compose_package("demo", &OWN_REFERENCE, &SHARED).unwrap();
431        let paths: Vec<&str> = package.iter().map(|(path, _)| path.as_str()).collect();
432        assert_eq!(
433            paths,
434            ["SKILL.md", "references/land.md", "references/plan-gate.md"]
435        );
436    }
437
438    /// VERIFIES skill-format:shared-content-is-authored-once
439    #[test]
440    fn a_name_both_sources_claim_fails_the_package() {
441        let error = compose_package("demo", &CLAIMED_TWICE, &SHARED).unwrap_err();
442        assert_eq!(
443            error,
444            PackageError::Collision {
445                skill: "demo".to_string(),
446                path: "references/plan-gate.md".to_string(),
447            }
448        );
449        assert!(
450            error
451                .to_string()
452                .contains("skill-format:shared-content-is-authored-once")
453        );
454    }
455
456    /// VERIFIES skill-format:a-package-holds-the-manual-and-its-references
457    #[test]
458    fn a_file_outside_the_allowlist_fails_the_package() {
459        let error = compose_package("demo", &UNLISTED, &SHARED).unwrap_err();
460        assert_eq!(
461            error,
462            PackageError::Unlisted {
463                skill: "demo".to_string(),
464                path: "scripts/check.sh".to_string(),
465            }
466        );
467    }
468
469    #[test]
470    fn a_name_the_payload_lacks_is_unknown() {
471        assert_eq!(
472            skill_package("no-such-skill"),
473            Err(PackageError::Unknown("no-such-skill".to_string()))
474        );
475    }
476
477    #[test]
478    fn rule_id_parser_matches_heading_shape_only() {
479        let text = "### `a-b:c-d` — Title\n### `Bad:Id`\nplain ### `x:y`\n### `no-colon`\n";
480        let ids: Vec<String> = rule_ids_in(text).collect();
481        assert_eq!(ids, vec!["a-b:c-d".to_string()]);
482    }
483}