Vakyartha documentation

1//! Declarative output template files and channel profile preferences.
2
3use crate::{
4 DeliveryError, Markup, TemplateActivation, TemplateNode, TemplateOrigin, TemplateRegistry,
5 TemplateSlot, TemplateSpec,
6};
7use serde::Deserialize;
8use std::collections::BTreeMap;
9use std::path::Path;
10
11#[derive(Debug, Clone, Default)]
12pub struct LoadedTemplates {
13 pub registry: TemplateRegistry,
14 pub channels: BTreeMap<String, ChannelPreference>,
15 pub warnings: Vec<String>,
16}
17
18#[derive(Debug, Clone, PartialEq, Deserialize)]
19pub struct ChannelPreference {
20 pub template: Option<String>,
21 pub markup: Option<Markup>,
22 pub max_chars: Option<usize>,
23 #[serde(flatten)]
24 unknown: BTreeMap<String, toml::Value>,
25}
26
27#[derive(Debug, Default, Deserialize)]
28#[serde(default)]
29struct TemplateFile {
30 templates: BTreeMap<String, TemplateDefinition>,
31 channels: BTreeMap<String, ChannelPreference>,
32 #[serde(flatten)]
33 unknown: BTreeMap<String, toml::Value>,
34}
35
36#[derive(Debug, Deserialize)]
37struct TemplateDefinition {
38 #[serde(default = "default_revision")]
39 revision: u32,
40 format: String,
41 #[serde(default)]
42 activation: TemplateActivation,
43 #[serde(flatten)]
44 unknown: BTreeMap<String, toml::Value>,
45}
46
47fn default_revision() -> u32 {
48 1
49}
50
51/// Load user and project layers. Project files are ignored unless the caller
52/// has already established project trust.
53pub fn load_layers(
54 user_path: &Path,
55 project_path: &Path,
56 project_trusted: bool,
57) -> LoadedTemplates {
58 let mut loaded = LoadedTemplates::default();
59 if project_trusted {
60 load_file(project_path, TemplateOrigin::Project, &mut loaded);
61 } else if project_path.exists() {
62 loaded.warnings.push(format!(
63 "ignored untrusted project output templates at {}",
64 project_path.display()
65 ));
66 }
67 load_file(user_path, TemplateOrigin::User, &mut loaded);
68 loaded
69}
70
71fn load_file(path: &Path, origin: TemplateOrigin, loaded: &mut LoadedTemplates) {
72 let text = match std::fs::read_to_string(path) {
73 Ok(text) => text,
74 Err(error) if error.kind() == std::io::ErrorKind::NotFound => return,
75 Err(error) => {
76 loaded
77 .warnings
78 .push(format!("could not read {}: {error}", path.display()));
79 return;
80 }
81 };
82 let parsed: TemplateFile = match toml::from_str(&text) {
83 Ok(parsed) => parsed,
84 Err(error) => {
85 loaded.warnings.push(format!(
86 "invalid output template {}: {error}",
87 path.display()
88 ));
89 return;
90 }
91 };
92 for key in parsed.unknown.keys() {
93 loaded.warnings.push(format!(
94 "ignored unknown output key {key} in {}",
95 path.display()
96 ));
97 }
98 for (id, definition) in parsed.templates {
99 for key in definition.unknown.keys() {
100 loaded.warnings.push(format!(
101 "ignored unknown template key {id}.{key} in {}",
102 path.display()
103 ));
104 }
105 match compile_template(id.clone(), definition, origin) {
106 Ok(template) => {
107 if let Err(error) = loaded.registry.upsert(template) {
108 loaded.warnings.push(format!(
109 "invalid template {id} in {}: {error}",
110 path.display()
111 ));
112 }
113 }
114 Err(error) => loaded.warnings.push(format!(
115 "invalid template {id} in {}: {error}",
116 path.display()
117 )),
118 }
119 }
120 for (surface, preference) in parsed.channels {
121 for key in preference.unknown.keys() {
122 loaded.warnings.push(format!(
123 "ignored unknown channel key {surface}.{key} in {}",
124 path.display()
125 ));
126 }
127 if surface.trim().is_empty() {
128 loaded
129 .warnings
130 .push(format!("empty channel name in {}", path.display()));
131 continue;
132 }
133 if preference.max_chars == Some(0) {
134 loaded.warnings.push(format!(
135 "channel {surface} in {} has max_chars = 0",
136 path.display()
137 ));
138 continue;
139 }
140 loaded.channels.insert(surface, preference);
141 }
142}
143
144fn compile_template(
145 id: String,
146 definition: TemplateDefinition,
147 origin: TemplateOrigin,
148) -> Result<TemplateSpec, DeliveryError> {
149 if definition.format.chars().count() > 32_768 {
150 return Err(DeliveryError::InvalidTemplate(
151 "format exceeds 32768 characters".into(),
152 ));
153 }
154 let template = TemplateSpec {
155 id,
156 revision: definition.revision,
157 origin,
158 activation: definition.activation,
159 nodes: parse_format(&definition.format)?,
160 };
161 template.validate()?;
162 Ok(template)
163}
164
165fn parse_format(format: &str) -> Result<Vec<TemplateNode>, DeliveryError> {
166 let mut nodes = Vec::new();
167 let mut literal = String::new();
168 let mut chars = format.chars().peekable();
169 while let Some(character) = chars.next() {
170 if character == '{' && chars.peek() == Some(&'{') {
171 chars.next();
172 literal.push('{');
173 continue;
174 }
175 if character == '}' && chars.peek() == Some(&'}') {
176 chars.next();
177 literal.push('}');
178 continue;
179 }
180 if character != '{' {
181 literal.push(character);
182 continue;
183 }
184 if !literal.is_empty() {
185 nodes.push(TemplateNode::Literal {
186 text: std::mem::take(&mut literal),
187 });
188 }
189 let mut name = String::new();
190 loop {
191 match chars.next() {
192 Some('}') => break,
193 Some('{') | None => {
194 return Err(DeliveryError::InvalidTemplate(
195 "unclosed or nested placeholder".into(),
196 ));
197 }
198 Some(value) => name.push(value),
199 }
200 }
201 nodes.push(TemplateNode::Slot {
202 slot: parse_slot(name.trim())?,
203 });
204 }
205 if !literal.is_empty() {
206 nodes.push(TemplateNode::Literal { text: literal });
207 }
208 Ok(nodes)
209}
210
211fn parse_slot(name: &str) -> Result<TemplateSlot, DeliveryError> {
212 match name {
213 "title" => Ok(TemplateSlot::Title),
214 "body" => Ok(TemplateSlot::Body),
215 "source_markdown" => Ok(TemplateSlot::SourceMarkdown),
216 "block_count" => Ok(TemplateSlot::BlockCount),
217 _ => name
218 .strip_prefix("metadata.")
219 .filter(|key| !key.is_empty())
220 .map(|key| TemplateSlot::Metadata { key: key.into() })
221 .ok_or_else(|| {
222 DeliveryError::InvalidTemplate(format!("unknown placeholder {{{name}}}"))
223 }),
224 }
225}
226
227#[cfg(test)]
228#[allow(clippy::expect_used)]
229mod tests {
230 use super::*;
231
232 #[test]
233 fn loads_safe_layer_and_rejects_unknown_placeholder() {
234 let root =
235 std::env::temp_dir().join(format!("vak-delivery-template-{}", std::process::id()));
236 std::fs::create_dir_all(&root).expect("root");
237 let user = root.join("output.toml");
238 std::fs::write(
239 &user,
240 "[templates.compact]\nformat = \"{title}\\n\\n{body}\"\n\n[channels.telegram]\ntemplate = \"compact\"\nmax_chars = 4000\n",
241 )
242 .expect("template");
243 let loaded = load_layers(&user, &root.join("project.toml"), true);
244 assert!(loaded.warnings.is_empty(), "{:?}", loaded.warnings);
245 assert!(loaded.registry.resolve("compact").is_some());
246 assert_eq!(loaded.channels["telegram"].max_chars, Some(4000));
247
248 std::fs::write(&user, "[templates.bad]\nformat = \"{execute}\"\n").expect("bad template");
249 let loaded = load_layers(&user, &root.join("project.toml"), true);
250 assert_eq!(loaded.warnings.len(), 1);
251 let _ = std::fs::remove_dir_all(root);
252 }
253}
254

1//! Declarative output template files and channel profile preferences.
2
3use crate::{
4 DeliveryError, Markup, TemplateActivation, TemplateNode, TemplateOrigin, TemplateRegistry,
5 TemplateSlot, TemplateSpec,
6};
7use serde::Deserialize;
8use std::collections::BTreeMap;
9use std::path::Path;
10
11#[derive(Debug, Clone, Default)]
12pub struct LoadedTemplates {
13 pub registry: TemplateRegistry,
14 pub channels: BTreeMap<String, ChannelPreference>,
15 pub warnings: Vec<String>,
16}
17
18#[derive(Debug, Clone, PartialEq, Deserialize)]
19pub struct ChannelPreference {
20 pub template: Option<String>,
21 pub markup: Option<Markup>,
22 pub max_chars: Option<usize>,
23 #[serde(flatten)]
24 unknown: BTreeMap<String, toml::Value>,
25}
26
27#[derive(Debug, Default, Deserialize)]
28#[serde(default)]
29struct TemplateFile {
30 templates: BTreeMap<String, TemplateDefinition>,
31 channels: BTreeMap<String, ChannelPreference>,
32 #[serde(flatten)]
33 unknown: BTreeMap<String, toml::Value>,
34}
35
36#[derive(Debug, Deserialize)]
37struct TemplateDefinition {
38 #[serde(default = "default_revision")]
39 revision: u32,
40 format: String,
41 #[serde(default)]
42 activation: TemplateActivation,
43 #[serde(flatten)]
44 unknown: BTreeMap<String, toml::Value>,
45}
46
47fn default_revision() -> u32 {
48 1
49}
50
51/// Load user and project layers. Project files are ignored unless the caller
52/// has already established project trust.
53pub fn load_layers(
54 user_path: &Path,
55 project_path: &Path,
56 project_trusted: bool,
57) -> LoadedTemplates {
58 let mut loaded = LoadedTemplates::default();
59 if project_trusted {
60 load_file(project_path, TemplateOrigin::Project, &mut loaded);
61 } else if project_path.exists() {
62 loaded.warnings.push(format!(
63 "ignored untrusted project output templates at {}",
64 project_path.display()
65 ));
66 }
67 load_file(user_path, TemplateOrigin::User, &mut loaded);
68 loaded
69}
70
71fn load_file(path: &Path, origin: TemplateOrigin, loaded: &mut LoadedTemplates) {
72 let text = match std::fs::read_to_string(path) {
73 Ok(text) => text,
74 Err(error) if error.kind() == std::io::ErrorKind::NotFound => return,
75 Err(error) => {
76 loaded
77 .warnings
78 .push(format!("could not read {}: {error}", path.display()));
79 return;
80 }
81 };
82 let parsed: TemplateFile = match toml::from_str(&text) {
83 Ok(parsed) => parsed,
84 Err(error) => {
85 loaded.warnings.push(format!(
86 "invalid output template {}: {error}",
87 path.display()
88 ));
89 return;
90 }
91 };
92 for key in parsed.unknown.keys() {
93 loaded.warnings.push(format!(
94 "ignored unknown output key {key} in {}",
95 path.display()
96 ));
97 }
98 for (id, definition) in parsed.templates {
99 for key in definition.unknown.keys() {
100 loaded.warnings.push(format!(
101 "ignored unknown template key {id}.{key} in {}",
102 path.display()
103 ));
104 }
105 match compile_template(id.clone(), definition, origin) {
106 Ok(template) => {
107 if let Err(error) = loaded.registry.upsert(template) {
108 loaded.warnings.push(format!(
109 "invalid template {id} in {}: {error}",
110 path.display()
111 ));
112 }
113 }
114 Err(error) => loaded.warnings.push(format!(
115 "invalid template {id} in {}: {error}",
116 path.display()
117 )),
118 }
119 }
120 for (surface, preference) in parsed.channels {
121 for key in preference.unknown.keys() {
122 loaded.warnings.push(format!(
123 "ignored unknown channel key {surface}.{key} in {}",
124 path.display()
125 ));
126 }
127 if surface.trim().is_empty() {
128 loaded
129 .warnings
130 .push(format!("empty channel name in {}", path.display()));
131 continue;
132 }
133 if preference.max_chars == Some(0) {
134 loaded.warnings.push(format!(
135 "channel {surface} in {} has max_chars = 0",
136 path.display()
137 ));
138 continue;
139 }
140 loaded.channels.insert(surface, preference);
141 }
142}
143
144fn compile_template(
145 id: String,
146 definition: TemplateDefinition,
147 origin: TemplateOrigin,
148) -> Result<TemplateSpec, DeliveryError> {
149 if definition.format.chars().count() > 32_768 {
150 return Err(DeliveryError::InvalidTemplate(
151 "format exceeds 32768 characters".into(),
152 ));
153 }
154 let template = TemplateSpec {
155 id,
156 revision: definition.revision,
157 origin,
158 activation: definition.activation,
159 nodes: parse_format(&definition.format)?,
160 };
161 template.validate()?;
162 Ok(template)
163}
164
165fn parse_format(format: &str) -> Result<Vec<TemplateNode>, DeliveryError> {
166 let mut nodes = Vec::new();
167 let mut literal = String::new();
168 let mut chars = format.chars().peekable();
169 while let Some(character) = chars.next() {
170 if character == '{' && chars.peek() == Some(&'{') {
171 chars.next();
172 literal.push('{');
173 continue;
174 }
175 if character == '}' && chars.peek() == Some(&'}') {
176 chars.next();
177 literal.push('}');
178 continue;
179 }
180 if character != '{' {
181 literal.push(character);
182 continue;
183 }
184 if !literal.is_empty() {
185 nodes.push(TemplateNode::Literal {
186 text: std::mem::take(&mut literal),
187 });
188 }
189 let mut name = String::new();
190 loop {
191 match chars.next() {
192 Some('}') => break,
193 Some('{') | None => {
194 return Err(DeliveryError::InvalidTemplate(
195 "unclosed or nested placeholder".into(),
196 ));
197 }
198 Some(value) => name.push(value),
199 }
200 }
201 nodes.push(TemplateNode::Slot {
202 slot: parse_slot(name.trim())?,
203 });
204 }
205 if !literal.is_empty() {
206 nodes.push(TemplateNode::Literal { text: literal });
207 }
208 Ok(nodes)
209}
210
211fn parse_slot(name: &str) -> Result<TemplateSlot, DeliveryError> {
212 match name {
213 "title" => Ok(TemplateSlot::Title),
214 "body" => Ok(TemplateSlot::Body),
215 "source_markdown" => Ok(TemplateSlot::SourceMarkdown),
216 "block_count" => Ok(TemplateSlot::BlockCount),
217 _ => name
218 .strip_prefix("metadata.")
219 .filter(|key| !key.is_empty())
220 .map(|key| TemplateSlot::Metadata { key: key.into() })
221 .ok_or_else(|| {
222 DeliveryError::InvalidTemplate(format!("unknown placeholder {{{name}}}"))
223 }),
224 }
225}
226
227#[cfg(test)]
228#[allow(clippy::expect_used)]
229mod tests {
230 use super::*;
231
232 #[test]
233 fn loads_safe_layer_and_rejects_unknown_placeholder() {
234 let root =
235 std::env::temp_dir().join(format!("vak-delivery-template-{}", std::process::id()));
236 std::fs::create_dir_all(&root).expect("root");
237 let user = root.join("output.toml");
238 std::fs::write(
239 &user,
240 "[templates.compact]\nformat = \"{title}\\n\\n{body}\"\n\n[channels.telegram]\ntemplate = \"compact\"\nmax_chars = 4000\n",
241 )
242 .expect("template");
243 let loaded = load_layers(&user, &root.join("project.toml"), true);
244 assert!(loaded.warnings.is_empty(), "{:?}", loaded.warnings);
245 assert!(loaded.registry.resolve("compact").is_some());
246 assert_eq!(loaded.channels["telegram"].max_chars, Some(4000));
247
248 std::fs::write(&user, "[templates.bad]\nformat = \"{execute}\"\n").expect("bad template");
249 let loaded = load_layers(&user, &root.join("project.toml"), true);
250 assert_eq!(loaded.warnings.len(), 1);
251 let _ = std::fs::remove_dir_all(root);
252 }
253}
254

Indexing the workspace…