Skip to main content

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}