fallow_types/sourced.rs
1//! Values that record their cause.
2//!
3//! A run decision, such as the production mode of one analysis, comes from
4//! one of several inputs. [`Sourced`](crate::sourced::Sourced) keeps the
5//! value together with the [`Source`](crate::sourced::Source) that gave it and
6//! the [`Scope`](crate::sourced::Scope) of that input. The rank
7//! `(Layer, Scope)` orders the inputs: a higher rank wins.
8
9use std::path::PathBuf;
10
11use serde::Serialize;
12
13/// The input layer of a value, from the weakest to the strongest.
14#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize)]
15#[serde(rename_all = "kebab-case")]
16pub enum Layer {
17 /// A built-in default, or a value that follows from another decision.
18 Default,
19 /// A key of the config file.
20 ConfigFile,
21 /// An environment variable.
22 Environment,
23 /// A value that the caller gives: a flag, a tool parameter, an editor
24 /// setting, or an API option.
25 Given,
26}
27
28/// The scope of an input. In one layer, an input of one analysis wins over an
29/// input of every analysis.
30#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize)]
31#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
32#[serde(rename_all = "kebab-case")]
33pub enum Scope {
34 /// The input applies to every analysis, for example `--production`.
35 Global,
36 /// The input applies to one analysis, for example `--production-health`.
37 Analysis,
38}
39
40/// The surface input that gave a [`Layer::Given`] value. The name is the
41/// spelling of the input on that surface.
42#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize)]
43#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
44#[serde(tag = "kind", content = "name", rename_all = "kebab-case")]
45pub enum Origin {
46 /// A CLI flag, for example `--production`.
47 Flag(&'static str),
48 /// An MCP tool parameter, for example `production_dead_code`.
49 ToolParam(&'static str),
50 /// An editor setting, for example `fallow.production`.
51 EditorSetting(&'static str),
52 /// An option of the Rust API, for example `analysis.production_override`.
53 ApiOption(&'static str),
54 /// An option of the Node bindings, for example `production`.
55 NodeOption(&'static str),
56}
57
58/// The input that gave a value.
59#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize)]
60#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
61#[serde(tag = "kind", rename_all = "kebab-case")]
62pub enum Source {
63 /// A built-in default. `rule` names the default.
64 Default {
65 /// The name of the default.
66 rule: &'static str,
67 },
68 /// A value that follows from another decision or input. `from` names it.
69 Derived {
70 /// The name of the decision or input.
71 from: &'static str,
72 },
73 /// A key of the config file. `file` is the top file of the `extends`
74 /// chain, because the merge of the chain keeps no file per key.
75 ConfigFile {
76 /// The top config file.
77 #[serde(serialize_with = "crate::serde_path::serialize")]
78 #[cfg_attr(feature = "schema", schemars(with = "String"))]
79 file: PathBuf,
80 /// The config key, for example `production.deadCode`.
81 key: &'static str,
82 },
83 /// An environment variable.
84 Environment {
85 /// The name of the variable, for example `FALLOW_PRODUCTION`.
86 name: &'static str,
87 },
88 /// A value that the caller gives.
89 Given {
90 /// The surface input.
91 origin: Origin,
92 },
93}
94
95impl Source {
96 /// The input layer of this source. [`Source::Default`] and
97 /// [`Source::Derived`] are in [`Layer::Default`].
98 #[must_use]
99 pub const fn layer(&self) -> Layer {
100 match self {
101 Self::Default { .. } | Self::Derived { .. } => Layer::Default,
102 Self::ConfigFile { .. } => Layer::ConfigFile,
103 Self::Environment { .. } => Layer::Environment,
104 Self::Given { .. } => Layer::Given,
105 }
106 }
107}
108
109/// A value with the input that gave it and the scope of that input.
110#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
111#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
112#[cfg_attr(feature = "schema", schemars(rename = "Sourced_for_{T}"))]
113pub struct Sourced<T> {
114 /// The value.
115 value: T,
116 /// The input that gave the value.
117 source: Source,
118 /// The scope of that input.
119 scope: Scope,
120}
121
122impl<T> Sourced<T> {
123 /// A value from `source`, an input with `scope`.
124 #[must_use]
125 pub const fn new(value: T, source: Source, scope: Scope) -> Self {
126 Self {
127 value,
128 source,
129 scope,
130 }
131 }
132
133 /// The value.
134 #[must_use]
135 pub const fn value(&self) -> &T {
136 &self.value
137 }
138
139 /// The value, without its source.
140 #[must_use]
141 pub fn into_value(self) -> T {
142 self.value
143 }
144
145 /// The input that gave the value.
146 #[must_use]
147 pub const fn source(&self) -> &Source {
148 &self.source
149 }
150
151 /// The rank of the input. Of two inputs for one decision, the input with
152 /// the higher rank wins.
153 #[must_use]
154 pub const fn rank(&self) -> (Layer, Scope) {
155 (self.source.layer(), self.scope)
156 }
157
158 /// The value changed by `f`, with the same source and scope.
159 #[must_use]
160 pub fn map<U>(self, f: impl FnOnce(T) -> U) -> Sourced<U> {
161 Sourced {
162 value: f(self.value),
163 source: self.source,
164 scope: self.scope,
165 }
166 }
167}
168
169/// A value that the caller gives, with the surface input that carries it.
170#[derive(Debug, Clone, Copy, PartialEq, Eq)]
171pub struct Given<T> {
172 /// The value.
173 pub value: T,
174 /// The surface input.
175 pub origin: Origin,
176}
177
178#[cfg(test)]
179mod tests {
180 use std::path::PathBuf;
181
182 use super::*;
183
184 #[test]
185 fn source_serializes_with_kebab_case_kind() {
186 let source = Source::ConfigFile {
187 file: PathBuf::from("project/.fallowrc.json"),
188 key: "production.deadCode",
189 };
190 assert_eq!(
191 serde_json::to_value(&source).unwrap(),
192 serde_json::json!({
193 "kind": "config-file",
194 "file": "project/.fallowrc.json",
195 "key": "production.deadCode",
196 })
197 );
198 }
199}