use crate::{Record, Resolution, Source};
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug)]
pub enum Severity {
Warning,
Error,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct LintPolicy {
unknown_flag: Severity,
unknown_variable: Severity,
out_of_scope_flag: Severity,
deprecated: Severity,
}
impl Default for LintPolicy {
fn default() -> Self {
Self::strict()
}
}
impl LintPolicy {
pub const fn strict() -> Self {
Self {
unknown_flag: Severity::Error,
unknown_variable: Severity::Error,
out_of_scope_flag: Severity::Error,
deprecated: Severity::Warning,
}
}
pub const fn lenient() -> Self {
Self {
unknown_flag: Severity::Warning,
unknown_variable: Severity::Warning,
out_of_scope_flag: Severity::Warning,
deprecated: Severity::Warning,
}
}
#[must_use]
pub const fn unknown_flags(mut self, severity: Severity) -> Self {
self.unknown_flag = severity;
self
}
#[must_use]
pub const fn unknown_variables(mut self, severity: Severity) -> Self {
self.unknown_variable = severity;
self
}
#[must_use]
pub const fn out_of_scope_flags(mut self, severity: Severity) -> Self {
self.out_of_scope_flag = severity;
self
}
#[must_use]
pub const fn deprecated(mut self, severity: Severity) -> Self {
self.deprecated = severity;
self
}
pub fn severity(&self, finding: &Finding) -> Severity {
match finding {
Finding::UnknownArg { .. } => self.unknown_flag,
Finding::UnknownEnv { .. } => self.unknown_variable,
Finding::OutOfScope { .. } => self.out_of_scope_flag,
Finding::Deprecated { .. } => self.deprecated,
Finding::InvalidValue { .. }
| Finding::UnknownToken { .. }
| Finding::MissingRequired { .. }
| Finding::MissingValue { .. }
| Finding::UnexpectedValue { .. } => Severity::Error,
}
}
}
#[derive(Clone, Debug, PartialEq)]
#[non_exhaustive]
pub enum Finding {
UnknownArg {
arg: String,
did_you_mean: Option<String>,
},
OutOfScope {
arg: String,
command: Option<String>,
applies_to: Vec<String>,
},
UnknownEnv {
name: String,
did_you_mean: String,
},
MissingValue {
arg: String,
},
UnexpectedValue {
arg: String,
},
InvalidValue {
key: String,
source: Source,
value: String,
reason: String,
},
UnknownToken {
key: String,
token: String,
allowed: Vec<String>,
},
MissingRequired {
key: String,
via: Vec<String>,
},
Deprecated {
key: String,
guidance: String,
},
}
impl Finding {
pub fn severity(&self) -> Severity {
LintPolicy::default().severity(self)
}
}
impl std::fmt::Display for Finding {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Finding::UnknownArg { arg, did_you_mean } => match did_you_mean {
Some(s) => write!(f, "{arg} is not a declared flag; did you mean {s}?"),
None => write!(f, "{arg} is not a declared flag"),
},
Finding::UnknownEnv { name, did_you_mean } => {
write!(f, "{name} is not declared; did you mean {did_you_mean}?")
}
Finding::OutOfScope {
arg,
command,
applies_to,
} => match command {
Some(command) => write!(
f,
"{arg} does not apply to `{command}` (it applies to: {})",
applies_to.join(", ")
),
None => write!(f, "{arg} only applies to: {}", applies_to.join(", ")),
},
Finding::MissingValue { arg } => write!(f, "{arg} needs a value"),
Finding::UnexpectedValue { arg } => write!(f, "{arg} takes no value"),
Finding::InvalidValue {
key,
source,
value,
reason,
} => write!(
f,
"{key} (from {source}) is `{value}`, which is invalid: {reason}"
),
Finding::UnknownToken {
key,
token,
allowed,
} => write!(
f,
"{key} contains unknown token `{token}`; accepted: {}",
allowed.join(", ")
),
Finding::MissingRequired { key, via } => {
if via.is_empty() {
write!(f, "{key} is required but was not supplied")
} else {
write!(f, "{key} is required; supply it with {}", via.join(" or "))
}
}
Finding::Deprecated { key, guidance } => {
if guidance.is_empty() {
write!(f, "{key} is deprecated")
} else {
write!(f, "{key} is deprecated: {guidance}")
}
}
}
}
}
pub fn lint(model: &[Record], resolution: &Resolution) -> Vec<Finding> {
let mut findings = resolution.findings().to_vec();
findings.extend(check_resolution(model, resolution));
findings.extend(check_environment(model, &resolution.env_names));
findings
}
fn check_resolution(model: &[Record], resolution: &Resolution) -> Vec<Finding> {
let mut findings = Vec::new();
let active = resolution.positionals().first().map(String::as_str);
for r in model {
let Some(value) = resolution.values().get(&r.key) else {
let in_scope = r.subcommands.is_empty()
|| active.is_some_and(|a| r.subcommands.iter().any(|s| s == a));
if r.required && in_scope {
let mut via = r.arg_labels();
via.extend(r.env_names().iter().map(|n| n.to_string()));
findings.push(Finding::MissingRequired {
key: r.key.clone(),
via,
});
}
continue;
};
if value.source == Source::Default {
continue;
}
let is_flag = r.arg.as_ref().is_some_and(|a| a.position.is_none());
let in_scope = r.subcommands.is_empty()
|| active.is_some_and(|a| r.subcommands.iter().any(|s| s == a));
if is_flag && value.source == Source::Arg && !in_scope {
findings.push(Finding::OutOfScope {
arg: r
.arg
.as_ref()
.and_then(|a| {
a.long
.as_ref()
.map(|l| format!("--{l}"))
.or_else(|| a.short.as_ref().map(|c| format!("-{c}")))
})
.unwrap_or_else(|| r.key.clone()),
command: active.map(str::to_string),
applies_to: r.subcommands.clone(),
});
continue;
}
if let Err(reason) = r.accepts(&value.raw) {
findings.push(Finding::InvalidValue {
key: r.key.clone(),
source: value.source,
value: value.raw.clone(),
reason,
});
}
if !r.allowed.is_empty() {
for token in r.tokens(&value.raw) {
if !r.allowed.iter().any(|a| a == token) {
findings.push(Finding::UnknownToken {
key: r.key.clone(),
token: token.to_string(),
allowed: r.allowed.clone(),
});
}
}
}
if let Some(dep) = &r.deprecation {
let guidance = dep
.get("replaced_by")
.and_then(|v| v.as_str())
.map(|s| format!("use {s} instead"))
.or_else(|| {
dep.get("migration")
.and_then(|v| v.as_str())
.map(str::to_string)
})
.unwrap_or_default();
findings.push(Finding::Deprecated {
key: r.key.clone(),
guidance,
});
}
}
findings
}
fn check_environment(model: &[Record], env_names: &[String]) -> Vec<Finding> {
let declared: Vec<String> = model
.iter()
.flat_map(|r| r.env_names().into_iter().map(str::to_string))
.collect();
let prefixes: std::collections::BTreeSet<&str> = declared
.iter()
.filter_map(|n| n.split_once('_').map(|(p, _)| p))
.collect();
let mut findings = Vec::new();
for name in env_names.iter().cloned() {
if declared.contains(&name) {
continue;
}
let shares_prefix = name
.split_once('_')
.map(|(p, _)| prefixes.contains(p))
.unwrap_or(false);
if !shares_prefix {
continue;
}
let known: Vec<&str> = declared.iter().map(String::as_str).collect();
if let Some(best) = nearest(&name, &known) {
findings.push(Finding::UnknownEnv {
name,
did_you_mean: best,
});
}
}
findings
}
pub(crate) fn nearest<S: AsRef<str>>(name: &str, known: &[S]) -> Option<String> {
let budget = (name.len() / 8).clamp(1, 3);
known
.iter()
.map(|d| (edit_distance(name, d.as_ref()), d.as_ref()))
.filter(|(dist, _)| *dist <= budget)
.min_by_key(|(dist, _)| *dist)
.map(|(_, d)| d.to_string())
}
fn edit_distance(a: &str, b: &str) -> usize {
let (a, b): (Vec<char>, Vec<char>) = (a.chars().collect(), b.chars().collect());
if a.is_empty() {
return b.len();
}
let mut prev: Vec<usize> = (0..=b.len()).collect();
let mut cur = vec![0usize; b.len() + 1];
for (i, ca) in a.iter().enumerate() {
cur[0] = i + 1;
for (j, cb) in b.iter().enumerate() {
let cost = usize::from(ca != cb);
cur[j + 1] = (prev[j + 1] + 1).min(cur[j] + 1).min(prev[j] + cost);
}
std::mem::swap(&mut prev, &mut cur);
}
prev[b.len()]
}