kizz_core/step.rs
1// Copyright (c) 2026 Sakura Industries LLC.
2//
3// SPDX-License-Identifier: AGPL-3.0-only
4
5//! The boundary between task programs and the engine.
6//!
7//! Each `run()` call in a task program builds a [`StepSpec`], the step
8//! specification, and hands it to the [`StepExecutor`] the task runs with. The
9//! executor decides how the step is run, traced, and cached, and returns a
10//! [`StepOutcome`]: how the command ended, its raw captured output, and whether the
11//! outcome came from the cache. Tests implement [`StepExecutor`] with a fake.
12
13use std::{collections::BTreeMap, fmt};
14
15use kizz_trace::{AbsolutePath, CaptureMode, CapturedOutput, Termination};
16
17/// One step, as a `run()` call in a task program specifies it.
18#[derive(Debug, Clone, PartialEq, Eq)]
19#[allow(
20 clippy::struct_excessive_bools,
21 reason = "independent command options mirror the Starlark API"
22)]
23pub struct StepSpec {
24 /// The argument vector: the program, then its arguments, each string exactly as
25 /// written, after `run()` expanded the lists and tuples among its arguments.
26 pub argv: Vec<String>,
27 /// The text for standard input, or `None` to connect `/dev/null`.
28 pub stdin: Option<String>,
29 /// The exact environment of the command: the task environment with the
30 /// per-run `env` applied.
31 pub env: BTreeMap<String, String>,
32 /// The absolute working directory: the task directory, or `cwd` resolved
33 /// against it.
34 pub cwd: AbsolutePath,
35 /// How standard output and standard error are captured.
36 pub capture: CaptureMode,
37 /// Whether output is also echoed live to the terminal.
38 pub stream: bool,
39 /// Whether the command runs on every build, even when cached.
40 pub always: bool,
41 /// Run without observing dependencies; implies one uncached execution per build.
42 pub untraced: bool,
43 /// Whether socket activity is expected and needs no warning.
44 pub network: bool,
45 /// The user exceptions: patterns of paths not recorded as dependencies.
46 pub ignore: Vec<String>,
47 /// The `/proc` and `/sys` files whose content counts as an input.
48 pub track: Vec<String>,
49 /// Whether a different modification or change time of a file or directory that
50 /// the step read, ran, listed, or checked is a change, even when the content is
51 /// the same.
52 pub timestamps: bool,
53 /// The names of the parts of the machine state that count as an input of the
54 /// step, sorted and without repeats; each is a [`MachinePart`] name.
55 ///
56 /// [`MachinePart`]: kizz_store::MachinePart
57 pub machine: Vec<String>,
58 /// The acceptable exit codes, or `None` when the exit status never fails the
59 /// task.
60 pub expect: Option<Vec<i32>>,
61}
62
63impl StepSpec {
64 /// The command as messages show it: the argument vector joined with spaces.
65 #[must_use]
66 pub fn command(&self) -> String {
67 self.argv.join(" ")
68 }
69}
70
71/// The outcome of one step.
72#[derive(Debug, Clone, PartialEq, Eq)]
73pub struct StepOutcome {
74 /// How the command ended.
75 pub termination: Termination,
76 /// The raw captured output, exactly as the command wrote it or as the cache
77 /// recorded it.
78 pub output: CapturedOutput,
79 /// Whether the outcome came from the cache.
80 pub cached: bool,
81}
82
83/// A step the executor could not run, such as a program that does not exist.
84///
85/// It fails the task with its message.
86#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
87#[error("{message}")]
88pub struct StepError {
89 /// What went wrong.
90 pub message: String,
91}
92
93impl StepError {
94 /// An error with `message`.
95 #[must_use]
96 pub fn new(message: impl fmt::Display) -> Self {
97 Self {
98 message: message.to_string(),
99 }
100 }
101}
102
103/// Runs the steps of a task program.
104///
105/// The runtime calls [`StepExecutor::execute`] once for each `run()` call, in
106/// program order, and returns the outcome to the program.
107pub trait StepExecutor {
108 /// Run one step and return its outcome.
109 ///
110 /// # Errors
111 ///
112 /// Returns [`StepError`] when the step cannot be run; the task then fails.
113 fn execute(
114 &self,
115 step: &StepSpec,
116 ) -> Result<StepOutcome, StepError>;
117}