Skip to main content

kizz_core/
runtime.rs

1// Copyright (c) 2026 Sakura Industries LLC.
2//
3// SPDX-License-Identifier: AGPL-3.0-only
4
5//! The Starlark runtime of task programs.
6//!
7//! A task program is a task block plus every module it loads, directly or
8//! indirectly. [`TaskProgram::load`] reads and evaluates the modules, records each
9//! module read as an access of the task, and computes the [`ProgramHash`] that
10//! covers the block and every module. [`TaskProgram::run`] then evaluates the block,
11//! handing each `run()` call to a [`StepExecutor`].
12//!
13//! Programs use the extended Starlark dialect, so top-level `if` and `for` work.
14//! The globals are the standard ones with `json.encode` and `json.decode`, plus
15//! `run`, `env`, `fs`, `print`, and `fail`; `load` is a statement, and `task`
16//! describes the running task. Functions from modules act on the task that calls
17//! them, and calling `run()` while a module is being loaded, outside any task, is
18//! an error.
19//!
20//! Each positional argument of `run()` is a string, or a list or tuple of strings,
21//! lists or tuples, which expands in place, in order and at any depth, into the
22//! step's command. The expansion walks the values with its own stack, fails on a
23//! list or tuple that contains itself, and stops past a million values, so it never
24//! recurses without bound and always ends.
25//!
26//! The task environment starts empty, and only the `env` functions change it;
27//! `env.caller` and `env.inherit` read the caller environment that
28//! [`TaskProgram::run`] is given, never the process environment. The task
29//! environment and the caller environment exist only while the task runs, so while
30//! a module is being loaded, the `env` functions other than `env.read` are errors,
31//! like `run()`. The `fs` functions and `env.read` work there too, and every file
32//! access they make, like each module read, is recorded against the task, as is
33//! every file that `fs.write` or `fs.write_json` changes.
34//!
35//! `run()` returns a value of the runtime's own Starlark type, `run_result`, with
36//! the attributes `rc`, `signal`, `stdout` and `stderr` or `output`, and `cached`.
37//! The value notes when the program reads `rc` or `signal`, or encodes the value
38//! with `json.encode` or `fs.write_json`, which encode it as an object of its
39//! attributes, as they encoded the struct that `run()` returned before. So when the
40//! program ends, [`TaskRun::unchecked`] lists every step that exited with a
41//! non-zero code or was killed by a signal, whose `run()` had no `expect`, and
42//! whose result the program never checked ("Exit codes and failure").
43//!
44//! The runtime never panics ("Kizz never panics"): the state of the running task
45//! and of a module being loaded lives in `Cell`s, which the private `cells` module
46//! takes out, changes and puts back, where `RefCell` borrows would panic while the
47//! cell is borrowed; and the blank lines that put the block at its line of the
48//! `kizz.md` are pushed into space reserved with `String::try_reserve_exact`, where
49//! `str::repeat` would panic on a length that overflows.
50
51use std::{
52    cell::Cell,
53    collections::{BTreeMap, HashMap, HashSet},
54    fmt, fs,
55    io::{self, ErrorKind},
56    path::PathBuf,
57    sync::{
58        Arc,
59        atomic::{AtomicBool, Ordering},
60    },
61};
62
63use allocative::Allocative;
64use kizz_store::MachinePart;
65use kizz_trace::{
66    AbsolutePath, AccessKind, Accesses, CaptureMode, CapturedOutput, NotAbsoluteError, Termination,
67};
68use starlark::{
69    PrintHandler,
70    any::ProvidesStaticType,
71    collections::SmallMap,
72    docs::{DocFunction, DocItem, DocMember},
73    environment::{FrozenModule, Globals, GlobalsBuilder, LibraryExtension, Module},
74    eval::{Evaluator, FileLoader},
75    pagable::{
76        StarlarkDeserialize, StarlarkDeserializeContext, StarlarkSerialize,
77        StarlarkSerializeContext,
78    },
79    starlark_module,
80    syntax::{AstModule, Dialect},
81    values::{
82        AllocValue, Heap, StarlarkValue, Value, ValueIdentity, ValueLike,
83        dict::{Dict, UnpackDictEntries},
84        list::ListRef,
85        list_or_tuple::UnpackListOrTuple,
86        none::{NoneOr, NoneType},
87        starlark_value,
88        structs::AllocStruct,
89        tuple::{TupleRef, UnpackTuple},
90    },
91};
92
93use crate::{
94    cells,
95    dotenv::{self, DotenvError},
96    files::{AccessOutcomes, FileChanges, FileError, Files},
97    step::{StepError, StepExecutor, StepOutcome, StepSpec},
98    tasks::Task,
99};
100
101/// The context string from which the program hash key is derived. A change to how
102/// the hash is computed changes the version at its end.
103const PROGRAM_HASH_CONTEXT: &str = "kizz task program hash, version 1";
104
105/// The running task, as task programs see it through `task` and as messages name
106/// it.
107#[derive(Debug, Clone, PartialEq, Eq)]
108pub struct TaskInfo {
109    /// The absolute directory of the task's `kizz.md`, the task directory.
110    pub dir: AbsolutePath,
111    /// The absolute path of the task's `kizz.md`.
112    pub file: AbsolutePath,
113    /// The path of the task's `kizz.md`, relative to the directory discovery started
114    /// in, as messages show it.
115    pub relative_file: PathBuf,
116    /// The line of the block's opening fence, counting from 1.
117    pub line: usize,
118    /// The index of the task block in its `kizz.md`, counting from zero.
119    pub index: u32,
120    /// The name that the block's `name=` option gives the task, if it has one.
121    pub name: Option<String>,
122    /// The nearest heading above the block, the task's heading, if there is one.
123    pub heading: Option<String>,
124    /// The targets on the block, in the order written.
125    pub targets: Vec<String>,
126    /// The requested targets that selected the task.
127    pub selected: Vec<String>,
128    /// The task's arguments, which programs read as `task.args`: empty under
129    /// `kizz build`. They are not part of the task program hash.
130    pub args: Vec<String>,
131    /// Whether the block's `cache=never` option marks the task, so every command of
132    /// the task runs as if it were marked `always`.
133    pub cache_never: bool,
134    /// The block's Starlark source.
135    pub source: String,
136}
137
138impl TaskInfo {
139    /// The information of `task`, selected by the requested targets `selected`, with
140    /// no arguments, as `kizz build` runs it.
141    ///
142    /// # Errors
143    ///
144    /// Returns [`NotAbsoluteError`] when the task's `kizz.md` path is not absolute.
145    pub fn new(
146        task: &Task,
147        selected: &[String],
148    ) -> Result<Self, NotAbsoluteError> {
149        let file = AbsolutePath::new(&task.id.file)?;
150        let dir = parent_dir(&file);
151        Ok(Self {
152            dir,
153            file,
154            relative_file: task.relative_file.clone(),
155            line: task.line,
156            index: task.id.index,
157            name: task.options.name.clone(),
158            heading: task.heading.clone(),
159            targets: task.targets.clone(),
160            selected: selected.to_vec(),
161            args: Vec::new(),
162            cache_never: task.options.cache_never,
163            source: task.source.clone(),
164        })
165    }
166
167    /// The information of `task` as `kizz run` runs it: with the arguments `args`,
168    /// which its program reads as `task.args`, and an empty `task.selected`,
169    /// because no target selected the task.
170    ///
171    /// # Errors
172    ///
173    /// Returns [`NotAbsoluteError`] when the task's `kizz.md` path is not absolute.
174    pub fn for_run(
175        task: &Task,
176        args: Vec<String>,
177    ) -> Result<Self, NotAbsoluteError> {
178        Ok(Self {
179            args,
180            ..Self::new(task, &[])?
181        })
182    }
183
184    /// The name that prefixes the task's `print` output: its name, else its heading,
185    /// else `path/kizz.md:LINE`.
186    #[must_use]
187    pub fn display_name(&self) -> String {
188        self.name
189            .clone()
190            .or_else(|| self.heading.clone())
191            .unwrap_or_else(|| format!("{}:{}", self.relative_file.display(), self.line))
192    }
193}
194
195/// Where the lines that task programs `print` go.
196pub trait PrintSink {
197    /// Show one line of `print` output, already prefixed with the task's
198    /// [`TaskInfo::display_name`]: its name, else its heading, else its location.
199    fn print_line(
200        &self,
201        line: &str,
202    );
203}
204
205/// The BLAKE3 hash of a task program: the block and every module the task loads.
206#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
207pub struct ProgramHash([u8; 32]);
208
209impl ProgramHash {
210    /// The hash with these bytes, as a stored task record holds it.
211    #[must_use]
212    pub const fn from_bytes(bytes: [u8; 32]) -> Self {
213        Self(bytes)
214    }
215
216    /// The hash's bytes.
217    #[must_use]
218    pub const fn as_bytes(&self) -> &[u8; 32] {
219        &self.0
220    }
221}
222
223impl fmt::Display for ProgramHash {
224    fn fmt(
225        &self,
226        f: &mut fmt::Formatter<'_>,
227    ) -> fmt::Result {
228        for byte in self.0 {
229            write!(f, "{byte:02x}")?;
230        }
231        Ok(())
232    }
233}
234
235/// A step whose exit status was not one its `expect` list accepts.
236#[derive(Debug, Clone, PartialEq, Eq)]
237pub struct UnexpectedExit {
238    /// The step's argument vector.
239    pub argv: Vec<String>,
240    /// How the command ended.
241    pub termination: Termination,
242    /// The acceptable exit codes.
243    pub expect: Vec<i32>,
244    /// The command's raw captured output.
245    pub output: CapturedOutput,
246}
247
248impl fmt::Display for UnexpectedExit {
249    fn fmt(
250        &self,
251        f: &mut fmt::Formatter<'_>,
252    ) -> fmt::Result {
253        let expected: Vec<String> = self.expect.iter().map(ToString::to_string).collect();
254        writeln!(
255            f,
256            "command `{}`: {}, but `expect` accepts exit code {}",
257            self.argv.join(" "),
258            self.termination,
259            if expected.is_empty() {
260                "none".to_owned()
261            } else {
262                expected.join(" or ")
263            },
264        )?;
265        write_captured(f, &self.output)
266    }
267}
268
269/// Write the captured output `output` under a header for each stream.
270fn write_captured(
271    f: &mut fmt::Formatter<'_>,
272    output: &CapturedOutput,
273) -> fmt::Result {
274    match output {
275        CapturedOutput::Split { stdout, stderr } => {
276            write_output(f, "stdout", stdout)?;
277            write_output(f, "stderr", stderr)
278        },
279        CapturedOutput::Merged { output } => write_output(f, "output", output),
280    }
281}
282
283/// A step whose command exited with a non-zero code or was killed by a signal,
284/// whose `run()` had no `expect`, and whose result the task program never checked:
285/// it never read the result's `rc` or `signal` and never encoded the result
286/// ("Exit codes and failure"). A result from the cache counts like any other.
287#[derive(Debug, Clone, PartialEq, Eq)]
288pub struct UncheckedExit {
289    /// The position of the step in the task's run, counting from zero: the number
290    /// of `run()` calls that reached the executor before it.
291    pub position: u32,
292    /// The step's argument vector.
293    pub argv: Vec<String>,
294    /// How the command ended: never with exit code 0.
295    pub termination: Termination,
296    /// The command's raw captured output.
297    pub output: CapturedOutput,
298    /// Whether the result came from the cache.
299    pub cached: bool,
300}
301
302impl UncheckedExit {
303    /// The command as messages name it: its arguments joined with spaces.
304    #[must_use]
305    pub fn command(&self) -> String {
306        self.argv.join(" ")
307    }
308}
309
310impl fmt::Display for UncheckedExit {
311    fn fmt(
312        &self,
313        f: &mut fmt::Formatter<'_>,
314    ) -> fmt::Result {
315        writeln!(
316            f,
317            "command `{}`: {}, which the task program never checked: its `run()` has no \
318             `expect`, and the program never read the result's `rc` or `signal`",
319            self.command(),
320            self.termination,
321        )?;
322        write_captured(f, &self.output)
323    }
324}
325
326/// The message of a task that `--fail-unchecked` fails because its program left
327/// the steps `exits` unchecked, under the command `invoked`, such as `kizz build`
328/// or `kizz run`: a line that says so and names the command with the option, then
329/// each command with its exit status and its captured output.
330fn unchecked_message(
331    exits: &[UncheckedExit],
332    invoked: &str,
333) -> String {
334    let mut message = format!(
335        "the task program left {} unchecked, and `{invoked} --fail-unchecked` makes that fail \
336         the task\n",
337        if exits.len() == 1 {
338            "a non-zero exit".to_owned()
339        } else {
340            format!("{} non-zero exits", exits.len())
341        }
342    );
343    for exit in exits {
344        message.push_str(&exit.to_string());
345    }
346    message
347}
348
349/// Write one captured stream under a header, decoded as UTF-8 with invalid bytes
350/// replaced.
351fn write_output(
352    f: &mut fmt::Formatter<'_>,
353    name: &str,
354    bytes: &[u8],
355) -> fmt::Result {
356    writeln!(f, "--- {name} ---")?;
357    let text = String::from_utf8_lossy(bytes);
358    if text.ends_with('\n') || text.is_empty() {
359        write!(f, "{text}")
360    } else {
361        writeln!(f, "{text}")
362    }
363}
364
365/// Why a task failed.
366#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
367pub enum TaskFailure {
368    /// The program failed: `fail()`, a Starlark error, a module that cannot be
369    /// loaded, a step the executor could not run, or `run()` called while a module
370    /// loads. The message includes the Starlark stack when there is one.
371    #[error("{message}")]
372    Program {
373        /// The error message.
374        message: String,
375    },
376    /// A step's exit status was not in its `expect` list.
377    #[error("{exit}{message}")]
378    UnexpectedExit {
379        /// The command, its exit status, and its captured output.
380        exit: Box<UnexpectedExit>,
381        /// The Starlark error message with the stack of the `run()` call.
382        message: String,
383    },
384    /// The program ended, and left steps unchecked, which fails the task with
385    /// `kizz build --fail-unchecked` or `kizz run --fail-unchecked` ("Exit codes and
386    /// failure").
387    #[error("{}", unchecked_message(.exits, .invoked))]
388    Unchecked {
389        /// Each unchecked step, in the order the program ran them, with its command,
390        /// its exit status, and its captured output.
391        exits: Vec<UncheckedExit>,
392        /// The command that was given `--fail-unchecked`, as the message names it:
393        /// `kizz build` or `kizz run` (see [`Engine::command_name`]).
394        ///
395        /// [`Engine::command_name`]: crate::Engine::command_name
396        invoked: &'static str,
397    },
398}
399
400impl TaskFailure {
401    /// A program failure with `message`.
402    fn program(message: impl fmt::Display) -> Self {
403        Self::Program {
404            message: message.to_string(),
405        }
406    }
407}
408
409/// The most values that the expansion of `run()`'s positional arguments visits:
410/// the positional arguments, and every string, list and tuple inside them, alike.
411/// The bound keeps the expansion of lists that share lists, which can double at each
412/// level, under a million steps, and it refuses no command that Linux could start.
413const MAX_ARGUMENT_VALUES: usize = 1_000_000;
414
415/// Where a value among `run()`'s positional arguments is: the positional argument,
416/// counted from 1, and the index path within it, as Starlark indexing writes it.
417#[derive(Debug, Clone, PartialEq, Eq)]
418struct ArgumentPlace {
419    /// The positional argument, counted from 1.
420    argument: usize,
421    /// The index into each list or tuple on the way to the value, outermost first;
422    /// empty for the positional argument itself.
423    path: Vec<usize>,
424}
425
426impl fmt::Display for ArgumentPlace {
427    /// `3` for a positional argument itself, and `2 at [1][0]` for `x[1][0]` where
428    /// `x` is the second positional argument.
429    fn fmt(
430        &self,
431        f: &mut fmt::Formatter<'_>,
432    ) -> fmt::Result {
433        write!(f, "{}", self.argument)?;
434        if !self.path.is_empty() {
435            f.write_str(" at ")?;
436            for index in &self.path {
437                write!(f, "[{index}]")?;
438            }
439        }
440        Ok(())
441    }
442}
443
444/// A list or tuple that the expansion of `run()`'s positional arguments is inside.
445struct ArgumentFrame<'v> {
446    /// The elements of the list or tuple.
447    items: &'v [Value<'v>],
448    /// The index of the next element to visit.
449    next: usize,
450    /// The identity of the list or tuple, which the cycle check holds while the
451    /// expansion is inside it.
452    identity: ValueIdentity<'v>,
453}
454
455/// The elements of `value` and its type, `list` or `tuple`, when it is a list or a
456/// tuple, frozen or not.
457fn list_or_tuple_items(value: Value<'_>) -> Option<(&[Value<'_>], &'static str)> {
458    if let Some(list) = ListRef::from_value(value) {
459        return Some((list.content(), value.get_type()));
460    }
461    TupleRef::from_value(value).map(|tuple| (tuple.content(), value.get_type()))
462}
463
464/// The command that `run()`'s positional arguments `arguments` give: each string as
465/// one argument, unchanged, and each list or tuple expanded in place, in order and at
466/// any depth.
467///
468/// The walk uses an explicit stack of frames, never recursion, so no depth of nesting
469/// can overflow the thread's stack. The identities of the lists and tuples on the
470/// current path are held in a set, so a list or tuple met again inside itself is an
471/// error, while the same list used twice side by side is not. Every visited value
472/// counts towards [`MAX_ARGUMENT_VALUES`], so lists that share lists end promptly.
473/// Errors come in the order of the walk.
474///
475/// # Errors
476///
477/// Returns [`RunError::ArgumentType`] for a value that is neither a string nor a list
478/// or tuple, [`RunError::SelfContaining`] for a list or tuple met again inside
479/// itself, and [`RunError::TooManyValues`] past the bound.
480fn expand_arguments(arguments: &[Value<'_>]) -> Result<Vec<String>, RunError> {
481    let mut argv = Vec::new();
482    let mut visited: usize = 0;
483    for (position, &argument) in arguments.iter().enumerate() {
484        let number = position.saturating_add(1);
485        let mut stack: Vec<ArgumentFrame<'_>> = Vec::new();
486        let mut on_path: HashSet<ValueIdentity<'_>> = HashSet::new();
487        let mut pending = Some(argument);
488        loop {
489            if let Some(value) = pending.take() {
490                if visited >= MAX_ARGUMENT_VALUES {
491                    return Err(RunError::TooManyValues);
492                }
493                visited = visited.saturating_add(1);
494                let place = || {
495                    ArgumentPlace {
496                        argument: number,
497                        path: stack
498                            .iter()
499                            .map(|frame| frame.next.saturating_sub(1))
500                            .collect(),
501                    }
502                };
503                if let Some(text) = value.unpack_str() {
504                    argv.push(text.to_owned());
505                } else if let Some((items, kind)) = list_or_tuple_items(value) {
506                    let identity = value.identity();
507                    if !on_path.insert(identity) {
508                        return Err(RunError::SelfContaining {
509                            place: place(),
510                            kind,
511                        });
512                    }
513                    stack.push(ArgumentFrame {
514                        items,
515                        next: 0,
516                        identity,
517                    });
518                } else {
519                    return Err(RunError::ArgumentType {
520                        place: place(),
521                        kind: value.get_type(),
522                    });
523                }
524            }
525            let Some(frame) = stack.last_mut() else {
526                break;
527            };
528            if let Some(&item) = frame.items.get(frame.next) {
529                frame.next = frame.next.saturating_add(1);
530                pending = Some(item);
531            } else {
532                on_path.remove(&frame.identity);
533                stack.pop();
534            }
535        }
536    }
537    Ok(argv)
538}
539
540/// Errors that `run()`, the `env` and `fs` functions, and module loading raise
541/// inside Starlark.
542#[derive(Debug, thiserror::Error)]
543enum RunError {
544    /// A function that needs the running task was called while a module was being
545    /// loaded, outside any task.
546    #[error("{call} cannot be called while {module} is being loaded, outside any task")]
547    WhileLoading {
548        /// The function, such as `run()`.
549        call: &'static str,
550        /// The module being loaded, as messages show it.
551        module: String,
552    },
553    /// `run()` was called with no program.
554    #[error("run() needs a program: run(\"program\", \"argument\", ...)")]
555    NoProgram,
556    /// A positional argument of `run()`, or a value inside one, is neither a string
557    /// nor a list or tuple.
558    #[error("run(): argument {place} is of type {kind}, not a string, list or tuple")]
559    ArgumentType {
560        /// Where the value is.
561        place: ArgumentPlace,
562        /// The value's type, as Starlark's `type()` names it.
563        kind: &'static str,
564    },
565    /// A list or tuple among the positional arguments of `run()` contains itself,
566    /// directly or through other lists or tuples.
567    #[error("run(): argument {place} is a {kind} that contains itself")]
568    SelfContaining {
569        /// Where the list or tuple is met again inside itself.
570        place: ArgumentPlace,
571        /// `list` or `tuple`.
572        kind: &'static str,
573    },
574    /// The positional arguments of `run()` would expand to more values than
575    /// [`MAX_ARGUMENT_VALUES`].
576    #[error(
577        "run(): the arguments expand to more than {max} strings, lists and tuples",
578        max = MAX_ARGUMENT_VALUES
579    )]
580    TooManyValues,
581    /// `capture` was neither `"split"` nor `"merged"`.
582    #[error("run(): capture must be \"split\" or \"merged\", not \"{0}\"")]
583    Capture(String),
584    /// `machine` named a part that the machine state does not have.
585    #[error(
586        "run(): machine has no part \"{0}\"; the parts are {parts}",
587        parts = MachinePart::names_text()
588    )]
589    MachinePart(String),
590    /// The executor could not run the step.
591    #[error("run(): {0}")]
592    Step(#[from] StepError),
593    /// The exit status was not in the `expect` list.
594    #[error("run(): command `{command}`: {termination}, which `expect` does not accept")]
595    Unexpected {
596        /// The command.
597        command: String,
598        /// How it ended.
599        termination: Termination,
600    },
601    /// A loader was asked for a module it was not given.
602    #[error("module `{0}` was not loaded")]
603    NotLoaded(String),
604    /// A file operation of an `env` or `fs` function failed.
605    #[error("{call}: {error}")]
606    File {
607        /// The function, such as `fs.read()`.
608        call: &'static str,
609        /// What went wrong.
610        error: FileError,
611    },
612    /// A dotenv file has a syntax error.
613    #[error("{call}: {path}:{}: {}", .error.line, .error.message)]
614    Dotenv {
615        /// The function, `env.load_file()` or `env.read()`.
616        call: &'static str,
617        /// The dotenv file.
618        path: AbsolutePath,
619        /// The line and what is wrong with it.
620        error: DotenvError,
621    },
622    /// A variable name or value cannot be part of an environment.
623    #[error("{call}: invalid variable {name:?}: {reason}")]
624    Variable {
625        /// The function, such as `env.set()`.
626        call: &'static str,
627        /// The variable's name.
628        name: String,
629        /// What is wrong with it.
630        reason: &'static str,
631    },
632    /// A value cannot be written as JSON.
633    #[error("fs.write_json(): {0}")]
634    NotJson(String),
635    /// `indent` was negative.
636    #[error("fs.write_json(): indent must be 0 or more, not {0}")]
637    Indent(i32),
638    /// A JSON number has no Starlark value.
639    #[error("fs.read_json(): the number {0} is out of range")]
640    NumberRange(String),
641    /// A JSON key has no Starlark dict key.
642    #[error("fs.read_json(): the key {0:?} cannot be a dict key")]
643    JsonKey(String),
644    /// A `run()` result was to be stored as a frozen value, which never happens,
645    /// because a result exists only while its task runs.
646    #[error("a run() result exists only while its task runs, so it cannot be stored")]
647    NotStored,
648}
649
650/// The state of the task whose program is being evaluated, reached by `run()`
651/// and the `env` and `fs` functions through the evaluator's `extra`.
652#[derive(ProvidesStaticType)]
653struct TaskState<'a> {
654    /// The task.
655    task: &'a TaskInfo,
656    /// Runs the task's steps.
657    executor: &'a dyn StepExecutor,
658    /// The caller environment, which `env.caller` and `env.inherit` read.
659    caller: &'a BTreeMap<String, String>,
660    /// The task environment, which starts empty.
661    env: Cell<BTreeMap<String, String>>,
662    /// Every file access the program makes.
663    accesses: Cell<Accesses>,
664    /// Every file the program changes.
665    changes: Cell<FileChanges>,
666    /// How each file access of the program ended, when the run notes it for the
667    /// report of `kizz run --output`, and otherwise `None`.
668    outcomes: Cell<Option<AccessOutcomes>>,
669    /// The step whose exit status `expect` did not accept, if any.
670    unexpected: Cell<Option<UnexpectedExit>>,
671    /// The number of `run()` calls that reached the executor so far, which is the
672    /// position of the next step in the task's run.
673    started: Cell<u32>,
674    /// The steps that exited with a non-zero code or were killed by a signal and
675    /// had no `expect`, in the order they ran, each with whether the program
676    /// checked its result.
677    watched: Cell<Vec<Watched>>,
678}
679
680/// A step that is unchecked unless the program checks its result before it ends:
681/// reads its `rc` or `signal`, or encodes it.
682struct Watched {
683    /// The step, as it is reported when it stays unchecked.
684    exit: UncheckedExit,
685    /// Set when the program reads the result's `rc` or `signal`, or encodes the
686    /// result; shared with the [`RunResult`] that `run()` returned for the step.
687    checked: Arc<AtomicBool>,
688}
689
690/// Marks an evaluator that loads a module, outside any task.
691#[derive(ProvidesStaticType)]
692struct LoadingModule {
693    /// The module being loaded.
694    path: AbsolutePath,
695    /// The directory of the task that loads it, against which `fs` paths resolve.
696    dir: AbsolutePath,
697    /// Every file access the module's top-level code makes.
698    accesses: Cell<Accesses>,
699    /// Every file the module's top-level code changes.
700    changes: Cell<FileChanges>,
701    /// How each file access of the module's top-level code ended, when the run
702    /// notes it, and otherwise `None`.
703    outcomes: Cell<Option<AccessOutcomes>>,
704}
705
706/// The error for `call`, a function that needs the running task, when `eval`
707/// evaluates no task.
708fn outside_task(
709    eval: &Evaluator<'_, '_, '_>,
710    call: &'static str,
711) -> starlark::Error {
712    let module = eval
713        .extra
714        .and_then(|extra| extra.downcast_ref::<LoadingModule>())
715        .map_or_else(
716            || "a module".to_owned(),
717            |loading| format!("the module {}", loading.path),
718        );
719    starlark::Error::new_other(RunError::WhileLoading { call, module })
720}
721
722/// Call `f` with the state of the task that `eval` evaluates.
723///
724/// # Errors
725///
726/// Fails when `eval` loads a module, outside any task, or when `f` fails.
727fn with_task<R>(
728    eval: &Evaluator<'_, '_, '_>,
729    call: &'static str,
730    f: impl FnOnce(&TaskState<'_>) -> Result<R, RunError>,
731) -> starlark::Result<R> {
732    let state = eval
733        .extra
734        .and_then(|extra| extra.downcast_ref::<TaskState>())
735        .ok_or_else(|| outside_task(eval, call))?;
736    f(state).map_err(starlark::Error::new_other)
737}
738
739/// Call `f` with the file operations of the task that `eval` evaluates or loads a
740/// module for, so every access and every change is recorded against that task, and
741/// the outcome of every access is noted when the run notes outcomes.
742///
743/// The accesses, the changes and the outcomes are taken out of their cells for the
744/// length of `f`, which only does file operations and reaches none of the cells,
745/// and put back after it.
746///
747/// # Errors
748///
749/// Fails when `f` fails.
750fn with_files<R>(
751    eval: &Evaluator<'_, '_, '_>,
752    call: &'static str,
753    f: impl FnOnce(&mut Files<'_>) -> Result<R, RunError>,
754) -> starlark::Result<R> {
755    let extra = eval.extra;
756    let (dir, accesses, changes, outcomes) = if let Some(state) =
757        extra.and_then(|extra| extra.downcast_ref::<TaskState>())
758    {
759        (
760            &state.task.dir,
761            &state.accesses,
762            &state.changes,
763            &state.outcomes,
764        )
765    } else if let Some(loading) = extra.and_then(|extra| extra.downcast_ref::<LoadingModule>()) {
766        (
767            &loading.dir,
768            &loading.accesses,
769            &loading.changes,
770            &loading.outcomes,
771        )
772    } else {
773        return Err(outside_task(eval, call));
774    };
775    let result = cells::update(accesses, |accesses| {
776        cells::update(changes, |changes| {
777            cells::update(outcomes, |outcomes| {
778                f(&mut Files::new(dir, accesses, changes).noting(outcomes.as_mut()))
779            })
780        })
781    });
782    result.map_err(starlark::Error::new_other)
783}
784
785/// Check that `name` and `value` can be a variable of an environment: a name that
786/// is not empty and holds no `=`, and neither holding a NUL character.
787fn check_variable(
788    call: &'static str,
789    name: &str,
790    value: &str,
791) -> Result<(), RunError> {
792    let reason = if name.is_empty() {
793        "the name is empty"
794    } else if name.contains('=') {
795        "the name contains ="
796    } else if name.contains('\0') || value.contains('\0') {
797        "it contains a NUL character"
798    } else {
799        return Ok(());
800    };
801    Err(RunError::Variable {
802        call,
803        name: name.to_owned(),
804        reason,
805    })
806}
807
808/// Read the dotenv file at `path` for `call`: its variables, or `None` when it is
809/// missing. The file is recorded as read, or probed when missing.
810fn read_dotenv(
811    files: &mut Files<'_>,
812    call: &'static str,
813    path: &str,
814) -> Result<Option<BTreeMap<String, String>>, RunError> {
815    let path = files.resolve(path);
816    let Some(bytes) = files
817        .read_bytes_if_present(&path)
818        .map_err(|error| RunError::File { call, error })?
819    else {
820        return Ok(None);
821    };
822    dotenv::parse(&String::from_utf8_lossy(&bytes))
823        .map(Some)
824        .map_err(|error| RunError::Dotenv { call, path, error })
825}
826
827/// The variables of the dotenv file at `path`, which must exist, for `call`.
828fn require_dotenv(
829    files: &mut Files<'_>,
830    call: &'static str,
831    path: &str,
832) -> Result<BTreeMap<String, String>, RunError> {
833    read_dotenv(files, call, path)?.ok_or_else(|| {
834        RunError::File {
835            call,
836            error: FileError::Io {
837                action: "cannot read",
838                path: files.resolve(path),
839                source: std::io::Error::from(ErrorKind::NotFound),
840            },
841        }
842    })
843}
844
845/// The modules one file loads, by the path its `load` statements give.
846#[derive(Default)]
847struct ModuleMap {
848    /// The frozen modules.
849    modules: HashMap<String, FrozenModule>,
850}
851
852impl FileLoader for ModuleMap {
853    fn load(
854        &self,
855        path: &str,
856    ) -> starlark::Result<FrozenModule> {
857        self.modules
858            .get(path)
859            .cloned()
860            .ok_or_else(|| starlark::Error::new_other(RunError::NotLoaded(path.to_owned())))
861    }
862}
863
864/// Prefixes each line a program prints with the task's
865/// [`TaskInfo::display_name`]: its name, else its heading, else its location.
866struct TaskPrinter<'a> {
867    /// The prefix: the task's name, else its heading, else `path/kizz.md:LINE`.
868    name: String,
869    /// Where the lines go.
870    sink: &'a dyn PrintSink,
871}
872
873impl PrintHandler for TaskPrinter<'_> {
874    fn println(
875        &self,
876        text: &str,
877    ) -> starlark::Result<()> {
878        for line in text.split('\n') {
879            self.sink.print_line(&format!("{}: {line}", self.name));
880        }
881        Ok(())
882    }
883}
884
885/// The globals of task programs and modules.
886#[starlark_module]
887fn kizz_globals(builder: &mut GlobalsBuilder) {
888    /// Run a command and return its result.
889    ///
890    /// The positional arguments are the program, then its arguments. Each is a
891    /// string, or a list or tuple of strings, lists or tuples, which expands in
892    /// place, in order and at any depth, so `[]` adds nothing. With
893    /// `expect = None`, `run()` always returns; with a list of exit codes, the task
894    /// fails when the exit code is not in it or a signal killed the command. A
895    /// non-zero exit or a signal without `expect` is unchecked unless the program
896    /// reads the result's `rc` or `signal`, or encodes the result, before it ends.
897    #[expect(
898        clippy::too_many_arguments,
899        reason = "run() takes every parameter that \"Running commands\" lists, as Starlark \
900                  keywords"
901    )]
902    fn run<'v>(
903        #[starlark(args)] argv: UnpackTuple<Value<'v>>,
904        #[starlark(require = named, default = NoneOr::None)] stdin: NoneOr<&str>,
905        #[starlark(require = named, default = NoneOr::None)] env: NoneOr<
906            UnpackDictEntries<&str, NoneOr<&str>>,
907        >,
908        #[starlark(require = named, default = NoneOr::None)] cwd: NoneOr<&str>,
909        #[starlark(require = named, default = "split")] capture: &str,
910        #[starlark(require = named, default = false)] stream: bool,
911        #[starlark(require = named, default = false)] always: bool,
912        #[starlark(require = named, default = false)] untraced: bool,
913        #[starlark(require = named, default = false)] network: bool,
914        #[starlark(require = named, default = UnpackListOrTuple::default())]
915        ignore: UnpackListOrTuple<String>,
916        #[starlark(require = named, default = UnpackListOrTuple::default())]
917        track: UnpackListOrTuple<String>,
918        #[starlark(require = named, default = false)] timestamps: bool,
919        #[starlark(require = named, default = UnpackListOrTuple::default())]
920        machine: UnpackListOrTuple<String>,
921        #[starlark(require = named, default = NoneOr::None)] expect: NoneOr<UnpackListOrTuple<i32>>,
922        eval: &mut Evaluator<'v, '_, '_>,
923    ) -> starlark::Result<Value<'v>> {
924        let Some(state) = eval
925            .extra
926            .and_then(|extra| extra.downcast_ref::<TaskState>())
927        else {
928            return Err(outside_task(eval, "run()"));
929        };
930        let argv = expand_arguments(&argv.items).map_err(starlark::Error::new_other)?;
931        if argv.is_empty() {
932            return Err(starlark::Error::new_other(RunError::NoProgram));
933        }
934        let capture = match capture {
935            "split" => CaptureMode::Split,
936            "merged" => CaptureMode::Merged,
937            other => {
938                return Err(starlark::Error::new_other(RunError::Capture(
939                    other.to_owned(),
940                )));
941            },
942        };
943        let mut machine = machine.items;
944        if let Some(unknown) = machine
945            .iter()
946            .find(|name| MachinePart::from_name(name).is_none())
947        {
948            return Err(starlark::Error::new_other(RunError::MachinePart(
949                unknown.clone(),
950            )));
951        }
952        machine.sort();
953        machine.dedup();
954        let mut step_env = cells::cloned(&state.env);
955        if let NoneOr::Other(entries) = env {
956            for (name, value) in entries.entries {
957                match value {
958                    NoneOr::Other(value) => {
959                        step_env.insert(name.to_owned(), value.to_owned());
960                    },
961                    NoneOr::None => {
962                        step_env.remove(name);
963                    },
964                }
965            }
966        }
967        let step = StepSpec {
968            argv,
969            stdin: stdin.into_option().map(str::to_owned),
970            env: step_env,
971            cwd: cwd
972                .into_option()
973                .map_or_else(|| state.task.dir.clone(), |cwd| state.task.dir.join(cwd)),
974            capture,
975            stream,
976            always,
977            untraced,
978            network,
979            ignore: ignore.items,
980            track: track.items,
981            timestamps,
982            machine,
983            expect: expect.into_option().map(|codes| codes.items),
984        };
985        let position = state.started.get();
986        state.started.set(position.saturating_add(1));
987        let outcome = state
988            .executor
989            .execute(&step)
990            .map_err(|error| starlark::Error::new_other(RunError::from(error)))?;
991        if let Some(expect) = &step.expect
992            && !matches!(outcome.termination, Termination::Exited(code) if expect.contains(&code))
993        {
994            let error = RunError::Unexpected {
995                command: step.command(),
996                termination: outcome.termination,
997            };
998            state.unexpected.set(Some(UnexpectedExit {
999                argv: step.argv,
1000                termination: outcome.termination,
1001                expect: expect.clone(),
1002                output: outcome.output,
1003            }));
1004            return Err(starlark::Error::new_other(error));
1005        }
1006        let result = RunResult::new(&outcome);
1007        if step.expect.is_none() && outcome.termination != Termination::Exited(0) {
1008            let watched = Watched {
1009                exit: UncheckedExit {
1010                    position,
1011                    argv: step.argv,
1012                    termination: outcome.termination,
1013                    output: outcome.output,
1014                    cached: outcome.cached,
1015                },
1016                checked: Arc::clone(&result.checked),
1017            };
1018            cells::update(&state.watched, |steps| steps.push(watched));
1019        }
1020        Ok(eval.heap().alloc(result))
1021    }
1022}
1023
1024/// The output of a `run()` result in the shape of its capture mode, decoded as
1025/// UTF-8 with invalid bytes replaced.
1026#[derive(Debug, Clone, PartialEq, Eq, Allocative)]
1027enum ResultOutput {
1028    /// With `capture = "split"`: standard output and standard error apart.
1029    Split {
1030        /// Standard output.
1031        stdout: String,
1032        /// Standard error.
1033        stderr: String,
1034    },
1035    /// With `capture = "merged"`: both streams in the order they were written.
1036    Merged {
1037        /// Both streams.
1038        output: String,
1039    },
1040}
1041
1042/// The value `run()` returns, of the Starlark type `run_result`: the attributes
1043/// `rc`, `signal`, `stdout` and `stderr` or `output` for the capture mode, and
1044/// `cached`, with the values a struct of them had, so `dir()`, `hasattr` and
1045/// `getattr` work as for that struct.
1046///
1047/// The value notes when the program checks it: reads `rc` or `signal`, as an
1048/// attribute or with `getattr`, or encodes the value with `json.encode` or
1049/// `fs.write_json`, also inside an encoded list or dict ("Exit codes and
1050/// failure"); `hasattr`, `dir()`, printing the value, and reading the output or
1051/// `cached` do not.
1052#[derive(Debug, ProvidesStaticType, Allocative)]
1053struct RunResult {
1054    /// The exit code, or `None` when a signal killed the command.
1055    rc: Option<i32>,
1056    /// The signal that killed the command, or `None` when it exited.
1057    signal: Option<i32>,
1058    /// The captured output.
1059    output: ResultOutput,
1060    /// Whether the result came from the cache.
1061    cached: bool,
1062    /// Set once the program reads `rc` or `signal` or encodes the value; shared with
1063    /// the runtime's [`Watched`] entry of the step, when it has one.
1064    checked: Arc<AtomicBool>,
1065}
1066
1067impl RunResult {
1068    /// The result of a step that ended as `outcome`, not checked yet.
1069    fn new(outcome: &StepOutcome) -> Self {
1070        let text = |bytes: &[u8]| String::from_utf8_lossy(bytes).into_owned();
1071        Self {
1072            rc: outcome.termination.code(),
1073            signal: outcome.termination.signal(),
1074            output: match &outcome.output {
1075                CapturedOutput::Split { stdout, stderr } => {
1076                    ResultOutput::Split {
1077                        stdout: text(stdout),
1078                        stderr: text(stderr),
1079                    }
1080                },
1081                CapturedOutput::Merged { output } => {
1082                    ResultOutput::Merged {
1083                        output: text(output),
1084                    }
1085                },
1086            },
1087            cached: outcome.cached,
1088            checked: Arc::new(AtomicBool::new(false)),
1089        }
1090    }
1091
1092    /// The names of the attributes, in the order the struct had them:
1093    /// [`SPLIT_RESULT_ATTRIBUTES`] or [`MERGED_RESULT_ATTRIBUTES`], for the capture
1094    /// mode.
1095    const fn attributes(&self) -> &'static [&'static str] {
1096        match self.output {
1097            ResultOutput::Split { .. } => SPLIT_RESULT_ATTRIBUTES,
1098            ResultOutput::Merged { .. } => MERGED_RESULT_ATTRIBUTES,
1099        }
1100    }
1101
1102    /// The value of the attribute `name`, or `None` for a name that
1103    /// [`Self::attributes`] lacks: the constants decide which attributes a result
1104    /// has, for `get_attr` and for the JSON encoding alike. Reading `rc` or `signal`
1105    /// checks the result.
1106    fn attribute(
1107        &self,
1108        name: &str,
1109    ) -> Option<AttributeValue<'_>> {
1110        if !self.attributes().contains(&name) {
1111            return None;
1112        }
1113        match (name, &self.output) {
1114            ("rc", _) => {
1115                self.checked.store(true, Ordering::Relaxed);
1116                Some(AttributeValue::Int(self.rc))
1117            },
1118            ("signal", _) => {
1119                self.checked.store(true, Ordering::Relaxed);
1120                Some(AttributeValue::Int(self.signal))
1121            },
1122            ("stdout", ResultOutput::Split { stdout, .. }) => Some(AttributeValue::Text(stdout)),
1123            ("stderr", ResultOutput::Split { stderr, .. }) => Some(AttributeValue::Text(stderr)),
1124            ("output", ResultOutput::Merged { output }) => Some(AttributeValue::Text(output)),
1125            ("cached", _) => Some(AttributeValue::Bool(self.cached)),
1126            _ => None,
1127        }
1128    }
1129
1130    /// Whether `other` has the same exit status, output and `cached`, whether or
1131    /// not either was checked.
1132    fn same_values(
1133        &self,
1134        other: &Self,
1135    ) -> bool {
1136        self.rc == other.rc
1137            && self.signal == other.signal
1138            && self.output == other.output
1139            && self.cached == other.cached
1140    }
1141}
1142
1143impl fmt::Display for RunResult {
1144    fn fmt(
1145        &self,
1146        f: &mut fmt::Formatter<'_>,
1147    ) -> fmt::Result {
1148        /// An optional integer as Starlark shows it.
1149        fn int(value: Option<i32>) -> String {
1150            value.map_or_else(|| "None".to_owned(), |value| value.to_string())
1151        }
1152        write!(
1153            f,
1154            "run_result(rc={}, signal={}, ",
1155            int(self.rc),
1156            int(self.signal)
1157        )?;
1158        match &self.output {
1159            ResultOutput::Split { stdout, stderr } => {
1160                write!(f, "stdout={stdout:?}, stderr={stderr:?}, ")?;
1161            },
1162            ResultOutput::Merged { output } => write!(f, "output={output:?}, ")?,
1163        }
1164        write!(f, "cached={})", if self.cached { "True" } else { "False" })
1165    }
1166}
1167
1168impl<'v> AllocValue<'v> for RunResult {
1169    fn alloc_value(
1170        self,
1171        heap: Heap<'v>,
1172    ) -> Value<'v> {
1173        heap.alloc_simple(self)
1174    }
1175}
1176
1177/// The value of one attribute of a `run()` result, which `get_attr` turns into a
1178/// Starlark value and the JSON encoding writes.
1179#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1180enum AttributeValue<'a> {
1181    /// An integer or `None`, such as `rc` and `signal`.
1182    Int(Option<i32>),
1183    /// A string, such as `stdout`.
1184    Text(&'a str),
1185    /// A boolean, such as `cached`.
1186    Bool(bool),
1187}
1188
1189/// The JSON encoding of `json.encode` and `fs.write_json`: an object of the
1190/// attributes of [`RunResult::attributes`], in their order, `rc`, `signal`,
1191/// `stdout` and `stderr` or `output`, and `cached`, with the same values, as the
1192/// struct that `run()` returned before encoded. Encoding the value checks it,
1193/// because its exit status then leaves the program on purpose ("Exit codes and
1194/// failure"). A listed name without a value is an error, never a panic.
1195impl serde::Serialize for RunResult {
1196    fn serialize<S: serde::Serializer>(
1197        &self,
1198        serializer: S,
1199    ) -> Result<S::Ok, S::Error> {
1200        use serde::ser::{Error as _, SerializeMap as _};
1201
1202        self.checked.store(true, Ordering::Relaxed);
1203        let mut map = serializer.serialize_map(Some(self.attributes().len()))?;
1204        for &name in self.attributes() {
1205            match self.attribute(name) {
1206                Some(AttributeValue::Int(value)) => map.serialize_entry(name, &value)?,
1207                Some(AttributeValue::Text(value)) => map.serialize_entry(name, value)?,
1208                Some(AttributeValue::Bool(value)) => map.serialize_entry(name, &value)?,
1209                None => {
1210                    return Err(S::Error::custom(format!(
1211                        "the run() result has no value for its attribute {name}"
1212                    )));
1213                },
1214            }
1215        }
1216        map.end()
1217    }
1218}
1219
1220/// A `run()` result exists only while its task runs and is never stored as a
1221/// frozen value, so this storage, which is not JSON, refuses it.
1222impl StarlarkSerialize for RunResult {
1223    fn starlark_serialize(
1224        &self,
1225        _ctx: &mut dyn StarlarkSerializeContext,
1226    ) -> starlark::Result<()> {
1227        Err(starlark::Error::new_other(RunError::NotStored))
1228    }
1229}
1230
1231/// A `run()` result is never stored, so it is never read back from storage either.
1232impl StarlarkDeserialize for RunResult {
1233    fn starlark_deserialize(
1234        _ctx: &mut dyn StarlarkDeserializeContext<'_>
1235    ) -> starlark::Result<Self> {
1236        Err(starlark::Error::new_other(RunError::NotStored))
1237    }
1238}
1239
1240#[starlark_value(type = "run_result")]
1241impl<'v> StarlarkValue<'v> for RunResult {
1242    fn get_attr(
1243        &self,
1244        attribute: &str,
1245        heap: Heap<'v>,
1246    ) -> Option<Value<'v>> {
1247        self.attribute(attribute).map(|value| {
1248            match value {
1249                AttributeValue::Int(value) => {
1250                    value.map_or_else(Value::new_none, |value| heap.alloc(value))
1251                },
1252                AttributeValue::Text(value) => heap.alloc(value),
1253                AttributeValue::Bool(value) => Value::new_bool(value),
1254            }
1255        })
1256    }
1257
1258    fn has_attr(
1259        &self,
1260        attribute: &str,
1261        _heap: Heap<'v>,
1262    ) -> bool {
1263        self.attributes().contains(&attribute)
1264    }
1265
1266    fn dir_attr(&self) -> Vec<String> {
1267        self.attributes()
1268            .iter()
1269            .map(|&name| name.to_owned())
1270            .collect()
1271    }
1272
1273    fn equals(
1274        &self,
1275        other: Value<'v>,
1276    ) -> starlark::Result<bool> {
1277        Ok(other
1278            .downcast_ref::<Self>()
1279            .is_some_and(|other| self.same_values(other)))
1280    }
1281}
1282
1283/// The `env` functions, which read the caller environment and dotenv files and
1284/// change the task environment.
1285#[starlark_module]
1286fn env_functions(builder: &mut GlobalsBuilder) {
1287    /// Read the variable `name` from the caller environment, or `default` when it
1288    /// is unset, without changing the task environment.
1289    fn caller<'v>(
1290        #[starlark(require = pos)] name: &str,
1291        default: Option<Value<'v>>,
1292        eval: &mut Evaluator<'v, '_, '_>,
1293    ) -> starlark::Result<Value<'v>> {
1294        let value = with_task(eval, "env.caller()", |state| {
1295            Ok(state.caller.get(name).cloned())
1296        })?;
1297        Ok(value.map_or_else(
1298            || default.unwrap_or_else(Value::new_none),
1299            |value| eval.heap().alloc(value),
1300        ))
1301    }
1302
1303    /// Copy the named variables from the caller environment into the task
1304    /// environment, skipping the unset ones.
1305    fn inherit(
1306        #[starlark(args)] names: UnpackTuple<&str>,
1307        eval: &mut Evaluator<'_, '_, '_>,
1308    ) -> starlark::Result<NoneType> {
1309        with_task(eval, "env.inherit()", |state| {
1310            cells::update(&state.env, |env| {
1311                for name in names.items {
1312                    if let Some(value) = state.caller.get(name) {
1313                        env.insert(name.to_owned(), value.clone());
1314                    }
1315                }
1316            });
1317            Ok(NoneType)
1318        })
1319    }
1320
1321    /// Read the dotenv file at `path`, fill in `defaults` for the variables it does
1322    /// not set, add the result to the task environment, and return it. The file is
1323    /// recorded as a dependency of the task; with `required = False`, a missing
1324    /// file means only the defaults apply.
1325    fn load_file<'v>(
1326        #[starlark(require = pos)] path: &str,
1327        #[starlark(default = UnpackDictEntries::default())] defaults: UnpackDictEntries<&str, &str>,
1328        #[starlark(default = true)] required: bool,
1329        eval: &mut Evaluator<'v, '_, '_>,
1330    ) -> starlark::Result<Value<'v>> {
1331        let call = "env.load_file()";
1332        let vars = with_task(eval, call, |state| {
1333            let mut vars = BTreeMap::new();
1334            for (name, value) in defaults.entries {
1335                check_variable(call, name, value)?;
1336                vars.insert(name.to_owned(), value.to_owned());
1337            }
1338            let file = cells::update(&state.accesses, |accesses| {
1339                cells::update(&state.changes, |changes| {
1340                    cells::update(&state.outcomes, |outcomes| {
1341                        let mut files = Files::new(&state.task.dir, accesses, changes)
1342                            .noting(outcomes.as_mut());
1343                        if required {
1344                            require_dotenv(&mut files, call, path).map(Some)
1345                        } else {
1346                            read_dotenv(&mut files, call, path)
1347                        }
1348                    })
1349                })
1350            })?;
1351            vars.extend(file.unwrap_or_default());
1352            cells::update(&state.env, |env| env.extend(vars.clone()));
1353            Ok(vars)
1354        })?;
1355        Ok(eval.heap().alloc(vars))
1356    }
1357
1358    /// Read the dotenv file at `path` into a dict, without changing the task
1359    /// environment.
1360    fn read<'v>(
1361        #[starlark(require = pos)] path: &str,
1362        eval: &mut Evaluator<'v, '_, '_>,
1363    ) -> starlark::Result<Value<'v>> {
1364        let vars = with_files(eval, "env.read()", |files| {
1365            require_dotenv(files, "env.read()", path)
1366        })?;
1367        Ok(eval.heap().alloc(vars))
1368    }
1369
1370    /// Set the variable `name` of the task environment to `value`.
1371    fn set(
1372        #[starlark(require = pos)] name: &str,
1373        #[starlark(require = pos)] value: &str,
1374        eval: &mut Evaluator<'_, '_, '_>,
1375    ) -> starlark::Result<NoneType> {
1376        with_task(eval, "env.set()", |state| {
1377            check_variable("env.set()", name, value)?;
1378            cells::update(&state.env, |env| {
1379                env.insert(name.to_owned(), value.to_owned());
1380            });
1381            Ok(NoneType)
1382        })
1383    }
1384
1385    /// Set every variable of the dict `values` in the task environment.
1386    fn update(
1387        #[starlark(require = pos)] values: UnpackDictEntries<&str, &str>,
1388        eval: &mut Evaluator<'_, '_, '_>,
1389    ) -> starlark::Result<NoneType> {
1390        with_task(eval, "env.update()", |state| {
1391            for (name, value) in &values.entries {
1392                check_variable("env.update()", name, value)?;
1393            }
1394            cells::update(&state.env, |env| {
1395                env.extend(
1396                    values
1397                        .entries
1398                        .iter()
1399                        .map(|&(name, value)| (name.to_owned(), value.to_owned())),
1400                );
1401            });
1402            Ok(NoneType)
1403        })
1404    }
1405
1406    /// Remove the variable `name` from the task environment, if it is set.
1407    fn unset(
1408        #[starlark(require = pos)] name: &str,
1409        eval: &mut Evaluator<'_, '_, '_>,
1410    ) -> starlark::Result<NoneType> {
1411        with_task(eval, "env.unset()", |state| {
1412            cells::update(&state.env, |env| {
1413                env.remove(name);
1414            });
1415            Ok(NoneType)
1416        })
1417    }
1418
1419    /// Read the variable `name` from the task environment, or `default` when it
1420    /// is unset.
1421    fn get<'v>(
1422        #[starlark(require = pos)] name: &str,
1423        default: Option<Value<'v>>,
1424        eval: &mut Evaluator<'v, '_, '_>,
1425    ) -> starlark::Result<Value<'v>> {
1426        let value = with_task(eval, "env.get()", |state| {
1427            Ok(cells::update(&state.env, |env| env.get(name).cloned()))
1428        })?;
1429        Ok(value.map_or_else(
1430            || default.unwrap_or_else(Value::new_none),
1431            |value| eval.heap().alloc(value),
1432        ))
1433    }
1434
1435    /// The task environment as a new dict.
1436    fn dict<'v>(eval: &mut Evaluator<'v, '_, '_>) -> starlark::Result<Value<'v>> {
1437        let env = with_task(eval, "env.dict()", |state| Ok(cells::cloned(&state.env)))?;
1438        Ok(eval.heap().alloc(env))
1439    }
1440
1441    /// Empty the task environment.
1442    fn clear(eval: &mut Evaluator<'_, '_, '_>) -> starlark::Result<NoneType> {
1443        with_task(eval, "env.clear()", |state| {
1444            cells::update(&state.env, BTreeMap::clear);
1445            Ok(NoneType)
1446        })
1447    }
1448}
1449
1450/// The `fs` functions, which read and write files and inspect the file system.
1451/// Paths are relative to the task directory, and every access is recorded.
1452#[starlark_module]
1453fn fs_functions(builder: &mut GlobalsBuilder) {
1454    /// The text of the file at `path`, with bytes that are not valid UTF-8
1455    /// replaced.
1456    fn read(
1457        #[starlark(require = pos)] path: &str,
1458        eval: &mut Evaluator<'_, '_, '_>,
1459    ) -> starlark::Result<String> {
1460        with_files(eval, "fs.read()", |files| {
1461            files.read_text(path).map_err(|error| {
1462                RunError::File {
1463                    call: "fs.read()",
1464                    error,
1465                }
1466            })
1467        })
1468    }
1469
1470    /// Write `text` to the file at `path`, creating parent directories, unless the
1471    /// file already holds exactly `text`.
1472    fn write(
1473        #[starlark(require = pos)] path: &str,
1474        #[starlark(require = pos)] text: &str,
1475        eval: &mut Evaluator<'_, '_, '_>,
1476    ) -> starlark::Result<NoneType> {
1477        with_files(eval, "fs.write()", |files| {
1478            files
1479                .write_bytes(path, text.as_bytes())
1480                .map(|_| NoneType)
1481                .map_err(|error| {
1482                    RunError::File {
1483                        call: "fs.write()",
1484                        error,
1485                    }
1486                })
1487        })
1488    }
1489
1490    /// The JSON value in the file at `path`, as a Starlark value.
1491    fn read_json<'v>(
1492        #[starlark(require = pos)] path: &str,
1493        eval: &mut Evaluator<'v, '_, '_>,
1494    ) -> starlark::Result<Value<'v>> {
1495        let value = with_files(eval, "fs.read_json()", |files| {
1496            files.read_json(path).map_err(|error| {
1497                RunError::File {
1498                    call: "fs.read_json()",
1499                    error,
1500                }
1501            })
1502        })?;
1503        json_value(eval.heap(), &value).map_err(starlark::Error::new_other)
1504    }
1505
1506    /// Write `value` to the file at `path` as stable JSON, with sorted keys,
1507    /// `indent` spaces per level, and a trailing newline, unless the file already
1508    /// holds exactly that text.
1509    fn write_json<'v>(
1510        #[starlark(require = pos)] path: &str,
1511        #[starlark(require = pos)] value: Value<'v>,
1512        #[starlark(default = 2)] indent: i32,
1513        eval: &mut Evaluator<'v, '_, '_>,
1514    ) -> starlark::Result<NoneType> {
1515        let indent = usize::try_from(indent)
1516            .map_err(|_| starlark::Error::new_other(RunError::Indent(indent)))?;
1517        let json = value
1518            .to_json_value()
1519            .map_err(|error| starlark::Error::new_other(RunError::NotJson(error.to_string())))?;
1520        with_files(eval, "fs.write_json()", |files| {
1521            files
1522                .write_json(path, &json, indent)
1523                .map(|_| NoneType)
1524                .map_err(|error| {
1525                    RunError::File {
1526                        call: "fs.write_json()",
1527                        error,
1528                    }
1529                })
1530        })
1531    }
1532
1533    /// Whether `path` exists, following symbolic links.
1534    fn exists(
1535        #[starlark(require = pos)] path: &str,
1536        eval: &mut Evaluator<'_, '_, '_>,
1537    ) -> starlark::Result<bool> {
1538        with_files(eval, "fs.exists()", |files| Ok(files.exists(path)))
1539    }
1540
1541    /// The names of the entries of the directory at `path`, sorted.
1542    fn list(
1543        #[starlark(require = pos, default = ".")] path: &str,
1544        eval: &mut Evaluator<'_, '_, '_>,
1545    ) -> starlark::Result<Vec<String>> {
1546        with_files(eval, "fs.list()", |files| {
1547            files.list(path).map_err(|error| {
1548                RunError::File {
1549                    call: "fs.list()",
1550                    error,
1551                }
1552            })
1553        })
1554    }
1555
1556    /// The paths that match the glob `pattern`, sorted.
1557    fn glob(
1558        #[starlark(require = pos)] pattern: &str,
1559        eval: &mut Evaluator<'_, '_, '_>,
1560    ) -> starlark::Result<Vec<String>> {
1561        with_files(eval, "fs.glob()", |files| {
1562            files.glob(pattern).map_err(|error| {
1563                RunError::File {
1564                    call: "fs.glob()",
1565                    error,
1566                }
1567            })
1568        })
1569    }
1570}
1571
1572/// The Starlark value of the JSON `value`: `None`, a bool, an int for integers
1573/// that fit in 64 bits, a float for other numbers, a string, a list, or a dict.
1574fn json_value<'v>(
1575    heap: Heap<'v>,
1576    value: &serde_json::Value,
1577) -> Result<Value<'v>, RunError> {
1578    Ok(match value {
1579        serde_json::Value::Null => Value::new_none(),
1580        serde_json::Value::Bool(value) => Value::new_bool(*value),
1581        serde_json::Value::Number(number) => {
1582            if let Some(int) = number.as_i64() {
1583                heap.alloc(int)
1584            } else if let Some(int) = number.as_u64() {
1585                heap.alloc(int)
1586            } else if let Some(float) = number.as_f64().filter(|float| float.is_finite()) {
1587                heap.alloc(float)
1588            } else {
1589                return Err(RunError::NumberRange(number.to_string()));
1590            }
1591        },
1592        serde_json::Value::String(text) => heap.alloc(text.as_str()),
1593        serde_json::Value::Array(items) => {
1594            let items = items
1595                .iter()
1596                .map(|item| json_value(heap, item))
1597                .collect::<Result<Vec<_>, _>>()?;
1598            heap.alloc(items)
1599        },
1600        serde_json::Value::Object(members) => {
1601            // Each key is hashed with `get_hashed`, whose error is returned, where
1602            // `AllocDict` "panics if a key is not hashable" (its documentation).
1603            let mut map = SmallMap::new();
1604            for (key, member) in members {
1605                let hashed = heap
1606                    .alloc(key.as_str())
1607                    .get_hashed()
1608                    .map_err(|_not_hashed| RunError::JsonKey(key.clone()))?;
1609                map.insert_hashed(hashed, json_value(heap, member)?);
1610            }
1611            heap.alloc(Dict::new(map))
1612        },
1613    })
1614}
1615
1616/// The globals of task programs and modules.
1617fn globals() -> Globals {
1618    GlobalsBuilder::extended_by(&[LibraryExtension::Json, LibraryExtension::Print])
1619        .with(kizz_globals)
1620        .with_namespace("env", env_functions)
1621        .with_namespace("fs", fs_functions)
1622        .build()
1623}
1624
1625/// The name of the value that describes the running task, which every task
1626/// program's module holds besides the globals.
1627pub const TASK_VALUE: &str = "task";
1628
1629/// The members of [`TASK_VALUE`], in the order the value holds them, under which
1630/// the runtime sets the values that describe the running task.
1631pub const TASK_MEMBERS: [&str; 8] = [
1632    "dir", "file", "line", "name", "heading", "targets", "selected", "args",
1633];
1634
1635/// The attributes of a `run()` result with `capture = "split"`, in the order the
1636/// struct that `run()` returned before had them.
1637pub const SPLIT_RESULT_ATTRIBUTES: &[&str] = &["rc", "signal", "stdout", "stderr", "cached"];
1638
1639/// The attributes of a `run()` result with `capture = "merged"`, in the order the
1640/// struct that `run()` returned before had them.
1641pub const MERGED_RESULT_ATTRIBUTES: &[&str] = &["rc", "signal", "output", "cached"];
1642
1643/// What a name that task programs use is, which decides how documentation writes
1644/// it: a function with `()`, such as `run()`, and a module or a value without, such
1645/// as `env` or `task.args`.
1646#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
1647pub enum NameKind {
1648    /// A function, such as `run` or `env.inherit`.
1649    Function,
1650    /// A module of members, such as `env` or `task`.
1651    Module,
1652    /// A value, such as `task.args`.
1653    Value,
1654}
1655
1656/// A name that task programs use beyond Starlark's standard globals.
1657#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
1658pub struct ProgramName {
1659    /// The name, after its module and a `.` for a member, such as `run`, `env` or
1660    /// `env.inherit`.
1661    pub name: String,
1662    /// What the name is.
1663    pub kind: NameKind,
1664}
1665
1666impl ProgramName {
1667    /// The name as documentation writes it: `run()` or `env.inherit()` for a
1668    /// function, and `env` or `task.args` for a module or a value.
1669    #[must_use]
1670    pub fn written(&self) -> String {
1671        match self.kind {
1672            NameKind::Function => format!("{}()", self.name),
1673            NameKind::Module | NameKind::Value => self.name.clone(),
1674        }
1675    }
1676}
1677
1678/// Everything that task programs use beyond Starlark's standard globals, read from
1679/// the runtime itself, so that the documentation can be checked against it.
1680#[derive(Debug, Clone, PartialEq, Eq, Default)]
1681pub struct ProgramNames {
1682    /// The globals that kizz adds to Starlark's standard ones, [`TASK_VALUE`]
1683    /// included, sorted.
1684    pub globals: Vec<ProgramName>,
1685    /// The members of the modules among the globals, `task`'s included, sorted.
1686    pub members: Vec<ProgramName>,
1687    /// The parameters of `run()`, in the order of its signature, the positional
1688    /// arguments first.
1689    pub run_parameters: Vec<String>,
1690    /// The attributes of a `run()` result in either capture mode, each once.
1691    pub result_attributes: Vec<String>,
1692}
1693
1694/// What `item`, the documentation of a global or a member, says the name is.
1695const fn name_kind(item: &DocItem) -> NameKind {
1696    match item {
1697        DocItem::Module(_) => NameKind::Module,
1698        DocItem::Member(DocMember::Function(_)) => NameKind::Function,
1699        DocItem::Type(_) | DocItem::Member(DocMember::Property(_)) => NameKind::Value,
1700    }
1701}
1702
1703/// The names of the parameters of `function`, in the order of its signature.
1704fn parameter_names(function: &DocFunction) -> Vec<String> {
1705    let params = &function.params;
1706    params
1707        .pos_only
1708        .iter()
1709        .chain(&params.pos_or_named)
1710        .chain(&params.args)
1711        .chain(&params.named_only)
1712        .chain(&params.kwargs)
1713        .map(|param| param.name.clone())
1714        .collect()
1715}
1716
1717/// Everything that task programs use beyond Starlark's standard globals: the
1718/// globals of task programs that the standard ones lack, with the members of each
1719/// module, `run()`'s parameters from its signature, `task` with [`TASK_MEMBERS`],
1720/// and the result's attributes from [`SPLIT_RESULT_ATTRIBUTES`] and
1721/// [`MERGED_RESULT_ATTRIBUTES`].
1722#[must_use]
1723pub fn program_names() -> ProgramNames {
1724    let standard = GlobalsBuilder::standard().build();
1725    let standard: Vec<&str> = standard.iter().map(|(name, _value)| name).collect();
1726    let mut names = ProgramNames::default();
1727    for (name, item) in globals().documentation().members {
1728        if standard.contains(&name.as_str()) {
1729            continue;
1730        }
1731        if let DocItem::Module(module) = &item {
1732            for (member, member_item) in &module.members {
1733                names.members.push(ProgramName {
1734                    name: format!("{name}.{member}"),
1735                    kind: name_kind(member_item),
1736                });
1737            }
1738        }
1739        if let DocItem::Member(DocMember::Function(function)) = &item
1740            && name == "run"
1741        {
1742            names.run_parameters = parameter_names(function);
1743        }
1744        names.globals.push(ProgramName {
1745            kind: name_kind(&item),
1746            name,
1747        });
1748    }
1749    names.globals.push(ProgramName {
1750        name: TASK_VALUE.to_owned(),
1751        kind: NameKind::Module,
1752    });
1753    names.members.extend(TASK_MEMBERS.iter().map(|member| {
1754        ProgramName {
1755            name: format!("{TASK_VALUE}.{member}"),
1756            kind: NameKind::Value,
1757        }
1758    }));
1759    names.globals.sort();
1760    names.members.sort();
1761    for attribute in SPLIT_RESULT_ATTRIBUTES
1762        .iter()
1763        .chain(MERGED_RESULT_ATTRIBUTES)
1764    {
1765        if !names
1766            .result_attributes
1767            .iter()
1768            .any(|known| known == attribute)
1769        {
1770            names.result_attributes.push((*attribute).to_owned());
1771        }
1772    }
1773    names
1774}
1775
1776/// Set [`TASK_VALUE`] in `module` to the values that describe `task`, under the
1777/// names of [`TASK_MEMBERS`]: `task.name` is the name that its `name=` option
1778/// gives, or `None`, `task.heading` its heading, or `None`, and `task.args` its
1779/// arguments.
1780fn set_task_value(
1781    module: &Module<'_>,
1782    task: &TaskInfo,
1783) {
1784    let heap = module.heap();
1785    let optional = |text: Option<&str>| text.map_or_else(Value::new_none, |text| heap.alloc(text));
1786    let values = [
1787        heap.alloc(task.dir.to_string()),
1788        heap.alloc(task.file.to_string()),
1789        heap.alloc(task.line),
1790        optional(task.name.as_deref()),
1791        optional(task.heading.as_deref()),
1792        heap.alloc(task.targets.clone()),
1793        heap.alloc(task.selected.clone()),
1794        heap.alloc(task.args.clone()),
1795    ];
1796    let value = heap.alloc(AllocStruct(TASK_MEMBERS.into_iter().zip(values)));
1797    module.set(TASK_VALUE, value);
1798}
1799
1800/// The directory that holds `path`, or `path` itself for the root.
1801fn parent_dir(path: &AbsolutePath) -> AbsolutePath {
1802    path.as_path()
1803        .parent()
1804        .and_then(|parent| AbsolutePath::new(parent).ok())
1805        .unwrap_or_else(|| path.clone())
1806}
1807
1808/// Loads the modules of one task program, depth first.
1809struct ModuleLoader<'a> {
1810    /// The task whose program is loaded.
1811    task: &'a TaskInfo,
1812    /// The globals.
1813    globals: &'a Globals,
1814    /// Where module `print` output goes.
1815    printer: &'a TaskPrinter<'a>,
1816    /// Every module read, and every module path found missing.
1817    accesses: Accesses,
1818    /// Every file the modules' top-level code changed.
1819    changes: FileChanges,
1820    /// How each module read and each file access of the modules' top-level code
1821    /// ended, when the run notes it, and otherwise `None`.
1822    outcomes: Option<AccessOutcomes>,
1823    /// The modules loaded so far, by absolute path.
1824    loaded: HashMap<AbsolutePath, FrozenModule>,
1825    /// The modules being loaded, outermost first, to find load cycles.
1826    loading: Vec<AbsolutePath>,
1827    /// The path and source of each loaded module, in the order loading finished.
1828    sources: Vec<(AbsolutePath, String)>,
1829}
1830
1831impl ModuleLoader<'_> {
1832    /// Load every module that `ast`, in the file `from` in `dir`, loads.
1833    fn load_imports(
1834        &mut self,
1835        ast: &AstModule,
1836        dir: &AbsolutePath,
1837        from: &str,
1838    ) -> Result<ModuleMap, TaskFailure> {
1839        let ids: Vec<String> = ast
1840            .loads()
1841            .iter()
1842            .map(|load| load.module_id.to_owned())
1843            .collect();
1844        let mut imports = ModuleMap::default();
1845        for id in ids {
1846            let module = self.load_module(&dir.join(&id), &id, from)?;
1847            imports.modules.insert(id, module);
1848        }
1849        Ok(imports)
1850    }
1851
1852    /// Load the module at `path`, which the file `from` loads as `id`.
1853    fn load_module(
1854        &mut self,
1855        path: &AbsolutePath,
1856        id: &str,
1857        from: &str,
1858    ) -> Result<FrozenModule, TaskFailure> {
1859        if let Some(module) = self.loaded.get(path) {
1860            return Ok(module.clone());
1861        }
1862        if self.loading.contains(path) {
1863            return Err(TaskFailure::program(format!(
1864                "{from}: load(\"{id}\"): the module {path} loads itself, directly or indirectly"
1865            )));
1866        }
1867        let source = match fs::read_to_string(path) {
1868            Ok(source) => {
1869                self.record(path, AccessKind::Read, None);
1870                source
1871            },
1872            Err(error) => {
1873                let kind = if error.kind() == ErrorKind::NotFound {
1874                    AccessKind::Probe
1875                } else {
1876                    AccessKind::Read
1877                };
1878                self.record(path, kind, Some(&error));
1879                return Err(TaskFailure::program(format!(
1880                    "{from}: load(\"{id}\"): cannot read {path}: {error}"
1881                )));
1882            },
1883        };
1884        let name = path.to_string();
1885        let ast = AstModule::parse(&name, source.clone(), &Dialect::Extended)
1886            .map_err(TaskFailure::program)?;
1887        self.loading.push(path.clone());
1888        let imports = self.load_imports(&ast, &parent_dir(path), &name);
1889        self.loading.pop();
1890        let imports = imports?;
1891        let module = evaluate_module(
1892            ast,
1893            path,
1894            &imports,
1895            self.task,
1896            self.globals,
1897            self.printer,
1898            &mut self.accesses,
1899            &mut self.changes,
1900            self.outcomes.as_mut(),
1901        )?;
1902        self.sources.push((path.clone(), source));
1903        self.loaded.insert(path.clone(), module.clone());
1904        Ok(module)
1905    }
1906
1907    /// Record that loading touched the module at `path` in the way `kind` names,
1908    /// and note that the read failed with `error`, or succeeded when it is `None`,
1909    /// when the run notes outcomes.
1910    fn record(
1911        &mut self,
1912        path: &AbsolutePath,
1913        kind: AccessKind,
1914        error: Option<&io::Error>,
1915    ) {
1916        if let Some(outcomes) = &mut self.outcomes {
1917            outcomes.note(path.clone(), kind, error);
1918        }
1919        self.accesses.record(path.clone(), kind);
1920    }
1921}
1922
1923/// Evaluate and freeze one module, outside any task, recording the file accesses
1924/// of its top-level code in `accesses`, the files it changed in `changes`, and,
1925/// when `outcomes` is `Some`, how each access ended in it.
1926#[expect(
1927    clippy::too_many_arguments,
1928    reason = "each argument is a separate part of the loading context"
1929)]
1930fn evaluate_module(
1931    ast: AstModule,
1932    path: &AbsolutePath,
1933    imports: &ModuleMap,
1934    task: &TaskInfo,
1935    globals: &Globals,
1936    printer: &TaskPrinter<'_>,
1937    accesses: &mut Accesses,
1938    changes: &mut FileChanges,
1939    outcomes: Option<&mut AccessOutcomes>,
1940) -> Result<FrozenModule, TaskFailure> {
1941    let marker = LoadingModule {
1942        path: path.clone(),
1943        dir: task.dir.clone(),
1944        accesses: Cell::new(Accesses::new()),
1945        changes: Cell::new(FileChanges::new()),
1946        outcomes: Cell::new(outcomes.is_some().then(AccessOutcomes::new)),
1947    };
1948    let result = Module::with_temp_heap(|module| {
1949        set_task_value(&module, task);
1950        {
1951            let mut eval = Evaluator::new(&module);
1952            eval.set_loader(imports);
1953            eval.set_print_handler(printer);
1954            eval.extra = Some(&marker);
1955            eval.eval_module(ast, globals)
1956                .map_err(TaskFailure::program)?;
1957        }
1958        module.freeze().map_err(|error| {
1959            TaskFailure::program(format!(
1960                "cannot freeze the module {path}: {}",
1961                error.err_msg
1962            ))
1963        })
1964    });
1965    accesses.merge(marker.accesses.into_inner());
1966    changes.merge(marker.changes.into_inner());
1967    if let (Some(outcomes), Some(noted)) = (outcomes, marker.outcomes.into_inner()) {
1968        outcomes.merge(noted);
1969    }
1970    result
1971}
1972
1973/// Hash one length-prefixed field.
1974fn hash_field(
1975    hasher: &mut blake3::Hasher,
1976    bytes: &[u8],
1977) {
1978    let len = u64::try_from(bytes.len()).unwrap_or(u64::MAX);
1979    hasher.update(&len.to_le_bytes());
1980    hasher.update(bytes);
1981}
1982
1983/// The parts of a task program and the hash of each, so explanations can say
1984/// whether the block or a named loaded module changed.
1985#[derive(Debug, Clone, PartialEq, Eq, Default)]
1986pub struct ProgramParts {
1987    /// The BLAKE3 hash of the block's source.
1988    pub block: [u8; 32],
1989    /// The absolute path of every module the block loads, directly or indirectly,
1990    /// with the BLAKE3 hash of its source, sorted by path.
1991    pub modules: Vec<(PathBuf, [u8; 32])>,
1992}
1993
1994/// The result of [`TaskProgram::load`] and [`TaskProgram::load_noting`].
1995#[derive(Debug)]
1996pub struct ProgramLoad {
1997    /// Every module the task read and every module path it found missing, with the
1998    /// file accesses of the modules' top-level code.
1999    pub accesses: Accesses,
2000    /// Every file the modules' top-level code changed through `fs.write` and
2001    /// `fs.write_json`, in the order it first changed each.
2002    pub changes: FileChanges,
2003    /// How each of those accesses ended, when the load noted it, and otherwise
2004    /// `None`.
2005    pub outcomes: Option<AccessOutcomes>,
2006    /// The loaded program, or why it could not be loaded.
2007    pub program: Result<TaskProgram, TaskFailure>,
2008}
2009
2010/// A task program whose modules are loaded, ready to run.
2011pub struct TaskProgram {
2012    /// The task.
2013    task: TaskInfo,
2014    /// The parsed block.
2015    ast: AstModule,
2016    /// The modules the block loads.
2017    imports: ModuleMap,
2018    /// The hash of the block and every module it loads.
2019    hash: ProgramHash,
2020    /// The hashes of the block and of each module.
2021    parts: ProgramParts,
2022    /// Whether its run notes how each file access ended, as the load did.
2023    noting: bool,
2024}
2025
2026impl fmt::Debug for TaskProgram {
2027    fn fmt(
2028        &self,
2029        f: &mut fmt::Formatter<'_>,
2030    ) -> fmt::Result {
2031        f.debug_struct("TaskProgram")
2032            .field("task", &self.task)
2033            .field("hash", &self.hash)
2034            .field("parts", &self.parts)
2035            .finish_non_exhaustive()
2036    }
2037}
2038
2039/// `source` after `lines` blank lines, so Starlark's line numbers are those of
2040/// the `kizz.md`.
2041///
2042/// The space is reserved first with `String::try_reserve_exact`, which returns an
2043/// error where `str::repeat` panics on a length that overflows, so the pushes that
2044/// follow fit.
2045///
2046/// # Errors
2047///
2048/// A [`TaskFailure::Program`] when the padded source cannot be allocated.
2049fn padded_source(
2050    lines: usize,
2051    source: &str,
2052) -> Result<String, TaskFailure> {
2053    let mut padded = String::new();
2054    padded
2055        .try_reserve_exact(lines.saturating_add(source.len()))
2056        .map_err(|error| {
2057            TaskFailure::program(format_args!(
2058                "cannot place the task's source after {lines} blank lines: {error}"
2059            ))
2060        })?;
2061    for _ in 0..lines {
2062        padded.push('\n');
2063    }
2064    padded.push_str(source);
2065    Ok(padded)
2066}
2067
2068impl TaskProgram {
2069    /// Parse the task block and load every module it loads, directly or
2070    /// indirectly.
2071    ///
2072    /// A `load` path is relative to the loading file, or absolute. Each module is
2073    /// evaluated once per task, outside the task, with `print` output going to
2074    /// `print`.
2075    #[must_use]
2076    pub fn load(
2077        task: TaskInfo,
2078        print: &dyn PrintSink,
2079    ) -> ProgramLoad {
2080        Self::load_noting(task, print, false)
2081    }
2082
2083    /// Load the task program as [`TaskProgram::load`] does; when `noting` is set,
2084    /// also note how each module read and each file access ended, in
2085    /// [`ProgramLoad::outcomes`] and then in [`TaskRun::outcomes`] of its run, for
2086    /// the observation report of `kizz run --output`.
2087    #[must_use]
2088    pub fn load_noting(
2089        task: TaskInfo,
2090        print: &dyn PrintSink,
2091        noting: bool,
2092    ) -> ProgramLoad {
2093        let globals = globals();
2094        let printer = TaskPrinter {
2095            name: task.display_name(),
2096            sink: print,
2097        };
2098        let mut loader = ModuleLoader {
2099            task: &task,
2100            globals: &globals,
2101            printer: &printer,
2102            accesses: Accesses::new(),
2103            changes: FileChanges::new(),
2104            outcomes: noting.then(AccessOutcomes::new),
2105            loaded: HashMap::new(),
2106            loading: Vec::new(),
2107            sources: Vec::new(),
2108        };
2109        let file_name = task.relative_file.display().to_string();
2110        // Blank lines before the source make Starlark's line numbers those of the
2111        // `kizz.md`.
2112        let parsed = padded_source(task.line, &task.source)
2113            .and_then(|padded| {
2114                AstModule::parse(&file_name, padded, &Dialect::Extended)
2115                    .map_err(TaskFailure::program)
2116            })
2117            .and_then(|ast| {
2118                let imports = loader.load_imports(&ast, &task.dir, &file_name)?;
2119                Ok((ast, imports))
2120            });
2121        let ModuleLoader {
2122            accesses,
2123            changes,
2124            outcomes,
2125            sources,
2126            ..
2127        } = loader;
2128        let program = parsed.map(|(ast, imports)| {
2129            let mut hasher = blake3::Hasher::new_derive_key(PROGRAM_HASH_CONTEXT);
2130            hash_field(&mut hasher, task.source.as_bytes());
2131            for (path, source) in &sources {
2132                hash_field(&mut hasher, path.as_path().as_os_str().as_encoded_bytes());
2133                hash_field(&mut hasher, source.as_bytes());
2134            }
2135            let hash = ProgramHash(*hasher.finalize().as_bytes());
2136            let mut modules: Vec<(PathBuf, [u8; 32])> = sources
2137                .iter()
2138                .map(|(path, source)| {
2139                    (
2140                        path.as_path().to_path_buf(),
2141                        *blake3::hash(source.as_bytes()).as_bytes(),
2142                    )
2143                })
2144                .collect();
2145            modules.sort();
2146            let parts = ProgramParts {
2147                block: *blake3::hash(task.source.as_bytes()).as_bytes(),
2148                modules,
2149            };
2150            Self {
2151                task,
2152                ast,
2153                imports,
2154                hash,
2155                parts,
2156                noting,
2157            }
2158        });
2159        ProgramLoad {
2160            accesses,
2161            changes,
2162            outcomes,
2163            program,
2164        }
2165    }
2166
2167    /// The hash of the block and every module it loads.
2168    #[must_use]
2169    pub const fn hash(&self) -> ProgramHash {
2170        self.hash
2171    }
2172
2173    /// The hashes of the block and of each module it loads, so explanations can
2174    /// name the part that changed.
2175    #[must_use]
2176    pub const fn parts(&self) -> &ProgramParts {
2177        &self.parts
2178    }
2179
2180    /// The task.
2181    #[must_use]
2182    pub const fn task(&self) -> &TaskInfo {
2183        &self.task
2184    }
2185
2186    /// Evaluate the task block, handing each `run()` call to `executor` in program
2187    /// order, with `print` output going to `print`.
2188    ///
2189    /// The task environment starts empty. `caller` is the caller environment, the
2190    /// only one that `env.caller` and `env.inherit` read. The result holds every
2191    /// file access the program made while it ran, and every file it changed,
2192    /// whether or not it failed, and every step it left unchecked: when the
2193    /// program ends, whether it succeeded or failed, each step that exited with a
2194    /// non-zero code or was killed by a signal, whose `run()` had no `expect`, and
2195    /// whose result's `rc` and `signal` the program never read.
2196    #[must_use]
2197    pub fn run(
2198        self,
2199        caller: &BTreeMap<String, String>,
2200        executor: &dyn StepExecutor,
2201        print: &dyn PrintSink,
2202    ) -> TaskRun {
2203        let Self {
2204            task,
2205            ast,
2206            imports,
2207            noting,
2208            ..
2209        } = self;
2210        let globals = globals();
2211        let printer = TaskPrinter {
2212            name: task.display_name(),
2213            sink: print,
2214        };
2215        let state = TaskState {
2216            task: &task,
2217            executor,
2218            caller,
2219            env: Cell::new(BTreeMap::new()),
2220            accesses: Cell::new(Accesses::new()),
2221            changes: Cell::new(FileChanges::new()),
2222            outcomes: Cell::new(noting.then(AccessOutcomes::new)),
2223            unexpected: Cell::new(None),
2224            started: Cell::new(0),
2225            watched: Cell::new(Vec::new()),
2226        };
2227        let result = Module::with_temp_heap(|module| {
2228            set_task_value(&module, &task);
2229            let mut eval = Evaluator::new(&module);
2230            eval.set_loader(&imports);
2231            eval.set_print_handler(&printer);
2232            eval.extra = Some(&state);
2233            eval.eval_module(ast, &globals).map(|_| ())
2234        });
2235        let result = result.map_err(|error| {
2236            let message = error.to_string();
2237            match state.unexpected.take() {
2238                Some(exit) => {
2239                    TaskFailure::UnexpectedExit {
2240                        exit: Box::new(exit),
2241                        message,
2242                    }
2243                },
2244                None => TaskFailure::Program { message },
2245            }
2246        });
2247        let unchecked = state
2248            .watched
2249            .take()
2250            .into_iter()
2251            .filter(|watched| !watched.checked.load(Ordering::Relaxed))
2252            .map(|watched| watched.exit)
2253            .collect();
2254        TaskRun {
2255            accesses: state.accesses.into_inner(),
2256            changes: state.changes.into_inner(),
2257            outcomes: state.outcomes.into_inner(),
2258            result,
2259            unchecked,
2260        }
2261    }
2262}
2263
2264/// The result of [`TaskProgram::run`].
2265#[derive(Debug)]
2266pub struct TaskRun {
2267    /// Every file access the program made while it ran, through the `fs`
2268    /// functions, `env.load_file`, and `env.read`, missing files and directory
2269    /// listings included.
2270    pub accesses: Accesses,
2271    /// Every file the program changed through `fs.write` and `fs.write_json` while
2272    /// it ran, in the order it first changed each, without repeats.
2273    pub changes: FileChanges,
2274    /// How each of those accesses ended, when the program was loaded with
2275    /// [`TaskProgram::load_noting`], and otherwise `None`.
2276    pub outcomes: Option<AccessOutcomes>,
2277    /// Whether the program succeeded, or why it failed. Unchecked steps never fail
2278    /// the run here; `kizz build --fail-unchecked` turns them into a failure.
2279    pub result: Result<(), TaskFailure>,
2280    /// Every step the program left unchecked, in the order they ran, with its
2281    /// command, how it ended, and its output; results from the cache included.
2282    pub unchecked: Vec<UncheckedExit>,
2283}
2284
2285/// Unit tests for the runtime's own logic.
2286#[cfg(test)]
2287#[allow(
2288    clippy::disallowed_macros,
2289    clippy::disallowed_methods,
2290    reason = "test code: the tests assert, borrow cells and lock"
2291)]
2292mod tests {
2293    use std::{cell::RefCell, collections::BTreeMap, path::PathBuf};
2294
2295    use kizz_trace::{AbsolutePath, CapturedOutput, Termination};
2296
2297    use super::{PrintSink, TaskFailure, TaskInfo, TaskProgram, UnexpectedExit, padded_source};
2298    use crate::step::{StepError, StepExecutor, StepOutcome, StepSpec};
2299
2300    /// Records each step and answers with exit status 0 and no output.
2301    #[derive(Default)]
2302    struct Recorder {
2303        /// The steps received, in order.
2304        steps: RefCell<Vec<StepSpec>>,
2305    }
2306
2307    impl StepExecutor for Recorder {
2308        fn execute(
2309            &self,
2310            step: &StepSpec,
2311        ) -> Result<StepOutcome, StepError> {
2312            self.steps.borrow_mut().push(step.clone());
2313            Ok(StepOutcome {
2314                termination: Termination::Exited(0),
2315                output: CapturedOutput::empty(step.capture),
2316                cached: false,
2317            })
2318        }
2319    }
2320
2321    /// Drops printed lines.
2322    struct NoPrint;
2323
2324    impl PrintSink for NoPrint {
2325        fn print_line(
2326            &self,
2327            _line: &str,
2328        ) {
2329        }
2330    }
2331
2332    /// A task in `/work` whose block is `source`.
2333    fn task(source: &str) -> TaskInfo {
2334        TaskInfo {
2335            dir: AbsolutePath::new("/work").unwrap(),
2336            file: AbsolutePath::new("/work/kizz.md").unwrap(),
2337            relative_file: PathBuf::from("kizz.md"),
2338            line: 1,
2339            index: 0,
2340            name: None,
2341            heading: None,
2342            targets: vec!["ci".to_owned()],
2343            selected: vec!["ci".to_owned()],
2344            args: Vec::new(),
2345            cache_never: false,
2346            source: source.to_owned(),
2347        }
2348    }
2349
2350    /// The per-run `env` applies to the task environment for one step only: a
2351    /// string sets a variable, and `None` removes it.
2352    #[test]
2353    fn per_run_env_sets_and_removes_task_variables() {
2354        let program = TaskProgram::load(
2355            task(
2356                "env.update({\"KEPT\": \"old\", \"REMOVED\": \"gone\"})\nrun(\"a\", env = \
2357                 {\"REMOVED\": None, \"ADDED\": \"new\", \"KEPT\": \"changed\"})\nrun(\"b\")\n",
2358            ),
2359            &NoPrint,
2360        )
2361        .program
2362        .unwrap();
2363        let recorder = Recorder::default();
2364        let start = BTreeMap::from([
2365            ("KEPT".to_owned(), "old".to_owned()),
2366            ("REMOVED".to_owned(), "gone".to_owned()),
2367        ]);
2368        program
2369            .run(&BTreeMap::new(), &recorder, &NoPrint)
2370            .result
2371            .unwrap();
2372        let envs: Vec<BTreeMap<String, String>> = recorder
2373            .steps
2374            .borrow()
2375            .iter()
2376            .map(|step| step.env.clone())
2377            .collect();
2378        assert_eq!(envs, [
2379            BTreeMap::from([
2380                ("ADDED".to_owned(), "new".to_owned()),
2381                ("KEPT".to_owned(), "changed".to_owned()),
2382            ]),
2383            start,
2384        ]);
2385    }
2386
2387    /// An unexpected exit shows the command, its exit status, the accepted codes,
2388    /// and the merged output, with a newline added when the output lacks one.
2389    #[test]
2390    fn unexpected_exit_shows_command_status_and_output() {
2391        let exit = UnexpectedExit {
2392            argv: vec!["make".to_owned(), "all".to_owned()],
2393            termination: Termination::Signaled(9),
2394            expect: vec![0],
2395            output: CapturedOutput::Merged {
2396                output: b"partial".to_vec(),
2397            },
2398        };
2399        assert_eq!(
2400            exit.to_string(),
2401            "command `make all`: killed by signal 9, but `expect` accepts exit code 0\n--- \
2402             output ---\npartial\n"
2403        );
2404    }
2405
2406    /// A task's source after blank lines whose total length cannot be reserved is a
2407    /// program failure, where `str::repeat` would panic: `usize::MAX` lines saturate
2408    /// the length, which overflows the largest length a `String` can reserve, so the
2409    /// reservation fails at once, without allocating; a length that fits is built in
2410    /// full.
2411    #[test]
2412    fn padding_that_cannot_be_reserved_is_a_program_failure() {
2413        let Err(TaskFailure::Program { message }) = padded_source(usize::MAX, "run(\"a\")\n")
2414        else {
2415            panic!("the padding was reserved");
2416        };
2417        assert!(
2418            message.starts_with(&format!(
2419                "cannot place the task's source after {} blank lines: ",
2420                usize::MAX
2421            )),
2422            "{message}"
2423        );
2424        assert_eq!(padded_source(2, "x").unwrap(), "\n\nx");
2425        assert_eq!(padded_source(0, "x").unwrap(), "x");
2426    }
2427}
2428
2429/// Unit tests of `expand_arguments`, the expansion of `run()`'s positional
2430/// arguments, on Starlark values that small programs build, or that a test
2431/// allocates directly: each form of the expansion, the errors with their exact
2432/// messages, the cycle check, the bound, and a nesting deep enough that a recursive
2433/// walk would overflow the stack.
2434#[cfg(test)]
2435#[allow(clippy::disallowed_macros, reason = "test code: the tests assert")]
2436mod argument_tests {
2437    use starlark::{
2438        environment::{Globals, Module},
2439        eval::Evaluator,
2440        syntax::{AstModule, Dialect},
2441        values::{Heap, tuple::TupleRef},
2442    };
2443
2444    use super::{MAX_ARGUMENT_VALUES, expand_arguments};
2445
2446    /// The expansion of the positional arguments that `source` gives, a Starlark
2447    /// program whose last statement is the tuple of the arguments, or the message of
2448    /// the expansion's error.
2449    fn expand(source: &str) -> Result<Vec<String>, String> {
2450        Module::with_temp_heap(|module| {
2451            let ast =
2452                AstModule::parse("arguments.star", source.to_owned(), &Dialect::Extended).unwrap();
2453            let globals = Globals::standard();
2454            let mut eval = Evaluator::new(&module);
2455            let value = eval.eval_module(ast, &globals).unwrap();
2456            let arguments = TupleRef::from_value(value).unwrap();
2457            expand_arguments(arguments.content()).map_err(|error| error.to_string())
2458        })
2459    }
2460
2461    /// `items` as owned strings.
2462    fn strings(items: &[&str]) -> Vec<String> {
2463        items.iter().map(|&item| item.to_owned()).collect()
2464    }
2465
2466    /// Lists and tuples expand in place, in order and at any depth, wherever they
2467    /// stand: first, last, in the middle, nested, or as the whole command; empty ones
2468    /// add nothing; each string, one with spaces and an empty one included, stays one
2469    /// argument; and the same list used twice, side by side, adds its strings twice.
2470    #[test]
2471    fn lists_and_tuples_expand_in_place_and_strings_stay_whole() {
2472        let this_is_test = strings(&["echo", "this", "is", "test"]);
2473        for source in [
2474            "(\"echo\", \"this\", \"is\", \"test\")",
2475            "(\"echo\", [\"this\", \"is\", \"test\"])",
2476            "([\"echo\", \"this\"], \"is\", \"test\")",
2477            "(\"echo\", [\"this\"], \"is\", (\"test\",))",
2478            "(\"echo\", [[\"this\"], (\"is\", [])], \"test\")",
2479            "((\"echo\",), [[\"this\"], (\"is\", [])], \"test\")",
2480            "([\"echo\", \"this\", \"is\", \"test\"],)",
2481            "(((\"echo\", [[[\"this\"]]]), \"is\"), [], (), [[]], \"test\")",
2482        ] {
2483            assert_eq!(expand(source), Ok(this_is_test.clone()), "{source}");
2484        }
2485        assert_eq!(
2486            expand("(\"printf\", [\"%s|\", \"a b\"], \"\", [\"\"])"),
2487            Ok(strings(&["printf", "%s|", "a b", "", ""]))
2488        );
2489        assert_eq!(
2490            expand("opt = [\"-v\"]\n(\"tool\", opt, \"x\", [opt, opt])"),
2491            Ok(strings(&["tool", "-v", "x", "-v", "-v"]))
2492        );
2493        assert_eq!(
2494            expand("flags = []\n(\"tool\", flags, \"x\")"),
2495            Ok(strings(&["tool", "x"]))
2496        );
2497    }
2498
2499    /// Arguments of nothing but empty lists and tuples, and no arguments at all,
2500    /// expand to no string, which `run()` then refuses as a call without a program.
2501    #[test]
2502    fn empty_lists_and_tuples_expand_to_nothing() {
2503        for source in ["()", "([],)", "([], ())", "([[]],)", "(([(), [[]]],),)"] {
2504            assert_eq!(expand(source), Ok(Vec::new()), "{source}");
2505        }
2506    }
2507
2508    /// A value that is neither a string nor a list or tuple fails with its argument,
2509    /// its index path within the lists, and its type, as Starlark's `type()` names
2510    /// it, and the first such value in the order of the walk is the one named.
2511    #[test]
2512    fn other_values_fail_with_their_place_and_type() {
2513        for (source, message) in [
2514            (
2515                "(\"p\", \"a\", 5)",
2516                "run(): argument 3 is of type int, not a string, list or tuple",
2517            ),
2518            (
2519                "(\"p\", True)",
2520                "run(): argument 2 is of type bool, not a string, list or tuple",
2521            ),
2522            (
2523                "(\"p\", [\"a\", [None]])",
2524                "run(): argument 2 at [1][0] is of type NoneType, not a string, list or tuple",
2525            ),
2526            (
2527                "([{\"a\": 1}],)",
2528                "run(): argument 1 at [0] is of type dict, not a string, list or tuple",
2529            ),
2530            (
2531                "(\"p\", (\"a\", range(3)))",
2532                "run(): argument 2 at [1] is of type range, not a string, list or tuple",
2533            ),
2534            (
2535                "([], 5)",
2536                "run(): argument 2 is of type int, not a string, list or tuple",
2537            ),
2538            (
2539                "a = [\"x\"]\na.append(a)\n(\"p\", [1], a)",
2540                "run(): argument 2 at [0] is of type int, not a string, list or tuple",
2541            ),
2542        ] {
2543            assert_eq!(expand(source), Err(message.to_owned()), "{source}");
2544        }
2545    }
2546
2547    /// A list or tuple that contains itself, directly, through another list, or
2548    /// through a list inside a tuple, fails where it is met again, with its own
2549    /// type, and the walk ends.
2550    #[test]
2551    fn a_list_or_tuple_that_contains_itself_fails() {
2552        for (source, message) in [
2553            (
2554                "a = [\"x\"]\na.append(a)\n(\"p\", a)",
2555                "run(): argument 2 at [1] is a list that contains itself",
2556            ),
2557            (
2558                "a = []\nb = [a]\na.append(b)\n(\"p\", a)",
2559                "run(): argument 2 at [0][0] is a list that contains itself",
2560            ),
2561            (
2562                "l = []\nt = (\"a\", l)\nl.append(t)\n(\"p\", t)",
2563                "run(): argument 2 at [1][0] is a tuple that contains itself",
2564            ),
2565        ] {
2566            assert_eq!(expand(source), Err(message.to_owned()), "{source}");
2567        }
2568    }
2569
2570    /// The expansion visits at most [`MAX_ARGUMENT_VALUES`] values: a list of
2571    /// 999,999 strings is 1,000,000 values and expands, one more string fails, and so
2572    /// do twenty-one doublings of a shared list, which would expand to 2,097,152
2573    /// strings, before the walk goes further.
2574    #[test]
2575    fn the_expansion_stops_past_a_million_values() {
2576        let limit = "run(): the arguments expand to more than 1000000 strings, lists and tuples";
2577        assert_eq!(MAX_ARGUMENT_VALUES, 1_000_000);
2578        assert_eq!(
2579            expand("([\"x\"] * 999999,)").as_ref().map(Vec::len),
2580            Ok(999_999)
2581        );
2582        assert_eq!(expand("([\"x\"] * 1000000,)"), Err(limit.to_owned()));
2583        assert_eq!(
2584            expand("a = [\"x\"]\nfor _ in range(21):\n    a = [a, a]\n(a,)"),
2585            Err(limit.to_owned())
2586        );
2587    }
2588
2589    /// A string inside 100,000 nested lists, passed inside a tuple, expands to that
2590    /// string, because the walk keeps its own stack rather than recursing. The lists
2591    /// are allocated directly on a heap, where no garbage collection runs: Starlark's
2592    /// collector, which the evaluator runs between a module's top-level statements,
2593    /// copies nested values recursively, so building this nesting in a program can
2594    /// overflow the stack in the collector, before any `run()` call.
2595    #[test]
2596    fn a_deep_nesting_expands_without_recursion() {
2597        Heap::temp(|heap| {
2598            let mut nested = heap.alloc("deep");
2599            for _ in 0..100_000 {
2600                nested = heap.alloc(vec![nested]);
2601            }
2602            let arguments = [heap.alloc("p"), heap.alloc((nested,))];
2603            assert_eq!(
2604                expand_arguments(&arguments).map_err(|error| error.to_string()),
2605                Ok(strings(&["p", "deep"]))
2606            );
2607        });
2608    }
2609}
2610
2611/// Unit tests of `program_names`, which the documentation coverage test reads, and
2612/// of the result-attribute constants that it lists.
2613#[cfg(test)]
2614#[allow(
2615    clippy::disallowed_macros,
2616    clippy::disallowed_methods,
2617    reason = "test code: the tests assert and borrow cells"
2618)]
2619mod names_tests {
2620    use std::{cell::RefCell, collections::BTreeMap, path::PathBuf};
2621
2622    use kizz_trace::{AbsolutePath, CapturedOutput, Termination};
2623    use starlark::values::{Heap, StarlarkValue as _};
2624
2625    use super::{
2626        MERGED_RESULT_ATTRIBUTES, PrintSink, ProgramName, ProgramNames, RunResult,
2627        SPLIT_RESULT_ATTRIBUTES, TaskInfo, TaskProgram, program_names,
2628    };
2629    use crate::step::{StepError, StepExecutor, StepOutcome, StepSpec};
2630
2631    /// Answers every step with exit status 0 and no output.
2632    struct Succeed;
2633
2634    impl StepExecutor for Succeed {
2635        fn execute(
2636            &self,
2637            step: &StepSpec,
2638        ) -> Result<StepOutcome, StepError> {
2639            Ok(StepOutcome {
2640                termination: Termination::Exited(0),
2641                output: CapturedOutput::empty(step.capture),
2642                cached: false,
2643            })
2644        }
2645    }
2646
2647    /// Keeps the lines that programs print.
2648    #[derive(Default)]
2649    struct Lines {
2650        /// The printed lines, in order, each with its prefix.
2651        lines: RefCell<Vec<String>>,
2652    }
2653
2654    impl PrintSink for Lines {
2655        fn print_line(
2656            &self,
2657            line: &str,
2658        ) {
2659            self.lines.borrow_mut().push(line.to_owned());
2660        }
2661    }
2662
2663    /// The members of `module` among `names`, without the module's name, sorted.
2664    fn members_of(
2665        names: &ProgramNames,
2666        module: &str,
2667    ) -> Vec<String> {
2668        let prefix = format!("{module}.");
2669        let mut members: Vec<String> = names
2670            .members
2671            .iter()
2672            .filter_map(|name| name.name.strip_prefix(&prefix).map(str::to_owned))
2673            .collect();
2674        members.sort();
2675        members
2676    }
2677
2678    /// `names` as owned strings, sorted.
2679    fn sorted(names: &[&str]) -> Vec<String> {
2680        let mut names: Vec<String> = names.iter().map(|&name| name.to_owned()).collect();
2681        names.sort();
2682        names
2683    }
2684
2685    /// What a task program in `/work` sees, as `dir()` lists it, of `env`, `fs`,
2686    /// `json`, `task`, and a `run()` result in each capture mode, each sorted.
2687    fn seen_by_a_program() -> Vec<Vec<String>> {
2688        let task = TaskInfo {
2689            dir: AbsolutePath::new("/work").unwrap(),
2690            file: AbsolutePath::new("/work/kizz.md").unwrap(),
2691            relative_file: PathBuf::from("kizz.md"),
2692            line: 1,
2693            index: 0,
2694            name: None,
2695            heading: None,
2696            targets: vec!["ci".to_owned()],
2697            selected: vec!["ci".to_owned()],
2698            args: Vec::new(),
2699            cache_never: false,
2700            source: "print(json.encode([dir(env), dir(fs), dir(json), dir(task), \
2701                     dir(run(\"a\")), dir(run(\"a\", capture = \"merged\"))]))\n"
2702                .to_owned(),
2703        };
2704        let lines = Lines::default();
2705        let program = TaskProgram::load(task, &lines).program.unwrap();
2706        program
2707            .run(&BTreeMap::new(), &Succeed, &lines)
2708            .result
2709            .unwrap();
2710        let printed = lines.lines.borrow();
2711        let [line] = printed.as_slice() else {
2712            panic!("the program printed {printed:?}");
2713        };
2714        let (_task, text) = line.split_once(": ").unwrap();
2715        let seen: Vec<Vec<String>> = serde_json::from_str(text).unwrap();
2716        seen.into_iter()
2717            .map(|mut names| {
2718                names.sort();
2719                names
2720            })
2721            .collect()
2722    }
2723
2724    /// The members, result attributes and `task` members that `program_names` lists
2725    /// are those that a task program sees with `dir()`; the globals are those that
2726    /// kizz adds to Starlark's standard ones, `task` included, and `run()`'s
2727    /// parameters come from its signature, the positional arguments first.
2728    #[test]
2729    fn program_names_are_what_programs_see() {
2730        let names = program_names();
2731        assert_eq!(seen_by_a_program(), [
2732            members_of(&names, "env"),
2733            members_of(&names, "fs"),
2734            members_of(&names, "json"),
2735            members_of(&names, "task"),
2736            sorted(SPLIT_RESULT_ATTRIBUTES),
2737            sorted(MERGED_RESULT_ATTRIBUTES),
2738        ]);
2739        let globals: Vec<String> = names.globals.iter().map(ProgramName::written).collect();
2740        assert_eq!(globals, ["env", "fs", "json", "print()", "run()", "task"]);
2741        let members: Vec<String> = names.members.iter().map(ProgramName::written).collect();
2742        assert!(members.contains(&"env.inherit()".to_owned()), "{members:?}");
2743        assert!(members.contains(&"task.args".to_owned()), "{members:?}");
2744        assert_eq!(names.run_parameters, [
2745            "argv",
2746            "stdin",
2747            "env",
2748            "cwd",
2749            "capture",
2750            "stream",
2751            "always",
2752            "untraced",
2753            "network",
2754            "ignore",
2755            "track",
2756            "timestamps",
2757            "machine",
2758            "expect",
2759        ]);
2760        assert_eq!(names.result_attributes, [
2761            "rc", "signal", "stdout", "stderr", "cached", "output"
2762        ]);
2763    }
2764
2765    /// The keys of a JSON object, in the order its text has them.
2766    struct Keys {
2767        /// The keys, in order.
2768        keys: Vec<String>,
2769    }
2770
2771    impl<'de> serde::Deserialize<'de> for Keys {
2772        fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
2773            /// Collects the keys of an object and skips its values.
2774            struct KeysVisitor;
2775
2776            impl<'de> serde::de::Visitor<'de> for KeysVisitor {
2777                type Value = Keys;
2778
2779                fn expecting(
2780                    &self,
2781                    formatter: &mut std::fmt::Formatter<'_>,
2782                ) -> std::fmt::Result {
2783                    formatter.write_str("a JSON object")
2784                }
2785
2786                fn visit_map<A: serde::de::MapAccess<'de>>(
2787                    self,
2788                    mut map: A,
2789                ) -> Result<Keys, A::Error> {
2790                    let mut keys = Vec::new();
2791                    while let Some((key, serde::de::IgnoredAny)) =
2792                        map.next_entry::<String, serde::de::IgnoredAny>()?
2793                    {
2794                        keys.push(key);
2795                    }
2796                    Ok(Keys { keys })
2797                }
2798            }
2799
2800            deserializer.deserialize_map(KeysVisitor)
2801        }
2802    }
2803
2804    /// The attribute constants decide which attributes a `run()` result has: in
2805    /// each capture mode, `get_attr` and `has_attr` answer every name of the mode's
2806    /// constant and no other, the other mode's names and unknown names included, and
2807    /// the JSON encoding writes exactly the constant's names, in its order.
2808    #[test]
2809    fn the_attribute_constants_decide_what_a_result_has() {
2810        let modes = [
2811            (
2812                CapturedOutput::Split {
2813                    stdout: b"out".to_vec(),
2814                    stderr: b"err".to_vec(),
2815                },
2816                SPLIT_RESULT_ATTRIBUTES,
2817            ),
2818            (
2819                CapturedOutput::Merged {
2820                    output: b"both".to_vec(),
2821                },
2822                MERGED_RESULT_ATTRIBUTES,
2823            ),
2824        ];
2825        let mut names: Vec<&str> = SPLIT_RESULT_ATTRIBUTES
2826            .iter()
2827            .chain(MERGED_RESULT_ATTRIBUTES)
2828            .copied()
2829            .collect();
2830        names.extend(["duration", "checked", "RC", ""]);
2831        for (output, attributes) in modes {
2832            let result = RunResult::new(&StepOutcome {
2833                termination: Termination::Exited(3),
2834                output,
2835                cached: true,
2836            });
2837            Heap::temp(|heap| {
2838                for &name in &names {
2839                    let listed = attributes.contains(&name);
2840                    assert_eq!(
2841                        result.get_attr(name, heap).is_some(),
2842                        listed,
2843                        "get_attr of {name:?} with {attributes:?}"
2844                    );
2845                    assert_eq!(
2846                        result.has_attr(name, heap),
2847                        listed,
2848                        "has_attr of {name:?} with {attributes:?}"
2849                    );
2850                }
2851            });
2852            let encoded = serde_json::to_string(&result).unwrap();
2853            let keys: Keys = serde_json::from_str(&encoded).unwrap();
2854            assert_eq!(keys.keys, attributes, "{encoded}");
2855        }
2856    }
2857}