Skip to main content

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}