1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
use serde::{Deserialize, Serialize};
use super::{KnownFields, default_true};
/// Universal processor config with all standard fields.
/// Checkers, generators, and simple processors all use this.
/// Fields not relevant to a given processor type are simply ignored.
#[derive(Debug, Deserialize, Serialize, Clone)]
pub struct StandardConfig {
#[serde(default)]
pub command: String,
#[serde(default)]
pub formats: Vec<String>,
#[serde(default)]
pub args: Vec<String>,
#[serde(default)]
pub dep_inputs: Vec<String>,
#[serde(default)]
pub dep_auto: Vec<String>,
#[serde(default)]
pub output_dir: String,
/// Extra tools this processor needs beyond `command`.
///
/// `required_tools()` normally reports just `command`, which is right when
/// the processor invokes the tool directly. It is wrong when `command` is a
/// wrapper -- a script that shells out to something else -- because the real
/// tool is then invisible to `tool install` and to version locking, and the
/// build only fails later, at the point the wrapper runs.
#[serde(default)]
pub required_tools: Vec<String>,
#[serde(default = "default_true")]
pub batch: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub max_jobs: Option<usize>,
/// Whether this processor is active. Set to false to disable without
/// removing the stanza from rsconstruct.toml.
#[serde(default = "default_true")]
pub enabled: bool,
/// Run this processor only on a machine where this directory exists
/// (`~/` expands to the home directory). Resolved once at config load
/// (`Config::apply_dir_conditions`): when the directory is missing the
/// instance is turned off exactly as `enabled = false` would, and the
/// build and `processor used` report it as skipped. For a processor whose job is a
/// side effect on the local machine (mirroring files into a synced
/// folder) rather than a build output. Not part of the cache key: it
/// decides whether the processor runs, not what it produces.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub enabled_if_dir_exists: Option<String>,
/// The result depends on the input files' paths, not only their
/// content: the output names its input (`// Generated from foo.c`), or
/// a checker applies per-path rules (ruff's `per-file-ignores`). Adds
/// the input paths to the cache key, so a renamed file, or an identical
/// file elsewhere, is rebuilt instead of reusing a cached result.
/// Read by the builder (`BuildGraph::key_by_input_paths`), not by the
/// processor itself.
#[serde(default)]
pub output_depends_on_input_name: bool,
/// The result depends on the Python packages installed in the
/// project's `./.venv`: a pyrefly verdict, a pytest run, a build script
/// that imports a third-party package. Adds a fingerprint of the
/// installed packages and interpreter version to the cache key, so an
/// upgrade (`uv lock --upgrade && uv sync`) rebuilds. `None` — neither
/// the user nor the plugin defaults set it — means detect: keyed when
/// one of the processor's tools runs the venv's Python. Read by the
/// builder (`python_env::processors_keyed_by_python_env`), not by the
/// processor itself.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub hash_python_env: Option<bool>,
/// Overrides `[build] execution_model` for this processor. `None`
/// follows the build-wide setting. Read by the executor
/// (`sandbox::spec_for`), not by the processor itself; not part of the
/// cache key, since a sandbox never changes a successful result.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub execution_model: Option<super::ExecutionModel>,
/// Under the sandbox execution model, let this processor's tools reach
/// the network (pip, npm, cargo fetching packages). Ignored natively.
#[serde(default)]
pub sandbox_network: bool,
/// Under the sandbox execution model, state directories this processor
/// may write beyond those its tools declare (`ToolInfo::sandbox_writable`):
/// paths relative to the project root, or `**/NAME` for a directory
/// named NAME anywhere. Needed for a user-supplied command (a script),
/// whose tool rsconstruct does not know. Ignored natively.
#[serde(default)]
pub sandbox_writable: Vec<String>,
// --- Scan fields (file discovery) ---
#[serde(default, skip_serializing_if = "Option::is_none")]
pub src_dirs: Option<Vec<String>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub src_extensions: Option<Vec<String>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub src_exclude_dirs: Option<Vec<String>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub src_exclude_files: Option<Vec<String>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub src_exclude_paths: Option<Vec<String>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub src_files: Option<Vec<String>>,
}
impl Default for StandardConfig {
fn default() -> Self {
Self {
command: String::new(),
formats: Vec::new(),
args: Vec::new(),
dep_inputs: Vec::new(),
dep_auto: Vec::new(),
output_dir: String::new(),
required_tools: Vec::new(),
batch: true,
max_jobs: None,
enabled: true,
enabled_if_dir_exists: None,
output_depends_on_input_name: false,
hash_python_env: None,
execution_model: None,
sandbox_network: false,
sandbox_writable: Vec::new(),
src_dirs: None,
src_extensions: None,
src_exclude_dirs: None,
src_exclude_files: None,
src_exclude_paths: None,
src_files: None,
}
}
}
impl StandardConfig {
pub(crate) fn src_dirs(&self) -> &[String] {
self.src_dirs
.as_deref()
.expect(crate::errors::SCAN_CONFIG_NOT_RESOLVED)
}
pub(crate) fn src_extensions(&self) -> &[String] {
self.src_extensions
.as_deref()
.expect(crate::errors::SCAN_CONFIG_NOT_RESOLVED)
}
pub(crate) fn src_exclude_dirs(&self) -> &[String] {
self.src_exclude_dirs
.as_deref()
.expect(crate::errors::SCAN_CONFIG_NOT_RESOLVED)
}
pub(crate) fn src_exclude_files(&self) -> &[String] {
self.src_exclude_files
.as_deref()
.expect(crate::errors::SCAN_CONFIG_NOT_RESOLVED)
}
pub(crate) fn src_exclude_paths(&self) -> &[String] {
self.src_exclude_paths
.as_deref()
.expect(crate::errors::SCAN_CONFIG_NOT_RESOLVED)
}
pub(crate) fn src_files(&self) -> &[String] {
self.src_files
.as_deref()
.expect(crate::errors::SCAN_CONFIG_NOT_RESOLVED)
}
/// Return the command string, or error with context if it was never set.
pub(crate) fn require_command(&self, context: &str) -> anyhow::Result<&str> {
if self.command.is_empty() {
anyhow::bail!("'command' is not set for processor '{context}'");
}
Ok(&self.command)
}
}
/// Lets `SimpleChecker`/`SimpleGenerator` be generic over their config type:
/// every processor config either *is* a `StandardConfig` or wraps one, and
/// this is how the generic code reaches the scan/discover half of it.
impl AsRef<Self> for StandardConfig {
fn as_ref(&self) -> &Self {
self
}
}
impl KnownFields for StandardConfig {
fn known_fields() -> &'static [&'static str] {
// Note: "enabled" is universal — declared once in
// STANDARD_EXTRA_FIELDS and merged in by the validator, not repeated here.
&[
"command",
"formats",
"args",
"dep_inputs",
"dep_auto",
"output_dir",
"required_tools",
"batch",
"max_jobs",
]
}
fn checksum_fields() -> &'static [&'static str] {
// formats and output_dir are excluded: format is encoded as a per-product
// variant in the cache key, and output_dir is encoded in the product's
// declared outputs path — both would double-count if hashed here.
&["command", "args"]
}
fn field_descriptions() -> &'static [(&'static str, &'static str)] {
// The "enabled" description lives in SHARED_FIELD_DESCRIPTIONS.
&[
("command", "Path to the tool executable"),
("formats", "Output formats to generate"),
("args", "Extra arguments passed to the tool"),
(
"output_dir",
"Directory where generated output files are written",
),
(
"required_tools",
"Extra tools needed beyond `command` (for wrapper scripts)",
),
]
}
}
/// Simple checker config. No custom fields. A checker produces no files,
/// so every `SimpleChecker` plugin lists formats and `output_dir` in its
/// `omit_standard_fields`.
#[derive(Debug, Deserialize, Serialize, Clone, Default)]
pub struct CheckerConfig {
#[serde(flatten)]
pub standard: StandardConfig,
}
impl KnownFields for CheckerConfig {
fn known_fields() -> &'static [&'static str] {
StandardConfig::known_fields()
}
fn checksum_fields() -> &'static [&'static str] {
StandardConfig::checksum_fields()
}
fn field_descriptions() -> &'static [(&'static str, &'static str)] {
StandardConfig::field_descriptions()
}
}