htl-cli 0.17.0

htl command line (also `cargo htl`): check / run / test / fmt / build / pkg / new for Teal projects
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
//! `--format json`: the same facts the text output prints, as one JSON document on
//! stdout (text goes to stderr, so the two never mix), and the same exit code as in text
//! mode. Field names are stable; new fields may be added, existing ones are not renamed.
//!
//! - `check`: `{ files, patched, diagnostics: [{ severity: "error"|"warning"|"lint", file,
//!   line, col, rule?, message, fix?, required_by?, origin? }], summary: { errors, warnings,
//!   lints, denied, strict, ok, cached, replayed }, statistics?: [{ rule, count, fixable,
//!   unsafe_fixable }] }` ([`CheckReport`], [`CheckSummary`], [`RuleStatistic`],
//!   `htl::Diagnostic`). `fix` is `{ applicability: "safe"|"unsafe"|"suggest", edits: [{
//!   line, col, end_line, end_col, text }] }`. `statistics` is present only under
//!   `--statistics`, and `diagnostics` is then empty: the two never both carry the run's
//!   findings.
//! - `test`: `{ files: [{ path, ok, diagnostics, error?, file_level, passed, failed,
//!   failures, tests: [{ name, ok, ms }], duration_ms, snapshots_written,
//!   snapshots_updated }], summary: { files, files_run, passed, failed, files_with_errors,
//!   replayed, duration_ms, ok, seed }, coverage?: { modules: [{ path, executed, total,
//!   unexecuted: [[first, last]], never_ran?: [{ name, line }] }], executed, total } }`
//!   ([`TestFile`], [`TestSummary`]; `coverage` with `--coverage`).
//! - `unused`, `resolve` and `adopt`: `htl::unused`, `htl::resolve` and `htl::adopt` say
//!   their shapes.
//!
//! GitHub Actions annotations from a check, for instance:
//!
//! ```sh
//! htl check . --format json | jq -r '.diagnostics[] |
//!   "::\(if .severity == "error" then "error" else "warning" end) file=\(.file),line=\(.line),col=\(.col)::\(.message)"'
//! ```

use anyhow::Result;
use htl::testing::FileReport;
use serde::Serialize;

// A diagnostic is the library's ([`htl::Diagnostic`]), and so is its text form (its
// `Display`): an LSP, a `build.rs` and this printer read the same values, and print them
// the one way the library does.
pub use htl::Diagnostic;

/// The tally key for an error the checker left unclassified (`d.rule` is `None`) — none
/// today: every error reaches [`Out::diagnostic`] already classed `tl:error` or
/// `forward-ref` by `collect_errors` in `prelude.lua`. Spelled so it is neither a current
/// nor a retired rule name (`"error"` is `RENAMED` to `"tl:error"` in `htl::lint`, and
/// handing that spelling to `--explain` or `htl fix --rule` would be told it was renamed
/// to the very class this key is standing in for not being).
const NO_RULE: &str = "(no rule)";

/// How many findings a rule produced, and how many of them carry a fix of each kind — the
/// running total behind one row of [`Out::statistics`]. Not public: [`RuleStatistic`] is
/// the document a caller reads; this is only what it is built from.
#[derive(Default)]
struct RuleTally {
    count: usize,
    fixable: usize,
    unsafe_fixable: usize,
}

/// Where a diagnostic goes once the run has decided to say it: printed as it comes
/// (text) or kept for the document (json) — or, under `--statistics`, neither, since the
/// table it asked for is the tally alone.
///
/// Which diagnostics a run says, and in what words, is the library's
/// ([`htl::project::Sink`]) — a dependency's error is said once per run, and a replayed
/// entry comes through the same decisions a fresh check does. What is left here is the
/// part that is genuinely a command line's: how a finding reads on a terminal.
pub struct Out {
    pub json: bool,
    diagnostics: Vec<Diagnostic>,
    /// Which rule each finding counted under, and its fix numbers, keyed by the rule name
    /// — in name order, which is what `rules_said()` wants and what `statistics()` sorts
    /// from. Recorded for every diagnostic as it arrives, in both text and json mode,
    /// whether or not `--statistics` was asked: tallying is cheap, and the caller decides
    /// what to do with it. An error the checker left unclassified (`d.rule` is `None`) is
    /// keyed by [`NO_RULE`] rather than dropped — see that constant for why such an error
    /// does not arise today.
    tally: std::collections::BTreeMap<String, RuleTally>,
    /// `--statistics`: tally every diagnostic as always, but print nothing (text) and
    /// push nothing (json) — the table (or the JSON `statistics` array) is the answer the
    /// flag asks for, in place of the findings rather than beside them.
    statistics_only: bool,
}

impl Out {
    pub fn new(json: bool, statistics_only: bool) -> Self {
        Self {
            json,
            diagnostics: Vec::new(),
            tally: Default::default(),
            statistics_only,
        }
    }

    pub fn take(&mut self) -> Vec<Diagnostic> {
        std::mem::take(&mut self.diagnostics)
    }

    /// The rules the findings said so far were under, each once, in name order: what
    /// `htl check` names `--explain` for after the findings. [`NO_RULE`] is a key of the
    /// tally, not a rule, and is skipped here.
    pub fn rules_said(&self) -> impl Iterator<Item = &str> {
        self.tally
            .keys()
            .map(String::as_str)
            .filter(|&r| r != NO_RULE)
    }

    /// One row per rule with at least one finding, count descending then rule ascending —
    /// `ruff --statistics`'s shape. A rule with no finding this run is not a key of the
    /// tally at all, so it is never a row.
    pub fn statistics(&self) -> Vec<RuleStatistic> {
        let mut rows: Vec<RuleStatistic> = self
            .tally
            .iter()
            .map(|(rule, t)| RuleStatistic {
                rule: rule.clone(),
                count: t.count,
                fixable: t.fixable,
                unsafe_fixable: t.unsafe_fixable,
            })
            .collect();
        rows.sort_by(|a, b| b.count.cmp(&a.count).then_with(|| a.rule.cmp(&b.rule)));
        rows
    }
}

/// One row of `htl check --statistics`'s table, and of its `--format json` form: a rule
/// with at least one finding this run, how many, and how many of those a fix covers.
///
/// `fixable` is `safe` and `suggest` findings together — what `htl fix` applies or shows
/// without `--unsafe` — and `unsafe_fixable` is the rest that still carry a fix. Neither
/// overlaps the other, and together they need not reach `count`: the difference is
/// findings with no fix at all.
#[derive(Serialize, Debug, PartialEq, Eq)]
pub struct RuleStatistic {
    pub rule: String,
    pub count: usize,
    pub fixable: usize,
    pub unsafe_fixable: usize,
}

impl htl::project::Output for Out {
    fn diagnostic(&mut self, d: &Diagnostic) {
        let key = d.rule.clone().unwrap_or_else(|| NO_RULE.to_string());
        let t = self.tally.entry(key).or_default();
        t.count += 1;
        match d.fix.as_ref().map(|f| f.applicability.as_str()) {
            Some("safe") | Some("suggest") => t.fixable += 1,
            Some("unsafe") => t.unsafe_fixable += 1,
            _ => {}
        }
        if self.statistics_only {
            return;
        }
        let severity = d.severity;
        if self.json {
            self.diagnostics.push(d.clone());
        } else if let Some(by) = &d.required_by {
            eprintln!("{severity}: {d}\n  (required by {by})");
        } else {
            let text = d;
            // Text mode: say a fix exists, so `htl fix` is discoverable from the output.
            match d.fix.as_ref().map(|f| f.applicability.as_str()) {
                // A suggestion is shown by `htl fix` and never written by it; the command
                // that carries the edit is still `htl fix` (`--diff` prints it), and what
                // it does with it is what it says when it runs.
                Some("safe") | Some("suggest") => {
                    eprintln!("{severity}: {text} (fixable: htl fix)")
                }
                Some("unsafe") => eprintln!("{severity}: {text} (fixable: htl fix --unsafe)"),
                _ => eprintln!("{severity}: {text}"),
            }
        }
    }
}

#[derive(Serialize, Debug)]
pub struct CheckReport {
    /// Every file the walk visited, a patched dependency's included — what it has always
    /// counted, left alone so that a consumer reading it is not moved by `patched`
    /// arriving beside it.
    pub files: usize,
    /// How many of `files` came out of a `patch_dir` dependency: the project's committed
    /// copy of somebody else's package, which a check reads and neither `htl fmt` nor
    /// `htl test` touches. Subtract it from `files` for the project's own, which is how
    /// the text summary prints the pair: `15 file(s) + 10 in patched dependencies`, the
    /// two adding up to `files`, and the one number alone when this is zero — a project
    /// with no patch reads as it read before the split existed.
    pub patched: usize,
    pub diagnostics: Vec<Diagnostic>,
    pub summary: CheckSummary,
    /// `--statistics`'s table, as the document's [`RuleStatistic`] rows — count
    /// descending, then rule ascending. `Some` only under that flag, and then
    /// `diagnostics` is empty: the two never both carry the run's findings.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub statistics: Option<Vec<RuleStatistic>>,
}

#[derive(Serialize, Debug)]
pub struct CheckSummary {
    pub errors: usize,
    pub warnings: usize,
    pub lints: usize,
    /// How many of `warnings` + `lints` were said under a rule the project set to `deny`.
    /// A count of levels, so it overlaps those two rather than adding to them.
    pub denied: usize,
    /// Every `warn` counted as `deny` for this run.
    pub strict: bool,
    /// What the exit code says: no errors and nothing at `deny` — and under `strict`,
    /// nothing reported at all.
    pub ok: bool,
    /// Every module came from the cache, so no checker was built. The diagnostics are the
    /// same either way; this says nothing ran to produce them.
    pub cached: bool,
    /// How many of `files` were replayed rather than checked. `cached` is this reaching
    /// `files`; between the two you can tell a wholly cached run from a mostly cached one.
    pub replayed: usize,
}

#[derive(Serialize, Debug)]
pub struct TestCase {
    pub name: String,
    pub ok: bool,
    pub ms: f64,
}

#[derive(Serialize, Debug)]
pub struct TestFile {
    pub path: String,
    pub ok: bool,
    pub diagnostics: Vec<Diagnostic>,
    /// Runtime error outside any test (the file itself raised): the text `htl test`
    /// prints for it, [`htl::developer_message`] with its frames, carried unchanged.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
    /// No test library was used: the file passed by running to completion.
    pub file_level: bool,
    pub passed: usize,
    pub failed: usize,
    /// One entry per failing test: the message and traceback as the text output prints
    /// them under the file, unchanged.
    pub failures: Vec<String>,
    pub tests: Vec<TestCase>,
    pub duration_ms: f64,
    pub snapshots_written: Vec<String>,
    pub snapshots_updated: Vec<String>,
}

/// Paths as a report spells them ([`htl::diagnostic::display_path`]): the text output and
/// the document name one file the same way.
fn spelled(paths: &[String]) -> Vec<String> {
    paths
        .iter()
        .map(|p| htl::diagnostic::display_path(std::path::Path::new(p)))
        .collect()
}

impl TestFile {
    pub fn from_report(rep: &FileReport, diagnostics: Vec<Diagnostic>) -> Self {
        Self {
            path: htl::diagnostic::display_path(&rep.path),
            ok: rep.ok(),
            diagnostics,
            error: rep.error.clone(),
            file_level: rep.file_level,
            passed: rep.passed,
            failed: rep.failed,
            failures: rep.failures.clone(),
            tests: rep
                .tests
                .iter()
                .map(|t| TestCase {
                    name: t.name.clone(),
                    ok: t.ok,
                    ms: t.ms,
                })
                .collect(),
            duration_ms: rep.duration_ms,
            snapshots_written: spelled(&rep.snapshots_written),
            snapshots_updated: spelled(&rep.snapshots_updated),
        }
    }
}

#[derive(Serialize, Debug)]
pub struct TestSummary {
    /// Files discovered.
    pub files: usize,
    /// Files actually run (`--fail-fast` may stop early).
    pub files_run: usize,
    pub passed: usize,
    pub failed: usize,
    pub files_with_errors: usize,
    /// Files whose check and codegen came from the cache. They still ran: only the work
    /// before the run is reusable.
    pub replayed: usize,
    pub duration_ms: f64,
    pub ok: bool,
    /// The run's random seed. Passing it back as `--seed` repeats what every file drew.
    pub seed: u64,
}

// Coverage is the library's too ([`htl::project::coverage_report`]): which modules a run
// reached, which statements of them ran, and the lcov tracefile that says so. The JSON
// shape is these types', printed here beside the rest of the document.
pub use htl::project::CoverageReport;

#[derive(Serialize, Debug)]
pub struct TestReport {
    pub files: Vec<TestFile>,
    pub summary: TestSummary,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub coverage: Option<CoverageReport>,
}

#[derive(Serialize, Debug)]
pub struct FixApplied {
    pub file: String,
    pub line: usize,
    pub rule: String,
    pub applicability: &'static str,
    pub pass: usize,
}

#[derive(Serialize, Debug)]
pub struct FixSkipped {
    pub file: String,
    pub line: usize,
    pub rule: String,
    pub reason: String,
}

#[derive(Serialize, Debug)]
pub struct FixFile {
    pub path: String,
    pub changed: bool,
    pub deferred: usize,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reverted: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub oscillation: Option<String>,
    /// Diagnostics after fixing.
    pub diagnostics: Vec<Diagnostic>,
}

#[derive(Serialize, Debug)]
pub struct FixReport {
    pub dry_run: bool,
    pub applied: Vec<FixApplied>,
    pub skipped: Vec<FixSkipped>,
    pub files: Vec<FixFile>,
    pub summary: FixSummary,
    /// What the project says about itself as a whole — a name with two owners, a require
    /// cycle, a contract problem — which belongs to no one file.
    pub diagnostics: Vec<Diagnostic>,
}

#[derive(Serialize, Debug)]
pub struct FixSummary {
    pub files: usize,
    pub files_changed: usize,
    pub applied: usize,
    pub skipped: usize,
    pub deferred: usize,
    pub reverted: usize,
    pub errors_remaining: usize,
    /// Teal's warnings and htl's lints left in the tree, as `htl check` would count them.
    pub warnings: usize,
    pub lints: usize,
    /// How many of those were said under a rule at `deny`.
    pub denied: usize,
    /// Whether every warning and lint counted as `deny` (`[lint] strict`).
    pub strict: bool,
    pub ok: bool,
}

/// Print one document to stdout.
pub fn emit<T: Serialize>(v: &T) -> Result<()> {
    println!("{}", serde_json::to_string_pretty(v)?);
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use htl::project::Output as _;

    /// The checker classifies every error it reports as `tl:error` or `forward-ref`
    /// before it reaches [`Out`] — a syntax error and a type error both go through
    /// `collect_errors` in `prelude.lua`, which never leaves one unclassified — so no
    /// small fixture drives `htl check` to hand this a `rule: None` error. The tally has
    /// to answer the case regardless, since nothing stops a future caller (or a different
    /// path through the checker, such as a codegen failure after a clean type-check) from
    /// handing it one, so it is exercised directly here.
    #[test]
    fn an_unclassified_error_is_tallied_under_no_rule() {
        let mut out = Out::new(false, false);
        out.diagnostic(&Diagnostic::new(
            htl::Severity::Error,
            "a.tl",
            1,
            1,
            "generate failed: boom",
            None,
        ));
        assert_eq!(
            out.statistics(),
            vec![RuleStatistic {
                rule: NO_RULE.to_string(),
                count: 1,
                fixable: 0,
                unsafe_fixable: 0,
            }]
        );
        // The synthetic key is a tally key, not a rule: the `--explain` hint loop reads
        // `rules_said()`, and it must not be asked to explain it.
        assert_eq!(out.rules_said().collect::<Vec<_>>(), Vec::<&str>::new());
    }
}