spec_driven_docs/domain/
profile.rs1use std::fmt;
10use std::sync::LazyLock;
11
12use camino::Utf8PathBuf;
13use clap::ValueEnum;
14use serde::{Deserialize, Serialize};
15
16pub use crate::domain::projection::Projection;
17use crate::domain::projection::{DECLARATION_PATH, Declaration};
18
19#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, ValueEnum, Serialize, Deserialize)]
21#[value(rename_all = "kebab-case")]
22#[serde(rename_all = "kebab-case")]
23pub enum ProfileId {
24 Codebase,
26 KnowledgeBase,
28}
29
30pub const EVERY_PROFILE: [ProfileId; 2] = [ProfileId::Codebase, ProfileId::KnowledgeBase];
32
33impl ProfileId {
34 pub fn every() -> impl Iterator<Item = Self> {
36 EVERY_PROFILE.into_iter()
37 }
38
39 #[must_use]
44 pub fn profile(self) -> &'static Profile<'static> {
45 match self {
46 Self::Codebase => &CODEBASE,
47 Self::KnowledgeBase => &KNOWLEDGE_BASE,
48 }
49 }
50
51 #[must_use]
53 pub const fn as_str(self) -> &'static str {
54 match self {
55 Self::Codebase => "codebase",
56 Self::KnowledgeBase => "knowledge-base",
57 }
58 }
59}
60
61impl fmt::Display for ProfileId {
62 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
63 f.write_str(self.as_str())
64 }
65}
66
67#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
69pub enum DocsRoot {
70 #[serde(rename = "docs")]
72 Docs,
73 #[serde(rename = "_docs")]
75 UnderscoreDocs,
76}
77
78impl DocsRoot {
79 #[must_use]
81 pub const fn as_str(self) -> &'static str {
82 match self {
83 Self::Docs => "docs",
84 Self::UnderscoreDocs => "_docs",
85 }
86 }
87}
88
89impl fmt::Display for DocsRoot {
90 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
91 f.write_str(self.as_str())
92 }
93}
94
95#[allow(
101 clippy::literal_string_with_formatting_args,
102 reason = "the braces are the template placeholder, not a formatting argument"
103)]
104pub const DOCS_ROOT_PLACEHOLDER: &str = "{docs_root}";
105
106#[must_use]
108pub fn render_root(text: &str, docs_root: &str) -> String {
109 text.replace(DOCS_ROOT_PLACEHOLDER, docs_root)
110}
111
112#[must_use]
114pub fn resolve_destination(destination: &str, docs_root: DocsRoot) -> Utf8PathBuf {
115 Utf8PathBuf::from(render_root(destination, docs_root.as_str()))
116}
117
118#[derive(Debug, Clone, Copy)]
120pub struct Profile<'a> {
121 pub id: ProfileId,
123 pub docs_root: DocsRoot,
125 pub managed: &'a [Projection],
127 pub adopted: &'a [Projection],
129}
130
131#[expect(
137 clippy::expect_used,
138 reason = "the declaration is compiled in; a parse failure is a build defect the canon suite catches first"
139)]
140pub static DECLARATION: LazyLock<Declaration> = LazyLock::new(|| {
141 let bytes = crate::embedded::asset(DECLARATION_PATH)
142 .expect("the payload carries instance/projection.toml");
143 Declaration::parse(bytes).expect("the embedded projection declaration parses")
144});
145
146pub static CANON_TEMPLATES: LazyLock<Vec<&'static str>> = LazyLock::new(|| {
148 DECLARATION
149 .canon_templates
150 .iter()
151 .map(String::as_str)
152 .collect()
153});
154
155static CODEBASE: LazyLock<Profile<'static>> = LazyLock::new(|| profile_of(ProfileId::Codebase));
156static KNOWLEDGE_BASE: LazyLock<Profile<'static>> =
157 LazyLock::new(|| profile_of(ProfileId::KnowledgeBase));
158
159#[expect(
161 clippy::expect_used,
162 reason = "a profile the declaration omits is the same build defect as a declaration that does not parse"
163)]
164fn profile_of(id: ProfileId) -> Profile<'static> {
165 DECLARATION
166 .profile(id)
167 .expect("the embedded declaration offers every profile")
168}
169
170#[cfg(test)]
171mod tests {
172 use super::*;
173
174 #[test]
175 fn profiles_bind_their_roots() {
176 assert_eq!(ProfileId::Codebase.profile().docs_root, DocsRoot::Docs);
177 assert_eq!(
178 ProfileId::KnowledgeBase.profile().docs_root,
179 DocsRoot::UnderscoreDocs
180 );
181 }
182
183 #[test]
184 fn destinations_resolve_per_root() {
185 assert_eq!(
186 resolve_destination("{docs_root}/specs/SPEC-distribution.md", DocsRoot::Docs),
187 Utf8PathBuf::from("docs/specs/SPEC-distribution.md")
188 );
189 assert_eq!(
190 resolve_destination(".spec-driven-docs/config.yaml", DocsRoot::UnderscoreDocs),
191 Utf8PathBuf::from(".spec-driven-docs/config.yaml")
192 );
193 }
194
195 #[test]
196 fn rendering_replaces_every_placeholder_and_nothing_else() {
197 assert_eq!(
198 render_root(
199 "see {docs_root}/specs/ and {docs_root}/guides/, not {writing_style} or {docs}",
200 "docs"
201 ),
202 "see docs/specs/ and docs/guides/, not {writing_style} or {docs}"
203 );
204 assert_eq!(render_root("no placeholder", "_docs"), "no placeholder");
205 }
206
207 #[test]
208 fn serde_uses_the_kebab_names() {
209 assert_eq!(
210 serde_json::to_string(&ProfileId::KnowledgeBase).unwrap(),
211 "\"knowledge-base\""
212 );
213 assert_eq!(
214 serde_json::to_string(&DocsRoot::UnderscoreDocs).unwrap(),
215 "\"_docs\""
216 );
217 }
218
219 #[test]
220 fn every_destination_lies_under_the_instance_or_the_documentation_root() {
221 let profile = ProfileId::KnowledgeBase.profile();
222 for entry in profile.managed {
223 assert!(
224 entry
225 .destination
226 .starts_with(&format!("{DOCS_ROOT_PLACEHOLDER}/"))
227 || entry
228 .destination
229 .starts_with(&format!("{}/", crate::domain::paths::INSTANCE_DIR)),
230 "{} is neither under the instance directory nor rooted at the documentation root",
231 entry.destination
232 );
233 }
234 for entry in profile.adopted {
235 if entry.destination == crate::domain::paths::CONFIG_PATH || entry.yield_set().is_some()
239 {
240 continue;
241 }
242 assert!(
243 entry.destination.starts_with("{docs_root}/"),
244 "{} is not rooted",
245 entry.destination
246 );
247 }
248 }
249
250 #[test]
251 fn the_canon_templates_come_from_the_declaration() {
252 assert_eq!(*CANON_TEMPLATES, DECLARATION.canon_templates);
253 }
254}