Skip to main content

graphrt_core/
source_map.rs

1//! Source positions of the values in a workflow document.
2//!
3//! A [`SourceMap`] maps document paths (`graph.nodes[1].template`, see
4//! [`DocPath`]) to the line and column of the YAML or JSON node they came
5//! from, so validation errors can point at the offending text. It is built by
6//! a second, span-aware parse of the same text and is best effort: when the
7//! text cannot be parsed, or the `yaml` feature (which provides the span-aware
8//! parser, also used for JSON) is disabled, the map is empty and diagnostics
9//! carry a path but no position.
10
11use std::collections::HashMap;
12use std::fmt;
13
14use serde::Serialize;
15
16/// A position in the source text. Lines and columns are 1-based and count
17/// characters, not bytes.
18#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
19pub struct SourceSpan {
20    pub line: u32,
21    pub column: u32,
22    /// Length of the node in characters (at least 1). For multi-line nodes
23    /// this runs past the end of the first line.
24    pub len: u32,
25}
26
27/// One segment of a [`DocPath`].
28#[derive(Clone, Debug, PartialEq, Eq, Hash)]
29pub enum PathSegment {
30    Key(String),
31    Index(usize),
32}
33
34/// Path of a value inside a workflow document, e.g. `graph.nodes[1].template`.
35#[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
36pub struct DocPath(Vec<PathSegment>);
37
38impl DocPath {
39    /// The document root.
40    pub fn root() -> Self {
41        Self::default()
42    }
43
44    /// This path extended by an object key.
45    #[must_use]
46    pub fn key(&self, key: &str) -> Self {
47        let mut segments = self.0.clone();
48        segments.push(PathSegment::Key(key.to_owned()));
49        Self(segments)
50    }
51
52    /// This path extended by an array index.
53    #[must_use]
54    pub fn index(&self, index: usize) -> Self {
55        let mut segments = self.0.clone();
56        segments.push(PathSegment::Index(index));
57        Self(segments)
58    }
59
60    /// The enclosing path, `None` at the root.
61    pub fn parent(&self) -> Option<Self> {
62        let (_, rest) = self.0.split_last()?;
63        Some(Self(rest.to_vec()))
64    }
65
66    /// The segments, outermost first.
67    pub fn segments(&self) -> &[PathSegment] {
68        &self.0
69    }
70
71    /// The last key, if the path ends in a key.
72    pub fn last_key(&self) -> Option<&str> {
73        match self.0.last() {
74            Some(PathSegment::Key(key)) => Some(key),
75            _ => None,
76        }
77    }
78
79    pub fn is_root(&self) -> bool {
80        self.0.is_empty()
81    }
82}
83
84impl fmt::Display for DocPath {
85    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
86        if self.0.is_empty() {
87            return f.write_str("<document>");
88        }
89        for (i, segment) in self.0.iter().enumerate() {
90            match segment {
91                PathSegment::Index(ix) => write!(f, "[{ix}]")?,
92                PathSegment::Key(key) if is_plain_key(key) => {
93                    if i > 0 {
94                        f.write_str(".")?;
95                    }
96                    f.write_str(key)?;
97                }
98                PathSegment::Key(key) => write!(f, "[{key:?}]")?,
99            }
100        }
101        Ok(())
102    }
103}
104
105impl Serialize for DocPath {
106    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
107        serializer.collect_str(self)
108    }
109}
110
111fn is_plain_key(key: &str) -> bool {
112    !key.is_empty() && key.chars().all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
113}
114
115/// Positions of keys and values, by document path.
116#[derive(Clone, Debug, Default)]
117pub struct SourceMap {
118    /// Position of the value at a path.
119    values: HashMap<DocPath, SourceSpan>,
120    /// Position of the mapping key introducing a path (object members only).
121    keys: HashMap<DocPath, SourceSpan>,
122}
123
124impl SourceMap {
125    /// An empty map (no positions known).
126    pub fn empty() -> Self {
127        Self::default()
128    }
129
130    /// Positions for a JSON or YAML document. Empty when the text cannot be
131    /// parsed or the `yaml` feature is disabled.
132    pub fn from_text(text: &str) -> Self {
133        #[cfg(feature = "yaml")]
134        {
135            spanned::parse(text).unwrap_or_default()
136        }
137        #[cfg(not(feature = "yaml"))]
138        {
139            let _ = text;
140            Self::default()
141        }
142    }
143
144    /// Position of the value at `path`.
145    pub fn value(&self, path: &DocPath) -> Option<SourceSpan> {
146        self.values.get(path).copied()
147    }
148
149    /// Position of the key that introduces `path` (for object members).
150    pub fn key(&self, path: &DocPath) -> Option<SourceSpan> {
151        self.keys.get(path).copied()
152    }
153
154    /// Best position for a diagnostic about `path`: the key (when `prefer_key`)
155    /// or the value at the path, else the closest enclosing value that has one.
156    pub fn locate(&self, path: &DocPath, prefer_key: bool) -> Option<SourceSpan> {
157        if prefer_key {
158            if let Some(span) = self.key(path) {
159                return Some(span);
160            }
161        }
162        let mut current = Some(path.clone());
163        while let Some(p) = current {
164            if let Some(span) = self.value(&p).or_else(|| self.key(&p)) {
165                return Some(span);
166            }
167            current = p.parent();
168        }
169        None
170    }
171
172    pub fn is_empty(&self) -> bool {
173        self.values.is_empty()
174    }
175}
176
177#[cfg(feature = "yaml")]
178mod spanned {
179    //! A span-aware parse with `serde_saphyr::Spanned`. JSON is parsed by the
180    //! same parser (JSON documents are YAML 1.2 flow documents).
181
182    use std::fmt;
183
184    use serde::de::{self, Deserialize, Deserializer, MapAccess, SeqAccess, Visitor};
185    use serde_saphyr::{Location, Spanned};
186
187    use super::{DocPath, SourceMap, SourceSpan};
188
189    /// A document tree that keeps the location of every node.
190    enum Tree {
191        Scalar,
192        Seq(Vec<Spanned<Tree>>),
193        Map(Vec<(Spanned<Key>, Spanned<Tree>)>),
194    }
195
196    /// A mapping key rendered as text.
197    struct Key(String);
198
199    pub(super) fn parse(text: &str) -> Option<SourceMap> {
200        let options = serde_saphyr::options! { strict_booleans: true };
201        let tree: Spanned<Tree> = serde_saphyr::from_str_with_options(text, options).ok()?;
202        let mut map = SourceMap::default();
203        record(&tree, &DocPath::root(), &mut map);
204        Some(map)
205    }
206
207    fn span(location: &Location) -> Option<SourceSpan> {
208        let line = u32::try_from(location.line()).ok().filter(|l| *l > 0)?;
209        let column = u32::try_from(location.column()).ok().filter(|c| *c > 0)?;
210        let len = u32::try_from(location.span().len()).unwrap_or(u32::MAX).max(1);
211        Some(SourceSpan { line, column, len })
212    }
213
214    fn record(node: &Spanned<Tree>, path: &DocPath, map: &mut SourceMap) {
215        if let Some(s) = span(&node.referenced) {
216            map.values.insert(path.clone(), s);
217        }
218        match &node.value {
219            Tree::Scalar => {}
220            Tree::Seq(items) => {
221                for (ix, item) in items.iter().enumerate() {
222                    record(item, &path.index(ix), map);
223                }
224            }
225            Tree::Map(entries) => {
226                for (key, value) in entries {
227                    let child = path.key(&key.value.0);
228                    if let Some(s) = span(&key.referenced) {
229                        map.keys.insert(child.clone(), s);
230                    }
231                    record(value, &child, map);
232                }
233            }
234        }
235    }
236
237    struct TreeVisitor;
238
239    impl<'de> Visitor<'de> for TreeVisitor {
240        type Value = Tree;
241
242        fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
243            f.write_str("any YAML value")
244        }
245
246        fn visit_bool<E: de::Error>(self, _: bool) -> Result<Tree, E> {
247            Ok(Tree::Scalar)
248        }
249        fn visit_i64<E: de::Error>(self, _: i64) -> Result<Tree, E> {
250            Ok(Tree::Scalar)
251        }
252        fn visit_i128<E: de::Error>(self, _: i128) -> Result<Tree, E> {
253            Ok(Tree::Scalar)
254        }
255        fn visit_u64<E: de::Error>(self, _: u64) -> Result<Tree, E> {
256            Ok(Tree::Scalar)
257        }
258        fn visit_u128<E: de::Error>(self, _: u128) -> Result<Tree, E> {
259            Ok(Tree::Scalar)
260        }
261        fn visit_f64<E: de::Error>(self, _: f64) -> Result<Tree, E> {
262            Ok(Tree::Scalar)
263        }
264        fn visit_str<E: de::Error>(self, _: &str) -> Result<Tree, E> {
265            Ok(Tree::Scalar)
266        }
267        fn visit_bytes<E: de::Error>(self, _: &[u8]) -> Result<Tree, E> {
268            Ok(Tree::Scalar)
269        }
270        fn visit_unit<E: de::Error>(self) -> Result<Tree, E> {
271            Ok(Tree::Scalar)
272        }
273        fn visit_none<E: de::Error>(self) -> Result<Tree, E> {
274            Ok(Tree::Scalar)
275        }
276        fn visit_some<D: Deserializer<'de>>(self, d: D) -> Result<Tree, D::Error> {
277            Tree::deserialize(d)
278        }
279        fn visit_seq<A: SeqAccess<'de>>(self, mut seq: A) -> Result<Tree, A::Error> {
280            let mut items = Vec::new();
281            while let Some(item) = seq.next_element::<Spanned<Tree>>()? {
282                items.push(item);
283            }
284            Ok(Tree::Seq(items))
285        }
286        fn visit_map<A: MapAccess<'de>>(self, mut access: A) -> Result<Tree, A::Error> {
287            let mut entries = Vec::new();
288            while let Some(key) = access.next_key::<Spanned<Key>>()? {
289                let value = access.next_value::<Spanned<Tree>>()?;
290                entries.push((key, value));
291            }
292            Ok(Tree::Map(entries))
293        }
294    }
295
296    impl<'de> Deserialize<'de> for Tree {
297        fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
298            d.deserialize_any(TreeVisitor)
299        }
300    }
301
302    struct KeyVisitor;
303
304    impl Visitor<'_> for KeyVisitor {
305        type Value = Key;
306
307        fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
308            f.write_str("a scalar mapping key")
309        }
310        fn visit_str<E: de::Error>(self, v: &str) -> Result<Key, E> {
311            Ok(Key(v.to_owned()))
312        }
313        fn visit_bool<E: de::Error>(self, v: bool) -> Result<Key, E> {
314            Ok(Key(v.to_string()))
315        }
316        fn visit_i64<E: de::Error>(self, v: i64) -> Result<Key, E> {
317            Ok(Key(v.to_string()))
318        }
319        fn visit_u64<E: de::Error>(self, v: u64) -> Result<Key, E> {
320            Ok(Key(v.to_string()))
321        }
322        fn visit_f64<E: de::Error>(self, v: f64) -> Result<Key, E> {
323            Ok(Key(v.to_string()))
324        }
325        fn visit_unit<E: de::Error>(self) -> Result<Key, E> {
326            Ok(Key("null".to_owned()))
327        }
328    }
329
330    impl<'de> Deserialize<'de> for Key {
331        fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
332            d.deserialize_any(KeyVisitor)
333        }
334    }
335}
336
337#[cfg(all(test, feature = "yaml"))]
338mod tests {
339    use super::*;
340
341    #[test]
342    fn records_key_and_value_positions() {
343        let text = "graph:\n  nodes:\n    - id: a\n      templat: hi\n";
344        let map = SourceMap::from_text(text);
345        let path = DocPath::root().key("graph").key("nodes").index(0).key("templat");
346        assert_eq!(map.key(&path), Some(SourceSpan { line: 4, column: 7, len: 7 }));
347        assert_eq!(map.value(&path).map(|s| (s.line, s.column)), Some((4, 16)));
348        assert_eq!(path.to_string(), "graph.nodes[0].templat");
349    }
350
351    #[test]
352    fn json_positions() {
353        let text = "{\"graph\": {\"nodes\": [\n  {\"id\": \"a\", \"type\": \"start\"}\n]}}";
354        let map = SourceMap::from_text(text);
355        let path = DocPath::root().key("graph").key("nodes").index(0).key("type");
356        assert_eq!(map.key(&path).map(|s| (s.line, s.column)), Some((2, 15)));
357    }
358
359    #[test]
360    fn locate_falls_back_to_ancestors() {
361        let map = SourceMap::from_text("graph:\n  nodes: []\n");
362        let path = DocPath::root().key("graph").key("nodes").index(3).key("x");
363        assert_eq!(map.locate(&path, true).map(|s| s.line), Some(2));
364        assert_eq!(DocPath::root().key("a b").index(1).to_string(), "[\"a b\"][1]");
365    }
366}