api_debug_lab/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2
3//! # API Support Debug Lab — diagnostic library
4//!
5//! This library is the engine behind the `api-debug-lab` CLI. It loads a
6//! [`Case`] from a fixture directory or a `case.json` path, runs a fixed
7//! set of rules over it, and returns a [`Report`] that ranks the firing
8//! diagnoses by confidence.
9//!
10//! ## How the pieces fit together
11//!
12//! ```text
13//! fixtures/cases/<name>/case.json    →  Case (serde, schema-validated)
14//! fixtures/cases/<name>/server.log   →  &str (lazy load via Case::load_log)
15//! fixtures/cases/<name>/secret.txt   →  Vec<u8> (via Case::load_secret)
16//!     │
17//!     ▼
18//! all_rules() : Vec<Box<dyn Rule>>
19//!     │
20//!     ▼   one Rule::evaluate per rule, all measured by diagnose_traced
21//! Diagnosis[]  ─ sorted by confidence desc, alphabetical tiebreak ─►  Report
22//! ```
23//!
24//! ## Determinism
25//!
26//! Every code path here is deterministic. Headers iterate via
27//! [`std::collections::BTreeMap`], reproductions inline the body so
28//! output paths never bake in machine-specific filesystem state, no
29//! system clock or RNG is consulted. The byte-stable contract is held
30//! to via snapshot tests in `tests/snapshots.rs`.
31//!
32//! ## No I/O beyond local files
33//!
34//! No network calls. No environment variables. No global state. The
35//! library is pure with respect to the inputs you hand it; the CLI
36//! does its own filesystem reads via [`Case::load`].
37//!
38//! ## Public surface
39//!
40//! Most callers will use the re-exports below: load a case with
41//! [`Case::load`], call [`diagnose`] or [`diagnose_traced`], and render
42//! the resulting [`Report`] through [`Report::render`].
43//!
44//! ```ignore
45//! use api_debug_lab::{Case, diagnose, Format};
46//! use std::path::Path;
47//!
48//! let case = Case::load("auth_missing", Path::new("fixtures")).unwrap();
49//! let report = diagnose(&case);
50//! print!("{}", report.render(Format::Human));
51//! std::process::exit(report.exit_code());
52//! ```
53
54#![deny(missing_docs)]
55
56pub mod cases;
57mod embedded;
58pub mod evidence;
59pub mod report;
60pub mod rules;
61
62pub use cases::{Case, CaseLoadError, Severity};
63pub use evidence::{Evidence, Pointer};
64pub use report::{Diagnosis, Format, Report};
65pub use rules::{all_rules, diagnose, diagnose_traced, Rule, RuleTrace};
api_debug_lab/lib.rs

api_debug_lab/
lib.rs
