dre_core/config/
node.rs

1//! A parsed YAML document as a tree of nodes, each with the line and column it was written at.
2//!
3//! YAML is parsed by `serde-saphyr`, YAML 1.2 with strict booleans: only `true` and `false` are
4//! booleans, so `yes`, `no`, `on` and `off` stay strings. Duplicate keys are errors; merge keys
5//! (`<<: *base`) are expanded. Typed config is then read from the tree (see [`super::de`]), so every
6//! diagnostic can point at the exact line of the key or value it's about.
7
8use std::fmt;
9
10use serde::de::{Deserialize, Deserializer, MapAccess, SeqAccess, Visitor};
11use serde_saphyr::Spanned;
12
13/// A YAML value and where it was written (1-based; 0 when unknown).
14#[derive(Debug, Clone, PartialEq)]
15pub struct Node {
16    pub kind: Kind,
17    pub line: usize,
18    pub column: usize,
19}
20
21#[derive(Debug, Clone, PartialEq)]
22pub enum Kind {
23    Null,
24    Bool(bool),
25    Int(i64),
26    UInt(u64),
27    Float(f64),
28    Str(String),
29    Seq(Vec<Node>),
30    /// In the file's order. Keys are strings: a scalar key (`2024:`) keeps its spelling.
31    Map(Vec<(Key, Node)>),
32}
33
34/// A map key and its line.
35#[derive(Debug, Clone, PartialEq, Eq)]
36pub struct Key {
37    pub name: String,
38    pub line: usize,
39}
40
41/// A YAML syntax error, with its line when known.
42#[derive(Debug, Clone, PartialEq, Eq)]
43pub struct SyntaxError {
44    pub line: Option<usize>,
45    pub message: String,
46}
47
48impl Kind {
49    /// How a value of this kind is named in diagnostics.
50    pub fn name(&self) -> &'static str {
51        match self {
52            Kind::Null => "nothing",
53            Kind::Bool(_) => "a boolean",
54            Kind::Int(_) | Kind::UInt(_) | Kind::Float(_) => "a number",
55            Kind::Str(_) => "a string",
56            Kind::Seq(_) => "a list",
57            Kind::Map(_) => "a map",
58        }
59    }
60}
61
62impl Node {
63    pub fn null() -> Node {
64        Node {
65            kind: Kind::Null,
66            line: 0,
67            column: 0,
68        }
69    }
70
71    pub fn as_str(&self) -> Option<&str> {
72        match &self.kind {
73            Kind::Str(s) => Some(s),
74            _ => None,
75        }
76    }
77
78    pub fn as_map(&self) -> Option<&[(Key, Node)]> {
79        match &self.kind {
80            Kind::Map(m) => Some(m),
81            _ => None,
82        }
83    }
84
85    /// A key's value in a map node.
86    pub fn get(&self, key: &str) -> Option<&Node> {
87        self.as_map()?.iter().find(|(k, _)| k.name == key).map(|(_, v)| v)
88    }
89
90    /// A key's entry (key and value) in a map node.
91    pub fn entry(&self, key: &str) -> Option<&(Key, Node)> {
92        self.as_map()?.iter().find(|(k, _)| k.name == key)
93    }
94
95    /// The node as JSON, for values handed on unvalidated (a plugin's fields). Keys are strings;
96    /// numbers that don't fit JSON's become strings.
97    pub fn to_json(&self) -> serde_json::Value {
98        use serde_json::Value as J;
99        match &self.kind {
100            Kind::Null => J::Null,
101            Kind::Bool(b) => J::Bool(*b),
102            Kind::Int(i) => J::from(*i),
103            Kind::UInt(u) => J::from(*u),
104            Kind::Float(f) => {
105                serde_json::Number::from_f64(*f).map_or_else(|| J::String(f.to_string()), J::Number)
106            }
107            Kind::Str(s) => J::String(s.clone()),
108            Kind::Seq(s) => J::Array(s.iter().map(Node::to_json).collect()),
109            Kind::Map(m) => J::Object(m.iter().map(|(k, v)| (k.name.clone(), v.to_json())).collect()),
110        }
111    }
112}
113
114/// Parse a YAML document. An empty document is a null node.
115pub fn parse(text: &str) -> Result<Node, SyntaxError> {
116    let mut options = serde_saphyr::options::Options::default();
117    options.strict_booleans = true;
118    options.duplicate_keys = serde_saphyr::options::DuplicateKeyPolicy::Error;
119    options.with_snippet = false;
120    // `.inf` and `.nan` are values like any other; a plugin decides what they mean.
121    options.reject_non_finite_typeless_float = false;
122    if text.trim().is_empty() {
123        return Ok(Node::null());
124    }
125    match serde_saphyr::from_str_with_options::<Spanned<Raw>>(text, options) {
126        Ok(raw) => {
127            let mut node: Node = raw.into();
128            // Top-level `x-*` keys (the docker-compose convention) hold YAML anchors to reuse
129            // with aliases and `<<:` merges; once those are resolved, DRE ignores them.
130            if let Kind::Map(m) = &mut node.kind {
131                m.retain(|(k, _)| !k.name.starts_with("x-"));
132            }
133            Ok(node)
134        }
135        Err(e) => Err(syntax_error(&e)),
136    }
137}
138
139fn syntax_error(e: &serde_saphyr::Error) -> SyntaxError {
140    static LOCATION: std::sync::LazyLock<regex::Regex> = std::sync::LazyLock::new(|| {
141        regex::Regex::new(r"^(?:error: )?(?:line \d+ column \d+: )?(.*?)(?: at line \d+, column \d+)?$")
142            .unwrap()
143    });
144    let line = e.location().map(|l| l.line() as usize).filter(|l| *l > 0);
145    let text = e.to_string();
146    let first = text.lines().next().unwrap_or_default();
147    // DRE prints the line itself, and serde-saphyr's hint names its own options.
148    let message = LOCATION
149        .captures(first)
150        .map_or(first, |c| c.get(1).map_or(first, |m| m.as_str()));
151    let message = message.replace(", set DuplicateKeyPolicy in Options if acceptable", "");
152    let message = if message.contains("merge value must be") {
153        "invalid YAML merge key (`<<`): `<<` must be a map or a list of maps".to_string()
154    } else {
155        message
156    };
157    SyntaxError { line, message }
158}
159
160/// The tree as serde-saphyr hands it over: every value with its location.
161enum Raw {
162    Null,
163    Bool(bool),
164    Int(i64),
165    UInt(u64),
166    Float(f64),
167    Str(String),
168    Seq(Vec<Spanned<Raw>>),
169    Map(Vec<(Spanned<KeyRaw>, Spanned<Raw>)>),
170}
171
172/// A map key as written: a scalar, kept as its spelling (`null`, `true`, `2024`).
173struct KeyRaw(String);
174
175impl From<Spanned<Raw>> for Node {
176    fn from(s: Spanned<Raw>) -> Node {
177        let kind = match s.value {
178            Raw::Null => Kind::Null,
179            Raw::Bool(b) => Kind::Bool(b),
180            Raw::Int(i) => Kind::Int(i),
181            Raw::UInt(u) => Kind::UInt(u),
182            Raw::Float(f) => Kind::Float(f),
183            Raw::Str(t) => Kind::Str(t),
184            Raw::Seq(items) => Kind::Seq(items.into_iter().map(Node::from).collect()),
185            Raw::Map(entries) => Kind::Map(
186                entries
187                    .into_iter()
188                    .map(|(k, v)| {
189                        let key = Key {
190                            name: k.value.0,
191                            line: k.referenced.line() as usize,
192                        };
193                        (key, Node::from(v))
194                    })
195                    .collect(),
196            ),
197        };
198        Node {
199            kind,
200            line: s.referenced.line() as usize,
201            column: s.referenced.column() as usize,
202        }
203    }
204}
205
206impl<'de> Deserialize<'de> for Raw {
207    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
208        struct V;
209        impl<'de> Visitor<'de> for V {
210            type Value = Raw;
211            fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
212                f.write_str("a YAML value")
213            }
214            fn visit_unit<E>(self) -> Result<Raw, E> {
215                Ok(Raw::Null)
216            }
217            fn visit_none<E>(self) -> Result<Raw, E> {
218                Ok(Raw::Null)
219            }
220            fn visit_some<D: Deserializer<'de>>(self, d: D) -> Result<Raw, D::Error> {
221                Raw::deserialize(d)
222            }
223            fn visit_bool<E>(self, v: bool) -> Result<Raw, E> {
224                Ok(Raw::Bool(v))
225            }
226            fn visit_i64<E>(self, v: i64) -> Result<Raw, E> {
227                Ok(Raw::Int(v))
228            }
229            fn visit_u64<E>(self, v: u64) -> Result<Raw, E> {
230                Ok(i64::try_from(v).map_or(Raw::UInt(v), Raw::Int))
231            }
232            fn visit_f64<E>(self, v: f64) -> Result<Raw, E> {
233                Ok(Raw::Float(v))
234            }
235            fn visit_str<E>(self, v: &str) -> Result<Raw, E> {
236                Ok(Raw::Str(v.to_string()))
237            }
238            fn visit_string<E>(self, v: String) -> Result<Raw, E> {
239                Ok(Raw::Str(v))
240            }
241            fn visit_seq<A: SeqAccess<'de>>(self, mut a: A) -> Result<Raw, A::Error> {
242                let mut items = Vec::new();
243                while let Some(x) = a.next_element()? {
244                    items.push(x);
245                }
246                Ok(Raw::Seq(items))
247            }
248            fn visit_map<A: MapAccess<'de>>(self, mut a: A) -> Result<Raw, A::Error> {
249                let mut entries = Vec::new();
250                while let Some(e) = a.next_entry()? {
251                    entries.push(e);
252                }
253                Ok(Raw::Map(entries))
254            }
255        }
256        d.deserialize_any(V)
257    }
258}
259
260/// The message for a key that's a list or a map.
261pub const COMPLEX_KEY: &str = "a map key is a list or a map; keys must be names";
262
263impl<'de> Deserialize<'de> for KeyRaw {
264    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
265        struct V;
266        impl<'de> Visitor<'de> for V {
267            type Value = KeyRaw;
268            fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
269                f.write_str("a key")
270            }
271            fn visit_unit<E>(self) -> Result<KeyRaw, E> {
272                Ok(KeyRaw("null".into()))
273            }
274            fn visit_none<E>(self) -> Result<KeyRaw, E> {
275                Ok(KeyRaw("null".into()))
276            }
277            fn visit_bool<E>(self, v: bool) -> Result<KeyRaw, E> {
278                Ok(KeyRaw(v.to_string()))
279            }
280            fn visit_i64<E>(self, v: i64) -> Result<KeyRaw, E> {
281                Ok(KeyRaw(v.to_string()))
282            }
283            fn visit_u64<E>(self, v: u64) -> Result<KeyRaw, E> {
284                Ok(KeyRaw(v.to_string()))
285            }
286            fn visit_f64<E>(self, v: f64) -> Result<KeyRaw, E> {
287                Ok(KeyRaw(v.to_string()))
288            }
289            fn visit_str<E>(self, v: &str) -> Result<KeyRaw, E> {
290                Ok(KeyRaw(v.to_string()))
291            }
292            fn visit_string<E>(self, v: String) -> Result<KeyRaw, E> {
293                Ok(KeyRaw(v))
294            }
295            fn visit_seq<A: SeqAccess<'de>>(self, _: A) -> Result<KeyRaw, A::Error> {
296                Err(serde::de::Error::custom(COMPLEX_KEY))
297            }
298            fn visit_map<A: MapAccess<'de>>(self, _: A) -> Result<KeyRaw, A::Error> {
299                Err(serde::de::Error::custom(COMPLEX_KEY))
300            }
301        }
302        d.deserialize_any(V)
303    }
304}
305
306#[cfg(test)]
307mod tests {
308    use super::*;
309
310    #[test]
311    fn values_keep_their_lines() {
312        let n = parse("a:\n  b: 1\n  c: [x, y]\n").unwrap();
313        let a = n.get("a").unwrap();
314        assert_eq!(n.entry("a").unwrap().0.line, 1);
315        assert_eq!(a.entry("c").unwrap().0.line, 3);
316        assert_eq!(a.get("b").unwrap().kind, Kind::Int(1));
317        assert_eq!(a.get("b").unwrap().line, 2);
318    }
319
320    #[test]
321    fn only_true_and_false_are_booleans() {
322        let n = parse("a: yes\nb: no\nc: on\nd: true\n").unwrap();
323        assert_eq!(n.get("a").unwrap().as_str(), Some("yes"));
324        assert_eq!(n.get("c").unwrap().as_str(), Some("on"));
325        assert_eq!(n.get("d").unwrap().kind, Kind::Bool(true));
326    }
327
328    #[test]
329    fn merge_keys_are_expanded_and_written_keys_win() {
330        let n = parse("base: &b {type: duckdb, path: x}\ndev: {<<: *b, path: y}\n").unwrap();
331        let dev = n.get("dev").unwrap();
332        assert_eq!(dev.get("type").unwrap().as_str(), Some("duckdb"));
333        assert_eq!(dev.get("path").unwrap().as_str(), Some("y"));
334    }
335
336    #[test]
337    fn duplicate_keys_are_errors_with_their_line() {
338        let e = parse("a: 1\na: 2\n").unwrap_err();
339        assert_eq!(e.line, Some(2));
340        assert_eq!(e.message, "duplicate mapping key: a");
341    }
342
343    #[test]
344    fn syntax_errors_have_a_line() {
345        let e = parse("a:\n  b: [1\n").unwrap_err();
346        assert_eq!(e.line, Some(2));
347        assert!(!e.message.starts_with("line"), "{}", e.message);
348    }
349
350    #[test]
351    fn scalar_keys_are_strings_and_empty_files_are_null() {
352        assert_eq!(
353            parse("2024: x\n").unwrap().get("2024").unwrap().as_str(),
354            Some("x")
355        );
356        assert_eq!(parse("\n# nothing\n").unwrap().kind, Kind::Null);
357    }
358
359    #[test]
360    fn jinja_in_quoted_values_is_a_string() {
361        let n = parse("pw: \"{{ env_var('X') }}\"\n").unwrap();
362        assert_eq!(n.get("pw").unwrap().as_str(), Some("{{ env_var('X') }}"));
363    }
364}
365
366#[cfg(test)]
367mod x_key_tests {
368    use super::*;
369
370    #[test]
371    fn top_level_x_keys_hold_anchors_and_are_dropped() {
372        let n = parse("x-dest: &dest {profile: s3, path: a.csv}\noutput:\n  destination:\n    <<: *dest\n    path: b.csv\n").unwrap();
373        let j = n.to_json();
374        assert!(j.get("x-dest").is_none(), "{j}");
375        assert_eq!(
376            j["output"]["destination"],
377            serde_json::json!({"profile": "s3", "path": "b.csv"})
378        );
379    }
380}
dre_core/config/node.rs

dre_core/config/
node.rs
