Skip to main content

docsrs_cli/
lib.rs

1//! One-shot library and CLI for crates.io search and docs.rs documentation.
2//!
3//! `docsrs-cli` is agent-first: structured data on stdout, diagnostics on stderr,
4//! deterministic exit codes, and a BORN → EXECUTE → FINALIZE → DIE lifecycle with
5//! no daemon or sticky session state.
6//!
7//! This crate **consumes** published documentation from crates.io and docs.rs
8//! (and stdlib pages on `doc.rust-lang.org`). It does **not** replace docs.rs
9//! or re-implement `cargo doc` as a proprietary host.
10//!
11//! # Concurrency model (Rules Rust — parallelism)
12//!
13//! Workload is **mixed I/O + CPU** (see binary `main`, [`concurrency`], [`http::HttpClient`]):
14//! multi-thread Tokio for HTTPS and `spawn_blocking` under
15//! [`concurrency::ConcurrencyBudget`] for HTML parse. The `all.html` hit scan is
16//! sequential by measurement: a `rayon` path lost at every size from 16 to 32768
17//! candidates and was removed, so the crate has no data-parallel dependency.
18//! Bound via `--max-concurrency` / auto CPU+RAM formula.
19//! Fixed auxiliary tasks (double-interrupt, [`shutdown::ProgressGuard`]) still
20//! abort-on-drop. Shared cancel uses `Arc<AtomicU8>`, not `Mutex` across `.await`.
21//!
22//! # HTTP retry (Rules Rust — retry/backoff)
23//!
24//! Product GETs use [`retry::RetryConfig`]: exponential full-jitter backoff,
25//! `Retry-After` delta-seconds **or** HTTP-date on 429/503, dual budget
26//! (`max_attempts` + `max_elapsed_ms`), no retry on permanent 4xx/parse/budget.
27//! Kill switch: `--disable-retry` / TOML `disable_retry` / `max_retries=0`. Policy is
28//! single-layer inside [`http::HttpClient`] only.
29//!
30//! # Features
31//!
32//! This package has no Cargo feature flags. All product capabilities ship in the
33//! default build. Optional network live tests are gated by `#[ignore]` and run
34//! with `cargo test -- --ignored` — no environment variable and no feature. They
35//! used to carry a second gate reading two `DOCSRS_CLI_*` variables, which made
36//! `--ignored` return early from all of them and still report them as passed.
37//!
38//! # Safety
39//!
40//! - Product code in `src/` contains no `unsafe` blocks (`#![forbid(unsafe_code)]`).
41//! - External input is validated at boundaries (domain newtypes, origin allowlist, body caps).
42//! - Threat model (STRIDE / accepted risks): `docs/decisions/0004-threat-model.md`.
43//! - Regexes compile with bounded `size_limit` / `dfa_size_limit` (ReDoS posture).
44//! - docs.rs builds enable `doc_cfg` via `#![cfg_attr(docsrs, feature(doc_cfg))]`
45//!   (post-2025 merge of `doc_auto_cfg` into `doc_cfg`). Local `cargo +stable doc`
46//!   does not require the nightly feature gate.
47//! - TLS is rustls-only; HTTP product methods are GET-only against an allowlist.
48//! - Agent lifecycle is documented as a Mermaid sequence fence on [`run`]
49//!   (plain rustdoc code block — no proc-macro renderer).
50//!
51//! # Examples
52//!
53//! Parse a crate name at the domain boundary:
54//!
55//! ```
56//! use docsrs_cli::domain::CrateName;
57//!
58//! let name = CrateName::parse("serde").expect("valid crate name");
59//! assert_eq!(name.as_str(), "serde");
60//! ```
61//!
62//! Map error kinds to process exit codes:
63//!
64//! ```
65//! use docsrs_cli::error::ErrorKind;
66//!
67//! assert_eq!(ErrorKind::NotFound.exit_code(), 66);
68//! assert!(ErrorKind::Timeout.retryable());
69//! ```
70
71// Defensive security (Rules Rust / ADR 0009): product has no FFI; forbid all `unsafe`.
72// Integration tests may use `unsafe` only for the Unix signal harness (`libc::kill`).
73// Loopback mocks use CLI/XDG `allow_loopback` — never `env::set_var`.
74#![forbid(unsafe_code)]
75#![warn(missing_docs)]
76// Gate for the `# Errors` / `# Panics` sections. Without these two lints the
77// sections regress silently: `missing_docs` only checks that an item is
78// documented, never that a fallible item documents *how* it fails.
79#![warn(clippy::missing_errors_doc)]
80#![warn(clippy::missing_panics_doc)]
81#![warn(rustdoc::missing_crate_level_docs)]
82#![warn(rustdoc::broken_intra_doc_links)]
83#![warn(rustdoc::private_intra_doc_links)]
84#![deny(rustdoc::invalid_html_tags)]
85#![deny(rustdoc::invalid_rust_codeblocks)]
86#![deny(rustdoc::bare_urls)]
87#![warn(rustdoc::redundant_explicit_links)]
88#![cfg_attr(docsrs, feature(doc_cfg))]
89
90pub mod agent_ops;
91pub mod cache;
92pub mod cli;
93pub mod concurrency;
94pub mod config;
95pub mod crates_io;
96pub mod diagnostics;
97mod dispatch;
98pub mod docs_rs;
99mod doctor;
100pub mod domain;
101pub mod error;
102pub mod http;
103pub mod i18n;
104pub mod item_kind;
105mod meta_cmds;
106mod ops;
107mod output;
108pub mod platform;
109pub mod render;
110pub mod retry;
111pub mod shutdown;
112mod suggest;
113
114use std::io::{self, IsTerminal, Write};
115use std::process::ExitCode;
116
117use clap::Parser;
118
119use crate::agent_ops::AgentOps;
120use crate::cli::Cli;
121use crate::cli::overrides::apply_cli_overrides;
122use crate::config::Config;
123use crate::diagnostics::init_tracing;
124use crate::dispatch::execute;
125use crate::error::{AppError, EXIT_BROKEN_PIPE, EXIT_USAGE, ErrorDetail, ErrorKind};
126use crate::i18n::Locale;
127use crate::render::error_envelope;
128use crate::shutdown::flush_stdio;
129
130/// True when argv requests JSON or stdout is non-TTY (agent mode) — used before full parse.
131fn argv_wants_json_mode(args: &[std::ffi::OsString], stdout_is_terminal: bool) -> bool {
132    let has_json = args.iter().any(|a| a == "--json");
133    let has_human_format = args.windows(2).any(|w| {
134        w[0] == "--format"
135            && w[1]
136                .to_str()
137                .is_some_and(|v| v == "text" || v == "markdown" || v == "md")
138    }) || args.iter().any(|a| {
139        a.to_str().is_some_and(|s| {
140            s.starts_with("--format=")
141                && (s.contains("text") || s.contains("markdown") || s.contains("md"))
142        })
143    });
144    if has_json {
145        return true;
146    }
147    if has_human_format {
148        return false;
149    }
150    !stdout_is_terminal
151}
152
153/// Parse argv and execute one command. Returns process exit code.
154///
155/// This is the binary entrypoint wrapper (stdin/stdout/stderr are process defaults).
156/// Agent-first: when stdout is not a TTY, JSON is auto-selected unless `--format` forces human.
157///
158/// # Lifecycle
159///
160/// Lifecycle (BORN → EXECUTE → FINALIZE → DIE), Mermaid form for agent readers:
161///
162/// ```text
163/// sequenceDiagram
164///   participant A as Agent
165///   participant C as docsrs-cli
166///   participant N as crates.io / docs.rs
167///   A->>C: BORN spawn
168///   C->>N: EXECUTE GET
169///   N-->>C: body
170///   C-->>A: stdout envelope
171///   C->>C: FINALIZE flush
172///   C->>C: DIE exit code
173/// ```
174pub async fn run<I, T>(args: I) -> ExitCode
175where
176    I: IntoIterator<Item = T>,
177    T: Into<std::ffi::OsString> + Clone,
178{
179    let stdout_is_terminal = io::stdout().is_terminal();
180    run_with_io(
181        args,
182        io::stdin(),
183        io::stdout(),
184        io::stderr(),
185        stdout_is_terminal,
186    )
187    .await
188}
189
190/// Injectable IO entrypoint for tests (`run(args, stdin, stdout, stderr, stdout_is_terminal)`).
191///
192/// `stdin` is reserved for future payload flows and is unused by current ops.
193/// Pass `stdout_is_terminal = true` to keep human markdown default in unit tests;
194/// the binary path passes the real `IsTerminal` of process stdout.
195pub async fn run_with_io<I, T, In, Out, ErrW>(
196    args: I,
197    _stdin: In,
198    mut stdout: Out,
199    mut stderr: ErrW,
200    stdout_is_terminal: bool,
201) -> ExitCode
202where
203    I: IntoIterator<Item = T>,
204    T: Into<std::ffi::OsString> + Clone,
205    In: io::Read,
206    Out: Write,
207    ErrW: Write,
208{
209    // Collect args once so we can detect --json / agent mode before parse fails.
210    let args: Vec<std::ffi::OsString> = args.into_iter().map(Into::into).collect();
211    let agent_json = argv_wants_json_mode(&args, stdout_is_terminal);
212
213    let cli = match Cli::try_parse_from(&args) {
214        Ok(c) => c,
215        Err(e) => {
216            // Help / version display: human text, success.
217            if !e.use_stderr() {
218                let _ = e.print();
219                flush_stdio();
220                return ExitCode::SUCCESS;
221            }
222            // Contract: usage failures are exit EXIT_USAGE with JSON envelope in agent/JSON mode.
223            let msg = e.to_string();
224            if agent_json {
225                let err = AppError::of(ErrorDetail::ClapUsage { message: msg });
226                let _ = output::write_json(&mut stdout, &error_envelope(&err, "usage", 0));
227                flush_stdio();
228                return ExitCode::from(EXIT_USAGE);
229            }
230            // Human TTY: print clap rendering to stderr, still EXIT_USAGE (unified contract).
231            let _ = e.print();
232            flush_stdio();
233            return ExitCode::from(EXIT_USAGE);
234        }
235    };
236
237    let code = match run_cli(cli, &mut stdout, &mut stderr, stdout_is_terminal).await {
238        Ok(code) => code,
239        Err(err) if err.kind() == ErrorKind::BrokenPipe => ExitCode::from(EXIT_BROKEN_PIPE),
240        Err(err) => {
241            // Domain errors should already have been turned into ExitCode via
242            // `emit_error` inside `run_cli`. This path is a last-resort safety net
243            // (preserves kind exit code; never hardcodes 70).
244            tracing::error!(
245                target: "docsrs_cli::diagnostics",
246                error = %err,
247                kind = ?err.kind(),
248                "error escaped structured emit path"
249            );
250            // Localized like every other error path. The `cli` was moved into
251            // `run_cli`, so the locale is re-read from argv — the same source the
252            // bootstrap failures in `main` use, and the only one still available
253            // here. A hardcoded `error:` prefix used to ship English whatever
254            // `--lang` said, precisely because this branch is rare enough to be
255            // forgotten.
256            let locale = Locale::from_argv_for_bootstrap(&args);
257            let _ = writeln!(stderr, "{}", locale.format_error(&err));
258            err.exit_code()
259        }
260    };
261    flush_stdio();
262    let _ = stdout.flush();
263    let _ = stderr.flush();
264    code
265}
266
267async fn run_cli<Out: Write, ErrW: Write>(
268    cli: Cli,
269    stdout: &mut Out,
270    stderr: &mut ErrW,
271    stdout_is_terminal: bool,
272) -> Result<ExitCode, AppError> {
273    let wire = cli.wire_command();
274
275    // Provisional locale for errors raised before the strict `--lang` resolution
276    // below. Soft mapping never fails, so an unsupported explicit tag still
277    // reaches its own fail-closed check and is reported in English there.
278    let early_locale = cli
279        .lang
280        .as_deref()
281        .map(Locale::soft_from_tag)
282        .unwrap_or_else(Locale::from_system);
283
284    if let Err(e) = cli.validate_format_conflict() {
285        return Ok(meta_cmds::emit_error(
286            &cli,
287            &e,
288            early_locale,
289            stdout,
290            stderr,
291            stdout_is_terminal,
292            wire,
293            0,
294        ));
295    }
296
297    // Config load must go through `emit_error` so exit 78 / JSON envelope are correct.
298    // A bare `?` would bubble to `run_with_io` and historically forced exit 70.
299    let mut cfg = match Config::load_with_options(
300        cli.config_dir.clone(),
301        cli.cache_dir.clone(),
302        cli.allow_loopback,
303    ) {
304        Ok(c) => c,
305        Err(e) => {
306            return Ok(meta_cmds::emit_error(
307                &cli,
308                &e,
309                early_locale,
310                stdout,
311                stderr,
312                stdout_is_terminal,
313                wire,
314                0,
315            ));
316        }
317    };
318
319    // Tracing installs *after* the config load so the XDG `log_directive` can
320    // steer it. Nothing is lost: the load emits no diagnostics of its own, and
321    // its failure already travels through `emit_error` above.
322    init_tracing(&cli, cfg.log_directive.as_deref());
323
324    // `cfg` is loaded now, so a `lang` written in config.toml can also steer this
325    // error. CLI still wins; soft mapping keeps the strict check below authoritative.
326    let cfg_locale = cli
327        .lang
328        .as_deref()
329        .or(cfg.lang.as_deref())
330        .map_or(early_locale, Locale::soft_from_tag);
331    if let Err(e) = apply_cli_overrides(&cli, &mut cfg) {
332        return Ok(meta_cmds::emit_error(
333            &cli,
334            &e,
335            cfg_locale,
336            stdout,
337            stderr,
338            stdout_is_terminal,
339            wire,
340            0,
341        ));
342    }
343
344    // Fail-closed on explicit/config lang before any network work (no product env).
345    let locale = match Locale::resolve(cli.lang.as_deref().or(cfg.lang.as_deref())) {
346        Ok(l) => l,
347        Err(e) => {
348            return Ok(meta_cmds::emit_error(
349                &cli,
350                &e,
351                Locale::En,
352                stdout,
353                stderr,
354                stdout_is_terminal,
355                wire,
356                0,
357            ));
358        }
359    };
360    // Reduction knobs are validated before any network work so a malformed
361    // `--filter` fails fast (exit 65) instead of after a paid round-trip.
362    let ops = match AgentOps::from_cli(&cli) {
363        Ok(o) => o,
364        Err(e) => {
365            return Ok(meta_cmds::emit_error(
366                &cli,
367                &e,
368                locale,
369                stdout,
370                stderr,
371                stdout_is_terminal,
372                wire,
373                0,
374            ));
375        }
376    };
377
378    if !(ops.is_active() && cli.wants_json(stdout_is_terminal)) {
379        return Ok(execute(&cli, &cfg, locale, stdout, stderr, stdout_is_terminal, wire).await);
380    }
381
382    // Agent-native reduction: capture the envelope, cut it, then emit. The buffer is
383    // bounded by the same `max_output_bytes` budget the direct path already enforces.
384    let mut captured: Vec<u8> = Vec::new();
385    let code = execute(
386        &cli,
387        &cfg,
388        locale,
389        &mut captured,
390        stderr,
391        stdout_is_terminal,
392        wire,
393    )
394    .await;
395    let reduced = ops.apply_to_bytes(&captured);
396    if !reduced.is_empty() && stdout.write_all(&reduced).is_err() {
397        return Ok(ExitCode::from(EXIT_BROKEN_PIPE));
398    }
399    let _ = stdout.flush();
400    Ok(code)
401}