argenv-resolve 0.3.2

Resolve an argenv contract against a real invocation - argv and envp, with precedence, defaults, and linting. Depends on argenv for the declared data; argenv depends on nothing here.
Documentation
//! Problem-handling policy: what to do when `lint` finds something.
//!
//! Rather than hand-rolling a loop every project, declare your policy once and
//! pass it to [`handle_problems`] or [`Model::parse_and_lint`]:
//!
//! ```no_run
//! # use argenv_resolve::*;
//! # let model: Vec<Record> = vec![];
//! # let resolved = argenv_resolve::parse(&model);
//! let findings = lint(&model, &resolved);
//! handle_problems(&findings, OnProblems::FailOnError);
//! ```

use crate::{Finding, LintPolicy, Severity};

/// What to do when [`crate::lint`] returns findings.
///
/// Pass to [`handle_problems`] or, more commonly, let [`crate::contract!`]'s
/// generated `Model::parse_and_lint` handle both steps at once.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum OnProblems {
    /// Print errors and warnings to stderr; exit with status 1 on any error.
    /// Warnings alone are printed but do not stop the program.
    ///
    /// This is the right default for most programs: a misspelled flag or
    /// variable is an error (the intent is clear but wrong), and use of a
    /// deprecated input is a warning. What counts as an error is decided by
    /// the [`LintPolicy`]; the default is strict, and a program that wants to
    /// be more forgiving passes its own to [`handle_problems_with`].
    FailOnError,

    /// Print all findings to stderr; exit with status 1 if there is anything
    /// at all — errors or warnings.
    ///
    /// Use this when warnings are unacceptable: a strict tool, a CI step,
    /// or a program where an unrecognised env var is never a coincidence.
    FailOnAny,

    /// Print all findings to stderr; never exit because of them.
    ///
    /// Use this for programs that want to surface problems without stopping,
    /// or for a startup phase where the caller handles the exit itself.
    WarnOnly,

    /// Discard all findings silently.
    ///
    /// Use this only when you have already handled findings yourself, or
    /// when the program genuinely cannot do anything useful with them.
    Ignore,
}

/// Apply a problem-handling policy to a set of findings.
///
/// Prints findings to stderr and exits the process if the policy requires it.
/// Returns normally when the policy allows the program to continue.
///
/// Severities come from the default, strict, [`LintPolicy`]; see
/// [`handle_problems_with`] to use another.
///
/// ```no_run
/// # use argenv_resolve::*;
/// # let model: Vec<Record> = vec![];
/// # let resolved = argenv_resolve::parse(&model);
/// handle_problems(&lint(&model, &resolved), OnProblems::FailOnError);
/// ```
pub fn handle_problems(findings: &[Finding], policy: OnProblems) {
    handle_problems_with(findings, policy, &LintPolicy::default());
}

/// [`handle_problems`], with this program's own idea of how serious each finding is.
///
/// ```no_run
/// # use argenv_resolve::*;
/// # let model: Vec<Record> = vec![];
/// # let resolved = argenv_resolve::parse(&model);
/// // A wrapper that forwards flags it does not declare: typos are only worth a warning.
/// let forgiving = LintPolicy::default().unknown_flags(Severity::Warning);
/// handle_problems_with(&lint(&model, &resolved), OnProblems::FailOnError, &forgiving);
/// ```
pub fn handle_problems_with(findings: &[Finding], on: OnProblems, policy: &LintPolicy) {
    if findings.is_empty() || on == OnProblems::Ignore {
        return;
    }

    for f in findings {
        let label = match policy.severity(f) {
            Severity::Error => "error",
            Severity::Warning => "warning",
        };
        eprintln!("{label}: {f}");
    }

    let should_exit = match on {
        OnProblems::FailOnError => findings
            .iter()
            .any(|f| policy.severity(f) == Severity::Error),
        OnProblems::FailOnAny => !findings.is_empty(),
        OnProblems::WarnOnly | OnProblems::Ignore => false,
    };

    if should_exit {
        std::process::exit(1);
    }
}