hank 0.4.0

In-memory, multi-tenant code-analysis engine — the structural signal for the Bobbin × Quipu stack
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
//! Structural (tree-sitter-tier) edit policies — the "rule" plane.
//!
//! A capability [`scope`](crate::policy) governs WHERE and HOW FAR an edit may
//! reach. A *rule* governs WHAT the edit's text may look like — the checks a
//! linter finds hard or slow: "a TODO must cite a ticket", "no ticket id in a
//! comment". A rule pairs a tree-sitter query (the **Selector** — which nodes)
//! with a regex predicate (the **Predicate** — what their text must or must not
//! be), so it maps one-to-one onto Quipu's `aegis:Selector` + `aegis:Predicate`
//! (`docs/book/src/design/policy-edit-hooks.md`): a policy projected from Quipu
//! deserializes straight into a [`Rule`], and the field names are chosen to say
//! so.
//!
//! Everything here is tree-sitter-tier ([`Tier::TreeSitter`]): the selector runs
//! against the same best-effort parse the extractor uses. The predicate match is
//! exact given a clean parse, but provenance is still tree-sitter — a misparse is
//! possible — so a verdict is tagged accordingly and never claims more.
//!
//! Pure like [`crate::policy`]: it evaluates a buffer and does no I/O. A rule
//! whose selector/predicate does not compile is surfaced by [`errors`], never
//! silently treated as "nothing matched" (the discipline
//! [`crate::policy::Scope::glob_errors`] applies to path globs).

use serde::{Deserialize, Serialize};

use crate::errors::Error;
use crate::extract::query::{run_query, Capture};
use crate::types::Tier;

/// How a rule's predicate is applied to the nodes its selector captures.
///
/// The string forms match Quipu's `aegis:matchType` enum so a projected policy
/// round-trips.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum MatchType {
    /// Every captured node's text MUST match the pattern; each that does not is a
    /// violation.
    MustMatch,
    /// No captured node's text may match the pattern; each that does is a
    /// violation.
    MustNotMatch,
    /// At least one captured node's text must match the pattern; a file with none
    /// is a single violation.
    MustExist,
}

impl MatchType {
    /// The default model-facing explanation, when a rule supplies no `message`.
    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")
            }
        }
    }
}

/// One structural rule: a Selector (tree-sitter query) + a Predicate (regex).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Rule {
    /// Stable identifier, used in verdicts and in the projected-policy IRI.
    pub name: String,
    /// The language whose grammar the selector is written against (`rust`,
    /// `python`, …). A rule only evaluates files of its own language.
    pub language: String,
    /// The **Selector**: a tree-sitter `.scm` capture query, e.g.
    /// `(line_comment) @c`. Mirrors `aegis:Selector.evidenceSource`.
    pub query: String,
    /// An optional pre-filter regex on a capture's text: only captures matching
    /// the gate are tested by the predicate (e.g. only comments containing
    /// `\bTODO\b`).
    #[serde(default)]
    pub gate: Option<String>,
    /// The **Predicate** direction. Mirrors `aegis:matchType`.
    pub match_type: MatchType,
    /// The **Predicate** regex tested against a capture's text. Mirrors
    /// `aegis:Predicate.evidenceSource`.
    pub pattern: String,
    /// Repo-relative path globs this rule applies to. Empty = every path.
    #[serde(default)]
    pub applies_to: Vec<String>,
    /// An optional custom model-facing explanation, overriding the default for
    /// [`MatchType`].
    #[serde(default)]
    pub message: Option<String>,
}

/// A single rule violation, with the text shown to the model.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RuleViolation {
    /// The rule that was broken.
    pub rule: String,
    /// Model-facing explanation: what was broken, where, and what to do.
    pub message: String,
}

impl Rule {
    /// Whether this rule governs `rel` (matches one of its `applies_to` globs, or
    /// applies everywhere when the list is empty). A malformed glob never
    /// matches — [`errors`] surfaces it instead of letting it silently widen or
    /// narrow the 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)))
    }

    /// Evaluate this rule against `source` (already known to be this rule's
    /// `language`), returning any violations. A selector/predicate that does not
    /// compile yields no violations here — the failure is reported by [`errors`]
    /// so the guard can fail open loudly rather than under-enforce silently.
    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)]
                }
            }
        }
    }

    /// Build the model-facing violation for `capture` (or a file-level one when
    /// `None`, as [`MatchType::MustExist`] produces).
    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()
            ),
        }
    }
}

/// Every rule whose selector, predicate, gate, or path glob does not compile,
/// as `(rule_name, reason)`. A rule set with such an entry is misconfigured and
/// the guard says so rather than quietly under-enforcing (the `glob_errors`
/// discipline, applied to rules).
///
/// A rule for a language this build cannot parse is NOT an error — it simply
/// never matches a file, so it is skipped, not reported.
#[must_use]
pub fn errors(rules: &[Rule]) -> Vec<(String, String)> {
    let mut out = Vec::new();
    for rule in rules {
        // Compiling against an empty source validates the query without needing a
        // real buffer; only a genuine query-compile failure is an error here.
        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
}

/// Evaluate every rule that governs `rel` and is written for `language` against
/// `source`, returning all violations. Rules for other languages or other paths
/// are skipped.
#[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()
}

/// The first line of `text`, capped so a long comment does not flood the model.
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() {
        // The awkward-for-a-linter rule: a TODO must cite a ticket.
        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());

        // A non-TODO comment is not gated in, so it is never asked for a ticket.
        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() {
        // The opposite direction: ticket ids belong in commits, not comments.
        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);
        // A file-level violation names the file, not a line.
        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,
        )];
        // Same text, but presented as a different language: the rust rule is skipped.
        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());
        // Outside the glob, the rule does not apply.
        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"));

        // ... and a malformed rule contributes no violations (it cannot pass as clean).
        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());
    }
}