argenv_resolve/problems.rs
1//! Problem-handling policy: what to do when `lint` finds something.
2//!
3//! Rather than hand-rolling a loop every project, declare your policy once and
4//! pass it to [`handle_problems`] or [`Model::parse_and_lint`]:
5//!
6//! ```no_run
7//! # use argenv_resolve::*;
8//! # let model: Vec<Record> = vec![];
9//! # let resolved = argenv_resolve::parse(&model);
10//! let findings = lint(&model, &resolved);
11//! handle_problems(&findings, OnProblems::FailOnError);
12//! ```
13
14use crate::{Finding, LintPolicy, Severity};
15
16/// What to do when [`crate::lint`] returns findings.
17///
18/// Pass to [`handle_problems`] or, more commonly, let [`crate::contract!`]'s
19/// generated `Model::parse_and_lint` handle both steps at once.
20#[derive(Clone, Copy, Debug, PartialEq, Eq)]
21pub enum OnProblems {
22 /// Print errors and warnings to stderr; exit with status 1 on any error.
23 /// Warnings alone are printed but do not stop the program.
24 ///
25 /// This is the right default for most programs: a misspelled flag or
26 /// variable is an error (the intent is clear but wrong), and use of a
27 /// deprecated input is a warning. What counts as an error is decided by
28 /// the [`LintPolicy`]; the default is strict, and a program that wants to
29 /// be more forgiving passes its own to [`handle_problems_with`].
30 FailOnError,
31
32 /// Print all findings to stderr; exit with status 1 if there is anything
33 /// at all — errors or warnings.
34 ///
35 /// Use this when warnings are unacceptable: a strict tool, a CI step,
36 /// or a program where an unrecognised env var is never a coincidence.
37 FailOnAny,
38
39 /// Print all findings to stderr; never exit because of them.
40 ///
41 /// Use this for programs that want to surface problems without stopping,
42 /// or for a startup phase where the caller handles the exit itself.
43 WarnOnly,
44
45 /// Discard all findings silently.
46 ///
47 /// Use this only when you have already handled findings yourself, or
48 /// when the program genuinely cannot do anything useful with them.
49 Ignore,
50}
51
52/// Apply a problem-handling policy to a set of findings.
53///
54/// Prints findings to stderr and exits the process if the policy requires it.
55/// Returns normally when the policy allows the program to continue.
56///
57/// Severities come from the default, strict, [`LintPolicy`]; see
58/// [`handle_problems_with`] to use another.
59///
60/// ```no_run
61/// # use argenv_resolve::*;
62/// # let model: Vec<Record> = vec![];
63/// # let resolved = argenv_resolve::parse(&model);
64/// handle_problems(&lint(&model, &resolved), OnProblems::FailOnError);
65/// ```
66pub fn handle_problems(findings: &[Finding], policy: OnProblems) {
67 handle_problems_with(findings, policy, &LintPolicy::default());
68}
69
70/// [`handle_problems`], with this program's own idea of how serious each finding is.
71///
72/// ```no_run
73/// # use argenv_resolve::*;
74/// # let model: Vec<Record> = vec![];
75/// # let resolved = argenv_resolve::parse(&model);
76/// // A wrapper that forwards flags it does not declare: typos are only worth a warning.
77/// let forgiving = LintPolicy::default().unknown_flags(Severity::Warning);
78/// handle_problems_with(&lint(&model, &resolved), OnProblems::FailOnError, &forgiving);
79/// ```
80pub fn handle_problems_with(findings: &[Finding], on: OnProblems, policy: &LintPolicy) {
81 if findings.is_empty() || on == OnProblems::Ignore {
82 return;
83 }
84
85 for f in findings {
86 let label = match policy.severity(f) {
87 Severity::Error => "error",
88 Severity::Warning => "warning",
89 };
90 eprintln!("{label}: {f}");
91 }
92
93 let should_exit = match on {
94 OnProblems::FailOnError => findings
95 .iter()
96 .any(|f| policy.severity(f) == Severity::Error),
97 OnProblems::FailOnAny => !findings.is_empty(),
98 OnProblems::WarnOnly | OnProblems::Ignore => false,
99 };
100
101 if should_exit {
102 std::process::exit(1);
103 }
104}