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 }, 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}