Skip to main content

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}