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}