argenv 0.3.1

A declared, typed contract for a program's invocation surface — argv and envp. The declaration is the accessor, so schema and code cannot drift.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
//! [`Input`] — the declaration. One input a program accepts, however it arrives.
use crate::{
    Arg, ArgBinding, ConfigKeyRef, Deprecation, Env, EnvBinding, Record, ReviewDate, Since,
    Stability, Type, THIS_VERSION,
};
use serde::Serialize;

/// The default for [`Input`]'s second type parameter — an input with no
/// `subcommands` scoping never needs to name a real subcommand enum. Zero
/// variants: nothing can ever construct one, which is the type-level way of
/// saying "this input is not scoped to anything."
#[derive(Clone, Copy, Debug, Serialize)]
pub enum NoCommand {}

/// One input a program accepts — its identity, its domain, and the doors it can
/// arrive through.
///
/// A declaration is simultaneously the **contract entry**, the **typed
/// accessor**, and a **compile-checked symbol**. Because there is only one
/// artifact, the published contract cannot drift from the code that reads the
/// value.
///
/// `key` is the identity and is transport-free; `env` and `arg` are bindings.
/// `--log-level` and `APP_LOG_LEVEL` are not two settings, they are one setting
/// with two doors, which is why they share a type, a domain, and a default.
///
/// ```
/// use argenv::*;
/// pub const LOG_LEVEL: Input<LogLevel> = Input {
///     key:     "log_level",
///     ty:      Type::Enum,
///     default: Some(LogLevel::Info),
///     allowed: LogLevel::TOKENS,
///     env:     Some(Env::new("APP_LOG_LEVEL")),
///     arg:     Some(Arg { value_name: "LEVEL", ..Arg::pair("log-level", 'l') }),
///     summary: "Log verbosity",
///     ..Input::EMPTY
/// };
/// assert!(LOG_LEVEL.check().is_empty());
/// assert_eq!(LOG_LEVEL.to_record().usage(), "-l, --log-level <LEVEL>");
/// ```
#[derive(Debug)]
pub struct Input<T: 'static, C: 'static = NoCommand> {
    /// **Required.** Transport-free identity, `snake_case`.
    ///
    /// This is what the contract, the resolver, and every generated binding join
    /// on. It is deliberately not a variable name or a flag: an input keeps its
    /// identity when a binding is renamed or a second one is added.
    pub key: &'static str,

    /// **Required.** The kind of value, which also fixes how many values the
    /// argument form takes: none for [`Type::Bool`], one for everything else.
    pub ty: Type,

    /// The value used when the input is absent — the real typed `T`, so an
    /// impossible default cannot be written down.
    pub default: Option<T>,

    /// Accepted tokens for [`Type::Enum`] and [`Type::List`].
    ///
    /// Point this at the domain type's own `TOKENS` const so the contract and
    /// the parser cannot disagree.
    pub allowed: &'static [&'static str],

    /// Characters that separate items in a [`Type::List`] value.
    pub separators: &'static [char],

    /// Whether the program requires this input.
    pub required: bool,

    /// How much a consumer may rely on this input.
    pub stability: Stability,

    /// The version in which this input was introduced.
    pub since: Since,

    /// Present if and only if `stability == Stability::Deprecated`.
    pub deprecation: Option<Deprecation>,

    /// A free-form grouping tag for documentation and help output.
    pub group: &'static str,

    /// A key in another configuration surface this input bridges to.
    pub maps_to: Option<ConfigKeyRef>,

    /// A copy-pasteable example, e.g. `"--log-level warn"`.
    pub example: &'static str,

    /// A field in the program's resolved-configuration output that this input
    /// visibly changes — the hook for confirming a declaration empirically.
    pub observe: Option<&'static str>,

    /// The date a **human** last verified this entry, `YYYY-MM-DD`.
    ///
    /// Hand-written on purpose: it asserts a person's judgement, which no tool
    /// can derive. `None` means nobody has vouched for the entry yet.
    pub reviewed: Option<ReviewDate>,

    /// What the input does, in prose.
    pub summary: &'static str,

    /// How the value may arrive from the environment.
    pub env: Option<Env>,

    /// How the value may arrive from the argument vector.
    pub arg: Option<Arg>,

    /// Restricts this input to one or more subcommands. Empty (the default)
    /// means always active, regardless of which subcommand — or none — was
    /// given.
    ///
    /// `C` is the program's own subcommand enum (the same type as the
    /// dispatch input's `T` — see the crate-level docs on subcommands), so
    /// `subcommands: &[Command::Add, Command::Import]` is checked by the
    /// compiler: a typo'd or removed variant fails to build, rather than
    /// silently doing nothing at runtime. One option genuinely shared by
    /// several subcommands (an `--input-dir` used by both `build` and `run`)
    /// is declared once, with both listed here, instead of duplicated per
    /// subcommand or wrongly made global.
    pub subcommands: &'static [C],
}

impl<T: 'static, C: 'static> Input<T, C> {
    /// The empty baseline: `Input { key: "...", ty: ..., ..Input::EMPTY }`.
    pub const EMPTY: Input<T, C> = Input {
        key: "",
        ty: Type::String,
        default: None,
        allowed: &[],
        separators: &[],
        required: false,
        stability: Stability::Unknown,
        since: Since::Unknown,
        deprecation: None,
        group: "",
        maps_to: None,
        example: "",
        observe: None,
        reviewed: None,
        summary: "",
        env: None,
        arg: None,
        subcommands: &[],
    };

    /// How many values the argument form consumes: `0` for a boolean flag whose
    /// presence is the value, `1` otherwise. Derived, never declared.
    pub const fn arity(&self) -> u8 {
        match self.ty {
            Type::Bool => 0,
            _ => 1,
        }
    }

    /// Validate this declaration against the contract's rules.
    ///
    /// Returns human-readable problems; empty means valid. Run it in a test so a
    /// bad declaration fails the build rather than a user's launch.
    pub fn check(&self) -> Vec<String> {
        let mut e = Vec::new();
        let at = if self.key.is_empty() {
            "<unnamed>"
        } else {
            self.key
        };

        if self.key.is_empty() {
            e.push("an input has an empty key".to_string());
        } else if let Err(why) = valid_key(self.key) {
            e.push(format!("{at}: key {why}"));
        }

        // An input with no binding cannot be supplied by anyone.
        if self.env.is_none() && self.arg.is_none() {
            e.push(format!(
                "{at}: declares neither an env nor an arg binding, so nothing can ever set it"
            ));
        }

        if let Some(env) = self.env {
            if let Err(why) = valid_env_name(env.name) {
                e.push(format!("{at}: env name `{}` {why}", env.name));
            }
            for a in env.aliases {
                if let Err(why) = valid_env_name(a) {
                    e.push(format!("{at}: env alias `{a}` {why}"));
                }
                if *a == env.name {
                    e.push(format!("{at}: env alias repeats the primary name"));
                }
            }
        }

        if let Some(arg) = self.arg {
            let named = arg.long.is_some() || arg.short.is_some();
            let positional = arg.position.is_some();
            if !named && !positional {
                e.push(format!(
                    "{at}: arg binding has neither a long/short form nor a position — it must be one or the other"
                ));
            }
            if named && positional {
                e.push(format!(
                    "{at}: arg binding has both a long/short form and a position — a flag is one or the other, never both"
                ));
            }
            if positional && self.ty == Type::Bool {
                e.push(format!(
                    "{at}: a positional cannot be Type::Bool — a positional's presence already                      means a value was given, so there is no separate on/off state for a bool to                      express; use a named flag for a switch instead"
                ));
            }
            if positional && arg.negatable {
                e.push(format!(
                    "{at}: `negatable` produces --no-… which only makes sense for a named flag"
                ));
            }
            if positional && arg.repeatable {
                e.push(format!("{at}: `repeatable` accumulates repeated occurrences of a named flag; a positional occurs at most once by construction"));
            }
            if let Some(l) = arg.long {
                if let Err(why) = valid_long(l) {
                    e.push(format!("{at}: long `--{l}` {why}"));
                }
            }
            if let Some(s) = arg.short {
                if !s.is_ascii_alphanumeric() {
                    e.push(format!(
                        "{at}: short `-{s}` must be an ASCII letter or digit"
                    ));
                }
            }
            if arg.negatable && self.ty != Type::Bool {
                e.push(format!(
                    "{at}: `negatable` produces --no-… and is meaningful only for bool, but type is {}",
                    self.ty
                ));
            }
            if arg.negatable && arg.long.is_none() {
                e.push(format!("{at}: `negatable` needs a long form to negate"));
            }
            if arg.repeatable && self.ty != Type::List {
                e.push(format!(
                    "{at}: `repeatable` accumulates values and is meaningful only for list, but type is {}",
                    self.ty
                ));
            }
            if self.ty == Type::Bool && !arg.value_name.is_empty() {
                e.push(format!(
                    "{at}: a bool flag takes no value, so `value_name` is meaningless"
                ));
            }
        }

        if let Some(v) = self.since.resolve() {
            if v > THIS_VERSION {
                e.push(format!(
                    "{at}: `since` {v} is newer than the current version {THIS_VERSION}"
                ));
            }
        }
        if let Some(r) = self.reviewed {
            // One day of slack: an author east of UTC writes their local date,
            // which is legitimately "tomorrow" by the build machine's clock.
            if r > ReviewDate::today().next_day() {
                e.push(format!("{at}: `reviewed` date {r} is in the future"));
            }
        }
        match (self.stability, self.deprecation.is_some()) {
            (Stability::Deprecated, false) => e.push(format!(
                "{at}: stability is Deprecated but no Deprecation details are given"
            )),
            (s, true) if s != Stability::Deprecated => e.push(format!(
                "{at}: has Deprecation details but stability is {s}"
            )),
            _ => {}
        }
        if let Some(d) = &self.deprecation {
            if d.since > THIS_VERSION {
                e.push(format!(
                    "{at}: deprecated-since {} is newer than the current version {THIS_VERSION}",
                    d.since
                ));
            }
        }

        let listy = matches!(self.ty, Type::Enum | Type::List);
        if listy && self.allowed.is_empty() {
            e.push(format!("{at}: type is {} but `allowed` is empty", self.ty));
        }
        if !self.allowed.is_empty() && !listy {
            e.push(format!(
                "{at}: `allowed` is only meaningful for enum/list, but type is {}",
                self.ty
            ));
        }
        if self.ty == Type::List && self.separators.is_empty() {
            e.push(format!(
                "{at}: type is list but no `separators` are declared, so a value cannot be split"
            ));
        }
        if !self.separators.is_empty() && self.ty != Type::List {
            e.push(format!(
                "{at}: `separators` are only meaningful for list, but type is {}",
                self.ty
            ));
        }
        e
    }
}

impl<T: 'static + Serialize, C: 'static + Serialize> Input<T, C> {
    /// Project this declaration down to the portable [`Record`] the contract
    /// describes.
    pub fn to_record(&self) -> Record {
        Record {
            key: self.key.to_string(),
            ty: self.ty.as_str().to_string(),
            default: self
                .default
                .as_ref()
                .map(|d| serde_json::to_value(d).unwrap_or(serde_json::Value::Null)),
            allowed: self.allowed.iter().map(|s| s.to_string()).collect(),
            separators: self.separators.iter().map(|c| c.to_string()).collect(),
            required: self.required,
            stability: self.stability.as_str().to_string(),
            since: self.since.to_json(),
            deprecation: self.deprecation.as_ref().map(|d| d.to_json()),
            group: non_empty(self.group),
            maps_to: self.maps_to.map(|c| c.0.to_string()),
            example: non_empty(self.example),
            observe: self.observe.map(|s| s.to_string()),
            reviewed: self.reviewed.map(|d| d.to_string()),
            summary: non_empty(self.summary),
            modified: None,
            source: None,
            env: self.env.map(|e| EnvBinding {
                name: e.name.to_string(),
                aliases: e.aliases.iter().map(|s| s.to_string()).collect(),
            }),
            arg: self.arg.map(|a| ArgBinding {
                long: a.long.map(str::to_string),
                short: a.short.map(|c| c.to_string()),
                // Derived here so no other language has to re-derive it.
                arity: self.arity(),
                value_name: non_empty(a.value_name),
                negatable: a.negatable,
                repeatable: a.repeatable,
                position: a.position,
            }),
            subcommands: self
                .subcommands
                .iter()
                .map(|c| {
                    // The same conversion `default` already goes through, so
                    // a token is derived here rather than requiring a second,
                    // separately-maintained "to string" mechanism.
                    match serde_json::to_value(c).ok() {
                        Some(serde_json::Value::String(s)) => s,
                        other => panic!(
                            "subcommand value did not serialise to a plain string: {other:?} \
                             — a subcommand enum should derive Serialize with rename_all = \
                             snake_case, the same convention LogLevel and Tristate use"
                        ),
                    }
                })
                .collect(),
        }
    }
}

/// An input's identity is `snake_case`: transport-free, so it reads the same in
/// every language a binding is generated for.
fn valid_key(key: &str) -> Result<(), String> {
    let mut chars = key.chars();
    match chars.next() {
        None => return Err("is empty".into()),
        Some(c) if c.is_ascii_lowercase() => {}
        Some(c) => {
            return Err(format!(
                "starts with `{c}`; must start with a lowercase letter"
            ))
        }
    }
    for c in chars {
        if !(c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_') {
            return Err(format!(
                "contains `{c}`; keys are snake_case (lowercase, digits, underscore)"
            ));
        }
    }
    Ok(())
}

/// Environment names are portable only within `[A-Za-z_][A-Za-z0-9_]*`. A name
/// with a space, a dash, or a leading digit cannot be set from a POSIX shell.
fn valid_env_name(name: &str) -> Result<(), String> {
    let mut chars = name.chars();
    match chars.next() {
        None => return Err("is empty".into()),
        Some(c) if c.is_ascii_alphabetic() || c == '_' => {}
        Some(c) => {
            return Err(format!(
                "starts with `{c}`; must start with a letter or underscore"
            ))
        }
    }
    for c in chars {
        if !(c.is_ascii_alphanumeric() || c == '_') {
            return Err(format!(
                "contains `{c}`; only letters, digits and underscore are portable"
            ));
        }
    }
    Ok(())
}

/// Long flags are kebab-case and are stored without their leading dashes, so a
/// declaration cannot disagree with itself about how many dashes to write.
fn valid_long(long: &str) -> Result<(), String> {
    if long.starts_with('-') {
        return Err("must be written without leading dashes".into());
    }
    let mut chars = long.chars();
    match chars.next() {
        None => return Err("is empty".into()),
        Some(c) if c.is_ascii_lowercase() => {}
        Some(c) => {
            return Err(format!(
                "starts with `{c}`; must start with a lowercase letter"
            ))
        }
    }
    // No blanket rejection of names starting with `no-` here: many real
    // flags are standalone (git's --no-pager, --no-edit; docker's --no-cache),
    // not auto-generated negations of anything. The real risk - an explicit
    // `no-X` colliding with the `--no-X` a *different*, negatable `X` input
    // would generate - needs the whole model to detect (arg_labels() already
    // includes the derived form for a negatable input), so check_unique
    // already catches an actual collision; a single input's own check()
    // cannot see other inputs to judge that here, and should not guess.
    for c in chars {
        if !(c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-') {
            return Err(format!(
                "contains `{c}`; long flags are kebab-case (lowercase, digits, dashes)"
            ));
        }
    }
    Ok(())
}

fn non_empty(s: &str) -> Option<String> {
    if s.is_empty() {
        None
    } else {
        Some(s.to_string())
    }
}