Skip to main content

kizz_core/
lib.rs

1// Copyright (c) 2026 Sakura Industries LLC.
2//
3// SPDX-License-Identifier: AGPL-3.0-only
4
5//! The kizz build engine.
6//!
7//! This crate holds discovery, Markdown parsing, the Starlark runtime, step keys,
8//! cache checks, explanations, ordering, observation reports, and running
9//! `kizz execute`. It contains no Linux-specific code: it runs commands only through
10//! the tracer interface of `kizz_trace`, reads extended attributes only through that
11//! interface's attribute query, and keeps its records in `kizz_store`, so its tests
12//! use a fake tracer.
13//!
14//! * [`discovery`]: every `kizz.md` under the current directory, in the default order.
15//! * [`tasks`]: the task blocks of a `kizz.md`.
16//! * [`targets`]: target names, target expressions joined with `+`, and task selection.
17//! * [`project`]: discovery and parsing together, with their configuration errors.
18//! * [`runtime`]: the Starlark runtime of task programs, with module loading, the program
19//!   hash, and the `env` and `fs` functions.
20//! * [`dotenv`]: the dotenv files that `env.load_file` and `env.read` read.
21//! * [`files`]: the file operations behind the `fs` functions, which record every access
22//!   and every file a write changed.
23//! * [`step`]: the step specification that `run()` builds, and the step executor the
24//!   runtime hands it to.
25//! * [`warning`]: the warnings of discovery and parsing.
26//! * [`key`]: step keys, derived with BLAKE3 from a deterministic CBOR encoding.
27//! * [`lookup`]: program lookup through the `PATH` of a task environment or of the caller
28//!   of `kizz execute`.
29//! * [`patterns`]: the path patterns of `ignore` and `track`.
30//! * [`observe`](mod@observe): the recorded state of every path a step touched.
31//! * [`states`]: the in-memory concurrent cache of file states and hashes of one build,
32//!   so a file is hashed once per build.
33//! * [`check`](mod@check): the cache check, which compares a step's recorded observations
34//!   with the file system.
35//! * [`engine`]: the engine side of the step executor, which checks the cache for each
36//!   step, replays a hit, and otherwise runs the step through the tracer and stores its
37//!   record, unless the result is not cached.
38//! * [`explain`](mod@explain): why each step ran, from the cache check, the step-position
39//!   records, and the last-writer records, with the warning for steps that re-run for a
40//!   self-inflicted reason.
41//! * [`render`]: the one-line and full reasons as output shows them.
42//! * [`why`](mod@why): the report of `kizz why`, read from the cache.
43//! * [`report`]: observation reports, built from the tracer's process trees and the
44//!   commands' outcomes, and written as text or JSON, hierarchical or compact.
45//! * [`execute`](mod@execute): running one command for `kizz execute`, with the caller's
46//!   environment and working directory, the kept terminal and the process tree, and its
47//!   exit status and observation report, without the cache.
48//! * [`build`](mod@build): building the selected tasks in passes, in the default or
49//!   learned order, until a pass does no work, with failure handling and the pass limit.
50//! * [`run`](mod@run): running one task by its name for `kizz run`, once, with its
51//!   arguments, the nearest task of the name winning, and the observation report of `kizz
52//!   run --output`.
53//! * [`cleanup`]: the entries `kizz cache clean` removes because their files are gone,
54//!   and the entries `kizz cache reset` wipes for the tasks under a path.
55//! * [`pool`]: the worker pool that runs a command's parallel work, whose threads start
56//!   through `kizz_threads`, so `rayon`'s global pool never starts.
57//!
58//! State that one thread changes through shared references lives in a `Cell`, which
59//! the private `cells` module takes out, changes and puts back, where a `RefCell`
60//! borrow would panic while the cell is borrowed; state that threads share is locked
61//! with `kizz_threads::lock`, where `Mutex::lock` may panic ("Kizz never panics").
62
63pub mod build;
64mod cells;
65pub mod check;
66pub mod cleanup;
67pub mod discovery;
68pub mod dotenv;
69pub mod engine;
70pub mod execute;
71pub mod explain;
72pub mod files;
73pub mod key;
74pub mod lookup;
75pub mod observe;
76pub mod patterns;
77pub mod pool;
78pub mod project;
79pub mod render;
80pub mod report;
81pub mod run;
82pub mod runtime;
83pub mod states;
84pub mod step;
85pub mod targets;
86pub mod tasks;
87pub mod warning;
88pub mod why;
89
90pub use build::{
91    BuildEvents, BuildOutcome, BuildReport, ChangingInput, FailedTask, INTERRUPTED, NoEvents, Pass,
92    ProgramWrite, TaskResult, UncheckedStep, build, learned_order, pass_limit, task_id, task_label,
93};
94pub use check::{Checked, RACY_WINDOW_NANOS, check};
95pub use cleanup::{Cleaned, ResetPlan, clean, plan_reset};
96pub use discovery::{Discovery, KIZZ_FILE_NAME, KizzFile, default_order, discover};
97pub use dotenv::DotenvError;
98pub use engine::{Engine, NoStepEvents, StepConnections, StepEvents, TaskSteps, UnknownCalls};
99pub use execute::{
100    ExecuteRequest, Executed, STATUS_FAILED, STATUS_NOT_EXECUTABLE, STATUS_NOT_FOUND, execute,
101    exit_status, not_executed,
102};
103pub use explain::{
104    Baseline, InputContext, RepeatedWarning, StepDecision, TaskIdentity, carried_from,
105    changed_inputs, spec_reasons,
106};
107pub use files::{AccessOutcomes, ChangedFile, FileChanges, FileError, Files, stable_json};
108pub use key::{KeyError, Occurrences, STEP_KEY_CONTEXT, step_key};
109pub use lookup::{
110    NoPathError, PATH_VARIABLE, ProgramLookup, ProgramSearch, check_path, find_program,
111    search_program, search_step_program,
112};
113pub use observe::{
114    HashCounter, Observed, access_bits, changed_after_read, is_kernel_path, kernel_links, observe,
115    path_state, reaches_kernel, record_attributes,
116};
117pub use patterns::{PathPatterns, PatternError, REGEX_PREFIX};
118pub use pool::{MAX_WORKERS, PoolError, WorkerPool};
119pub use project::{ConfigError, LoadError, Project, load};
120pub use render::{CACHED, Render, access_kinds};
121pub use report::{
122    CommandInput, CommandOutcome, Execution, JSON_FIELDS, JsonField, Report, ReportFormat,
123    ReportMode, TaskProgramInput,
124};
125pub use run::{NameError, RunObservations, RunReport, run, select_by_name, task_level};
126pub use runtime::{
127    PrintSink, ProgramHash, ProgramLoad, ProgramParts, TaskFailure, TaskInfo, TaskProgram, TaskRun,
128    UncheckedExit, UnexpectedExit,
129};
130pub use states::FileStates;
131pub use step::{StepError, StepExecutor, StepOutcome, StepSpec};
132pub use targets::{Selected, TARGET_NAME_RULE, TargetExpr, TargetExprError, is_valid_target};
133pub use tasks::{
134    OptionProblem, ParsedFile, TASK_LANGUAGE, TASK_NAME_RULE, TASK_OPTION_KEYS, Task, TaskOptions,
135    parse_tasks,
136};
137pub use warning::Warning;
138pub use why::{WhyReport, WhyStep, WhyTask, why};