Skip to main content

htl_cli/
report.rs

1//! `--format json`: the same facts the text output prints, as one JSON document on
2//! stdout (text goes to stderr, so the two never mix), and the same exit code as in text
3//! mode. Field names are stable; new fields may be added, existing ones are not renamed.
4//!
5//! - `check`: `{ files, patched, diagnostics: [{ severity: "error"|"warning"|"lint", file,
6//!   line, col, rule?, message, fix?, required_by?, origin? }], summary: { errors, warnings,
7//!   lints, denied, strict, ok, cached, replayed } }` ([`CheckReport`], [`CheckSummary`],
8//!   `htl::Diagnostic`). `fix` is `{ applicability: "safe"|"unsafe"|"suggest", edits: [{
9//!   line, col, end_line, end_col, text }] }`.
10//! - `test`: `{ files: [{ path, ok, diagnostics, error?, file_level, passed, failed,
11//!   failures, tests: [{ name, ok, ms }], duration_ms, snapshots_written,
12//!   snapshots_updated }], summary: { files, files_run, passed, failed, files_with_errors,
13//!   replayed, duration_ms, ok, seed }, coverage?: { modules: [{ path, executed, total,
14//!   unexecuted: [[first, last]], never_ran?: [{ name, line }] }], executed, total } }`
15//!   ([`TestFile`], [`TestSummary`]; `coverage` with `--coverage`).
16//! - `unused` and `resolve`: `htl::unused` and `htl::resolve` say their shapes.
17//!
18//! GitHub Actions annotations from a check, for instance:
19//!
20//! ```sh
21//! htl check . --format json | jq -r '.diagnostics[] |
22//!   "::\(if .severity == "error" then "error" else "warning" end) file=\(.file),line=\(.line),col=\(.col)::\(.message)"'
23//! ```
24
25use anyhow::Result;
26use htl::testing::FileReport;
27use serde::Serialize;
28
29// A diagnostic is the library's ([`htl::Diagnostic`]), and so is its text form (its
30// `Display`): an LSP, a `build.rs` and this printer read the same values, and print them
31// the one way the library does.
32pub use htl::Diagnostic;
33
34/// Where a diagnostic goes once the run has decided to say it: printed as it comes
35/// (text) or kept for the document (json).
36///
37/// Which diagnostics a run says, and in what words, is the library's
38/// ([`htl::project::Sink`]) — a dependency's error is said once per run, and a replayed
39/// entry comes through the same decisions a fresh check does. What is left here is the
40/// part that is genuinely a command line's: how a finding reads on a terminal.
41pub struct Out {
42    pub json: bool,
43    diagnostics: Vec<Diagnostic>,
44    /// The rules the findings said so far were under, each once, in name order: what
45    /// `htl check` names `--explain` for after the findings. Kept whether or not the run
46    /// prints text, since recording is cheap and the caller decides what to do with it.
47    rules: std::collections::BTreeSet<String>,
48}
49
50impl Out {
51    pub fn new(json: bool) -> Self {
52        Self {
53            json,
54            diagnostics: Vec::new(),
55            rules: Default::default(),
56        }
57    }
58
59    pub fn take(&mut self) -> Vec<Diagnostic> {
60        std::mem::take(&mut self.diagnostics)
61    }
62
63    /// The rules the findings said so far were under, each once, in name order.
64    pub fn rules_said(&self) -> impl Iterator<Item = &str> {
65        self.rules.iter().map(String::as_str)
66    }
67}
68
69impl htl::project::Output for Out {
70    fn diagnostic(&mut self, d: &Diagnostic) {
71        if let Some(rule) = &d.rule {
72            self.rules.insert(rule.clone());
73        }
74        let severity = d.severity;
75        if self.json {
76            self.diagnostics.push(d.clone());
77        } else if let Some(by) = &d.required_by {
78            eprintln!("{severity}: {d}\n  (required by {by})");
79        } else {
80            let text = d;
81            // Text mode: say a fix exists, so `htl fix` is discoverable from the output.
82            match d.fix.as_ref().map(|f| f.applicability.as_str()) {
83                // A suggestion is shown by `htl fix` and never written by it; the command
84                // that carries the edit is still `htl fix` (`--diff` prints it), and what
85                // it does with it is what it says when it runs.
86                Some("safe") | Some("suggest") => {
87                    eprintln!("{severity}: {text} (fixable: htl fix)")
88                }
89                Some("unsafe") => eprintln!("{severity}: {text} (fixable: htl fix --unsafe)"),
90                _ => eprintln!("{severity}: {text}"),
91            }
92        }
93    }
94}
95
96#[derive(Serialize, Debug)]
97pub struct CheckReport {
98    /// Every file the walk visited, a patched dependency's included — what it has always
99    /// counted, left alone so that a consumer reading it is not moved by `patched`
100    /// arriving beside it.
101    pub files: usize,
102    /// How many of `files` came out of a `patch_dir` dependency: the project's committed
103    /// copy of somebody else's package, which a check reads and neither `htl fmt` nor
104    /// `htl test` touches. Subtract it from `files` for the project's own, which is how
105    /// the text summary prints the pair: `15 file(s) + 10 in patched dependencies`, the
106    /// two adding up to `files`, and the one number alone when this is zero — a project
107    /// with no patch reads as it read before the split existed.
108    pub patched: usize,
109    pub diagnostics: Vec<Diagnostic>,
110    pub summary: CheckSummary,
111}
112
113#[derive(Serialize, Debug)]
114pub struct CheckSummary {
115    pub errors: usize,
116    pub warnings: usize,
117    pub lints: usize,
118    /// How many of `warnings` + `lints` were said under a rule the project set to `deny`.
119    /// A count of levels, so it overlaps those two rather than adding to them.
120    pub denied: usize,
121    /// Every `warn` counted as `deny` for this run.
122    pub strict: bool,
123    /// What the exit code says: no errors and nothing at `deny` — and under `strict`,
124    /// nothing reported at all.
125    pub ok: bool,
126    /// Every module came from the cache, so no checker was built. The diagnostics are the
127    /// same either way; this says nothing ran to produce them.
128    pub cached: bool,
129    /// How many of `files` were replayed rather than checked. `cached` is this reaching
130    /// `files`; between the two you can tell a wholly cached run from a mostly cached one.
131    pub replayed: usize,
132}
133
134#[derive(Serialize, Debug)]
135pub struct TestCase {
136    pub name: String,
137    pub ok: bool,
138    pub ms: f64,
139}
140
141#[derive(Serialize, Debug)]
142pub struct TestFile {
143    pub path: String,
144    pub ok: bool,
145    pub diagnostics: Vec<Diagnostic>,
146    /// Runtime error outside any test (the file itself raised): the text `htl test`
147    /// prints for it, [`htl::developer_message`] with its frames, carried unchanged.
148    #[serde(skip_serializing_if = "Option::is_none")]
149    pub error: Option<String>,
150    /// No test library was used: the file passed by running to completion.
151    pub file_level: bool,
152    pub passed: usize,
153    pub failed: usize,
154    /// One entry per failing test: the message and traceback as the text output prints
155    /// them under the file, unchanged.
156    pub failures: Vec<String>,
157    pub tests: Vec<TestCase>,
158    pub duration_ms: f64,
159    pub snapshots_written: Vec<String>,
160    pub snapshots_updated: Vec<String>,
161}
162
163/// Paths as a report spells them ([`htl::diagnostic::display_path`]): the text output and
164/// the document name one file the same way.
165fn spelled(paths: &[String]) -> Vec<String> {
166    paths
167        .iter()
168        .map(|p| htl::diagnostic::display_path(std::path::Path::new(p)))
169        .collect()
170}
171
172impl TestFile {
173    pub fn from_report(rep: &FileReport, diagnostics: Vec<Diagnostic>) -> Self {
174        Self {
175            path: htl::diagnostic::display_path(&rep.path),
176            ok: rep.ok(),
177            diagnostics,
178            error: rep.error.clone(),
179            file_level: rep.file_level,
180            passed: rep.passed,
181            failed: rep.failed,
182            failures: rep.failures.clone(),
183            tests: rep
184                .tests
185                .iter()
186                .map(|t| TestCase {
187                    name: t.name.clone(),
188                    ok: t.ok,
189                    ms: t.ms,
190                })
191                .collect(),
192            duration_ms: rep.duration_ms,
193            snapshots_written: spelled(&rep.snapshots_written),
194            snapshots_updated: spelled(&rep.snapshots_updated),
195        }
196    }
197}
198
199#[derive(Serialize, Debug)]
200pub struct TestSummary {
201    /// Files discovered.
202    pub files: usize,
203    /// Files actually run (`--fail-fast` may stop early).
204    pub files_run: usize,
205    pub passed: usize,
206    pub failed: usize,
207    pub files_with_errors: usize,
208    /// Files whose check and codegen came from the cache. They still ran: only the work
209    /// before the run is reusable.
210    pub replayed: usize,
211    pub duration_ms: f64,
212    pub ok: bool,
213    /// The run's random seed. Passing it back as `--seed` repeats what every file drew.
214    pub seed: u64,
215}
216
217// Coverage is the library's too ([`htl::project::coverage_report`]): which modules a run
218// reached, which statements of them ran, and the lcov tracefile that says so. The JSON
219// shape is these types', printed here beside the rest of the document.
220pub use htl::project::CoverageReport;
221
222#[derive(Serialize, Debug)]
223pub struct TestReport {
224    pub files: Vec<TestFile>,
225    pub summary: TestSummary,
226    #[serde(skip_serializing_if = "Option::is_none")]
227    pub coverage: Option<CoverageReport>,
228}
229
230#[derive(Serialize, Debug)]
231pub struct FixApplied {
232    pub file: String,
233    pub line: usize,
234    pub rule: String,
235    pub applicability: &'static str,
236    pub pass: usize,
237}
238
239#[derive(Serialize, Debug)]
240pub struct FixSkipped {
241    pub file: String,
242    pub line: usize,
243    pub rule: String,
244    pub reason: String,
245}
246
247#[derive(Serialize, Debug)]
248pub struct FixFile {
249    pub path: String,
250    pub changed: bool,
251    pub deferred: usize,
252    #[serde(skip_serializing_if = "Option::is_none")]
253    pub reverted: Option<String>,
254    #[serde(skip_serializing_if = "Option::is_none")]
255    pub oscillation: Option<String>,
256    /// Diagnostics after fixing.
257    pub diagnostics: Vec<Diagnostic>,
258}
259
260#[derive(Serialize, Debug)]
261pub struct FixReport {
262    pub dry_run: bool,
263    pub applied: Vec<FixApplied>,
264    pub skipped: Vec<FixSkipped>,
265    pub files: Vec<FixFile>,
266    pub summary: FixSummary,
267    /// What the project says about itself as a whole — a name with two owners, a require
268    /// cycle, a contract problem — which belongs to no one file.
269    pub diagnostics: Vec<Diagnostic>,
270}
271
272#[derive(Serialize, Debug)]
273pub struct FixSummary {
274    pub files: usize,
275    pub files_changed: usize,
276    pub applied: usize,
277    pub skipped: usize,
278    pub deferred: usize,
279    pub reverted: usize,
280    pub errors_remaining: usize,
281    /// Teal's warnings and htl's lints left in the tree, as `htl check` would count them.
282    pub warnings: usize,
283    pub lints: usize,
284    /// How many of those were said under a rule at `deny`.
285    pub denied: usize,
286    /// Whether every warning and lint counted as `deny` (`[lint] strict`).
287    pub strict: bool,
288    pub ok: bool,
289}
290
291/// Print one document to stdout.
292pub fn emit<T: Serialize>(v: &T) -> Result<()> {
293    println!("{}", serde_json::to_string_pretty(v)?);
294    Ok(())
295}