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}