astrs-cli 0.1.0

The astrs command line: run, build, monitor, migrate and bridge robotic dataflows.
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
//! [`CliDiagnostic`]: the one flat, orderable diagnostic shape
//! `astrs validate` renders, unifying four different upstream types
//! (an I/O failure, [`astrs_manifest::ManifestError`],
//! [`astrs_manifest::ValidationError`], [`astrs_manifest::expand::ExpandError`]
//! and [`astrs_graph::Diagnostic`]) that otherwise share no common trait
//! beyond `Display` โ€” blueprint ยง17's "human diagnostics (path, severity,
//! colored)" and `--json` need one list to print, not five differently
//! shaped error types each rendered by hand.
//!
//! Every failure mode `astrs validate` can encounter โ€” the file not
//! existing, the YAML not parsing, a structural violation, a module that
//! fails to expand, a type mismatch, an unconsumed output โ€” becomes one
//! [`CliDiagnostic`] rather than aborting the command outright. This is
//! deliberate: a diagnostic tool's job is to tell the user everything
//! that's wrong in one pass, not to stop at the first problem (the same
//! reasoning [`astrs_manifest::ValidationErrors`] itself documents).

use std::fmt;

pub use astrs_graph::Severity;

/// Which stage of the `validate` pipeline produced a [`CliDiagnostic`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
#[serde(rename_all = "snake_case")]
pub enum Source {
    /// The manifest file could not be read from disk.
    Io,
    /// The manifest did not parse as YAML.
    Parse,
    /// [`astrs_manifest::Manifest::validate`] reported a structural
    /// violation.
    Structural,
    /// [`astrs_manifest::expand::expand`] failed.
    Expand,
    /// [`astrs_graph::DataflowGraph::diagnostics`] (or its construction
    /// pass) reported an observation.
    Graph,
    /// `--prove` was requested but formal verification is not enabled in
    /// this build.
    Prove,
}

impl fmt::Display for Source {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(match self {
            Self::Io => "io",
            Self::Parse => "parse",
            Self::Structural => "structural",
            Self::Expand => "expand",
            Self::Graph => "graph",
            Self::Prove => "prove",
        })
    }
}

/// One unified validation observation.
#[derive(Debug, Clone, serde::Serialize)]
pub struct CliDiagnostic {
    /// How serious this observation is.
    pub severity: Severity,
    /// Which stage produced it.
    pub source: Source,
    /// A document path (`nodes[3].inputs.frames`) when the underlying
    /// observation is anchored to one, e.g. every
    /// [`Source::Structural`] entry. `None` for whole-file observations
    /// ([`Source::Io`], [`Source::Parse`] without a known location,
    /// [`Source::Prove`]) and for [`Source::Graph`] entries (that crate's
    /// [`astrs_graph::Diagnostic`] identifies nodes/edges structurally
    /// rather than via a document path; see its own `Display`, folded
    /// into [`Self::message`] instead).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub path: Option<String>,
    /// A human-readable rendering of the observation.
    pub message: String,
}

impl CliDiagnostic {
    /// The manifest file could not be read.
    #[must_use]
    pub fn io(message: impl Into<String>) -> Self {
        Self {
            severity: Severity::Error,
            source: Source::Io,
            path: None,
            message: message.into(),
        }
    }

    /// The manifest did not parse as YAML.
    #[must_use]
    pub fn parse(err: &astrs_manifest::ManifestError) -> Self {
        let path = match (err.line(), err.column()) {
            (Some(line), Some(column)) => Some(format!("line {line}, column {column}")),
            _ => None,
        };
        Self {
            severity: Severity::Error,
            source: Source::Parse,
            path,
            message: err.to_string(),
        }
    }

    /// One structural violation from [`astrs_manifest::Manifest::validate`].
    #[must_use]
    pub fn structural(err: &astrs_manifest::ValidationError) -> Self {
        Self {
            severity: Severity::Error,
            source: Source::Structural,
            path: Some(err.path.clone()),
            message: err.kind.to_string(),
        }
    }

    /// Module expansion failed.
    #[must_use]
    pub fn expand(err: &astrs_manifest::expand::ExpandError) -> Self {
        Self {
            severity: Severity::Error,
            source: Source::Expand,
            path: None,
            message: err.to_string(),
        }
    }

    /// [`astrs_graph::DataflowGraph::from_manifest`] rejected the
    /// manifest outright.
    ///
    /// Reachable in practice only when the manifest skipped
    /// [`astrs_manifest::Manifest::validate`] โ€” see that function's own
    /// docs โ€” which `validate`'s pipeline never does; kept as a
    /// diagnostic rather than an assumed-unreachable panic so a future
    /// regression in that pipeline degrades to a reported error instead
    /// of a crash.
    #[must_use]
    pub fn graph_build_error(err: &astrs_graph::GraphBuildError) -> Self {
        Self {
            severity: Severity::Error,
            source: Source::Graph,
            path: None,
            message: err.to_string(),
        }
    }

    /// One observation from [`astrs_graph::DataflowGraph::diagnostics`] (or
    /// its construction pass).
    #[must_use]
    pub fn graph(diag: &astrs_graph::Diagnostic) -> Self {
        Self {
            severity: diag.severity,
            source: Source::Graph,
            path: None,
            message: diag.to_string(),
        }
    }

    /// `--prove` was requested on a build without the `verify` feature.
    ///
    /// A warning rather than an error: the obligations were still encoded
    /// and printed, and the command reports the missing solver through
    /// [`crate::error::CliError::ProofUnavailable`]'s exit code rather
    /// than by inflating the diagnostic scale.
    #[must_use]
    pub fn prove_unavailable() -> Self {
        Self {
            severity: Severity::Warning,
            source: Source::Prove,
            path: None,
            message: "--prove encoded every obligation but this build has no solver; \
                      rebuild with `--features verify` to discharge them"
                .to_string(),
        }
    }

    /// One refuted obligation.
    #[must_use]
    pub fn prove_violation(heading: &str, headline: &str) -> Self {
        Self {
            severity: Severity::Error,
            source: Source::Prove,
            path: None,
            message: format!("{heading}: {headline}"),
        }
    }

    /// Some obligation left a hole in the proof, so the run rules out what
    /// it lists and no more.
    ///
    /// `missing_declaration` counts only *gaps* โ€” obligations that needed a
    /// fact nobody supplied. An obligation with nothing to prove (no
    /// declared budget, no typed edge) is vacuously satisfied and is
    /// deliberately not counted here, even though the proof report lists it
    /// under "not attempted".
    #[must_use]
    pub fn prove_incomplete(missing_declaration: usize, inconclusive: usize) -> Self {
        Self {
            severity: Severity::Warning,
            source: Source::Prove,
            path: None,
            message: format!(
                "{missing_declaration} obligation(s) lack a declaration to decide them and \
                 {inconclusive} were left undecided; this proof rules out what it lists, and no more"
            ),
        }
    }

    /// The proof run could not be set up at all.
    #[must_use]
    pub fn prove_error(message: impl Into<String>) -> Self {
        Self {
            severity: Severity::Error,
            source: Source::Prove,
            path: None,
            message: message.into(),
        }
    }
}

/// The worst [`Severity`] across `diagnostics`, or `None` for an empty
/// list.
#[must_use]
pub fn max_severity(diagnostics: &[CliDiagnostic]) -> Option<Severity> {
    diagnostics.iter().map(|d| d.severity).max()
}

/// `astrs validate`'s exit code convention (blueprint ยง17): `0` clean,
/// `1` warnings only, `2` any error (including a file that never parsed).
#[must_use]
pub fn exit_code_for(diagnostics: &[CliDiagnostic]) -> i32 {
    match max_severity(diagnostics) {
        None | Some(Severity::Info) => 0,
        Some(Severity::Warning) => 1,
        Some(Severity::Error) => 2,
    }
}

const RED: &str = "\x1b[31m";
const YELLOW: &str = "\x1b[33m";
const CYAN: &str = "\x1b[36m";
const BOLD: &str = "\x1b[1m";
const RESET: &str = "\x1b[0m";

fn severity_color(severity: Severity) -> &'static str {
    match severity {
        Severity::Error => RED,
        Severity::Warning => YELLOW,
        Severity::Info => CYAN,
    }
}

/// Render one diagnostic as a single human-readable line: `[severity]
/// (source) path: message`, with the severity tag and source both
/// wrapped in plain ANSI SGR codes when `use_color` is set (no `path`
/// segment when the diagnostic has none).
#[must_use]
pub fn render_line(diagnostic: &CliDiagnostic, use_color: bool) -> String {
    let severity_str = diagnostic.severity.to_string();
    let tag = if use_color {
        format!(
            "{BOLD}{}[{severity_str}]{RESET}",
            severity_color(diagnostic.severity)
        )
    } else {
        format!("[{severity_str}]")
    };
    let mut line = format!("{tag} ({}) ", diagnostic.source);
    if let Some(path) = &diagnostic.path {
        line.push_str(path);
        line.push_str(": ");
    }
    line.push_str(&diagnostic.message);
    line
}

/// Render every diagnostic, one per line, in list order.
#[must_use]
pub fn render_human(diagnostics: &[CliDiagnostic], use_color: bool) -> String {
    diagnostics
        .iter()
        .map(|d| render_line(d, use_color))
        .collect::<Vec<_>>()
        .join("\n")
}

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
    use super::*;

    #[test]
    fn max_severity_is_none_for_an_empty_list() {
        assert_eq!(max_severity(&[]), None);
        assert_eq!(exit_code_for(&[]), 0);
    }

    #[test]
    fn exit_code_reflects_the_worst_severity() {
        let info = vec![CliDiagnostic {
            severity: Severity::Info,
            source: Source::Graph,
            path: None,
            message: "m".to_string(),
        }];
        assert_eq!(exit_code_for(&info), 0);

        let warning = vec![CliDiagnostic {
            severity: Severity::Warning,
            source: Source::Graph,
            path: None,
            message: "m".to_string(),
        }];
        assert_eq!(exit_code_for(&warning), 1);

        let error = vec![CliDiagnostic {
            severity: Severity::Error,
            source: Source::Io,
            path: None,
            message: "m".to_string(),
        }];
        assert_eq!(exit_code_for(&error), 2);
    }

    #[test]
    fn exit_code_takes_the_worst_across_a_mixed_list() {
        let mixed = vec![
            CliDiagnostic {
                severity: Severity::Info,
                source: Source::Graph,
                path: None,
                message: "info".to_string(),
            },
            CliDiagnostic {
                severity: Severity::Warning,
                source: Source::Graph,
                path: None,
                message: "warning".to_string(),
            },
        ];
        assert_eq!(exit_code_for(&mixed), 1);
    }

    #[test]
    fn render_line_without_color_has_no_escape_codes() {
        let d = CliDiagnostic::io("cannot read file");
        let line = render_line(&d, false);
        assert!(!line.contains('\x1b'));
        assert!(line.contains("[error]"));
        assert!(line.contains("(io)"));
        assert!(line.contains("cannot read file"));
    }

    #[test]
    fn render_line_with_color_wraps_the_severity_tag() {
        let d = CliDiagnostic::io("cannot read file");
        let line = render_line(&d, true);
        assert!(line.contains('\x1b'));
        assert!(line.contains(RESET));
    }

    #[test]
    fn render_line_includes_path_when_present() {
        let d = CliDiagnostic {
            severity: Severity::Error,
            source: Source::Structural,
            path: Some("nodes[2].id".to_string()),
            message: "bad".to_string(),
        };
        let line = render_line(&d, false);
        assert!(line.contains("nodes[2].id: bad"));
    }

    #[test]
    fn structural_diagnostic_carries_the_validation_error_path() {
        let err = astrs_manifest::ValidationError {
            path: "nodes[0].id".to_string(),
            kind: astrs_manifest::ValidationErrorKind::InvalidIdCharset {
                id: "bad id".to_string(),
            },
        };
        let d = CliDiagnostic::structural(&err);
        assert_eq!(d.path.as_deref(), Some("nodes[0].id"));
        assert_eq!(d.severity, Severity::Error);
    }

    #[test]
    fn parse_diagnostic_captures_line_and_column_when_available() {
        let err = astrs_manifest::Manifest::from_yaml_str("nodes: [").unwrap_err();
        let d = CliDiagnostic::parse(&err);
        assert!(d.path.is_some(), "path was: {:?}", d.path);
    }

    #[test]
    fn graph_diagnostic_preserves_its_severity() {
        let diag = astrs_graph::Diagnostic::new(
            Severity::Warning,
            astrs_graph::DiagnosticKind::UnconsumedOutput {
                node: astrs_graph::NodeId::new("camera"),
                output: astrs_graph::PortName::new("frames"),
            },
        );
        let d = CliDiagnostic::graph(&diag);
        assert_eq!(d.severity, Severity::Warning);
        assert!(d.message.contains("camera"));
    }

    #[test]
    fn prove_unavailable_points_at_the_rebuild() {
        let d = CliDiagnostic::prove_unavailable();
        assert_eq!(d.severity, Severity::Warning);
        assert_eq!(d.source, Source::Prove);
        assert!(d.message.contains("--features verify"), "{}", d.message);
    }

    #[test]
    fn prove_violation_is_an_error_naming_both_halves() {
        let d = CliDiagnostic::prove_violation("deadlock freedom", "`a` can never fire");
        assert_eq!(d.severity, Severity::Error);
        assert_eq!(d.source, Source::Prove);
        assert!(d.message.contains("deadlock freedom"));
        assert!(d.message.contains("can never fire"));
    }

    #[test]
    fn prove_incomplete_is_a_warning_counting_both_gaps() {
        let d = CliDiagnostic::prove_incomplete(2, 1);
        assert_eq!(d.severity, Severity::Warning);
        assert!(d.message.contains('2') && d.message.contains('1'));
    }

    #[test]
    fn prove_error_is_an_error() {
        let d = CliDiagnostic::prove_error("profile is inconsistent");
        assert_eq!(d.severity, Severity::Error);
        assert_eq!(d.source, Source::Prove);
    }

    #[test]
    fn json_serialization_omits_absent_path() {
        let d = CliDiagnostic::io("nope");
        let json = serde_json::to_string(&d).unwrap();
        assert!(!json.contains("\"path\""));
        assert!(json.contains("\"severity\":\"error\""));
    }

    #[test]
    fn json_serialization_includes_present_path() {
        let d = CliDiagnostic {
            severity: Severity::Error,
            source: Source::Structural,
            path: Some("nodes[0]".to_string()),
            message: "m".to_string(),
        };
        let json = serde_json::to_string(&d).unwrap();
        assert!(json.contains("\"path\":\"nodes[0]\""));
    }
}