Skip to main content

kizz_store/
explanation.rs

1// Copyright (c) 2026 Sakura Industries LLC.
2//
3// SPDX-License-Identifier: AGPL-3.0-only
4
5//! The contents of explanations: why a step ran, or that it was cached, as a build
6//! decided it ("Explaining decisions").
7//!
8//! The step-position records hold a [`Verdict`] for each step of a task's most
9//! recent run, so `kizz why` can print the reasons stored by the most recent build.
10//! A [`Reason`] is one of the kinds the spec lists:
11//!
12//! * never run: there is no record for this step;
13//! * the task program changed: its block, or a named loaded module;
14//! * the arguments changed: old and new, word by word;
15//! * the environment changed: the variables added, removed, or changed, with their
16//!   values, which only `--verbose` shows;
17//! * the working directory, `stdin`, capture mode, ignore patterns, `track` patterns,
18//!   `timestamps`, or `machine` changed;
19//! * inputs changed: every changed path, what changed about it, and who last wrote it;
20//! * the machine state that the step names changed: each changed value, old and new;
21//! * the command is marked `always`;
22//! * its task is marked `cache=never`;
23//! * `kizz run --no-cache` was given;
24//! * the previous run could not be cached, and why.
25//!
26//! Every type here is encoded by the rules of "Step keys": definite lengths, fields
27//! in a fixed order, and paths as byte strings.
28
29use std::path::PathBuf;
30
31use minicbor::{Decode, Encode};
32
33use crate::{
34    machine::MachineChange,
35    records::TaskId,
36    step::{Capture, Change, NotCachedReason, path_bytes, path_list},
37};
38
39/// The identity of one build: when it started, in nanoseconds since the Unix
40/// epoch, made larger than every earlier build of the same process. One process at
41/// a time uses a cache, so later builds have larger identities.
42#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default, Encode, Decode)]
43#[cbor(transparent)]
44pub struct BuildId(#[n(0)] pub u64);
45
46/// A task as explanations name it: its identity, the line of its block, and its
47/// heading.
48#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
49pub struct TaskLabel {
50    /// The task.
51    #[n(0)]
52    pub task: TaskId,
53    /// The line of the block's opening fence, counting from 1, or 0 when unknown.
54    #[n(1)]
55    pub line: u32,
56    /// The nearest heading above the block, if there is one.
57    #[n(2)]
58    pub heading: Option<String>,
59}
60
61/// Who last wrote a changed input.
62#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
63pub enum Writer {
64    /// This command, on its previous run: the step at the same position of the same
65    /// task, or a step with the same key.
66    #[n(0)]
67    ThisCommand,
68    /// Another step that ran earlier in this build.
69    #[n(1)]
70    ThisBuild {
71        /// The task of the step.
72        #[n(0)]
73        task: TaskLabel,
74        /// The position of the step in its task's run, counting from zero.
75        #[n(1)]
76        position: u32,
77    },
78    /// A step of an earlier build.
79    #[n(2)]
80    EarlierBuild {
81        /// The task of the step.
82        #[n(0)]
83        task: TaskLabel,
84        /// The position of the step in its task's run, counting from zero.
85        #[n(1)]
86        position: u32,
87    },
88    /// Something outside kizz: no step or task program recorded a write to the path
89    /// after the recorded state was taken.
90    #[n(3)]
91    Outside,
92    /// The program of a task, through `fs.write` or `fs.write_json`, in this build.
93    #[n(4)]
94    ProgramThisBuild {
95        /// The task.
96        #[n(0)]
97        task: TaskLabel,
98    },
99    /// The program of a task, through `fs.write` or `fs.write_json`, in an earlier
100    /// build.
101    #[n(5)]
102    ProgramEarlierBuild {
103        /// The task.
104        #[n(0)]
105        task: TaskLabel,
106    },
107}
108
109/// Why a changed input is a self-inflicted reason to run: kizz's own build changes
110/// it on every build.
111#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
112pub enum SelfInflicted {
113    /// This command writes the file and also reads it.
114    #[n(0)]
115    WritesAndReads,
116    /// Another step that runs on every build, because it is marked `always`, its
117    /// task is marked `cache=never`, or it re-runs for a self-inflicted reason
118    /// itself, wrote the file in this build.
119    #[n(1)]
120    WrittenEveryBuild {
121        /// The task of the writing step.
122        #[n(0)]
123        task: TaskLabel,
124        /// The position of the writing step in its task's run, counting from zero.
125        #[n(1)]
126        position: u32,
127    },
128}
129
130/// One changed input: the path, what changed about it, and who last wrote it.
131#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
132pub struct ChangedInput {
133    /// The absolute path.
134    #[cbor(n(0), with = "path_bytes")]
135    pub path: PathBuf,
136    /// What changed about it.
137    #[n(1)]
138    pub change: Change,
139    /// Who last wrote it.
140    #[n(2)]
141    pub writer: Writer,
142    /// Whether the change is self-inflicted, and how.
143    #[n(3)]
144    pub self_inflicted: Option<SelfInflicted>,
145}
146
147/// How a loaded module changed.
148#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Encode, Decode)]
149#[cbor(index_only)]
150pub enum ModuleChangeKind {
151    /// Its source changed.
152    #[n(0)]
153    Changed,
154    /// The program loads it now and did not before.
155    #[n(1)]
156    Added,
157    /// The program loaded it before and does not now.
158    #[n(2)]
159    Removed,
160}
161
162/// One loaded module that changed.
163#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
164pub struct ModuleChange {
165    /// The absolute path of the module.
166    #[cbor(n(0), with = "path_bytes")]
167    pub path: PathBuf,
168    /// How it changed.
169    #[n(1)]
170    pub kind: ModuleChangeKind,
171}
172
173/// One environment variable that was added, removed, or changed.
174///
175/// The values are kept so `--verbose` can show them; without it, output shows only
176/// the name, because values can be secrets.
177#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
178pub struct EnvChange {
179    /// The variable's name.
180    #[n(0)]
181    pub name: String,
182    /// The old value, or `None` when the variable was added.
183    #[n(1)]
184    pub old: Option<String>,
185    /// The new value, or `None` when the variable was removed.
186    #[n(2)]
187    pub new: Option<String>,
188}
189
190/// One reason a step ran.
191#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
192pub enum Reason {
193    /// There is no record for this step, and no earlier specification at its
194    /// position explains why.
195    #[n(0)]
196    NeverRun,
197    /// The task program changed.
198    #[n(1)]
199    ProgramChanged {
200        /// Whether the block changed.
201        #[n(0)]
202        block: bool,
203        /// Every loaded module that changed, was added, or was removed, sorted by
204        /// path. With neither a block nor a module, which part changed is unknown.
205        #[n(1)]
206        modules: Vec<ModuleChange>,
207    },
208    /// The arguments changed.
209    #[n(2)]
210    ArgumentsChanged {
211        /// The old argument vector.
212        #[n(0)]
213        old: Vec<String>,
214        /// The new argument vector.
215        #[n(1)]
216        new: Vec<String>,
217    },
218    /// The environment changed.
219    #[n(3)]
220    EnvironmentChanged {
221        /// Every variable added, removed, or changed, sorted by name.
222        #[n(0)]
223        changes: Vec<EnvChange>,
224    },
225    /// The working directory changed.
226    #[n(4)]
227    WorkingDirectoryChanged {
228        /// The old working directory.
229        #[cbor(n(0), with = "path_bytes")]
230        old: PathBuf,
231        /// The new working directory.
232        #[cbor(n(1), with = "path_bytes")]
233        new: PathBuf,
234    },
235    /// The `stdin` text changed.
236    #[n(5)]
237    StdinChanged {
238        /// The old text, or `None` for `/dev/null`.
239        #[n(0)]
240        old: Option<String>,
241        /// The new text, or `None` for `/dev/null`.
242        #[n(1)]
243        new: Option<String>,
244    },
245    /// The capture mode changed.
246    #[n(6)]
247    CaptureChanged {
248        /// The old mode.
249        #[n(0)]
250        old: Capture,
251        /// The new mode.
252        #[n(1)]
253        new: Capture,
254    },
255    /// The ignore patterns changed.
256    #[n(7)]
257    IgnoreChanged {
258        /// The old patterns.
259        #[n(0)]
260        old: Vec<String>,
261        /// The new patterns.
262        #[n(1)]
263        new: Vec<String>,
264    },
265    /// The `track` patterns changed.
266    #[n(8)]
267    TrackChanged {
268        /// The old patterns.
269        #[n(0)]
270        old: Vec<String>,
271        /// The new patterns.
272        #[n(1)]
273        new: Vec<String>,
274    },
275    /// The `timestamps` option changed.
276    #[n(12)]
277    TimestampsChanged {
278        /// The old value.
279        #[n(0)]
280        old: bool,
281        /// The new value.
282        #[n(1)]
283        new: bool,
284    },
285    /// The `machine` names changed.
286    #[n(13)]
287    MachineNamesChanged {
288        /// The old names.
289        #[n(0)]
290        old: Vec<String>,
291        /// The new names.
292        #[n(1)]
293        new: Vec<String>,
294    },
295    /// Recorded inputs changed.
296    #[n(9)]
297    InputsChanged {
298        /// Every changed input, sorted by path.
299        #[n(0)]
300        inputs: Vec<ChangedInput>,
301    },
302    /// Values of the machine state that the step names changed.
303    #[n(14)]
304    MachineChanged {
305        /// Each changed value, old and new, in the order of the step's names.
306        #[n(0)]
307        changes: Vec<MachineChange>,
308    },
309    /// The command is marked `always`.
310    #[n(10)]
311    Always,
312    /// The previous run could not be cached.
313    #[n(11)]
314    NotCached {
315        /// Why it could not be cached.
316        #[n(0)]
317        why: NotCachedReason,
318        /// Every input that changed since that run, sorted by path.
319        #[n(1)]
320        inputs: Vec<ChangedInput>,
321    },
322    /// The command's task is marked `cache=never`, so the command runs as if it were
323    /// marked `always`.
324    #[n(15)]
325    TaskCacheNever,
326    /// `kizz run --no-cache` was given, so the command ran although its record may
327    /// have been a cache hit. Unlike [`Reason::Always`] and
328    /// [`Reason::TaskCacheNever`], it does not make the step one that runs on every
329    /// build.
330    #[n(16)]
331    RunNoCache,
332    /// Dependency tracing is disabled; the command runs once per build.
333    #[n(17)]
334    Untraced,
335    /// The dependency tracing mode changed.
336    #[n(18)]
337    TracingChanged {
338        /// The previous value of the untraced option.
339        #[n(0)]
340        old: bool,
341        /// The current value of the untraced option.
342        #[n(1)]
343        new: bool,
344    },
345}
346
347impl Reason {
348    /// The changed inputs of this reason, if it has any.
349    #[must_use]
350    pub fn inputs(&self) -> &[ChangedInput] {
351        match self {
352            Self::InputsChanged { inputs } | Self::NotCached { inputs, .. } => inputs,
353            _ => &[],
354        }
355    }
356}
357
358/// Why a step ran.
359#[derive(Debug, Clone, PartialEq, Eq, Default, Encode, Decode)]
360pub struct Explanation {
361    /// Every reason, in the order of the spec's list.
362    #[n(0)]
363    pub reasons: Vec<Reason>,
364    /// The self-inflicted inputs that also made the step run in its task's previous
365    /// build, sorted: the step re-runs in consecutive builds for the same
366    /// self-inflicted reason, which deserves a loud warning.
367    #[cbor(n(1), with = "path_list")]
368    pub repeated: Vec<PathBuf>,
369}
370
371impl Explanation {
372    /// The paths of every self-inflicted changed input, sorted and without
373    /// duplicates.
374    #[must_use]
375    pub fn self_inflicted(&self) -> Vec<PathBuf> {
376        let mut paths: Vec<PathBuf> = self
377            .reasons
378            .iter()
379            .flat_map(Reason::inputs)
380            .filter(|input| input.self_inflicted.is_some())
381            .map(|input| input.path.clone())
382            .collect();
383        paths.sort();
384        paths.dedup();
385        paths
386    }
387
388    /// Whether the step runs on every build: it is marked `always`, its task is
389    /// marked `cache=never`, or one of its changed inputs is self-inflicted.
390    #[must_use]
391    pub fn runs_every_build(&self) -> bool {
392        self.reasons.iter().any(|reason| {
393            matches!(
394                reason,
395                Reason::Always | Reason::TaskCacheNever | Reason::Untraced
396            ) || reason
397                .inputs()
398                .iter()
399                .any(|input| input.self_inflicted.is_some())
400        })
401    }
402}
403
404/// What a build decided about one step.
405#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
406pub enum Verdict {
407    /// The step ran, for these reasons.
408    #[n(0)]
409    Ran(#[n(0)] Explanation),
410    /// The step was cached: every recorded input was unchanged, or its result in
411    /// this build was returned again.
412    #[n(1)]
413    Cached,
414}
415
416/// Unit tests for the encoding of explanations.
417#[cfg(test)]
418#[allow(
419    clippy::disallowed_macros,
420    clippy::disallowed_methods,
421    reason = "test code: the tests assert and lock"
422)]
423mod tests {
424    use super::*;
425
426    /// A task label.
427    fn label() -> TaskLabel {
428        TaskLabel {
429            task: TaskId {
430                file: PathBuf::from("/w/kizz.md"),
431                index: 1,
432            },
433            line: 3,
434            heading: Some("Build".to_owned()),
435        }
436    }
437
438    /// One reason of each kind.
439    fn reasons() -> Vec<Reason> {
440        let input = |writer, self_inflicted| {
441            ChangedInput {
442                path: PathBuf::from("/w/in\u{e9}"),
443                change: Change::Content,
444                writer,
445                self_inflicted,
446            }
447        };
448        vec![
449            Reason::NeverRun,
450            Reason::ProgramChanged {
451                block: true,
452                modules: vec![ModuleChange {
453                    path: PathBuf::from("/w/lib.star"),
454                    kind: ModuleChangeKind::Removed,
455                }],
456            },
457            Reason::ArgumentsChanged {
458                old: vec!["a".to_owned()],
459                new: vec!["b".to_owned()],
460            },
461            Reason::EnvironmentChanged {
462                changes: vec![EnvChange {
463                    name: "A".to_owned(),
464                    old: None,
465                    new: Some("1".to_owned()),
466                }],
467            },
468            Reason::WorkingDirectoryChanged {
469                old: PathBuf::from("/a"),
470                new: PathBuf::from("/b"),
471            },
472            Reason::StdinChanged {
473                old: None,
474                new: Some("x".to_owned()),
475            },
476            Reason::CaptureChanged {
477                old: Capture::Split,
478                new: Capture::Merged,
479            },
480            Reason::IgnoreChanged {
481                old: Vec::new(),
482                new: vec!["*.o".to_owned()],
483            },
484            Reason::TrackChanged {
485                old: vec!["/proc/x".to_owned()],
486                new: Vec::new(),
487            },
488            Reason::TimestampsChanged {
489                old: false,
490                new: true,
491            },
492            Reason::MachineNamesChanged {
493                old: Vec::new(),
494                new: vec!["kernel".to_owned()],
495            },
496            Reason::InputsChanged {
497                inputs: vec![
498                    input(Writer::ThisCommand, Some(SelfInflicted::WritesAndReads)),
499                    input(
500                        Writer::ThisBuild {
501                            task: label(),
502                            position: 2,
503                        },
504                        Some(SelfInflicted::WrittenEveryBuild {
505                            task: label(),
506                            position: 2,
507                        }),
508                    ),
509                    input(
510                        Writer::EarlierBuild {
511                            task: label(),
512                            position: 0,
513                        },
514                        None,
515                    ),
516                    input(Writer::Outside, None),
517                    input(Writer::ProgramThisBuild { task: label() }, None),
518                    input(Writer::ProgramEarlierBuild { task: label() }, None),
519                ],
520            },
521            Reason::MachineChanged {
522                changes: vec![MachineChange {
523                    value: "kernel release".to_owned(),
524                    old: "6.12.0".to_owned(),
525                    new: "6.13.0".to_owned(),
526                }],
527            },
528            Reason::Always,
529            Reason::TaskCacheNever,
530            Reason::RunNoCache,
531            Reason::NotCached {
532                why: NotCachedReason::Signaled { signal: 9 },
533                inputs: Vec::new(),
534            },
535        ]
536    }
537
538    #[test]
539    fn verdicts_round_trip_with_stable_bytes() {
540        let verdicts = [
541            Verdict::Cached,
542            Verdict::Ran(Explanation {
543                reasons: reasons(),
544                repeated: vec![PathBuf::from("/w/in\u{e9}"), PathBuf::from("/w/b")],
545            }),
546        ];
547        for verdict in verdicts {
548            let first = minicbor::to_vec(&verdict).unwrap();
549            assert_eq!(first, minicbor::to_vec(&verdict).unwrap());
550            assert_eq!(minicbor::decode::<Verdict>(&first).unwrap(), verdict);
551        }
552    }
553
554    #[test]
555    fn self_inflicted_paths_and_every_build_runs() {
556        let explanation = Explanation {
557            reasons: reasons(),
558            repeated: Vec::new(),
559        };
560        assert_eq!(explanation.self_inflicted(), [PathBuf::from("/w/in\u{e9}")]);
561        assert!(explanation.runs_every_build());
562        let plain = Explanation {
563            reasons: vec![Reason::NeverRun],
564            repeated: Vec::new(),
565        };
566        assert_eq!(plain.self_inflicted(), Vec::<PathBuf>::new());
567        assert!(!plain.runs_every_build());
568        let always = Explanation {
569            reasons: vec![Reason::Always],
570            repeated: Vec::new(),
571        };
572        assert!(always.runs_every_build());
573        let never = Explanation {
574            reasons: vec![Reason::TaskCacheNever],
575            repeated: Vec::new(),
576        };
577        assert!(never.runs_every_build());
578        assert_eq!(never.self_inflicted(), Vec::<PathBuf>::new());
579        let no_cache = Explanation {
580            reasons: vec![Reason::RunNoCache],
581            repeated: Vec::new(),
582        };
583        assert!(!no_cache.runs_every_build());
584        assert_eq!(no_cache.self_inflicted(), Vec::<PathBuf>::new());
585    }
586
587    /// The reason of a command whose task is marked `cache=never` encodes
588    /// differently from `always`, and an explanation that holds it round-trips.
589    #[test]
590    fn the_task_cache_never_reason_encodes_and_round_trips() {
591        let never = minicbor::to_vec(&Reason::TaskCacheNever).unwrap();
592        assert_ne!(never, minicbor::to_vec(&Reason::Always).unwrap());
593        assert_eq!(
594            minicbor::decode::<Reason>(&never).unwrap(),
595            Reason::TaskCacheNever
596        );
597        let verdict = Verdict::Ran(Explanation {
598            reasons: vec![Reason::TaskCacheNever],
599            repeated: Vec::new(),
600        });
601        let bytes = minicbor::to_vec(&verdict).unwrap();
602        assert_eq!(minicbor::decode::<Verdict>(&bytes).unwrap(), verdict);
603    }
604
605    /// The reason of a command that ran because `kizz run --no-cache` was given
606    /// encodes differently from `always` and from `cache=never`, and an explanation
607    /// that holds it round-trips.
608    #[test]
609    fn the_run_no_cache_reason_encodes_and_round_trips() {
610        let no_cache = minicbor::to_vec(&Reason::RunNoCache).unwrap();
611        assert_ne!(no_cache, minicbor::to_vec(&Reason::Always).unwrap());
612        assert_ne!(no_cache, minicbor::to_vec(&Reason::TaskCacheNever).unwrap());
613        assert_eq!(
614            minicbor::decode::<Reason>(&no_cache).unwrap(),
615            Reason::RunNoCache
616        );
617        let verdict = Verdict::Ran(Explanation {
618            reasons: vec![Reason::RunNoCache],
619            repeated: Vec::new(),
620        });
621        let bytes = minicbor::to_vec(&verdict).unwrap();
622        assert_eq!(minicbor::decode::<Verdict>(&bytes).unwrap(), verdict);
623    }
624}