1use 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
101const PROGRAM_HASH_CONTEXT: &str = "kizz task program hash, version 1";
104
105#[derive(Debug, Clone, PartialEq, Eq)]
108pub struct TaskInfo {
109 pub dir: AbsolutePath,
111 pub file: AbsolutePath,
113 pub relative_file: PathBuf,
116 pub line: usize,
118 pub index: u32,
120 pub name: Option<String>,
122 pub heading: Option<String>,
124 pub targets: Vec<String>,
126 pub selected: Vec<String>,
128 pub args: Vec<String>,
131 pub cache_never: bool,
134 pub source: String,
136}
137
138impl TaskInfo {
139 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 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 #[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
195pub trait PrintSink {
197 fn print_line(
200 &self,
201 line: &str,
202 );
203}
204
205#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
207pub struct ProgramHash([u8; 32]);
208
209impl ProgramHash {
210 #[must_use]
212 pub const fn from_bytes(bytes: [u8; 32]) -> Self {
213 Self(bytes)
214 }
215
216 #[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#[derive(Debug, Clone, PartialEq, Eq)]
237pub struct UnexpectedExit {
238 pub argv: Vec<String>,
240 pub termination: Termination,
242 pub expect: Vec<i32>,
244 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
269fn 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#[derive(Debug, Clone, PartialEq, Eq)]
288pub struct UncheckedExit {
289 pub position: u32,
292 pub argv: Vec<String>,
294 pub termination: Termination,
296 pub output: CapturedOutput,
298 pub cached: bool,
300}
301
302impl UncheckedExit {
303 #[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
326fn 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
349fn 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#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
367pub enum TaskFailure {
368 #[error("{message}")]
372 Program {
373 message: String,
375 },
376 #[error("{exit}{message}")]
378 UnexpectedExit {
379 exit: Box<UnexpectedExit>,
381 message: String,
383 },
384 #[error("{}", unchecked_message(.exits, .invoked))]
388 Unchecked {
389 exits: Vec<UncheckedExit>,
392 invoked: &'static str,
397 },
398}
399
400impl TaskFailure {
401 fn program(message: impl fmt::Display) -> Self {
403 Self::Program {
404 message: message.to_string(),
405 }
406 }
407}
408
409const MAX_ARGUMENT_VALUES: usize = 1_000_000;
414
415#[derive(Debug, Clone, PartialEq, Eq)]
418struct ArgumentPlace {
419 argument: usize,
421 path: Vec<usize>,
424}
425
426impl fmt::Display for ArgumentPlace {
427 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
444struct ArgumentFrame<'v> {
446 items: &'v [Value<'v>],
448 next: usize,
450 identity: ValueIdentity<'v>,
453}
454
455fn 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
464fn 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#[derive(Debug, thiserror::Error)]
543enum RunError {
544 #[error("{call} cannot be called while {module} is being loaded, outside any task")]
547 WhileLoading {
548 call: &'static str,
550 module: String,
552 },
553 #[error("run() needs a program: run(\"program\", \"argument\", ...)")]
555 NoProgram,
556 #[error("run(): argument {place} is of type {kind}, not a string, list or tuple")]
559 ArgumentType {
560 place: ArgumentPlace,
562 kind: &'static str,
564 },
565 #[error("run(): argument {place} is a {kind} that contains itself")]
568 SelfContaining {
569 place: ArgumentPlace,
571 kind: &'static str,
573 },
574 #[error(
577 "run(): the arguments expand to more than {max} strings, lists and tuples",
578 max = MAX_ARGUMENT_VALUES
579 )]
580 TooManyValues,
581 #[error("run(): capture must be \"split\" or \"merged\", not \"{0}\"")]
583 Capture(String),
584 #[error(
586 "run(): machine has no part \"{0}\"; the parts are {parts}",
587 parts = MachinePart::names_text()
588 )]
589 MachinePart(String),
590 #[error("run(): {0}")]
592 Step(#[from] StepError),
593 #[error("run(): command `{command}`: {termination}, which `expect` does not accept")]
595 Unexpected {
596 command: String,
598 termination: Termination,
600 },
601 #[error("module `{0}` was not loaded")]
603 NotLoaded(String),
604 #[error("{call}: {error}")]
606 File {
607 call: &'static str,
609 error: FileError,
611 },
612 #[error("{call}: {path}:{}: {}", .error.line, .error.message)]
614 Dotenv {
615 call: &'static str,
617 path: AbsolutePath,
619 error: DotenvError,
621 },
622 #[error("{call}: invalid variable {name:?}: {reason}")]
624 Variable {
625 call: &'static str,
627 name: String,
629 reason: &'static str,
631 },
632 #[error("fs.write_json(): {0}")]
634 NotJson(String),
635 #[error("fs.write_json(): indent must be 0 or more, not {0}")]
637 Indent(i32),
638 #[error("fs.read_json(): the number {0} is out of range")]
640 NumberRange(String),
641 #[error("fs.read_json(): the key {0:?} cannot be a dict key")]
643 JsonKey(String),
644 #[error("a run() result exists only while its task runs, so it cannot be stored")]
647 NotStored,
648}
649
650#[derive(ProvidesStaticType)]
653struct TaskState<'a> {
654 task: &'a TaskInfo,
656 executor: &'a dyn StepExecutor,
658 caller: &'a BTreeMap<String, String>,
660 env: Cell<BTreeMap<String, String>>,
662 accesses: Cell<Accesses>,
664 changes: Cell<FileChanges>,
666 outcomes: Cell<Option<AccessOutcomes>>,
669 unexpected: Cell<Option<UnexpectedExit>>,
671 started: Cell<u32>,
674 watched: Cell<Vec<Watched>>,
678}
679
680struct Watched {
683 exit: UncheckedExit,
685 checked: Arc<AtomicBool>,
688}
689
690#[derive(ProvidesStaticType)]
692struct LoadingModule {
693 path: AbsolutePath,
695 dir: AbsolutePath,
697 accesses: Cell<Accesses>,
699 changes: Cell<FileChanges>,
701 outcomes: Cell<Option<AccessOutcomes>>,
704}
705
706fn 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
722fn 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
739fn 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
785fn 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
808fn 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
827fn 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#[derive(Default)]
847struct ModuleMap {
848 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
864struct TaskPrinter<'a> {
867 name: String,
869 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#[starlark_module]
887fn kizz_globals(builder: &mut GlobalsBuilder) {
888 #[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#[derive(Debug, Clone, PartialEq, Eq, Allocative)]
1027enum ResultOutput {
1028 Split {
1030 stdout: String,
1032 stderr: String,
1034 },
1035 Merged {
1037 output: String,
1039 },
1040}
1041
1042#[derive(Debug, ProvidesStaticType, Allocative)]
1053struct RunResult {
1054 rc: Option<i32>,
1056 signal: Option<i32>,
1058 output: ResultOutput,
1060 cached: bool,
1062 checked: Arc<AtomicBool>,
1065}
1066
1067impl RunResult {
1068 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 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 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 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 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#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1180enum AttributeValue<'a> {
1181 Int(Option<i32>),
1183 Text(&'a str),
1185 Bool(bool),
1187}
1188
1189impl 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
1220impl 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
1231impl 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#[starlark_module]
1286fn env_functions(builder: &mut GlobalsBuilder) {
1287 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 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 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 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 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 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 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 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 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 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#[starlark_module]
1453fn fs_functions(builder: &mut GlobalsBuilder) {
1454 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 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 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 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 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 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 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
1572fn 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 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
1616fn 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
1625pub const TASK_VALUE: &str = "task";
1628
1629pub const TASK_MEMBERS: [&str; 8] = [
1632 "dir", "file", "line", "name", "heading", "targets", "selected", "args",
1633];
1634
1635pub const SPLIT_RESULT_ATTRIBUTES: &[&str] = &["rc", "signal", "stdout", "stderr", "cached"];
1638
1639pub const MERGED_RESULT_ATTRIBUTES: &[&str] = &["rc", "signal", "output", "cached"];
1642
1643#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
1647pub enum NameKind {
1648 Function,
1650 Module,
1652 Value,
1654}
1655
1656#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
1658pub struct ProgramName {
1659 pub name: String,
1662 pub kind: NameKind,
1664}
1665
1666impl ProgramName {
1667 #[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#[derive(Debug, Clone, PartialEq, Eq, Default)]
1681pub struct ProgramNames {
1682 pub globals: Vec<ProgramName>,
1685 pub members: Vec<ProgramName>,
1687 pub run_parameters: Vec<String>,
1690 pub result_attributes: Vec<String>,
1692}
1693
1694const 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
1703fn parameter_names(function: &DocFunction) -> Vec<String> {
1705 let params = &function.params;
1706 params
1707 .pos_only
1708 .iter()
1709 .chain(¶ms.pos_or_named)
1710 .chain(¶ms.args)
1711 .chain(¶ms.named_only)
1712 .chain(¶ms.kwargs)
1713 .map(|param| param.name.clone())
1714 .collect()
1715}
1716
1717#[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
1776fn 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
1800fn 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
1808struct ModuleLoader<'a> {
1810 task: &'a TaskInfo,
1812 globals: &'a Globals,
1814 printer: &'a TaskPrinter<'a>,
1816 accesses: Accesses,
1818 changes: FileChanges,
1820 outcomes: Option<AccessOutcomes>,
1823 loaded: HashMap<AbsolutePath, FrozenModule>,
1825 loading: Vec<AbsolutePath>,
1827 sources: Vec<(AbsolutePath, String)>,
1829}
1830
1831impl ModuleLoader<'_> {
1832 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 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 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#[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
1973fn 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#[derive(Debug, Clone, PartialEq, Eq, Default)]
1986pub struct ProgramParts {
1987 pub block: [u8; 32],
1989 pub modules: Vec<(PathBuf, [u8; 32])>,
1992}
1993
1994#[derive(Debug)]
1996pub struct ProgramLoad {
1997 pub accesses: Accesses,
2000 pub changes: FileChanges,
2003 pub outcomes: Option<AccessOutcomes>,
2006 pub program: Result<TaskProgram, TaskFailure>,
2008}
2009
2010pub struct TaskProgram {
2012 task: TaskInfo,
2014 ast: AstModule,
2016 imports: ModuleMap,
2018 hash: ProgramHash,
2020 parts: ProgramParts,
2022 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
2039fn 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 #[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 #[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 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 #[must_use]
2169 pub const fn hash(&self) -> ProgramHash {
2170 self.hash
2171 }
2172
2173 #[must_use]
2176 pub const fn parts(&self) -> &ProgramParts {
2177 &self.parts
2178 }
2179
2180 #[must_use]
2182 pub const fn task(&self) -> &TaskInfo {
2183 &self.task
2184 }
2185
2186 #[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#[derive(Debug)]
2266pub struct TaskRun {
2267 pub accesses: Accesses,
2271 pub changes: FileChanges,
2274 pub outcomes: Option<AccessOutcomes>,
2277 pub result: Result<(), TaskFailure>,
2280 pub unchecked: Vec<UncheckedExit>,
2283}
2284
2285#[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 #[derive(Default)]
2302 struct Recorder {
2303 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 struct NoPrint;
2323
2324 impl PrintSink for NoPrint {
2325 fn print_line(
2326 &self,
2327 _line: &str,
2328 ) {
2329 }
2330 }
2331
2332 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 #[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 #[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 #[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#[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 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 fn strings(items: &[&str]) -> Vec<String> {
2463 items.iter().map(|&item| item.to_owned()).collect()
2464 }
2465
2466 #[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 #[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 #[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 #[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 #[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 #[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#[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 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 #[derive(Default)]
2649 struct Lines {
2650 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 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 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 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 #[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 struct Keys {
2767 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 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 #[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}