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}