Skip to main content

cargo_critpath/
cli.rs

1//! The command line: arguments, the pipeline they drive, and the exit codes.
2//!
3//! Cargo invokes an external subcommand as `cargo-critpath critpath <args>`, so a leading
4//! `critpath` word is accepted and skipped. Everything is written to a caller-supplied stream
5//! rather than to the process's own, which is what lets the tests read the output back.
6
7use core::fmt;
8use std::ffi::OsString;
9use std::io::{self, Write};
10use std::num::NonZeroU32;
11use std::path::{Path, PathBuf};
12
13use critpath_core::{analyze, Millis, Policy};
14use lexopt::ValueExt;
15
16use crate::findings;
17use crate::timings::TimingReport;
18use crate::{json, parse_with_metadata, report, ParseError};
19
20/// What the tool did, and the exit code that says so.
21///
22/// The codes are a contract with CI scripts: a threshold that was exceeded has to be
23/// distinguishable from a tool that could not run, or the script has to parse prose.
24#[derive(Clone, Copy, Debug, PartialEq, Eq)]
25#[non_exhaustive]
26pub enum Outcome {
27    /// The analysis ran and every threshold was met.
28    Completed,
29    /// The arguments were wrong, or a path could not be read.
30    Usage,
31    /// The input was not something this tool can analyse.
32    Rejected,
33    /// The analysis ran and a `--fail-if` threshold was exceeded.
34    ThresholdExceeded,
35}
36
37impl Outcome {
38    /// The process exit code for this outcome.
39    #[must_use]
40    pub const fn code(self) -> i32 {
41        match self {
42            Self::Completed => 0,
43            Self::Usage => 1,
44            Self::Rejected => 2,
45            Self::ThresholdExceeded => 3,
46        }
47    }
48}
49
50/// The help text, written by hand because the tool has no argument-parsing framework to generate
51/// one. See `docs/decisions.md`, D3, for why.
52const HELP: &str = "\
53cargo-critpath — what to change in a Cargo build, and how much time it would save
54
55USAGE
56    cargo critpath --log <path> --timings <path> [options]
57
58    Capture the two inputs from one clean build:
59
60        cargo clean
61        cargo build --timings -v --offline 2>build.log
62        cargo critpath --log build.log --timings target/cargo-timings/cargo-timing.html
63
64REQUIRED
65    --log <path>        the verbose build log: Cargo's stderr from `cargo build -v`
66    --timings <path>    a `cargo-timing.html` report from the same build. Repeatable: give one
67                        per clean build of the same commit and the run-to-run spread of the
68                        critical path is measured, so that a saving smaller than the noise can
69                        be marked as such
70
71OPTIONS
72    --metadata <path>   `cargo metadata --format-version 1` output, which attributes a
73                        workspace-local source path to its package exactly rather than by
74                        directory name
75    --jobs <n>          how many executors to analyse for. Defaults to the -j the build ran with
76    --format <f>        human (default) or json. The JSON contract is documented at
77                        https://github.com/eventvoid/cargo-critpath/blob/main/docs/json-schema.md
78    --policy <p>        cargo-like (default), which reproduces Cargo's cost-blind ordering, or
79                        longest-path, which schedules better than Cargo does. The gap between
80                        them is what Cargo's ordering alone costs
81    --include-units     add the per-unit array to the JSON output
82    --top <n>           how many ranked units and scenarios to show (default 10)
83    --fail-if-critical-path-over <ms>
84                        exit 3 if the critical path is longer than this
85    --help              print this and exit
86    --version           print the version and exit
87
88EXIT CODES
89    0  the analysis completed
90    1  the arguments were wrong, or a path could not be read
91    2  the input was rejected: fresh units, an unreadable report, or a build that was not
92       `cargo build`
93    3  the analysis completed and a --fail-if threshold was exceeded
94
95WHAT THIS DOES NOT DO
96    It analyses `cargo build` only, and refuses a report from `cargo check`, `cargo test` or
97    `cargo doc` by name: those are different graphs, not variations on one.
98    Every weight comes from one real build at one executor count and is not invariant to it, so
99    an absolute time for another executor count is marked unreliable rather than presented.
100    A split cannot be modelled exactly, so it is reported as an interval with its assumptions
101    printed, never as a single number.
102";
103
104/// The options a run was asked for.
105struct Options {
106    log: PathBuf,
107    timings: Vec<PathBuf>,
108    metadata: Option<PathBuf>,
109    jobs: Option<NonZeroU32>,
110    format: Format,
111    policy: Policy,
112    include_units: bool,
113    top: usize,
114    fail_if_over: Option<Millis>,
115}
116
117/// Which renderer to use.
118#[derive(Clone, Copy, PartialEq, Eq)]
119enum Format {
120    Human,
121    Json,
122}
123
124/// What the arguments asked the tool to do.
125enum Command {
126    Help,
127    Version,
128    Analyse(Box<Options>),
129}
130
131/// Every option the tool accepts, for the message an unknown one produces.
132const OPTIONS: &str = "--log, --timings, --metadata, --jobs, --format, --policy, --include-units, \
133                       --top, --fail-if-critical-path-over, --help, --version";
134
135/// An argument that could not be used, and what to do about it.
136enum UsageError {
137    Unknown(String),
138    Unexpected(String),
139    MissingValue(String),
140    BadValue {
141        option: &'static str,
142        value: String,
143        expected: &'static str,
144    },
145    Missing(&'static str),
146    Unreadable {
147        path: String,
148        detail: String,
149    },
150    /// The file was read but holds something other than the UTF-8 text Cargo writes.
151    MisEncoded {
152        detail: String,
153    },
154    ExecutorCountUnknown,
155}
156
157impl fmt::Display for UsageError {
158    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
159        match self {
160            Self::Unknown(option) => write!(
161                f,
162                "unknown option `{option}`. The options are: {OPTIONS}. \
163                 Run `cargo critpath --help` for what each one does"
164            ),
165            Self::Unexpected(value) => write!(
166                f,
167                "unexpected argument `{value}`: this tool takes options only, apart from the \
168                 `critpath` word Cargo itself inserts. The options are: {OPTIONS}"
169            ),
170            Self::MissingValue(option) => write!(
171                f,
172                "the option `{option}` needs a value and was given none. \
173                 Run `cargo critpath --help` for what it expects"
174            ),
175            Self::BadValue {
176                option,
177                value,
178                expected,
179            } => write!(
180                f,
181                "`{value}` is not a usable value for `{option}`: {expected}"
182            ),
183            Self::Missing(option) => write!(
184                f,
185                "`{option}` is required and was not given. \
186                 Capture both inputs from one clean build with \
187                 `cargo build --timings -v --offline 2>build.log`, then pass the log to `--log` \
188                 and `target/cargo-timings/cargo-timing.html` to `--timings`"
189            ),
190            Self::Unreadable { path, detail } => write!(
191                f,
192                "cannot read `{path}`: {detail}. \
193                 Check the path, and that the build that was supposed to write it completed"
194            ),
195            // No advice about the path or the build: the file was found and read, and neither is
196            // the problem.
197            Self::MisEncoded { detail } => write!(f, "{detail}"),
198            Self::ExecutorCountUnknown => write!(
199                f,
200                "the timing report does not record what `-j` the build ran with, so there is no \
201                 executor count to analyse for. Pass `--jobs <n>` to choose one"
202            ),
203        }
204    }
205}
206
207impl From<lexopt::Error> for UsageError {
208    fn from(error: lexopt::Error) -> Self {
209        match error {
210            lexopt::Error::UnexpectedOption(option) => Self::Unknown(option),
211            lexopt::Error::UnexpectedArgument(value) => {
212                Self::Unexpected(value.to_string_lossy().into_owned())
213            }
214            lexopt::Error::MissingValue { option } => {
215                Self::MissingValue(option.unwrap_or_else(|| "an option".to_owned()))
216            }
217            other => Self::Unknown(other.to_string()),
218        }
219    }
220}
221
222/// Runs the tool, writing its report to `out` and anything that went wrong to `err`.
223///
224/// `args` is the whole command line including the program name, as [`std::env::args_os`] gives it.
225/// Nothing is written to the process's own streams, so a caller can capture both.
226///
227/// ```no_run
228/// let mut out = Vec::new();
229/// let mut err = Vec::new();
230/// let outcome = cargo_critpath::cli::run(std::env::args_os(), &mut out, &mut err);
231/// std::process::exit(outcome.code());
232/// ```
233pub fn run<I>(args: I, out: &mut dyn Write, err: &mut dyn Write) -> Outcome
234where
235    I: IntoIterator,
236    I::Item: Into<OsString>,
237{
238    let command = match parse(args) {
239        Ok(command) => command,
240        Err(problem) => {
241            let _ = writeln!(err, "error: {problem}");
242            return Outcome::Usage;
243        }
244    };
245    match command {
246        Command::Help => {
247            let _ = write!(out, "{HELP}");
248            Outcome::Completed
249        }
250        Command::Version => {
251            let _ = writeln!(out, "cargo-critpath {}", env!("CARGO_PKG_VERSION"));
252            Outcome::Completed
253        }
254        Command::Analyse(options) => analyse(&options, out, err),
255    }
256}
257
258fn parse<I>(args: I) -> Result<Command, UsageError>
259where
260    I: IntoIterator,
261    I::Item: Into<OsString>,
262{
263    let mut log: Option<PathBuf> = None;
264    let mut timings: Vec<PathBuf> = Vec::new();
265    let mut metadata: Option<PathBuf> = None;
266    let mut jobs: Option<NonZeroU32> = None;
267    let mut format = Format::Human;
268    let mut policy = Policy::CargoLike;
269    let mut include_units = false;
270    let mut top = 10usize;
271    let mut fail_if_over: Option<Millis> = None;
272    let mut seen_subcommand = false;
273
274    let mut parser = lexopt::Parser::from_iter(args);
275    while let Some(argument) = parser.next()? {
276        match argument {
277            lexopt::Arg::Long("log") => log = Some(PathBuf::from(parser.value()?)),
278            lexopt::Arg::Long("timings") => timings.push(PathBuf::from(parser.value()?)),
279            lexopt::Arg::Long("metadata") => metadata = Some(PathBuf::from(parser.value()?)),
280            lexopt::Arg::Long("jobs") => {
281                let raw = parser.value()?.string()?;
282                jobs = Some(raw.parse().ok().and_then(NonZeroU32::new).ok_or(
283                    UsageError::BadValue {
284                        option: "--jobs",
285                        value: raw.clone(),
286                        expected: "it must be a whole number of executors, at least 1",
287                    },
288                )?);
289            }
290            lexopt::Arg::Long("format") => {
291                let raw = parser.value()?.string()?;
292                format = match raw.as_str() {
293                    "human" => Format::Human,
294                    "json" => Format::Json,
295                    _ => {
296                        return Err(UsageError::BadValue {
297                            option: "--format",
298                            value: raw,
299                            expected: "the formats are `human` and `json`",
300                        })
301                    }
302                };
303            }
304            lexopt::Arg::Long("policy") => {
305                let raw = parser.value()?.string()?;
306                policy = match raw.as_str() {
307                    "cargo-like" => Policy::CargoLike,
308                    "longest-path" => Policy::LongestPath,
309                    _ => {
310                        return Err(UsageError::BadValue {
311                            option: "--policy",
312                            value: raw,
313                            expected: "the policies are `cargo-like` and `longest-path`",
314                        })
315                    }
316                };
317            }
318            lexopt::Arg::Long("include-units") => include_units = true,
319            lexopt::Arg::Long("top") => {
320                let raw = parser.value()?.string()?;
321                top = raw.parse().map_err(|_| UsageError::BadValue {
322                    option: "--top",
323                    value: raw.clone(),
324                    expected: "it must be a whole number of entries, and may be 0",
325                })?;
326            }
327            lexopt::Arg::Long("fail-if-critical-path-over") => {
328                let raw = parser.value()?.string()?;
329                let ms: u64 = raw.parse().map_err(|_| UsageError::BadValue {
330                    option: "--fail-if-critical-path-over",
331                    value: raw.clone(),
332                    expected: "it must be a whole number of milliseconds",
333                })?;
334                fail_if_over = Some(Millis::new(ms));
335            }
336            lexopt::Arg::Long("help") => return Ok(Command::Help),
337            lexopt::Arg::Long("version") => return Ok(Command::Version),
338            // Cargo runs an external subcommand as `cargo-critpath critpath …`, so the first
339            // positional argument is the subcommand's own name.
340            lexopt::Arg::Value(value) if !seen_subcommand && value == *"critpath" => {
341                seen_subcommand = true;
342            }
343            lexopt::Arg::Value(value) => {
344                return Err(UsageError::Unexpected(value.to_string_lossy().into_owned()))
345            }
346            lexopt::Arg::Long(name) => return Err(UsageError::Unknown(format!("--{name}"))),
347            lexopt::Arg::Short(letter) => return Err(UsageError::Unknown(format!("-{letter}"))),
348        }
349    }
350
351    let log = log.ok_or(UsageError::Missing("--log"))?;
352    if timings.is_empty() {
353        return Err(UsageError::Missing("--timings"));
354    }
355    Ok(Command::Analyse(Box::new(Options {
356        log,
357        timings,
358        metadata,
359        jobs,
360        format,
361        policy,
362        include_units,
363        top,
364        fail_if_over,
365    })))
366}
367
368fn analyse(options: &Options, out: &mut dyn Write, err: &mut dyn Write) -> Outcome {
369    let log = match read(&options.log) {
370        Ok(text) => text,
371        Err(problem) => return usage(err, &problem),
372    };
373    let metadata = match options.metadata.as_deref() {
374        Some(path) => match read(path) {
375            Ok(text) => Some(text),
376            Err(problem) => return usage(err, &problem),
377        },
378        None => None,
379    };
380    let mut reports = Vec::with_capacity(options.timings.len());
381    for path in &options.timings {
382        match read(path) {
383            Ok(text) => reports.push(text),
384            Err(problem) => return usage(err, &problem),
385        }
386    }
387
388    // The subcommand is decided before anything is matched, because a parser written against the
389    // `cargo build` alphabet does not merely degrade on another subcommand's report: it silently
390    // produces a smaller graph with a meaningless critical path.
391    for text in &reports {
392        let report = match crate::parse_timing_report(text) {
393            Ok(report) => report,
394            Err(problem) => return rejected(err, &problem),
395        };
396        if let Some(subcommand) = subcommand_of(&report) {
397            let _ = writeln!(
398                err,
399                "error: this timing report is from `{subcommand}`, which this tool does not \
400                 analyse. Only `cargo build` is supported, because the other subcommands build \
401                 genuinely different graphs: on one measured project, `cargo build` and \
402                 `cargo check` shared exactly one unit on their critical paths. Capture a build \
403                 with `cargo clean && cargo build --timings -v --offline 2>build.log`"
404            );
405            return Outcome::Rejected;
406        }
407    }
408
409    let mut builds = Vec::with_capacity(reports.len());
410    for text in &reports {
411        match parse_with_metadata(&log, text, metadata.as_deref()) {
412            Ok(build) => builds.push(build),
413            Err(problem) => return rejected(err, &problem),
414        }
415    }
416    let Some(primary) = builds.first() else {
417        return usage(err, &UsageError::Missing("--timings"));
418    };
419
420    let executors = match options
421        .jobs
422        .or_else(|| primary.build.jobs.and_then(NonZeroU32::new))
423    {
424        Some(executors) => executors,
425        None => return usage(err, &UsageError::ExecutorCountUnknown),
426    };
427    let samples: Vec<Millis> = builds
428        .iter()
429        .map(|build| analyze(&build.graph).critical_path_len())
430        .collect();
431
432    let findings = findings::assemble(primary, &samples, executors, options.policy, options.top);
433    let written = match options.format {
434        Format::Human => report::write(out, &findings),
435        Format::Json => json::write(out, &findings, options.include_units),
436    };
437    if let Err(problem) = written {
438        let _ = writeln!(err, "error: cannot write the report: {problem}");
439        return Outcome::Usage;
440    }
441
442    match options.fail_if_over {
443        Some(limit) if findings.baseline.critical_path > limit => {
444            let _ = writeln!(
445                err,
446                "error: the critical path is {} against the {limit} limit given by \
447                 --fail-if-critical-path-over",
448                findings.baseline.critical_path
449            );
450            Outcome::ThresholdExceeded
451        }
452        _ => Outcome::Completed,
453    }
454}
455
456/// The Cargo subcommand a timing report came from, when it was not `cargo build`.
457///
458/// The `target` field is a display string whose alphabet depends on the subcommand, recorded in
459/// `docs/cargo-data-sources.md`: `cargo check` suffixes `(check)`, `cargo test` `(test)` and
460/// `(doc test)`, and so on. `cargo build` never suffixes anything.
461fn subcommand_of(report: &TimingReport) -> Option<&'static str> {
462    const MARKERS: [(&str, &str); 5] = [
463        ("(doc test)", "cargo test"),
464        ("(test)", "cargo test"),
465        ("(bench)", "cargo bench"),
466        ("(check)", "cargo check"),
467        ("(doc)", "cargo doc"),
468    ];
469    report.units.iter().find_map(|unit| {
470        let label = unit.target.label();
471        MARKERS
472            .iter()
473            .find(|(marker, _)| label.ends_with(marker))
474            .map(|(_, command)| *command)
475    })
476}
477
478fn read(path: &Path) -> Result<String, UsageError> {
479    crate::collect::read_text(path).map_err(|problem| {
480        if problem.kind() == io::ErrorKind::InvalidData {
481            UsageError::MisEncoded {
482                detail: problem.to_string(),
483            }
484        } else {
485            UsageError::Unreadable {
486                path: path.display().to_string(),
487                detail: problem.to_string(),
488            }
489        }
490    })
491}
492
493fn usage(err: &mut dyn Write, problem: &UsageError) -> Outcome {
494    let _ = writeln!(err, "error: {problem}");
495    match problem {
496        // The file was found and read; what it holds is unusable. That is the same outcome as a
497        // report this tool cannot analyse, and it must not depend on whether the file happened to
498        // carry a byte-order mark: a mis-encoded log without one is caught by the parser and
499        // reported as rejected, and one with a BOM has to agree.
500        UsageError::MisEncoded { .. } => Outcome::Rejected,
501        _ => Outcome::Usage,
502    }
503}
504
505fn rejected(err: &mut dyn Write, problem: &ParseError) -> Outcome {
506    let _ = writeln!(err, "error: {problem}");
507    Outcome::Rejected
508}