Skip to main content

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}