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