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}