Skip to main content

c4/
trace.rs

1//! Provenance: [`SourceRef`] labels and the [`TracedValue`] tree that
2//! `Loader::trace` returns. Serializes to `$id`-tagged JSON leaves — a
3//! debug/test aid, never config data.
4
5use std::collections::BTreeMap;
6use std::path::PathBuf;
7
8use crate::Value;
9
10/// Where a traced value came from.
11///
12/// Source labels exist for debugging and testing — they are not config
13/// data, and no config semantics should be built on top of them.
14#[derive(Debug, Clone, PartialEq, Eq)]
15pub enum SourceRef {
16    /// The file path as the loader saw it (source path joined with the
17    /// relative path inside a folder source).
18    File(PathBuf),
19    /// A [`Source::String`](crate::Source::String) entry, by its index in
20    /// the sources list.
21    String(usize),
22    /// A [`Source::Value`](crate::Source::Value) entry (a 1-tuple
23    /// `(value,)` source), by its index in the sources list.
24    Value(usize),
25}
26
27/// The result of [`Loader::trace`](crate::Loader::trace): the merged tree
28/// with per-leaf
29/// provenance. Objects recurse; every non-object value (including whole
30/// arrays) is a [`TracedValue::Leaf`].
31///
32/// Serializes to JSON as
33/// `{ "$id": "Leaf", "value": …, "source": …, "format": … }` leaves —
34/// the shape used by the CLI `--trace` output and the test fixtures'
35/// expect.json. `$id` tags the node kind (an object node is a plain
36/// map), `source` is the file path (`SourceRef::String(i)` prints as
37/// `"string:<i>"`), `format` is the value's [`Value::format_id`].
38#[derive(Debug, Clone, PartialEq)]
39pub enum TracedValue {
40    Leaf { value: Value, source: SourceRef },
41    Object(BTreeMap<String, TracedValue>),
42}
43
44impl SourceRef {
45    /// The label used in serialized traces: the file path, or
46    /// `string:<index>` for string sources.
47    fn label(&self) -> String {
48        match self {
49            SourceRef::File(path) => path.to_string_lossy().into_owned(),
50            SourceRef::String(index) => format!("string:{index}"),
51            SourceRef::Value(index) => format!("value:{index}"),
52        }
53    }
54}
55
56impl serde::Serialize for TracedValue {
57    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
58    where
59        S: serde::Serializer,
60    {
61        use serde::ser::SerializeMap;
62        match self {
63            TracedValue::Leaf { value, source } => {
64                // "$id" tags the node kind: a plain config object could
65                // itself have value/source/format keys, and the tag makes
66                // json trace output self-describing for debugging
67                let mut map = serializer.serialize_map(Some(4))?;
68                map.serialize_entry("$id", "Leaf")?;
69                map.serialize_entry("value", value)?;
70                map.serialize_entry("source", &source.label())?;
71                map.serialize_entry("format", &value.format_id())?;
72                map.end()
73            }
74            TracedValue::Object(entries) => serializer.collect_map(entries),
75        }
76    }
77}