drep/languages/runner/mod.rs
1//! Run a project's own deterministic checkers and turn their output into Findings.
2//!
3//! This is the gating half of analysis. Tool findings are precise - they come
4//! from the rules the project itself configured - so they block, while the
5//! LLM's semantic findings inform. Keeping the two apart by *source* rather
6//! than by severity is what makes the gate calibratable at all.
7//!
8//! Three states, deliberately distinct:
9//!
10//! - [`ToolStatus::Ok`] the tool ran; its findings are authoritative.
11//! - [`ToolStatus::Skipped`] the project has not configured this tool, so it
12//! has no opinion here. A pass.
13//! - [`ToolStatus::Unavailable`] the tool should have run and could not.
14//! **Not** a pass - reporting it as clean is the same "unanalyzed is not
15//! clean" mistake that would let a commit gate rubber-stamp commits.
16
17use std::ffi::OsStr;
18use std::path::{Path, PathBuf};
19use std::process::{Output, Stdio};
20use std::time::Duration;
21
22use tokio::process::Command;
23use tokio::time::Instant;
24
25use crate::analysis::findings::Finding;
26use crate::languages::spec::{
27 DEFAULT_TOOL_TIMEOUT_SECS, DiagnosticsStream, ToolArguments, ToolSpec,
28};
29
30mod ancestry;
31mod go_packages;
32mod markers;
33mod narrow;
34pub mod parsers;
35mod uri;
36
37pub(crate) use parsers::TYPE_CHECK_KIND;
38pub use parsers::parse_output;
39
40pub(crate) use ancestry::absolute;
41pub(crate) use ancestry::ancestors_within;
42pub(crate) use ancestry::lexically_normal;
43pub(crate) use markers::configured_marker;
44pub use markers::is_configured;
45pub(crate) use markers::marker_names_path;
46pub(crate) use narrow::joined_reported;
47use narrow::retain_requested;
48
49#[cfg(test)]
50mod tests;
51
52/// Default ceiling for deterministic tools. Individual tools can extend it
53/// when their own execution model includes a legitimate wait, such as Cargo's
54/// build-directory lock.
55pub const TOOL_TIMEOUT: Duration = Duration::from_secs(DEFAULT_TOOL_TIMEOUT_SECS);
56
57/// Whether a tool ran, declined to run, or failed to.
58///
59/// The three are distinct because only the third is a problem: `Skipped` is
60/// the project exercising a choice, `Unavailable` is drep failing to check
61/// something it was supposed to.
62#[derive(Debug, Clone, PartialEq, Eq)]
63pub enum ToolStatus {
64 /// The tool ran. Its findings are authoritative.
65 Ok,
66 /// The project has not configured this tool, so it has no opinion here.
67 Skipped,
68 /// The tool should have run and could not. **Not** a pass.
69 Unavailable,
70}
71
72/// What happened when one tool was asked to check some files.
73#[derive(Debug, Clone, PartialEq, Eq)]
74pub struct ToolOutcome {
75 pub tool: &'static str,
76 pub status: ToolStatus,
77 pub findings: Vec<Finding>,
78 pub detail: String,
79 pub compilation_succeeded: bool,
80 /// Requested files the tool did not check because the project's build excludes them, as given: a `//go:build tools` file, an `x_windows.go` on a Mac. Not failures and not compiled, the same as CI's `go vet ./...` treats them. See [`ToolArguments::GoPackages`].
81 pub excluded: Vec<String>,
82}
83
84impl ToolOutcome {
85 fn skipped(spec: &ToolSpec) -> Self {
86 let listed = spec.config_files[..spec.config_files.len().min(3)].join(", ");
87 Self::empty(
88 spec,
89 ToolStatus::Skipped,
90 format!("not configured (add one of: {listed})"),
91 )
92 }
93
94 fn unavailable(spec: &ToolSpec, detail: String) -> Self {
95 Self::empty(spec, ToolStatus::Unavailable, detail)
96 }
97
98 fn ready(spec: &ToolSpec) -> Self {
99 Self::empty(spec, ToolStatus::Ok, "ready".to_owned())
100 }
101
102 fn empty(spec: &ToolSpec, status: ToolStatus, detail: String) -> Self {
103 Self {
104 tool: spec.name,
105 status,
106 findings: Vec::new(),
107 detail,
108 compilation_succeeded: false,
109 excluded: Vec::new(),
110 }
111 }
112}
113
114/// The tool produced output we could not parse.
115///
116/// Raised rather than swallowed: unparseable output means we do not know
117/// whether the file is clean, and guessing "clean" is the failure this module
118/// exists to prevent.
119#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
120#[error("{0}")]
121pub struct ToolOutputError(pub String);
122
123/// Whether a path is a regular file that the OS will execute.
124///
125/// `pub(crate)` because `cli::init` needs the same answer when it decides
126/// whether a git hook will actually run - git ignores a non-executable hook
127/// silently, which is the same class of failure this function was written for.
128/// Two definitions of "executable" that could disagree is exactly the bug.
129///
130/// One function with the `cfg` inside its body, not two cfg-gated
131/// definitions. Two definitions means the inactive one is unreachable on
132/// this platform, so every mutation of it survives by construction and
133/// shows up as an untestable finding in `cargo mutants`. This way the
134/// mutation lands in code the tests actually run.
135pub(crate) fn is_executable(path: &Path) -> bool {
136 #[cfg(unix)]
137 {
138 use std::os::unix::fs::PermissionsExt;
139 match path.metadata() {
140 Ok(meta) => meta.is_file() && meta.permissions().mode() & 0o111 != 0,
141 Err(_) => false,
142 }
143 }
144 // Windows has no executable bit; existence is the only signal there is.
145 #[cfg(not(unix))]
146 {
147 path.is_file()
148 }
149}
150
151/// Find the executable for a tool, preferring the project's own copy.
152///
153/// Repo-local first so a project is checked by the version its CI runs -
154/// `node_modules/.bin/eslint` rather than whatever happens to be installed
155/// globally, which may resolve plugins differently or not at all.
156///
157/// A path that exists but is not executable is **skipped**, not failed -
158/// half-installed shims on `PATH` would otherwise block a tool that
159/// happens to be on PATH under the same name.
160pub fn resolve_tool(spec: &ToolSpec, root: &Path) -> Option<PathBuf> {
161 resolve_tool_in(spec, root, std::env::var_os("PATH").as_deref())
162}
163
164/// `resolve_tool`, against an explicit `PATH` value. See [`which_first_in`]
165/// for why this seam exists.
166pub(crate) fn resolve_tool_in(
167 spec: &ToolSpec,
168 root: &Path,
169 path: Option<&std::ffi::OsStr>,
170) -> Option<PathBuf> {
171 resolve_tool_at(spec, root, root, path)
172}
173
174/// Resolve a tool for a configured workspace, allowing dependencies hoisted
175/// to any ancestor up to the repository root.
176fn resolve_tool_at(
177 spec: &ToolSpec,
178 repository_root: &Path,
179 workspace_root: &Path,
180 path: Option<&std::ffi::OsStr>,
181) -> Option<PathBuf> {
182 for directory in ancestors_within(workspace_root, repository_root) {
183 for relative in spec.local_paths {
184 let candidate = directory.join(relative);
185 if is_executable(&candidate) {
186 return Some(candidate);
187 }
188 }
189 }
190
191 // `first()`, not `[0]`. A `ToolSpec` with an empty `command` is a
192 // definitions bug, but this function is documented never to panic and a
193 // panic here would take the whole gate down rather than reporting the
194 // tool unavailable.
195 let name = spec.command.first()?;
196 which_first_in(name, path?).map(PathBuf::from)
197}
198
199/// Look up `command` on PATH; `std::process::Command` does not expose this
200/// resolution directly.
201///
202/// Crucially checks executability, not just existence: a half-installed
203/// shim on PATH that is not executable would otherwise be reported as `Ok`
204/// by `tool_status` only to fail when `run_tool` actually executed it.
205/// Using the same `is_executable` helper the repo-local branch uses keeps
206/// the two paths consistent — a path that passes one is rejected by the
207/// other is the bug this guard exists to prevent.
208/// `which_first`, against an explicit `PATH` value.
209///
210/// Split out so tests can exercise PATH lookup without mutating the process
211/// environment. `std::env::set_var` is `unsafe` in edition 2024 because any
212/// other thread reading the environment concurrently is a data race - and
213/// these tests run beside ones that spawn `git`, which reads `PATH` to find
214/// it. A test-local mutex cannot fix that: it excludes other tests that take
215/// the same mutex, not every reader in the process. Passing the value in
216/// removes the shared mutable state instead of guarding it.
217fn which_first_in(command: &str, path: &std::ffi::OsStr) -> Option<String> {
218 for dir in std::env::split_paths(path) {
219 let candidate = dir.join(command);
220 if is_executable(&candidate) {
221 return Some(candidate.to_string_lossy().into_owned());
222 }
223 }
224 None
225}
226
227/// The nearest configured ancestor for `file`, bounded by `repository_root`.
228///
229/// Looking along the file's ancestor chain avoids both monorepo blind spots
230/// and accidental discovery in unrelated dependency/build directories.
231pub(crate) fn configuration_root(
232 spec: &ToolSpec,
233 repository_root: &Path,
234 file: &Path,
235) -> Option<PathBuf> {
236 let repository_root = absolute(repository_root);
237 let file = if file.is_absolute() {
238 file.to_path_buf()
239 } else {
240 repository_root.join(file)
241 };
242 ancestors_within(file.parent()?, &repository_root)
243 .into_iter()
244 .find(|directory| is_configured(spec, directory))
245}
246
247/// Whether this tool will run here, without running it.
248///
249/// The single derivation of eligibility, so `drep doctor` reports exactly
250/// what `drep check` will do. Deriving it twice means doctor confidently
251/// says "ready" for a tool check then skips - the failure doctor exists
252/// to prevent.
253pub fn tool_status(spec: &ToolSpec, root: &Path) -> ToolOutcome {
254 tool_status_at(spec, root, root)
255}
256
257/// Run one deterministic tool over some files.
258///
259/// Never returns an error and never panics for an absent or failing tool;
260/// that is reported as [`ToolStatus::Unavailable`] so the caller can surface
261/// it rather than mistake it for a clean result.
262pub async fn run_tool(spec: &ToolSpec, root: &Path, files: &[String]) -> ToolOutcome {
263 run_tool_at(spec, root, root, files).await
264}
265
266/// Run a tool from one configured workspace, resolving hoisted executables
267/// through the repository root.
268pub(crate) async fn run_tool_at(
269 spec: &ToolSpec,
270 repository_root: &Path,
271 workspace_root: &Path,
272 files: &[String],
273) -> ToolOutcome {
274 let executable = match eligible_executable(spec, repository_root, workspace_root) {
275 Ok(executable) => executable,
276 Err(outcome) => return outcome,
277 };
278
279 // Absolutised before spawning. `resolve_tool` returns `root.join(relative)`
280 // for a repo-local hit, and the child gets `current_dir(root)` below - so a
281 // relative `root` like "repo" produced "repo/node_modules/.bin/eslint"
282 // resolved *from* "repo", i.e. "repo/repo/node_modules/...". It works today
283 // only because the CLI passes "." and the tests pass absolute temp dirs.
284 let executable = if executable.is_relative() {
285 std::env::current_dir()
286 .map(|cwd| cwd.join(&executable))
287 .unwrap_or(executable)
288 } else {
289 executable
290 };
291
292 let mut argv: Vec<String> = Vec::with_capacity(spec.command.len() + files.len() + 2);
293 argv.push(executable.to_string_lossy().into_owned());
294 argv.extend(spec.command[1..].iter().map(|s| (*s).to_owned()));
295 // A tool that will not look for its own config gets handed the one
296 // `config_files` found - through the same lookup that decided the tool was
297 // configured at all, so the two cannot disagree about what counts.
298 if let Some(flag) = spec.config_flag
299 && let Some(config) = configured_marker(spec, workspace_root)
300 {
301 argv.push(flag.to_owned());
302 argv.push(config);
303 }
304 // One ceiling for the whole tool: `go list` and `go vet` share it rather than getting one each.
305 let deadline = Instant::now() + Duration::from_secs(spec.timeout_secs);
306 let mut excluded = Vec::new();
307 let mut directories = Vec::new();
308 match spec.arguments {
309 ToolArguments::Files => argv.extend(file_arguments(files)),
310 ToolArguments::Project => {}
311 ToolArguments::GoPackages => {
312 let plan = match go_packages::plan(&executable, workspace_root, files, deadline).await {
313 Ok(plan) => plan,
314 Err(detail) => return ToolOutcome::unavailable(spec, detail),
315 };
316 // See `ToolArguments::GoPackages`: a load error aborts the whole vet call, so it is the answer.
317 if !plan.load_errors.is_empty() {
318 return ToolOutcome {
319 findings: plan.load_errors,
320 excluded: plan.excluded,
321 ..ToolOutcome::empty(
322 spec,
323 ToolStatus::Ok,
324 "a package failed to load".to_owned(),
325 )
326 };
327 }
328 if plan.directories.is_empty() {
329 return ToolOutcome {
330 excluded: plan.excluded,
331 ..ToolOutcome::empty(
332 spec,
333 ToolStatus::Skipped,
334 "the build excludes every file".to_owned(),
335 )
336 };
337 }
338 argv.extend(plan.directories.iter().cloned());
339 directories = plan.directories;
340 excluded = plan.excluded;
341 }
342 }
343
344 let mut outcome = execute(spec, &argv, workspace_root, files, &directories, deadline).await;
345 outcome.excluded = excluded;
346 outcome
347}
348
349/// Spawn `argv` from `workspace_root` and read its diagnostics into an outcome for `files`. `directories` are the package directories a [`ToolArguments::GoPackages`] tool was handed, as `./dir`, and empty for any other.
350async fn execute(
351 spec: &ToolSpec,
352 argv: &[String],
353 workspace_root: &Path,
354 files: &[String],
355 directories: &[String],
356 deadline: Instant,
357) -> ToolOutcome {
358 let output = match run_bounded(&argv[0], &argv[1..], workspace_root, deadline).await {
359 Ok(output) => output,
360 Err(Bounded::Failed(err)) => {
361 return ToolOutcome::unavailable(
362 spec,
363 format!("{} could not be executed: {err}", spec.name),
364 );
365 }
366 Err(Bounded::TimedOut) => {
367 let context = spec.timeout_context.unwrap_or_default();
368 return ToolOutcome::unavailable(
369 spec,
370 format!(
371 "{} timed out after {}s{context}",
372 spec.name, spec.timeout_secs
373 ),
374 );
375 }
376 };
377
378 // The exit code alone is not a verdict: ruff/eslint/clippy exit non-zero
379 // *because* they found issues, and that is the success path. But it is not
380 // irrelevant either. A tool that exits non-zero having produced no
381 // diagnostics at all did not run - a bad config, a crash, a bad
382 // invocation - and reporting that as `Ok` with zero findings is precisely
383 // the "unavailable is not a pass" failure this module exists to prevent.
384 // So the rule is the conjunction: non-zero AND nothing on the diagnostics
385 // stream. For the skipping parsers the conjunction needs a second form:
386 // they drop lines they do not recognise by design, so a run whose every
387 // diagnostic is of a shape they do not know - an SDK error such as
388 // MSBuild's position-less `x.csproj : error NETSDK1004`, a rejected tsc
389 // option - parses as zero findings on a *non-empty* stream, invisible to
390 // the first form. The JSON-shaped parsers error on such output instead,
391 // which is already `Unavailable`.
392 let stdout = String::from_utf8_lossy(&output.stdout);
393 let stderr = String::from_utf8_lossy(&output.stderr);
394 let (diagnostics, other) = match spec.diagnostics_stream {
395 DiagnosticsStream::Stderr => (stderr.as_ref(), stdout.as_ref()),
396 DiagnosticsStream::Stdout => (stdout.as_ref(), stderr.as_ref()),
397 };
398
399 let parse_result = parse_output(
400 spec,
401 diagnostics,
402 files.first().map(String::as_str).unwrap_or(""),
403 );
404 let compilation_succeeded = spec.establishes_compilation && output.status.success();
405 match parse_result {
406 Ok(findings)
407 if findings.is_empty() && !output.status.success() && diagnostics.trim().is_empty() =>
408 {
409 // Exited non-zero, said nothing on the stream we read for
410 // diagnostics, and produced no findings. Whatever it did, it did
411 // not check the files. The other stream usually carries the real
412 // error, so it becomes the detail.
413 ToolOutcome::unavailable(
414 spec,
415 format!(
416 "{} exited {} without producing diagnostics: {}",
417 spec.name,
418 exit_word(&output.status),
419 stream_detail(other)
420 ),
421 )
422 }
423 Ok(findings)
424 if findings.is_empty()
425 && !output.status.success()
426 && spec.output_format.skips_unmatched_input() =>
427 {
428 // Exited non-zero and every line it did produce was dropped by a
429 // parser that skips what it cannot match: the run failed in a
430 // shape the parser does not know. The unmatched lines are the
431 // diagnostic, so they become the detail.
432 ToolOutcome::unavailable(
433 spec,
434 format!(
435 "{} exited {} without a recognisable diagnostic: {}",
436 spec.name,
437 exit_word(&output.status),
438 stream_detail(diagnostics)
439 ),
440 )
441 }
442 Ok(findings) => ToolOutcome {
443 tool: spec.name,
444 status: ToolStatus::Ok,
445 findings: retain_requested(spec, findings, files, directories, workspace_root),
446 detail: stream_detail(other),
447 compilation_succeeded,
448 excluded: Vec::new(),
449 },
450 Err(err) => ToolOutcome::unavailable(
451 spec,
452 format!("{err}. other stream: {}", stream_detail(other)),
453 ),
454 }
455}
456
457/// Why [`run_bounded`] produced no output.
458pub(super) enum Bounded {
459 /// The process could not be spawned, or its streams could not be read.
460 Failed(std::io::Error),
461 /// The process was still running at the deadline, and was killed.
462 TimedOut,
463}
464
465/// Run `program` with `args` from `cwd`, stdin closed and both streams captured, killing it if it is still running at `deadline`.
466///
467/// `wait_with_output` drains both pipes into buffers before returning, and rejects on any IO error from the spawn or the read. `kill_on_drop` is what kills the process when the deadline drops that future.
468pub(super) async fn run_bounded(
469 program: impl AsRef<OsStr>,
470 args: impl IntoIterator<Item = impl AsRef<OsStr>>,
471 cwd: &Path,
472 deadline: Instant,
473) -> Result<Output, Bounded> {
474 let mut command = Command::new(program);
475 command.args(args);
476 command.current_dir(cwd);
477 command.stdin(Stdio::null());
478 command.stdout(Stdio::piped());
479 command.stderr(Stdio::piped());
480 command.kill_on_drop(true);
481 let child = command.spawn().map_err(Bounded::Failed)?;
482 match tokio::time::timeout_at(deadline, child.wait_with_output()).await {
483 Ok(result) => result.map_err(Bounded::Failed),
484 Err(_) => Err(Bounded::TimedOut),
485 }
486}
487
488/// The files a [`ToolArguments::Files`] tool is handed.
489///
490/// A repository can contain a file whose name begins with `-`, and every checker here would read `--fix` as an option rather than a path. `--` is the conventional guard but is not universally supported across ruff/eslint/tsc/gofmt/go vet/clippy, whereas a `./` prefix is unambiguous to any argument parser and leaves ordinary paths untouched. A Go package directory already carries one.
491fn file_arguments(files: &[String]) -> impl Iterator<Item = String> + '_ {
492 files.iter().map(|f| {
493 if f.starts_with('-') {
494 format!("./{f}")
495 } else {
496 f.clone()
497 }
498 })
499}
500
501pub(crate) fn tool_status_at(
502 spec: &ToolSpec,
503 repository_root: &Path,
504 workspace_root: &Path,
505) -> ToolOutcome {
506 match eligible_executable(spec, repository_root, workspace_root) {
507 Ok(_) => ToolOutcome::ready(spec),
508 Err(outcome) => outcome,
509 }
510}
511
512fn eligible_executable(
513 spec: &ToolSpec,
514 repository_root: &Path,
515 workspace_root: &Path,
516) -> Result<PathBuf, ToolOutcome> {
517 if !is_configured(spec, workspace_root) {
518 return Err(ToolOutcome::skipped(spec));
519 }
520 if let Some(executable) = resolve_tool_at(
521 spec,
522 repository_root,
523 workspace_root,
524 std::env::var_os("PATH").as_deref(),
525 ) {
526 return Ok(executable);
527 }
528 let looked = if spec.local_paths.is_empty() {
529 "PATH".to_owned()
530 } else if absolute(repository_root) == absolute(workspace_root) {
531 format!("{}, then PATH", spec.local_paths.join(", "))
532 } else {
533 format!(
534 "{} from {} through {}, then PATH",
535 spec.local_paths.join(", "),
536 workspace_root.display(),
537 repository_root.display()
538 )
539 };
540 Err(ToolOutcome::unavailable(
541 spec,
542 format!("configured but not found (looked in {looked})"),
543 ))
544}
545
546/// One of a tool's own streams, bounded for the `detail` field.
547///
548/// `crate::text::excerpt` is the single bounding of text drep did not write,
549/// and a tool's stdout and stderr are exactly that: they reach a terminal
550/// through `doctor` and through the failure block, so an escape sequence in
551/// them must be stripped rather than passed through. The predecessor here
552/// bounded *bytes* and stripped nothing, which is the second copy that rule
553/// exists to prevent.
554///
555/// The empty case is the one thing `excerpt` cannot answer for this caller.
556/// A clean run's other stream is legitimately empty and `detail` is then the
557/// empty string; `excerpt` returns `<nothing>`, which is right for a quoted
558/// model response and wrong for a field `doctor` prints after a colon.
559pub(crate) fn stream_detail(stream: &str) -> String {
560 let trimmed = stream.trim();
561 if trimmed.is_empty() {
562 return String::new();
563 }
564 crate::text::excerpt(trimmed, DETAIL_MAX_CHARS)
565}
566
567/// How much of a tool's stream reaches the `detail` field.
568const DETAIL_MAX_CHARS: usize = 200;
569
570/// How a process ended, for a diagnostic sentence.
571///
572/// Shared by the two `Unavailable` arms below so the signal wording has one
573/// definition rather than one per arm.
574fn exit_word(status: &std::process::ExitStatus) -> String {
575 status
576 .code()
577 .map_or("by signal".to_owned(), |code| code.to_string())
578}