Skip to main content

skif_cli/
lib.rs

1//! The `skif` command line as a library: a thin consumer of the `skif` library.
2//!
3//! It is the only code that reads the environment, prints, prompts, writes files, spawns a process and opens a network
4//! connection (`skif update` only); [`run`] returns an exit code and no function below calls `std::process::exit`.
5//! The npm addon calls [`run`]; the binary calls [`run_to_exit`], which also changes the current directory under
6//! `bazel run` and leaves the memory of a run to the operating system.
7
8use std::cell::Cell;
9use std::ffi::OsString;
10use std::io::Write;
11use std::sync::Once;
12
13use clap::Parser;
14use serde_json::Map;
15
16mod args;
17mod baseline;
18mod cache;
19mod cache_command;
20mod commands;
21mod config;
22mod config_toml;
23mod env;
24mod error;
25mod explain;
26mod filter;
27mod fix;
28mod format;
29mod install;
30mod instances;
31mod lint;
32mod lsp;
33mod mcp;
34mod migrate;
35mod npmrc;
36mod output;
37mod registry;
38mod roots;
39mod trace;
40mod update;
41mod watch;
42mod write;
43
44use args::{Cli, Command, Format};
45use env::Env;
46pub use error::{CliError, Kind};
47use lint::Teardown;
48pub use lint::{LintCache, lint_to_json, lint_to_json_cached};
49use output::{emit_error, emit_error_with};
50
51/// Runs the CLI with `args` (the first item is the program name, as in `std::env::args_os`) and returns the exit
52/// code. The npm addon calls this; the `skif` binary calls [`run_to_exit`], which differs only in what happens to
53/// memory and in entering the `bazel run` directory; everything else is shared, so their behaviour cannot drift.
54///
55/// It never changes the process's current directory, even under `bazel run`: in a host such as Node.js, which caches
56/// its own current directory, a change made here would leave the host out of step. A host that runs skif under
57/// `bazel run` enters that directory itself first, as the npm package's `skif` bin does (ADR 0011).
58///
59/// A panic in skif that reaches this call is caught and exits 2, as in the binary; the panic hook prints the message
60/// and its location to stderr, and with `--format json` or `toon` stdout also receives the `error` document (kind
61/// `internal`) naming both.
62///
63/// To learn the location, the first call chains a hook in front of the process's panic hook (`std::panic::set_hook`),
64/// once per process; it records the panic for the thread that raised it and then calls the hook it replaced, so the
65/// host's own handling still runs. A host that sets its own hook after that call drops the recording hook: a panic
66/// still exits 2, but the `error` document then names only the panic's payload, without the location.
67pub fn run(args: impl IntoIterator<Item = OsString>) -> u8 {
68    let raw: Vec<OsString> = args.into_iter().collect();
69    exit_two_on_panic(&raw, &mut std::io::stdout(), || run_with(raw.clone(), Teardown::Free))
70}
71
72thread_local! {
73    /// The last panic of this thread seen by the hook [`record_panics`] chains in front of the host's: its message
74    /// and location, which the payload that `catch_unwind` returns does not carry. Per thread, since `catch_unwind`
75    /// runs on the thread that panicked and a panic elsewhere in the process must not be reported as this one.
76    static LAST_PANIC: Cell<Option<String>> = const { Cell::new(None) };
77}
78
79/// Chains a hook in front of the current panic hook, once per process, that records each panic in [`LAST_PANIC`]
80/// and then calls the hook it replaced, so the host's panic handling is unchanged.
81fn record_panics() {
82    static ONCE: Once = Once::new();
83    ONCE.call_once(|| {
84        let previous = std::panic::take_hook();
85        std::panic::set_hook(Box::new(move |info| {
86            // A panic while the thread's locals are torn down goes unrecorded; the payload then describes it.
87            let _ = LAST_PANIC.try_with(|last| last.set(Some(info.to_string())));
88            previous(info);
89        }));
90    });
91}
92
93/// The stack of each worker of rayon's global pool. A worker that waits for a parallel job takes other queued jobs
94/// on its own stack, so the analyses of the roots of a recursive run nest on one worker, and with few cores that
95/// outgrew the 2 MiB default. Only the pages a thread touches are committed.
96const WORKER_STACK_SIZE: usize = 64 << 20;
97
98/// Builds rayon's global pool, once per process, with 64 MiB stacks. The thread count still follows
99/// `RAYON_NUM_THREADS`. A host that built the global pool first keeps its own.
100pub fn configure_global_pool() {
101    static ONCE: Once = Once::new();
102    ONCE.call_once(|| {
103        let _ = rayon::ThreadPoolBuilder::new()
104            .stack_size(WORKER_STACK_SIZE)
105            .thread_name(|index| format!("skif-worker-{index}"))
106            .build_global();
107    });
108}
109
110/// `body`'s exit code, or 2 when it panics, after the `internal` error document on `stdout` when `raw` asks for JSON
111/// or TOON.
112/// The panic hook has already printed the message and location to stderr. The document names the location the hook
113/// recorded on this thread, or only the payload when the hook did not run for this panic: a host replaced it, or the
114/// panic was raised on another thread and resumed here, after a panic `body` caught itself was recorded.
115fn exit_two_on_panic(raw: &[OsString], stdout: &mut dyn Write, body: impl FnOnce() -> u8) -> u8 {
116    record_panics();
117    LAST_PANIC.with(|last| last.set(None));
118    let outcome = std::panic::catch_unwind(std::panic::AssertUnwindSafe(body));
119    skif_core::timing::flush_stderr();
120    outcome.unwrap_or_else(|payload| {
121        let recorded = LAST_PANIC.with(Cell::take);
122        let format = error_format(raw);
123        if matches!(format, Format::Json | Format::Toon) {
124            let text = payload
125                .downcast_ref::<&str>()
126                .copied()
127                .or_else(|| payload.downcast_ref::<String>().map(String::as_str));
128            let report = match (recorded, text) {
129                (Some(recorded), Some(text)) if !recorded.ends_with(text) => text.to_owned(),
130                (Some(recorded), _) => recorded,
131                (None, text) => text.unwrap_or("panic").to_owned(),
132            };
133            emit_error_with(&internal_error(&report), format, Map::new(), stdout);
134        }
135        2
136    })
137}
138
139/// The error a panic becomes; `report` describes it: the panic hook's `panicked at <location>:` and the message, or
140/// the payload alone.
141fn internal_error(report: &str) -> CliError {
142    CliError::new(Kind::Internal, format!("internal error: {report}"))
143}
144
145/// Like [`run`], for a process that exits as soon as this returns: the lint command leaves its diagnostics, workspace
146/// model and file caches to the operating system instead of freeing them one allocation at a time, a measurable part
147/// of a large run. Never call it from a long-lived host such as the npm addon: that memory would leak on every call.
148///
149/// Under `bazel run` (`BUILD_WORKSPACE_DIRECTORY` is set) it first changes the process's current directory to
150/// `BUILD_WORKING_DIRECTORY`, else to the workspace root, so paths on the command line resolve as the user typed them
151/// rather than in the runfiles tree (ADR 0011); a directory it cannot enter exits 2.
152///
153/// A panic exits 2 as in [`run`]. The release binary unwinds (`panic = "unwind"`) instead of aborting, so the panic
154/// reaches this call.
155pub fn run_to_exit(args: impl IntoIterator<Item = OsString>) -> u8 {
156    let raw: Vec<OsString> = args.into_iter().collect();
157    if let Err(error) = env::enter_bazel_run_directory() {
158        emit_error(&error, error_format(&raw));
159        return 2;
160    }
161    exit_two_on_panic(&raw, &mut std::io::stdout(), || run_with(raw.clone(), Teardown::Leak))
162}
163
164fn run_with(args: impl IntoIterator<Item = OsString>, teardown: Teardown) -> u8 {
165    let raw: Vec<OsString> = args.into_iter().collect();
166    configure_global_pool();
167    env::enable_timings();
168    if let Some(error) = removed_flag(&raw) {
169        emit_error(&error, error_format(&raw));
170        return 2;
171    }
172    let cli = match Cli::try_parse_from(&raw) {
173        Ok(cli) => cli,
174        Err(error) => return usage(&raw, &error),
175    };
176    match cli.command {
177        None if cli.lint.watch => watch::run(&cli.lint, Env::detect()),
178        None => lint::run(&cli.lint, Env::detect(), teardown),
179        Some(Command::Rules(args)) => commands::rules(&args),
180        Some(Command::Schema) => commands::schema(),
181        Some(Command::Init(args)) => commands::init(&args),
182        Some(Command::Config(args)) => config::run(&args),
183        Some(Command::ExplainUsage(args)) => explain::run(&args),
184        Some(Command::Migrate(args)) => migrate::run(&args),
185        Some(Command::Baseline(args)) => baseline::run(&args),
186        Some(Command::Update(args)) => update::run(&args, Env::detect()),
187        Some(Command::List(args)) => instances::list(&args),
188        Some(Command::Json(args)) => instances::json(&args),
189        Some(Command::Format(args)) => format::run(&args, Env::detect(), teardown),
190        Some(Command::Cache(args)) => cache_command::run(&args),
191        Some(Command::Mcp) => mcp::run(),
192        Some(Command::Lsp) => lsp::run(),
193    }
194}
195
196/// The flags of the type-aware analysis, which skif 0.9.0 removed.
197const REMOVED_FLAGS: [&str; 2] = ["--type-aware", "--no-type-aware"];
198
199/// The usage error for a removed flag among the options of `raw` (before a `--`), so that it says the flag was removed
200/// where clap would only call it unexpected.
201fn removed_flag(raw: &[OsString]) -> Option<CliError> {
202    raw.iter()
203        .skip(1)
204        .take_while(|arg| arg.to_str() != Some("--"))
205        .filter_map(|arg| arg.to_str()?.split('=').next())
206        .find(|flag| REMOVED_FLAGS.contains(flag))
207        .map(|flag| {
208            CliError::new(
209                Kind::Usage,
210                format!(
211                    "`{flag}` is no longer a flag: type-aware analysis was removed in skif 0.9.0 and every member is \
212                     judged by name, as it was without types; drop the flag"
213                ),
214            )
215        })
216}
217
218/// Help and version go to stdout with exit 0; usage errors exit 2, as the `error` document when `--format json` or
219/// `--format toon` is on the command line.
220fn usage(raw: &[OsString], error: &clap::Error) -> u8 {
221    if !error.use_stderr() {
222        let _ = error.print();
223        return 0;
224    }
225    let format = error_format(raw);
226    if matches!(format, Format::Json | Format::Toon) {
227        let message = error.to_string();
228        emit_error(&CliError::new(Kind::Usage, message.trim_end()), format);
229    } else {
230        let _ = error.print();
231    }
232    2
233}
234
235/// The format of the errors the command line asks for: `json` or `toon` when that is the format that goes to stdout,
236/// or, when every `--format` names a file, the first one (ADR 0012); else human. Read from the raw arguments, before
237/// clap has parsed them.
238fn error_format(raw: &[OsString]) -> Format {
239    let args: Vec<&str> = raw.iter().filter_map(|arg| arg.to_str()).collect();
240    let mut values = Vec::new();
241    for (index, arg) in args.iter().enumerate() {
242        if let Some(value) = arg.strip_prefix("--format=") {
243            values.push(value);
244        } else if *arg == "--format" {
245            values.extend(args.get(index + 1));
246        }
247    }
248    let chosen = values
249        .iter()
250        .find(|value| !value.contains('='))
251        .or_else(|| values.first())
252        .and_then(|value| value.split('=').next());
253    match chosen {
254        Some("json") => Format::Json,
255        Some("toon") => Format::Toon,
256        _ => Format::Human,
257    }
258}
259
260#[cfg(test)]
261mod tests {
262    use super::*;
263
264    fn args(list: &[&str]) -> Vec<OsString> {
265        list.iter().map(OsString::from).collect()
266    }
267
268    #[test]
269    fn a_removed_type_aware_flag_is_named_before_clap_parses() {
270        for flag in REMOVED_FLAGS {
271            for raw in [
272                args(&["skif", flag]),
273                args(&["skif", "explain-usage", "a.ts", flag]),
274                args(&["skif", "baseline", "write", &format!("{flag}=true")]),
275            ] {
276                let error = removed_flag(&raw).unwrap_or_else(|| panic!("{raw:?}"));
277                assert_eq!(error.kind, Kind::Usage);
278                let message = error.to_string();
279                assert!(
280                    message.starts_with(&format!("`{flag}` is no longer a flag")),
281                    "{message}"
282                );
283                assert!(
284                    message.contains("type-aware analysis was removed in skif 0.9.0"),
285                    "{message}"
286                );
287            }
288        }
289        assert!(removed_flag(&args(&["skif", "--no-js", "."])).is_none());
290        assert!(
291            removed_flag(&args(&["skif", "--", "--type-aware"])).is_none(),
292            "a path after `--`"
293        );
294    }
295
296    #[test]
297    fn a_panic_exits_two_in_every_format() {
298        for (raw, format) in [
299            (args(&["skif"]), Format::Human),
300            (args(&["skif", "--format", "json"]), Format::Json),
301            (args(&["skif", "--format", "toon"]), Format::Toon),
302        ] {
303            let mut stdout = Vec::new();
304            assert_eq!(exit_two_on_panic(&raw, &mut stdout, || panic!("boom")), 2);
305            let text = String::from_utf8_lossy(&stdout);
306            let document: serde_json::Value = match format {
307                Format::Json => serde_json::from_str(&text).unwrap(),
308                Format::Toon => serde_toon::decode_to_value(&text).unwrap_or_else(|error| panic!("{error}: {text:?}")),
309                _ => {
310                    assert!(stdout.is_empty(), "{text}");
311                    continue;
312                }
313            };
314            assert_eq!(document["error"]["kind"], "internal", "{document:#}");
315            let message = document["error"]["message"].as_str().unwrap();
316            assert!(
317                message.starts_with("internal error: panicked at ")
318                    && message.contains("lib.rs:")
319                    && message.ends_with(":\nboom"),
320                "the message names the location and the panic: {message}"
321            );
322        }
323    }
324
325    /// The JSON `error` message of a run of `body` that exits 2.
326    fn panic_message(body: impl FnOnce() -> u8) -> String {
327        let mut stdout = Vec::new();
328        assert_eq!(
329            exit_two_on_panic(&args(&["skif", "--format", "json"]), &mut stdout, body),
330            2
331        );
332        let document: serde_json::Value = serde_json::from_slice(&stdout).unwrap();
333        document["error"]["message"].as_str().unwrap().to_owned()
334    }
335
336    #[test]
337    fn a_panic_on_another_thread_is_not_reported_as_this_one() {
338        // `resume_unwind` skips the panic hook, so only the payload describes this panic; the other thread's panic
339        // goes through the hook while this run is in progress.
340        let message = panic_message(|| {
341            let other = std::thread::spawn(|| std::panic::panic_any("another thread's panic"));
342            assert!(other.join().is_err(), "the other thread panicked");
343            std::panic::resume_unwind(Box::new("boom"))
344        });
345        assert_eq!(message, "internal error: boom");
346    }
347
348    #[test]
349    fn a_panic_caught_earlier_on_this_thread_is_not_reported_again() {
350        record_panics();
351        let earlier = std::panic::catch_unwind(|| std::panic::panic_any("an earlier panic"));
352        assert!(earlier.is_err(), "the earlier body panicked");
353        let message = panic_message(|| std::panic::resume_unwind(Box::new(String::from("boom"))));
354        assert_eq!(message, "internal error: boom");
355    }
356
357    #[test]
358    fn a_panic_caught_inside_the_run_does_not_end_it() {
359        let mut stdout = Vec::new();
360        let code = exit_two_on_panic(&args(&["skif", "--format", "json"]), &mut stdout, || {
361            let fallback = std::panic::catch_unwind(|| std::panic::panic_any("the checker's panic"));
362            assert!(fallback.is_err(), "the inner body panicked");
363            0
364        });
365        assert_eq!(code, 0);
366        assert_eq!(stdout, b"");
367    }
368
369    #[test]
370    fn a_panic_caught_inside_the_run_is_not_reported_as_the_one_that_ended_it() {
371        let message = panic_message(|| {
372            let fallback = std::panic::catch_unwind(|| std::panic::panic_any("the checker's panic"));
373            assert!(fallback.is_err(), "the inner body panicked");
374            std::panic::resume_unwind(Box::new("a worker's panic"))
375        });
376        assert_eq!(message, "internal error: a worker's panic");
377    }
378
379    #[test]
380    fn a_panic_of_a_rayon_worker_exits_two() {
381        let message = panic_message(|| {
382            rayon::scope(|scope| scope.spawn(|_| panic!("a worker's panic")));
383            0
384        });
385        assert!(message.ends_with("a worker's panic"), "{message}");
386    }
387
388    #[test]
389    fn without_a_panic_the_exit_code_is_the_body_s() {
390        let mut stdout = Vec::new();
391        assert_eq!(
392            exit_two_on_panic(&args(&["skif", "--format", "json"]), &mut stdout, || 1),
393            1
394        );
395        assert_eq!(stdout, b"");
396    }
397}