use serde::{Deserialize, Serialize};
use crate::errors::Error;
use crate::extract::query::{run_query, Capture};
use crate::types::Tier;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum MatchType {
MustMatch,
MustNotMatch,
MustExist,
}
impl MatchType {
fn default_explanation(self, pattern: &str) -> String {
match self {
MatchType::MustMatch => {
format!("each selected node's text must match /{pattern}/, but this one does not")
}
MatchType::MustNotMatch => {
format!("no selected node's text may match /{pattern}/, but this one does")
}
MatchType::MustExist => {
format!("at least one selected node's text must match /{pattern}/, but none does")
}
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Rule {
pub name: String,
pub language: String,
pub query: String,
#[serde(default)]
pub gate: Option<String>,
pub match_type: MatchType,
pub pattern: String,
#[serde(default)]
pub applies_to: Vec<String>,
#[serde(default)]
pub message: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RuleViolation {
pub rule: String,
pub message: String,
}
impl Rule {
#[must_use]
pub fn applies(&self, rel: &str) -> bool {
self.applies_to.is_empty()
|| self
.applies_to
.iter()
.any(|g| glob::Pattern::new(g).is_ok_and(|p| p.matches(rel)))
}
fn violations(&self, source: &str, rel: &str) -> Vec<RuleViolation> {
let Ok(captures) = run_query(source, &self.language, &self.query) else {
return Vec::new();
};
let Ok(pattern) = regex::Regex::new(&self.pattern) else {
return Vec::new();
};
let gate = match &self.gate {
Some(g) => match regex::Regex::new(g) {
Ok(re) => Some(re),
Err(_) => return Vec::new(),
},
None => None,
};
let gated: Vec<&Capture> = captures
.iter()
.filter(|c| gate.as_ref().is_none_or(|g| g.is_match(&c.text)))
.collect();
match self.match_type {
MatchType::MustMatch => gated
.iter()
.filter(|c| !pattern.is_match(&c.text))
.map(|c| self.violation(rel, Some(c)))
.collect(),
MatchType::MustNotMatch => gated
.iter()
.filter(|c| pattern.is_match(&c.text))
.map(|c| self.violation(rel, Some(c)))
.collect(),
MatchType::MustExist => {
if gated.iter().any(|c| pattern.is_match(&c.text)) {
Vec::new()
} else {
vec![self.violation(rel, None)]
}
}
}
}
fn violation(&self, rel: &str, capture: Option<&Capture>) -> RuleViolation {
let explanation = self
.message
.clone()
.unwrap_or_else(|| self.match_type.default_explanation(&self.pattern));
let (location, offending) = match capture {
Some(c) => (
format!("{rel}:{}", c.start_line),
format!(" Offending text: `{}`.", truncate(&c.text)),
),
None => (rel.to_string(), String::new()),
};
RuleViolation {
rule: self.name.clone(),
message: format!(
"hank: {location}: rule `{}` — {explanation}.{offending} \
({} tier)",
self.name,
Tier::TreeSitter.as_str()
),
}
}
}
#[must_use]
pub fn errors(rules: &[Rule]) -> Vec<(String, String)> {
let mut out = Vec::new();
for rule in rules {
if let Err(Error::Parse(e)) = run_query("", &rule.language, &rule.query) {
out.push((rule.name.clone(), format!("selector: {e}")));
}
if let Err(e) = regex::Regex::new(&rule.pattern) {
out.push((rule.name.clone(), format!("predicate regex: {e}")));
}
if let Some(gate) = &rule.gate {
if let Err(e) = regex::Regex::new(gate) {
out.push((rule.name.clone(), format!("gate regex: {e}")));
}
}
for pattern in &rule.applies_to {
if let Err(e) = glob::Pattern::new(pattern) {
out.push((
rule.name.clone(),
format!("applies_to glob `{pattern}`: {e}"),
));
}
}
}
out
}
#[must_use]
pub fn evaluate(rules: &[Rule], source: &str, language: &str, rel: &str) -> Vec<RuleViolation> {
rules
.iter()
.filter(|r| r.language == language && r.applies(rel))
.flat_map(|r| r.violations(source, rel))
.collect()
}
fn truncate(text: &str) -> String {
let line = text.lines().next().unwrap_or_default();
if line.chars().count() > 80 {
format!("{}…", line.chars().take(79).collect::<String>())
} else {
line.to_string()
}
}
#[cfg(test)]
mod tests {
use super::*;
fn rule(name: &str, match_type: MatchType, pattern: &str, gate: Option<&str>) -> Rule {
Rule {
name: name.to_string(),
language: "rust".to_string(),
query: "(line_comment) @c".to_string(),
gate: gate.map(str::to_string),
match_type,
pattern: pattern.to_string(),
applies_to: Vec::new(),
message: None,
}
}
const TICKET: &str = r"\b[A-Z]+-[0-9]+\b";
#[test]
fn todo_without_a_ticket_is_flagged_and_with_one_passes() {
let rules = vec![rule(
"todo-needs-ticket",
MatchType::MustMatch,
TICKET,
Some(r"\bTODO\b"),
)];
let bad = "// TODO: wire this up\nfn f() {}\n";
let violations = evaluate(&rules, bad, "rust", "src/a.rs");
assert_eq!(violations.len(), 1);
assert_eq!(violations[0].rule, "todo-needs-ticket");
assert!(violations[0].message.contains("src/a.rs:1"));
let good = "// TODO(ABC-123): wire this up\nfn f() {}\n";
assert!(evaluate(&rules, good, "rust", "src/a.rs").is_empty());
let plain = "// just a note\nfn f() {}\n";
assert!(evaluate(&rules, plain, "rust", "src/a.rs").is_empty());
}
#[test]
fn a_ticket_in_a_comment_is_flagged_and_without_one_passes() {
let rules = vec![rule(
"no-ticket-in-comment",
MatchType::MustNotMatch,
TICKET,
None,
)];
let bad = "// see ABC-123 for context\nfn f() {}\n";
let violations = evaluate(&rules, bad, "rust", "src/a.rs");
assert_eq!(violations.len(), 1);
assert!(violations[0].message.contains("ABC-123"));
let good = "// see the linked design doc\nfn f() {}\n";
assert!(evaluate(&rules, good, "rust", "src/a.rs").is_empty());
}
#[test]
fn must_exist_flags_a_file_missing_the_required_comment() {
let rules = vec![rule(
"needs-license-header",
MatchType::MustExist,
r"SPDX-License-Identifier",
None,
)];
let missing = "fn f() {}\n";
let violations = evaluate(&rules, missing, "rust", "src/a.rs");
assert_eq!(violations.len(), 1);
assert!(violations[0].message.contains("src/a.rs:"));
assert!(!violations[0].message.contains("src/a.rs:1"));
let present = "// SPDX-License-Identifier: MIT\nfn f() {}\n";
assert!(evaluate(&rules, present, "rust", "src/a.rs").is_empty());
}
#[test]
fn a_rule_only_evaluates_its_own_language() {
let rules = vec![rule(
"no-ticket-in-comment",
MatchType::MustNotMatch,
TICKET,
None,
)];
assert!(evaluate(&rules, "// ABC-123\n", "python", "a.py").is_empty());
}
#[test]
fn applies_to_scopes_a_rule_to_matching_paths() {
let mut r = rule(
"no-ticket-in-comment",
MatchType::MustNotMatch,
TICKET,
None,
);
r.applies_to = vec!["src/**".to_string()];
let rules = vec![r];
let bad = "// ABC-123\n";
assert!(!evaluate(&rules, bad, "rust", "src/a.rs").is_empty());
assert!(evaluate(&rules, bad, "rust", "vendor/a.rs").is_empty());
}
#[test]
fn a_custom_message_overrides_the_default_explanation() {
let mut r = rule(
"no-ticket-in-comment",
MatchType::MustNotMatch,
TICKET,
None,
);
r.message = Some("keep ticket refs out of source comments".to_string());
let violations = evaluate(&[r], "// ABC-123\n", "rust", "a.rs");
assert!(violations[0]
.message
.contains("keep ticket refs out of source comments"));
}
#[test]
fn a_malformed_selector_or_predicate_is_reported_not_silently_ignored() {
let bad_query = Rule {
query: "(nonexistent_node) @x".to_string(),
..rule("bad-selector", MatchType::MustNotMatch, TICKET, None)
};
let bad_regex = Rule {
pattern: "(".to_string(),
..rule("bad-predicate", MatchType::MustNotMatch, "(", None)
};
let bad_glob = Rule {
applies_to: vec!["src/[".to_string()],
..rule("bad-glob", MatchType::MustNotMatch, TICKET, None)
};
let errs = errors(&[bad_query, bad_regex, bad_glob]);
let names: Vec<&str> = errs.iter().map(|(n, _)| n.as_str()).collect();
assert!(names.contains(&"bad-selector"));
assert!(names.contains(&"bad-predicate"));
assert!(names.contains(&"bad-glob"));
assert!(evaluate(
&[Rule {
query: "(nonexistent_node) @x".to_string(),
..rule("bad", MatchType::MustNotMatch, TICKET, None)
}],
"// ABC-123\n",
"rust",
"a.rs"
)
.is_empty());
}
#[test]
fn match_type_parses_from_kebab_case_toml() {
#[derive(Deserialize)]
struct W {
m: MatchType,
}
assert_eq!(
toml::from_str::<W>("m = \"must-not-match\"").unwrap().m,
MatchType::MustNotMatch
);
assert!(toml::from_str::<W>("m = \"must_not_match\"").is_err());
}
}