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 }, statistics?: [{ rule, count, fixable,
8//! unsafe_fixable }] }` ([`CheckReport`], [`CheckSummary`], [`RuleStatistic`],
9//! `htl::Diagnostic`). `fix` is `{ applicability: "safe"|"unsafe"|"suggest", edits: [{
10//! line, col, end_line, end_col, text }] }`. `statistics` is present only under
11//! `--statistics`, and `diagnostics` is then empty: the two never both carry the run's
12//! findings.
13//! - `test`: `{ files: [{ path, ok, diagnostics, error?, file_level, passed, failed,
14//! failures, tests: [{ name, ok, ms }], duration_ms, snapshots_written,
15//! snapshots_updated }], summary: { files, files_run, passed, failed, files_with_errors,
16//! replayed, duration_ms, ok, seed }, coverage?: { modules: [{ path, executed, total,
17//! unexecuted: [[first, last]], never_ran?: [{ name, line }] }], executed, total } }`
18//! ([`TestFile`], [`TestSummary`]; `coverage` with `--coverage`).
19//! - `unused`, `resolve` and `adopt`: `htl::unused`, `htl::resolve` and `htl::adopt` say
20//! their shapes.
21//!
22//! GitHub Actions annotations from a check, for instance:
23//!
24//! ```sh
25//! htl check . --format json | jq -r '.diagnostics[] |
26//! "::\(if .severity == "error" then "error" else "warning" end) file=\(.file),line=\(.line),col=\(.col)::\(.message)"'
27//! ```
28
29use anyhow::Result;
30use htl::testing::FileReport;
31use serde::Serialize;
32
33// A diagnostic is the library's ([`htl::Diagnostic`]), and so is its text form (its
34// `Display`): an LSP, a `build.rs` and this printer read the same values, and print them
35// the one way the library does.
36pub use htl::Diagnostic;
37
38/// The tally key for an error the checker left unclassified (`d.rule` is `None`) — none
39/// today: every error reaches [`Out::diagnostic`] already classed `tl:error` or
40/// `forward-ref` by `collect_errors` in `prelude.lua`. Spelled so it is neither a current
41/// nor a retired rule name (`"error"` is `RENAMED` to `"tl:error"` in `htl::lint`, and
42/// handing that spelling to `--explain` or `htl fix --rule` would be told it was renamed
43/// to the very class this key is standing in for not being).
44const NO_RULE: &str = "(no rule)";
45
46/// How many findings a rule produced, and how many of them carry a fix of each kind — the
47/// running total behind one row of [`Out::statistics`]. Not public: [`RuleStatistic`] is
48/// the document a caller reads; this is only what it is built from.
49#[derive(Default)]
50struct RuleTally {
51 count: usize,
52 fixable: usize,
53 unsafe_fixable: usize,
54}
55
56/// Where a diagnostic goes once the run has decided to say it: printed as it comes
57/// (text) or kept for the document (json) — or, under `--statistics`, neither, since the
58/// table it asked for is the tally alone.
59///
60/// Which diagnostics a run says, and in what words, is the library's
61/// ([`htl::project::Sink`]) — a dependency's error is said once per run, and a replayed
62/// entry comes through the same decisions a fresh check does. What is left here is the
63/// part that is genuinely a command line's: how a finding reads on a terminal.
64pub struct Out {
65 pub json: bool,
66 diagnostics: Vec<Diagnostic>,
67 /// Which rule each finding counted under, and its fix numbers, keyed by the rule name
68 /// — in name order, which is what `rules_said()` wants and what `statistics()` sorts
69 /// from. Recorded for every diagnostic as it arrives, in both text and json mode,
70 /// whether or not `--statistics` was asked: tallying is cheap, and the caller decides
71 /// what to do with it. An error the checker left unclassified (`d.rule` is `None`) is
72 /// keyed by [`NO_RULE`] rather than dropped — see that constant for why such an error
73 /// does not arise today.
74 tally: std::collections::BTreeMap<String, RuleTally>,
75 /// `--statistics`: tally every diagnostic as always, but print nothing (text) and
76 /// push nothing (json) — the table (or the JSON `statistics` array) is the answer the
77 /// flag asks for, in place of the findings rather than beside them.
78 statistics_only: bool,
79}
80
81impl Out {
82 pub fn new(json: bool, statistics_only: bool) -> Self {
83 Self {
84 json,
85 diagnostics: Vec::new(),
86 tally: Default::default(),
87 statistics_only,
88 }
89 }
90
91 pub fn take(&mut self) -> Vec<Diagnostic> {
92 std::mem::take(&mut self.diagnostics)
93 }
94
95 /// The rules the findings said so far were under, each once, in name order: what
96 /// `htl check` names `--explain` for after the findings. [`NO_RULE`] is a key of the
97 /// tally, not a rule, and is skipped here.
98 pub fn rules_said(&self) -> impl Iterator<Item = &str> {
99 self.tally
100 .keys()
101 .map(String::as_str)
102 .filter(|&r| r != NO_RULE)
103 }
104
105 /// One row per rule with at least one finding, count descending then rule ascending —
106 /// `ruff --statistics`'s shape. A rule with no finding this run is not a key of the
107 /// tally at all, so it is never a row.
108 pub fn statistics(&self) -> Vec<RuleStatistic> {
109 let mut rows: Vec<RuleStatistic> = self
110 .tally
111 .iter()
112 .map(|(rule, t)| RuleStatistic {
113 rule: rule.clone(),
114 count: t.count,
115 fixable: t.fixable,
116 unsafe_fixable: t.unsafe_fixable,
117 })
118 .collect();
119 rows.sort_by(|a, b| b.count.cmp(&a.count).then_with(|| a.rule.cmp(&b.rule)));
120 rows
121 }
122}
123
124/// One row of `htl check --statistics`'s table, and of its `--format json` form: a rule
125/// with at least one finding this run, how many, and how many of those a fix covers.
126///
127/// `fixable` is `safe` and `suggest` findings together — what `htl fix` applies or shows
128/// without `--unsafe` — and `unsafe_fixable` is the rest that still carry a fix. Neither
129/// overlaps the other, and together they need not reach `count`: the difference is
130/// findings with no fix at all.
131#[derive(Serialize, Debug, PartialEq, Eq)]
132pub struct RuleStatistic {
133 pub rule: String,
134 pub count: usize,
135 pub fixable: usize,
136 pub unsafe_fixable: usize,
137}
138
139impl htl::project::Output for Out {
140 fn diagnostic(&mut self, d: &Diagnostic) {
141 let key = d.rule.clone().unwrap_or_else(|| NO_RULE.to_string());
142 let t = self.tally.entry(key).or_default();
143 t.count += 1;
144 match d.fix.as_ref().map(|f| f.applicability.as_str()) {
145 Some("safe") | Some("suggest") => t.fixable += 1,
146 Some("unsafe") => t.unsafe_fixable += 1,
147 _ => {}
148 }
149 if self.statistics_only {
150 return;
151 }
152 let severity = d.severity;
153 if self.json {
154 self.diagnostics.push(d.clone());
155 } else if let Some(by) = &d.required_by {
156 eprintln!("{severity}: {d}\n (required by {by})");
157 } else {
158 let text = d;
159 // Text mode: say a fix exists, so `htl fix` is discoverable from the output.
160 match d.fix.as_ref().map(|f| f.applicability.as_str()) {
161 // A suggestion is shown by `htl fix` and never written by it; the command
162 // that carries the edit is still `htl fix` (`--diff` prints it), and what
163 // it does with it is what it says when it runs.
164 Some("safe") | Some("suggest") => {
165 eprintln!("{severity}: {text} (fixable: htl fix)")
166 }
167 Some("unsafe") => eprintln!("{severity}: {text} (fixable: htl fix --unsafe)"),
168 _ => eprintln!("{severity}: {text}"),
169 }
170 }
171 }
172}
173
174#[derive(Serialize, Debug)]
175pub struct CheckReport {
176 /// Every file the walk visited, a patched dependency's included — what it has always
177 /// counted, left alone so that a consumer reading it is not moved by `patched`
178 /// arriving beside it.
179 pub files: usize,
180 /// How many of `files` came out of a `patch_dir` dependency: the project's committed
181 /// copy of somebody else's package, which a check reads and neither `htl fmt` nor
182 /// `htl test` touches. Subtract it from `files` for the project's own, which is how
183 /// the text summary prints the pair: `15 file(s) + 10 in patched dependencies`, the
184 /// two adding up to `files`, and the one number alone when this is zero — a project
185 /// with no patch reads as it read before the split existed.
186 pub patched: usize,
187 pub diagnostics: Vec<Diagnostic>,
188 pub summary: CheckSummary,
189 /// `--statistics`'s table, as the document's [`RuleStatistic`] rows — count
190 /// descending, then rule ascending. `Some` only under that flag, and then
191 /// `diagnostics` is empty: the two never both carry the run's findings.
192 #[serde(skip_serializing_if = "Option::is_none")]
193 pub statistics: Option<Vec<RuleStatistic>>,
194}
195
196#[derive(Serialize, Debug)]
197pub struct CheckSummary {
198 pub errors: usize,
199 pub warnings: usize,
200 pub lints: usize,
201 /// How many of `warnings` + `lints` were said under a rule the project set to `deny`.
202 /// A count of levels, so it overlaps those two rather than adding to them.
203 pub denied: usize,
204 /// Every `warn` counted as `deny` for this run.
205 pub strict: bool,
206 /// What the exit code says: no errors and nothing at `deny` — and under `strict`,
207 /// nothing reported at all.
208 pub ok: bool,
209 /// Every module came from the cache, so no checker was built. The diagnostics are the
210 /// same either way; this says nothing ran to produce them.
211 pub cached: bool,
212 /// How many of `files` were replayed rather than checked. `cached` is this reaching
213 /// `files`; between the two you can tell a wholly cached run from a mostly cached one.
214 pub replayed: usize,
215}
216
217#[derive(Serialize, Debug)]
218pub struct TestCase {
219 pub name: String,
220 pub ok: bool,
221 pub ms: f64,
222}
223
224#[derive(Serialize, Debug)]
225pub struct TestFile {
226 pub path: String,
227 pub ok: bool,
228 pub diagnostics: Vec<Diagnostic>,
229 /// Runtime error outside any test (the file itself raised): the text `htl test`
230 /// prints for it, [`htl::developer_message`] with its frames, carried unchanged.
231 #[serde(skip_serializing_if = "Option::is_none")]
232 pub error: Option<String>,
233 /// No test library was used: the file passed by running to completion.
234 pub file_level: bool,
235 pub passed: usize,
236 pub failed: usize,
237 /// One entry per failing test: the message and traceback as the text output prints
238 /// them under the file, unchanged.
239 pub failures: Vec<String>,
240 pub tests: Vec<TestCase>,
241 pub duration_ms: f64,
242 pub snapshots_written: Vec<String>,
243 pub snapshots_updated: Vec<String>,
244}
245
246/// Paths as a report spells them ([`htl::diagnostic::display_path`]): the text output and
247/// the document name one file the same way.
248fn spelled(paths: &[String]) -> Vec<String> {
249 paths
250 .iter()
251 .map(|p| htl::diagnostic::display_path(std::path::Path::new(p)))
252 .collect()
253}
254
255impl TestFile {
256 pub fn from_report(rep: &FileReport, diagnostics: Vec<Diagnostic>) -> Self {
257 Self {
258 path: htl::diagnostic::display_path(&rep.path),
259 ok: rep.ok(),
260 diagnostics,
261 error: rep.error.clone(),
262 file_level: rep.file_level,
263 passed: rep.passed,
264 failed: rep.failed,
265 failures: rep.failures.clone(),
266 tests: rep
267 .tests
268 .iter()
269 .map(|t| TestCase {
270 name: t.name.clone(),
271 ok: t.ok,
272 ms: t.ms,
273 })
274 .collect(),
275 duration_ms: rep.duration_ms,
276 snapshots_written: spelled(&rep.snapshots_written),
277 snapshots_updated: spelled(&rep.snapshots_updated),
278 }
279 }
280}
281
282#[derive(Serialize, Debug)]
283pub struct TestSummary {
284 /// Files discovered.
285 pub files: usize,
286 /// Files actually run (`--fail-fast` may stop early).
287 pub files_run: usize,
288 pub passed: usize,
289 pub failed: usize,
290 pub files_with_errors: usize,
291 /// Files whose check and codegen came from the cache. They still ran: only the work
292 /// before the run is reusable.
293 pub replayed: usize,
294 pub duration_ms: f64,
295 pub ok: bool,
296 /// The run's random seed. Passing it back as `--seed` repeats what every file drew.
297 pub seed: u64,
298}
299
300// Coverage is the library's too ([`htl::project::coverage_report`]): which modules a run
301// reached, which statements of them ran, and the lcov tracefile that says so. The JSON
302// shape is these types', printed here beside the rest of the document.
303pub use htl::project::CoverageReport;
304
305#[derive(Serialize, Debug)]
306pub struct TestReport {
307 pub files: Vec<TestFile>,
308 pub summary: TestSummary,
309 #[serde(skip_serializing_if = "Option::is_none")]
310 pub coverage: Option<CoverageReport>,
311}
312
313#[derive(Serialize, Debug)]
314pub struct FixApplied {
315 pub file: String,
316 pub line: usize,
317 pub rule: String,
318 pub applicability: &'static str,
319 pub pass: usize,
320}
321
322#[derive(Serialize, Debug)]
323pub struct FixSkipped {
324 pub file: String,
325 pub line: usize,
326 pub rule: String,
327 pub reason: String,
328}
329
330#[derive(Serialize, Debug)]
331pub struct FixFile {
332 pub path: String,
333 pub changed: bool,
334 pub deferred: usize,
335 #[serde(skip_serializing_if = "Option::is_none")]
336 pub reverted: Option<String>,
337 #[serde(skip_serializing_if = "Option::is_none")]
338 pub oscillation: Option<String>,
339 /// Diagnostics after fixing.
340 pub diagnostics: Vec<Diagnostic>,
341}
342
343#[derive(Serialize, Debug)]
344pub struct FixReport {
345 pub dry_run: bool,
346 pub applied: Vec<FixApplied>,
347 pub skipped: Vec<FixSkipped>,
348 pub files: Vec<FixFile>,
349 pub summary: FixSummary,
350 /// What the project says about itself as a whole — a name with two owners, a require
351 /// cycle, a contract problem — which belongs to no one file.
352 pub diagnostics: Vec<Diagnostic>,
353}
354
355#[derive(Serialize, Debug)]
356pub struct FixSummary {
357 pub files: usize,
358 pub files_changed: usize,
359 pub applied: usize,
360 pub skipped: usize,
361 pub deferred: usize,
362 pub reverted: usize,
363 pub errors_remaining: usize,
364 /// Teal's warnings and htl's lints left in the tree, as `htl check` would count them.
365 pub warnings: usize,
366 pub lints: usize,
367 /// How many of those were said under a rule at `deny`.
368 pub denied: usize,
369 /// Whether every warning and lint counted as `deny` (`[lint] strict`).
370 pub strict: bool,
371 pub ok: bool,
372}
373
374/// Print one document to stdout.
375pub fn emit<T: Serialize>(v: &T) -> Result<()> {
376 println!("{}", serde_json::to_string_pretty(v)?);
377 Ok(())
378}
379
380#[cfg(test)]
381mod tests {
382 use super::*;
383 use htl::project::Output as _;
384
385 /// The checker classifies every error it reports as `tl:error` or `forward-ref`
386 /// before it reaches [`Out`] — a syntax error and a type error both go through
387 /// `collect_errors` in `prelude.lua`, which never leaves one unclassified — so no
388 /// small fixture drives `htl check` to hand this a `rule: None` error. The tally has
389 /// to answer the case regardless, since nothing stops a future caller (or a different
390 /// path through the checker, such as a codegen failure after a clean type-check) from
391 /// handing it one, so it is exercised directly here.
392 #[test]
393 fn an_unclassified_error_is_tallied_under_no_rule() {
394 let mut out = Out::new(false, false);
395 out.diagnostic(&Diagnostic::new(
396 htl::Severity::Error,
397 "a.tl",
398 1,
399 1,
400 "generate failed: boom",
401 None,
402 ));
403 assert_eq!(
404 out.statistics(),
405 vec![RuleStatistic {
406 rule: NO_RULE.to_string(),
407 count: 1,
408 fixable: 0,
409 unsafe_fixable: 0,
410 }]
411 );
412 // The synthetic key is a tally key, not a rule: the `--explain` hint loop reads
413 // `rules_said()`, and it must not be asked to explain it.
414 assert_eq!(out.rules_said().collect::<Vec<_>>(), Vec::<&str>::new());
415 }
416}