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}