1use std::{
39 collections::{BTreeMap, BTreeSet},
40 path::PathBuf,
41};
42
43use kizz_store::{
44 AccessBits, BuildId, ChangedInput, ContentHash, Difference, EnvChange, LastWriter,
45 ModuleChange, ModuleChangeKind, ModuleHash, Observation, PathKey, PositionKey, Reason,
46 SelfInflicted, StepKey, StepPosition, StepSpecRecord, StoreError, TaskId, TaskLabel,
47 TaskRecord, Txn, Verdict, Writer, WrittenBy,
48};
49use kizz_trace::AbsolutePath;
50
51use crate::runtime::{ProgramHash, ProgramParts, TaskProgram};
52
53#[derive(Debug, Clone, PartialEq, Eq)]
56pub struct TaskIdentity {
57 pub id: TaskId,
59 pub line: u32,
61 pub heading: Option<String>,
63 pub targets: Vec<String>,
65 pub program: ProgramHash,
67 pub parts: ProgramParts,
69 pub dir: AbsolutePath,
71}
72
73impl TaskIdentity {
74 #[must_use]
76 pub fn of(program: &TaskProgram) -> Self {
77 let task = program.task();
78 Self {
79 id: TaskId {
80 file: task.file.as_path().to_path_buf(),
81 index: task.index,
82 },
83 line: u32::try_from(task.line).unwrap_or(u32::MAX),
84 heading: task.heading.clone(),
85 targets: task.targets.clone(),
86 program: program.hash(),
87 parts: program.parts().clone(),
88 dir: task.dir.clone(),
89 }
90 }
91
92 #[must_use]
94 pub fn label(&self) -> TaskLabel {
95 TaskLabel {
96 task: self.id.clone(),
97 line: self.line,
98 heading: self.heading.clone(),
99 }
100 }
101
102 #[must_use]
105 pub fn task_record(
106 &self,
107 succeeded: bool,
108 build: BuildId,
109 steps: u32,
110 ) -> TaskRecord {
111 TaskRecord {
112 program_hash: *self.program.as_bytes(),
113 succeeded,
114 build,
115 steps,
116 line: self.line,
117 heading: self.heading.clone(),
118 targets: self.targets.clone(),
119 block: ContentHash(self.parts.block),
120 modules: self
121 .parts
122 .modules
123 .iter()
124 .map(|(path, hash)| {
125 ModuleHash {
126 path: path.clone(),
127 hash: ContentHash(*hash),
128 }
129 })
130 .collect(),
131 }
132 }
133}
134
135#[derive(Debug, Clone, PartialEq, Eq)]
138pub struct StepDecision {
139 pub position: u32,
141 pub command: String,
143 pub verdict: Verdict,
145}
146
147#[derive(Debug, Clone, PartialEq, Eq)]
150pub struct RepeatedWarning {
151 pub task: Option<TaskLabel>,
153 pub position: u32,
155 pub command: String,
157 pub paths: Vec<PathBuf>,
159}
160
161#[derive(Debug, Clone, PartialEq, Eq, Default)]
164pub struct Baseline {
165 pub recorded_at_nanos: u64,
167 pub writes_and_reads: BTreeSet<PathBuf>,
169}
170
171impl Baseline {
172 #[must_use]
175 pub fn new(
176 observations: &[Observation],
177 recorded_at_nanos: u64,
178 ) -> Self {
179 Self {
180 recorded_at_nanos,
181 writes_and_reads: observations
182 .iter()
183 .filter(|observation| {
184 observation.access.contains(AccessBits::WRITE)
185 && observation.access.contains(AccessBits::READ)
186 })
187 .map(|observation| observation.path.clone())
188 .collect(),
189 }
190 }
191}
192
193#[derive(Debug, Clone, Copy)]
195pub struct InputContext<'a> {
196 pub identity: Option<&'a TaskIdentity>,
198 pub position: u32,
200 pub key: StepKey,
202 pub build: BuildId,
204 pub baseline: Option<&'a Baseline>,
206}
207
208#[must_use]
215pub fn spec_reasons(
216 old: &StepSpecRecord,
217 new: &StepSpecRecord,
218 old_task: Option<&TaskRecord>,
219 new_parts: Option<&ProgramParts>,
220) -> Vec<Reason> {
221 let mut reasons = Vec::new();
222 if old.program_hash != new.program_hash {
223 reasons.push(program_reason(old, old_task, new_parts));
224 }
225 if old.argv != new.argv {
226 reasons.push(Reason::ArgumentsChanged {
227 old: old.argv.clone(),
228 new: new.argv.clone(),
229 });
230 }
231 let changes = env_changes(&old.env, &new.env);
232 if !changes.is_empty() {
233 reasons.push(Reason::EnvironmentChanged { changes });
234 }
235 if old.cwd != new.cwd {
236 reasons.push(Reason::WorkingDirectoryChanged {
237 old: old.cwd.clone(),
238 new: new.cwd.clone(),
239 });
240 }
241 if old.stdin != new.stdin {
242 reasons.push(Reason::StdinChanged {
243 old: old.stdin.clone(),
244 new: new.stdin.clone(),
245 });
246 }
247 if old.capture != new.capture {
248 reasons.push(Reason::CaptureChanged {
249 old: old.capture,
250 new: new.capture,
251 });
252 }
253 if old.ignore != new.ignore {
254 reasons.push(Reason::IgnoreChanged {
255 old: old.ignore.clone(),
256 new: new.ignore.clone(),
257 });
258 }
259 if old.track != new.track {
260 reasons.push(Reason::TrackChanged {
261 old: old.track.clone(),
262 new: new.track.clone(),
263 });
264 }
265 if old.timestamps != new.timestamps {
266 reasons.push(Reason::TimestampsChanged {
267 old: old.timestamps,
268 new: new.timestamps,
269 });
270 }
271 if old.untraced != new.untraced {
272 reasons.push(Reason::TracingChanged {
273 old: old.untraced,
274 new: new.untraced,
275 });
276 }
277 if old.machine != new.machine {
278 reasons.push(Reason::MachineNamesChanged {
279 old: old.machine.clone(),
280 new: new.machine.clone(),
281 });
282 }
283 reasons
284}
285
286fn program_reason(
289 old: &StepSpecRecord,
290 old_task: Option<&TaskRecord>,
291 new_parts: Option<&ProgramParts>,
292) -> Reason {
293 let unknown = Reason::ProgramChanged {
294 block: false,
295 modules: Vec::new(),
296 };
297 let (Some(old_task), Some(new_parts)) = (old_task, new_parts) else {
298 return unknown;
299 };
300 if old_task.program_hash != old.program_hash.0 {
301 return unknown;
302 }
303 let old_modules: BTreeMap<&PathBuf, &ContentHash> = old_task
304 .modules
305 .iter()
306 .map(|module| (&module.path, &module.hash))
307 .collect();
308 let new_modules: BTreeMap<&PathBuf, ContentHash> = new_parts
309 .modules
310 .iter()
311 .map(|(path, hash)| (path, ContentHash(*hash)))
312 .collect();
313 let paths: BTreeSet<&PathBuf> = old_modules
314 .keys()
315 .chain(new_modules.keys())
316 .copied()
317 .collect();
318 let modules = paths
319 .into_iter()
320 .filter_map(|path| {
321 let kind = match (old_modules.get(path), new_modules.get(path)) {
322 (Some(old), Some(new)) if *old == new => return None,
323 (Some(_), Some(_)) => ModuleChangeKind::Changed,
324 (None, _) => ModuleChangeKind::Added,
325 (Some(_), None) => ModuleChangeKind::Removed,
326 };
327 Some(ModuleChange {
328 path: path.clone(),
329 kind,
330 })
331 })
332 .collect();
333 Reason::ProgramChanged {
334 block: old_task.block.0 != new_parts.block,
335 modules,
336 }
337}
338
339fn env_changes(
342 old: &BTreeMap<String, String>,
343 new: &BTreeMap<String, String>,
344) -> Vec<EnvChange> {
345 let names: BTreeSet<&String> = old.keys().chain(new.keys()).collect();
346 names
347 .into_iter()
348 .filter_map(|name| {
349 let (old, new) = (old.get(name), new.get(name));
350 (old != new).then(|| {
351 EnvChange {
352 name: name.clone(),
353 old: old.cloned(),
354 new: new.cloned(),
355 }
356 })
357 })
358 .collect()
359}
360
361pub fn changed_inputs(
368 txn: &Txn<'_>,
369 context: &InputContext<'_>,
370 differences: &[Difference],
371) -> Result<Vec<ChangedInput>, StoreError> {
372 differences
373 .iter()
374 .map(|difference| {
375 let entry = txn.get::<LastWriter>(&PathKey(difference.path.clone()))?;
376 let writer = attribute(txn, context, entry.as_ref())?;
377 let writes_and_reads = writer == Writer::ThisCommand
381 && context
382 .baseline
383 .is_some_and(|baseline| baseline.writes_and_reads.contains(&difference.path));
384 let self_inflicted = if writes_and_reads {
385 Some(SelfInflicted::WritesAndReads)
386 } else if let (Writer::ThisBuild { task, position }, Some(entry)) = (&writer, &entry)
387 && writes_every_build(txn, entry, context.build)?
388 {
389 Some(SelfInflicted::WrittenEveryBuild {
390 task: task.clone(),
391 position: *position,
392 })
393 } else {
394 None
395 };
396 Ok(ChangedInput {
397 path: difference.path.clone(),
398 change: difference.change.clone(),
399 writer,
400 self_inflicted,
401 })
402 })
403 .collect()
404}
405
406fn attribute(
408 txn: &Txn<'_>,
409 context: &InputContext<'_>,
410 entry: Option<&LastWriter>,
411) -> Result<Writer, StoreError> {
412 let Some(entry) = entry else {
413 return Ok(Writer::Outside);
414 };
415 let baseline_at = context
416 .baseline
417 .map_or(0, |baseline| baseline.recorded_at_nanos);
418 if entry.written_at_nanos <= baseline_at {
419 return Ok(Writer::Outside);
422 }
423 let this_build = entry.build == context.build;
424 let WrittenBy::Step { step, position } = entry.by else {
425 let task = label_of(txn, context.identity, &entry.task)?;
426 return Ok(if this_build {
427 Writer::ProgramThisBuild { task }
428 } else {
429 Writer::ProgramEarlierBuild { task }
430 });
431 };
432 let same_position = context
433 .identity
434 .is_some_and(|identity| identity.id == entry.task && position == context.position);
435 if step == context.key || same_position {
436 return Ok(Writer::ThisCommand);
437 }
438 let task = label_of(txn, context.identity, &entry.task)?;
439 Ok(if this_build {
440 Writer::ThisBuild { task, position }
441 } else {
442 Writer::EarlierBuild { task, position }
443 })
444}
445
446fn label_of(
449 txn: &Txn<'_>,
450 identity: Option<&TaskIdentity>,
451 task: &TaskId,
452) -> Result<TaskLabel, StoreError> {
453 if let Some(identity) = identity.filter(|identity| identity.id == *task) {
454 return Ok(identity.label());
455 }
456 Ok(match txn.get::<TaskRecord>(task)? {
457 Some(record) => {
458 TaskLabel {
459 task: task.clone(),
460 line: record.line,
461 heading: record.heading,
462 }
463 },
464 None => {
465 TaskLabel {
466 task: task.clone(),
467 line: 0,
468 heading: None,
469 }
470 },
471 })
472}
473
474fn writes_every_build(
479 txn: &Txn<'_>,
480 entry: &LastWriter,
481 build: BuildId,
482) -> Result<bool, StoreError> {
483 let WrittenBy::Step { step, position } = entry.by else {
484 return Ok(false);
485 };
486 let position_record = txn.get::<StepPosition>(&PositionKey {
487 task: entry.task.clone(),
488 position,
489 })?;
490 Ok(position_record.is_some_and(|record| {
491 record.build == build
492 && record.step == step
493 && matches!(&record.verdict, Verdict::Ran(explanation) if explanation.runs_every_build())
494 }))
495}
496
497#[must_use]
505pub fn carried_from(
506 previous: Option<&StepPosition>,
507 build: BuildId,
508) -> Vec<PathBuf> {
509 match previous {
510 Some(previous) if previous.build == build => previous.carried.clone(),
511 Some(StepPosition {
512 verdict: Verdict::Ran(explanation),
513 ..
514 }) => explanation.self_inflicted(),
515 Some(_) | None => Vec::new(),
516 }
517}
518
519#[cfg(test)]
521#[allow(
522 clippy::disallowed_macros,
523 clippy::disallowed_methods,
524 reason = "test code: the tests assert and lock"
525)]
526mod tests {
527 use kizz_store::{Capture, Change, Explanation};
528
529 use super::*;
530
531 fn spec() -> StepSpecRecord {
533 StepSpecRecord {
534 program_hash: ContentHash([1; 32]),
535 cwd: PathBuf::from("/w"),
536 argv: vec!["cc".to_owned(), "-O2".to_owned()],
537 env: [
538 ("KEEP".to_owned(), "1".to_owned()),
539 ("GONE".to_owned(), "2".to_owned()),
540 ("EDIT".to_owned(), "3".to_owned()),
541 ]
542 .into(),
543 stdin: None,
544 capture: Capture::Split,
545 stream: false,
546 always: false,
547 untraced: false,
548 ignore: Vec::new(),
549 track: Vec::new(),
550 timestamps: false,
551 machine: Vec::new(),
552 expect: None,
553 occurrence: 0,
554 }
555 }
556
557 fn old_task() -> TaskRecord {
559 TaskRecord {
560 program_hash: [1; 32],
561 succeeded: true,
562 build: BuildId(1),
563 steps: 1,
564 line: 1,
565 heading: None,
566 targets: Vec::new(),
567 block: ContentHash([7; 32]),
568 modules: vec![
569 ModuleHash {
570 path: PathBuf::from("/w/a.star"),
571 hash: ContentHash([2; 32]),
572 },
573 ModuleHash {
574 path: PathBuf::from("/w/b.star"),
575 hash: ContentHash([3; 32]),
576 },
577 ],
578 }
579 }
580
581 #[test]
582 fn identical_specifications_have_no_reasons() {
583 assert_eq!(
584 spec_reasons(&spec(), &spec(), None, None),
585 Vec::<Reason>::new()
586 );
587 let mut repeated = spec();
588 repeated.occurrence = 1;
589 repeated.stream = true;
590 repeated.always = true;
591 repeated.expect = Some(vec![0]);
592 assert_eq!(
593 spec_reasons(&spec(), &repeated, None, None),
594 Vec::<Reason>::new()
595 );
596 }
597
598 #[test]
599 fn every_changed_value_gives_its_reason_in_order() {
600 let mut new = spec();
601 new.program_hash = ContentHash([9; 32]);
602 new.argv = vec!["cc".to_owned(), "-O0".to_owned()];
603 new.env.remove("GONE");
604 new.env.insert("EDIT".to_owned(), "4".to_owned());
605 new.env.insert("ADDED".to_owned(), "5".to_owned());
606 new.cwd = PathBuf::from("/x");
607 new.stdin = Some("in".to_owned());
608 new.capture = Capture::Merged;
609 new.ignore = vec!["*.o".to_owned()];
610 new.track = vec!["/proc/cpuinfo".to_owned()];
611 new.timestamps = true;
612 new.machine = vec!["kernel".to_owned()];
613 let parts = ProgramParts {
614 block: [7; 32],
615 modules: vec![
616 (PathBuf::from("/w/a.star"), [2; 32]),
617 (PathBuf::from("/w/b.star"), [4; 32]),
618 (PathBuf::from("/w/c.star"), [5; 32]),
619 ],
620 };
621 let reasons = spec_reasons(&spec(), &new, Some(&old_task()), Some(&parts));
622 assert_eq!(reasons, vec![
623 Reason::ProgramChanged {
624 block: false,
625 modules: vec![
626 ModuleChange {
627 path: PathBuf::from("/w/b.star"),
628 kind: ModuleChangeKind::Changed,
629 },
630 ModuleChange {
631 path: PathBuf::from("/w/c.star"),
632 kind: ModuleChangeKind::Added,
633 },
634 ],
635 },
636 Reason::ArgumentsChanged {
637 old: spec().argv,
638 new: new.argv.clone(),
639 },
640 Reason::EnvironmentChanged {
641 changes: vec![
642 EnvChange {
643 name: "ADDED".to_owned(),
644 old: None,
645 new: Some("5".to_owned()),
646 },
647 EnvChange {
648 name: "EDIT".to_owned(),
649 old: Some("3".to_owned()),
650 new: Some("4".to_owned()),
651 },
652 EnvChange {
653 name: "GONE".to_owned(),
654 old: Some("2".to_owned()),
655 new: None,
656 },
657 ],
658 },
659 Reason::WorkingDirectoryChanged {
660 old: PathBuf::from("/w"),
661 new: PathBuf::from("/x"),
662 },
663 Reason::StdinChanged {
664 old: None,
665 new: Some("in".to_owned()),
666 },
667 Reason::CaptureChanged {
668 old: Capture::Split,
669 new: Capture::Merged,
670 },
671 Reason::IgnoreChanged {
672 old: Vec::new(),
673 new: vec!["*.o".to_owned()],
674 },
675 Reason::TrackChanged {
676 old: Vec::new(),
677 new: vec!["/proc/cpuinfo".to_owned()],
678 },
679 Reason::TimestampsChanged {
680 old: false,
681 new: true,
682 },
683 Reason::MachineNamesChanged {
684 old: Vec::new(),
685 new: vec!["kernel".to_owned()],
686 },
687 ]);
688 }
689
690 #[test]
691 fn a_changed_program_names_its_parts_only_when_they_are_known() {
692 let mut new = spec();
693 new.program_hash = ContentHash([9; 32]);
694 let parts = ProgramParts {
695 block: [8; 32],
696 modules: vec![(PathBuf::from("/w/a.star"), [2; 32])],
697 };
698 assert_eq!(
699 spec_reasons(&spec(), &new, Some(&old_task()), Some(&parts)),
700 vec![Reason::ProgramChanged {
701 block: true,
702 modules: vec![ModuleChange {
703 path: PathBuf::from("/w/b.star"),
704 kind: ModuleChangeKind::Removed,
705 }],
706 }]
707 );
708 let unknown = vec![Reason::ProgramChanged {
709 block: false,
710 modules: Vec::new(),
711 }];
712 assert_eq!(spec_reasons(&spec(), &new, None, Some(&parts)), unknown);
713 let mut other = old_task();
714 other.program_hash = [5; 32];
715 assert_eq!(
716 spec_reasons(&spec(), &new, Some(&other), Some(&parts)),
717 unknown
718 );
719 }
720
721 #[test]
722 fn positions_carry_the_self_inflicted_inputs_of_the_previous_build() {
723 let input = ChangedInput {
724 path: PathBuf::from("/w/cache"),
725 change: Change::Content,
726 writer: Writer::Outside,
727 self_inflicted: Some(SelfInflicted::WritesAndReads),
728 };
729 let ran = StepPosition {
730 step: StepKey([1; 32]),
731 build: BuildId(1),
732 verdict: Verdict::Ran(Explanation {
733 reasons: vec![Reason::InputsChanged {
734 inputs: vec![input],
735 }],
736 repeated: Vec::new(),
737 }),
738 carried: vec![PathBuf::from("/w/older")],
739 };
740 assert_eq!(carried_from(Some(&ran), BuildId(2)), [PathBuf::from(
741 "/w/cache"
742 )]);
743 assert_eq!(carried_from(Some(&ran), BuildId(1)), [PathBuf::from(
744 "/w/older"
745 )]);
746 let cached = StepPosition {
747 verdict: Verdict::Cached,
748 ..ran
749 };
750 assert_eq!(
751 carried_from(Some(&cached), BuildId(2)),
752 Vec::<PathBuf>::new()
753 );
754 assert_eq!(carried_from(None, BuildId(2)), Vec::<PathBuf>::new());
755 }
756
757 #[test]
758 fn a_baseline_keeps_the_paths_written_and_read() {
759 let observation = |path: &str, access| {
760 Observation {
761 path: PathBuf::from(path),
762 access: AccessBits(access),
763 tracked: false,
764 state: kizz_store::PathState::Absent,
765 attributes: None,
766 }
767 };
768 let baseline = Baseline::new(
769 &[
770 observation("/both", AccessBits::READ | AccessBits::WRITE),
771 observation("/written", AccessBits::WRITE),
772 observation("/read", AccessBits::READ),
773 ],
774 5,
775 );
776 assert_eq!(baseline.recorded_at_nanos, 5);
777 assert_eq!(
778 baseline.writes_and_reads,
779 [PathBuf::from("/both")].into_iter().collect()
780 );
781 }
782}