termproof 0.4.1

Evidence-first verification for TUI and terminal applications: recipe model, schema, steps, assertions, orchestration, terminal sessions and the evidence pipeline
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
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
//! Choosing which recipes to run for a set of changed files.
//!
//! Running a whole suite on every change is the honest default and, past a
//! certain size, the reason nobody runs it. This maps a changeset onto the
//! recipes that could plausibly be affected, using each recipe's `ci_paths`
//! globs.
//!
//! Two rules do the work:
//!
//! **Smoke recipes always run.** A changeset that matches nothing still gets a
//! baseline, so "selected nothing" never silently means "verified nothing".
//!
//! **A change to the harness selects only smoke.** If any changed file is under
//! [`SelectionConfig::harness_root`], the change is to the verifier rather than
//! to what it verifies, and matching individual `ci_paths` would be noise. One
//! such path in a changeset suppresses every other match in it.
//!
//! ```
//! use termproof::selection::{select, SelectionConfig};
//! # use termproof::recipe::Recipe;
//! # fn recipe(name: &str, paths: &[&str]) -> Recipe {
//! #     serde_json::from_value(serde_json::json!({
//! #         "name": name, "ci_paths": paths, "steps": [],
//! #         "command": {"argv": ["true"]}
//! #     })).expect("valid recipe")
//! # }
//! let recipes = vec![
//!     recipe("smoke", &[]),
//!     recipe("payments", &["src/payments/**"]),
//!     recipe("search", &["src/search/**"]),
//! ];
//! let config = SelectionConfig {
//!     harness_root: "verify/",
//!     repo_marker: "/repo/",
//!     smoke: &["smoke"],
//! };
//!
//! let picked = select(&recipes, &["src/payments/api.rs".to_string()], &config);
//! let names: Vec<&str> = picked.iter().map(|r| r.meta.name.as_str()).collect();
//! assert_eq!(names, ["smoke", "payments"]);
//! ```

use std::collections::HashSet;

use globset::GlobBuilder;
use globset::GlobSetBuilder;

use crate::recipe::{Recipe, RecipeMeta};

/// Facts about one repository's layout that selection needs.
///
/// All three are the caller's to supply: they describe a checkout, not
/// verification.
pub struct SelectionConfig<'a> {
    /// Repo-relative prefix where the verification harness itself lives.
    ///
    /// A change under this prefix means the harness changed rather than the
    /// thing it verifies, so only [`SelectionConfig::smoke`] runs.
    pub harness_root: &'a str,

    /// Path segment marking the repository root inside an absolute path.
    ///
    /// Changed-file lists arrive with whatever prefix the caller's checkout
    /// has; everything up to and including this marker is stripped so paths
    /// compare repo-relative. One repo's `/src/` is another's `/code/`.
    pub repo_marker: &'a str,

    /// Recipes that run for every changeset, whatever it touched.
    pub smoke: &'a [&'a str],
}

/// Read newline-delimited changed files, dropping blank lines.
pub fn changed_files_from_file(path: &str) -> std::io::Result<Vec<String>> {
    let contents = std::fs::read_to_string(path)?;
    Ok(contents
        .lines()
        .map(|l| l.trim().to_string())
        .filter(|l| !l.is_empty())
        .collect())
}

/// What selection needs to know about a recipe.
///
/// Selection is a function of a name and a glob list; it never runs anything.
/// Requiring a [`Recipe`] therefore excluded the callers most likely to want
/// it — a suite whose recipes branch on what the screen shows cannot be
/// expressed as a declarative [`Recipe`], but it still has names and
/// `ci_paths`, and it still has the problem of running everything on every
/// change.
///
/// [`Recipe`] implements this, so existing callers are unaffected and type
/// inference keeps their calls compiling unchanged. `(String, Vec<String>)`
/// implements it too, for callers who would rather not write a trait impl to
/// ask a question — that pairing is what the Python implementation's
/// `select_names` has always taken.
///
/// Since #199 the imperative caller has a third option that costs nothing:
/// [`RecipeMeta`] implements this, and it is a type such a caller can hold as
/// its own metadata rather than re-declaring `name` and `ci_paths` beside it.
pub trait Selectable {
    /// The recipe's name.
    fn name(&self) -> &str;

    /// Globs for the sources this recipe covers, repo-relative.
    fn ci_paths(&self) -> &[String];
}

impl Selectable for RecipeMeta {
    fn name(&self) -> &str {
        &self.name
    }

    fn ci_paths(&self) -> &[String] {
        &self.ci_paths
    }
}

impl Selectable for Recipe {
    fn name(&self) -> &str {
        self.meta.name()
    }

    fn ci_paths(&self) -> &[String] {
        self.meta.ci_paths()
    }
}

impl Selectable for (String, Vec<String>) {
    fn name(&self) -> &str {
        &self.0
    }

    fn ci_paths(&self) -> &[String] {
        &self.1
    }
}

/// The recipes to run for `changed_files`, in their original order.
pub fn select<'a, R: Selectable>(
    recipes: &'a [R],
    changed_files: &[String],
    config: &SelectionConfig<'_>,
) -> Vec<&'a R> {
    let mut chosen: HashSet<&str> = config
        .smoke
        .iter()
        .filter(|name| recipes.iter().any(|r| r.name() == **name))
        .copied()
        .collect();

    let paths: Vec<String> = changed_files
        .iter()
        .map(|p| normalize_path(p, config.repo_marker))
        .collect();

    let touches_harness = paths.iter().any(|p| p.starts_with(config.harness_root));
    if !touches_harness {
        for r in recipes {
            if matches_any_path(r.ci_paths(), &paths, config.repo_marker) {
                chosen.insert(r.name());
            }
        }
    }

    recipes
        .iter()
        .filter(|r| chosen.contains(r.name()))
        .collect()
}

/// Names of the recipes [`select`] would run.
pub fn select_names<R: Selectable>(
    recipes: &[R],
    changed_files: &[String],
    config: &SelectionConfig<'_>,
) -> Vec<String> {
    select(recipes, changed_files, config)
        .into_iter()
        .map(|r| r.name().to_string())
        .collect()
}

/// Reduce a path to a repo-relative, forward-slashed form.
fn normalize_path(path: &str, repo_marker: &str) -> String {
    let mut normalized = path.trim().replace('\\', "/");
    while let Some(rest) = normalized.strip_prefix("./") {
        normalized = rest.to_string();
    }
    // Everything up to *and including* the marker goes: the marker names the
    // checkout directory, which is not part of a repo-relative path. Keeping
    // it would leave `repo/src/foo.rs`, which no `ci_paths` pattern matches.
    if let Some(idx) = normalized.find(repo_marker) {
        normalized = normalized[idx + repo_marker.len()..].to_string();
    }
    normalized.trim_end_matches('/').to_string()
}

/// Whether any of `paths` matches any of `patterns`.
///
/// `literal_separator(false)` so `*` crosses `/`, matching `fnmatch` rather
/// than shell globbing. A pattern that does not compile is skipped rather than
/// failing the selection: a typo in one recipe's `ci_paths` should not stop the
/// suite from choosing the others.
fn matches_any_path(patterns: &[String], paths: &[String], repo_marker: &str) -> bool {
    if patterns.is_empty() || paths.is_empty() {
        return false;
    }
    let mut builder = GlobSetBuilder::new();
    let mut any = false;
    for pattern in patterns {
        if let Ok(glob) = GlobBuilder::new(&normalize_path(pattern, repo_marker))
            .literal_separator(false)
            .build()
        {
            builder.add(glob);
            any = true;
        }
    }
    if !any {
        return false;
    }
    match builder.build() {
        Ok(set) => paths.iter().any(|p| set.is_match(p)),
        Err(_) => false,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Build through serde rather than a struct literal: `Recipe` has many
    /// `#[serde(default = "...")]` fields, and a literal would hard-code my
    /// guesses at their values instead of using theirs.
    fn recipe(name: &str, paths: &[&str]) -> Recipe {
        serde_json::from_value(serde_json::json!({
            "name": name,
            "ci_paths": paths,
            "steps": [],
            // `command` is the one required field with no serde default.
            // Selection never reads it, but a `Recipe` cannot exist without one.
            "command": {"argv": ["true"]},
        }))
        .expect("valid recipe")
    }

    fn all() -> Vec<Recipe> {
        vec![
            recipe("smoke", &[]),
            recipe("payments", &["src/payments/**"]),
            recipe("search", &["src/search/**/*.rs"]),
        ]
    }

    fn cfg() -> SelectionConfig<'static> {
        SelectionConfig {
            harness_root: "verify/",
            repo_marker: "/repo/",
            smoke: &["smoke"],
        }
    }

    fn names(changed: &[&str]) -> Vec<String> {
        let owned: Vec<String> = changed.iter().map(|s| s.to_string()).collect();
        select_names(&all(), &owned, &cfg())
    }

    #[test]
    fn smoke_runs_even_when_nothing_matches() {
        // "Selected nothing" must never quietly mean "verified nothing".
        assert_eq!(names(&["docs/readme.md"]), vec!["smoke".to_string()]);
    }

    #[test]
    fn a_matching_path_adds_its_recipe() {
        assert_eq!(
            names(&["src/payments/api.rs"]),
            vec!["smoke".to_string(), "payments".to_string()]
        );
    }

    #[test]
    fn a_harness_change_suppresses_every_other_match() {
        // The change is to the verifier, not to what it verifies. One such path
        // in a changeset suppresses the rest.
        assert_eq!(
            names(&["src/payments/api.rs", "verify/runner.rs"]),
            vec!["smoke".to_string()]
        );
    }

    #[test]
    fn absolute_paths_are_made_repo_relative() {
        assert_eq!(
            names(&["/home/someone/repo/src/search/index.rs"]),
            vec!["smoke".to_string(), "search".to_string()]
        );
    }

    #[test]
    fn windows_separators_and_dot_prefixes_normalise() {
        assert_eq!(
            names(&[".\\src\\payments\\api.rs"]),
            vec!["smoke".to_string(), "payments".to_string()]
        );
    }

    #[test]
    fn a_star_crosses_directory_separators() {
        // fnmatch semantics, not shell globbing: `src/search/**/*.rs` has to
        // match a file several directories down.
        assert_eq!(
            names(&["src/search/backend/index/mod.rs"]),
            vec!["smoke".to_string(), "search".to_string()]
        );
    }

    #[test]
    fn a_broken_glob_does_not_stop_the_others() {
        let recipes = vec![
            recipe("smoke", &[]),
            recipe("broken", &["["]),
            recipe("payments", &["src/payments/**"]),
        ];
        let changed = vec!["src/payments/api.rs".to_string()];
        let got = select_names(&recipes, &changed, &cfg());
        assert!(got.contains(&"payments".to_string()), "{got:?}");
    }

    #[test]
    fn a_smoke_name_that_does_not_exist_is_ignored() {
        let config = SelectionConfig {
            harness_root: "verify/",
            repo_marker: "/repo/",
            smoke: &["smoke", "nonexistent"],
        };
        let changed = vec!["docs/readme.md".to_string()];
        assert_eq!(
            select_names(&all(), &changed, &config),
            vec!["smoke".to_string()]
        );
    }

    #[test]
    fn selection_preserves_the_input_order() {
        // Callers report on this list; a set-ordered result would reshuffle
        // reports between runs for no reason.
        let changed = vec![
            "src/search/index.rs".to_string(),
            "src/payments/api.rs".to_string(),
        ];
        assert_eq!(
            select_names(&all(), &changed, &cfg()),
            vec![
                "smoke".to_string(),
                "payments".to_string(),
                "search".to_string()
            ]
        );
    }

    #[test]
    fn an_empty_changeset_still_runs_smoke() {
        assert_eq!(select_names(&all(), &[], &cfg()), vec!["smoke".to_string()]);
    }

    /// A recipe type that is not `Recipe` — the case the trait exists for.
    struct ImperativeRecipe {
        name: String,
        ci_paths: Vec<String>,
    }

    impl Selectable for ImperativeRecipe {
        fn name(&self) -> &str {
            &self.name
        }

        fn ci_paths(&self) -> &[String] {
            &self.ci_paths
        }
    }

    #[test]
    fn a_foreign_recipe_type_can_be_selected() {
        let recipes = vec![
            ImperativeRecipe {
                name: "smoke".into(),
                ci_paths: vec![],
            },
            ImperativeRecipe {
                name: "payments".into(),
                ci_paths: vec!["src/payments/**".into()],
            },
            ImperativeRecipe {
                name: "search".into(),
                ci_paths: vec!["src/search/**".into()],
            },
        ];
        let changed = vec!["src/payments/api.rs".to_string()];
        assert_eq!(
            select_names(&recipes, &changed, &cfg()),
            vec!["smoke".to_string(), "payments".to_string()]
        );
    }

    #[test]
    fn a_name_and_paths_pair_is_selectable_without_a_trait_impl() {
        // The shape Python's `select_names` takes, so the two implementations
        // can be called the same way.
        let recipes = vec![
            ("smoke".to_string(), Vec::<String>::new()),
            ("payments".to_string(), vec!["src/payments/**".to_string()]),
        ];
        let changed = vec!["src/payments/api.rs".to_string()];
        assert_eq!(
            select_names(&recipes, &changed, &cfg()),
            vec!["smoke".to_string(), "payments".to_string()]
        );
    }

    #[test]
    fn a_harness_change_suppresses_matches_for_a_foreign_type_too() {
        let recipes = vec![
            ImperativeRecipe {
                name: "smoke".into(),
                ci_paths: vec![],
            },
            ImperativeRecipe {
                name: "payments".into(),
                ci_paths: vec!["src/payments/**".into()],
            },
        ];
        let changed = vec![
            "verify/runner.rs".to_string(),
            "src/payments/api.rs".to_string(),
        ];
        assert_eq!(
            select_names(&recipes, &changed, &cfg()),
            vec!["smoke".to_string()]
        );
    }
}