Skip to main content

argenv/
vocabulary.rs

1//! Vocabulary — the closed sets and structured scalars a declaration is built
2//! from. No naked primitive ever stands for a domain-meaningful value.
3use crate::Version;
4use serde_json::Value;
5use std::fmt;
6
7/// The coarse wire *kind* a variable exposes in the contract.
8///
9/// This is the portable label other languages see; the Rust type parameter on
10/// [`crate::Input`] is the real enforcement.
11#[derive(Clone, Copy, PartialEq, Eq, Debug)]
12pub enum Type {
13    /// Opaque text with no further structure.
14    String,
15    /// A two-state toggle (`1/0`, `true/false`, `on/off`).
16    Bool,
17    /// Exactly one token from `allowed`.
18    Enum,
19    /// A separated list of tokens from `allowed`.
20    List,
21    /// A non-negative integer.
22    Uint,
23    /// A signed integer.
24    Int,
25    /// A floating-point number.
26    Float,
27    /// A filesystem path.
28    Path,
29}
30
31impl Type {
32    /// The wire spelling used in the JSON contract.
33    pub const fn as_str(self) -> &'static str {
34        match self {
35            Type::String => "string",
36            Type::Bool => "bool",
37            Type::Enum => "enum",
38            Type::List => "list",
39            Type::Uint => "uint",
40            Type::Int => "int",
41            Type::Float => "float",
42            Type::Path => "path",
43        }
44    }
45    /// Every wire spelling, in declaration order — the schema's `enum` list.
46    pub const ALL: &'static [&'static str] = &[
47        "string", "bool", "enum", "list", "uint", "int", "float", "path",
48    ];
49}
50
51impl fmt::Display for Type {
52    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
53        f.write_str(self.as_str())
54    }
55}
56
57/// How much a consumer may rely on a variable.
58///
59/// `Deprecated` must be paired with a [`Deprecation`]; [`crate::Input::check`]
60/// enforces that, so an entry can never be half-deprecated.
61#[derive(Clone, Copy, PartialEq, Eq, Debug)]
62pub enum Stability {
63    /// Not yet classified. The honest default for a freshly harvested name.
64    Unknown,
65    /// Safe to depend on; changes follow the project's compatibility policy.
66    Stable,
67    /// May change or vanish without notice.
68    Experimental,
69    /// Diagnostic knob. Present in shipped builds, but not a supported interface.
70    Debug,
71    /// Scheduled for removal; see [`Deprecation`] for the migration path.
72    Deprecated,
73}
74
75impl Stability {
76    /// The wire spelling used in the JSON contract.
77    pub const fn as_str(self) -> &'static str {
78        match self {
79            Stability::Unknown => "unknown",
80            Stability::Stable => "stable",
81            Stability::Experimental => "experimental",
82            Stability::Debug => "debug",
83            Stability::Deprecated => "deprecated",
84        }
85    }
86    /// Every wire spelling — the schema's `enum` list.
87    pub const ALL: &'static [&'static str] =
88        &["unknown", "stable", "experimental", "debug", "deprecated"];
89}
90
91impl fmt::Display for Stability {
92    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
93        f.write_str(self.as_str())
94    }
95}
96
97/// When a variable was introduced — never a bare string.
98#[derive(Clone, Copy, PartialEq, Eq, Debug)]
99pub enum Since {
100    /// Not yet classified.
101    Unknown,
102    /// Introduced in the version currently being built ([`crate::THIS_VERSION`]).
103    /// Use this for a variable you are adding right now: it can never go stale.
104    This,
105    /// Introduced in an explicit, parsed, comparable version.
106    At(Version),
107}
108
109impl Since {
110    /// Resolve to a concrete version, if known.
111    pub fn resolve(self) -> Option<Version> {
112        match self {
113            Since::Unknown => None,
114            Since::This => Some(crate::THIS_VERSION),
115            Since::At(v) => Some(v),
116        }
117    }
118    pub(crate) fn to_json(self) -> Option<String> {
119        self.resolve().map(|v| v.to_string())
120    }
121}
122
123/// A reference to a key in another configuration surface that this variable
124/// bridges to (for example a `.conf` key the variable overrides).
125///
126/// Format-validated: must be namespaced (`section.key`). The target lives in a
127/// different system, so only the *shape* can be checked here — this is the one
128/// deliberately-weak reference in the model, and it is typed rather than a bare
129/// string so it cannot be confused with prose.
130#[derive(Clone, Copy, PartialEq, Eq, Debug)]
131pub struct ConfigKeyRef(pub &'static str);
132
133impl ConfigKeyRef {
134    /// Validate and wrap a namespaced config key.
135    ///
136    /// # Panics
137    /// At **compile time** if the key contains no `.` separator.
138    pub const fn new(s: &'static str) -> ConfigKeyRef {
139        let b = s.as_bytes();
140        let mut i = 0usize;
141        let mut dot = false;
142        while i < b.len() {
143            if b[i] == b'.' {
144                dot = true;
145            }
146            i += 1;
147        }
148        if !dot {
149            panic!("config key must be namespaced, e.g. \"section.key\"");
150        }
151        ConfigKeyRef(s)
152    }
153}
154
155impl fmt::Display for ConfigKeyRef {
156    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
157        f.write_str(self.0)
158    }
159}
160
161/// Why a variable is going away and what to do instead.
162///
163/// Bundled into one struct so an entry cannot be half-deprecated.
164#[derive(Clone, Copy, Debug)]
165pub struct Deprecation {
166    /// The version in which the variable became deprecated.
167    pub since: Version,
168    /// A **compile-checked** reference to the successor, when there is a clean
169    /// 1:1 replacement. Store a function that reads the successor's `key`
170    /// (`Some(|| Model::NEW_INPUT.key)`): rename or delete the successor and
171    /// this stops compiling, so the pointer can never dangle.
172    pub replaced_by: Option<fn() -> &'static str>,
173    /// Human guidance when there is no clean successor — a config key to use, a
174    /// "simply remove it", a split into two variables. Advisory prose: a machine
175    /// must not try to apply it automatically.
176    pub migration: &'static str,
177}
178
179impl Deprecation {
180    pub(crate) fn to_json(self) -> Value {
181        serde_json::json!({
182            "since": self.since.to_string(),
183            "replaced_by": self.replaced_by.map(|f| f()),
184            "migration": if self.migration.is_empty() { None } else { Some(self.migration) },
185        })
186    }
187}