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}