Skip to main content

htl_cli/
lib.rs

1//! htl CLI. Also built as `cargo-htl` so `cargo htl <verb>` works.
2//!
3//! - `htl check <paths...>`   type-check files or directories
4//! - `htl gen <file.tl>`      emit readable Lua (escape hatch)
5//! - `htl run <file.tl|.hb>`  type-check then execute (strict: type errors abort)
6//! - `htl build <dir>`        compile a tree of `.tl` into one stripped-bytecode bundle
7//! - `htl bundle info <.hb>`  print what a bundle records, without running it
8//! - `htl lsp`                a language server on stdio; its diagnostics are `htl check`'s
9
10use htl::cache;
11mod junit;
12mod lsp;
13mod pin;
14pub mod report;
15mod scaffold;
16
17/// Output format of every command that has `--format`. One enum, so its help must be
18/// true of all of them: `check` / `test` / `fix` / `unused` / `adopt` print their JSON
19/// document on stdout and nothing on stderr, and their text form on stderr only, so the
20/// two never mix; `cache status` / `bundle info` / `resolve` are reports rather than runs,
21/// so both of their forms go to stdout. The exit code is the same in either form.
22#[derive(Clone, Copy, PartialEq, Eq, Debug, clap::ValueEnum)]
23enum Format {
24    /// Human-readable lines
25    Text,
26    /// One JSON document on stdout (README, "Machine-readable output":
27    /// https://github.com/ynishi/htl#machine-readable-output)
28    Json,
29}
30
31/// How `htl check` grains its cache. Separate from whether it caches at all, which is
32/// `--no-cache`.
33#[derive(Clone, Copy, PartialEq, Eq, Debug, clap::ValueEnum)]
34enum CacheModeArg {
35    /// One entry per module: an edit costs that module and what depends on it
36    PerModule,
37    /// One entry per run: any edit re-checks everything, a run with no edits reads one file
38    WholeRun,
39}
40
41#[derive(Subcommand)]
42enum TypesCmd {
43    /// Copy a library's declarations from teal-types into `types/`, and record which
44    /// commit they came from
45    Add {
46        /// The library as teal-types names it (`luasocket`, `lpeg`, …)
47        library: String,
48        /// Take them from a checkout of teal-types already on disk instead of fetching
49        #[arg(long)]
50        from: Option<PathBuf>,
51        /// Replace declarations that are already in `types/`
52        #[arg(long)]
53        force: bool,
54    },
55}
56
57#[derive(Subcommand)]
58enum PkgCmd {
59    /// Fetch every dependency `mlua-pkg.toml` declares and write `mlua-pkg.lock`
60    Install,
61    /// Write a dependency into `mlua-pkg.toml`; `install` is what fetches it
62    Add {
63        /// The name `require()` will use for it
64        name: String,
65        /// Remote git URL
66        git: String,
67        /// Pin to a tag: exact (`v1.0.0`), or a prefix that follows its patches (`v1.0`)
68        #[arg(long)]
69        tag: Option<String>,
70        /// Pin to a commit
71        #[arg(long)]
72        rev: Option<String>,
73        /// Track a branch (a build from it is not reproducible)
74        #[arg(long)]
75        branch: Option<String>,
76        /// The subdirectory `require()` resolves through, when it is not the one the
77        /// package declares
78        #[arg(long)]
79        entry: Option<PathBuf>,
80        /// Copy the package into this directory instead of linking it (manifest-relative,
81        /// rewritten by every install)
82        #[arg(long)]
83        target_dir: Option<PathBuf>,
84    },
85    /// Refresh dependencies, bump the pins that follow releases, then install
86    Update {
87        /// One dependency; every one when omitted
88        name: Option<String>,
89        /// Print the plan and write nothing
90        #[arg(long)]
91        dry_run: bool,
92        /// Bump exact tag pins too, to the highest release the remote has
93        #[arg(long)]
94        force: bool,
95    },
96    /// Remove cached packages the lockfile no longer refers to
97    Clean {
98        /// Remove the whole cache rather than the unreferenced entries
99        #[arg(long)]
100        all: bool,
101    },
102    /// Take a dependency's source into `patches/<dep>/`: a copy the project owns, edits
103    /// and commits, which install resolves the dependency from
104    Patch {
105        /// The dependency as `mlua-pkg.toml` names it
106        dep: String,
107        /// Refresh the copy even when it has uncommitted changes (they are discarded)
108        #[arg(long)]
109        force: bool,
110    },
111}
112
113#[derive(Subcommand)]
114enum CacheCmd {
115    /// Delete this project's stored check results
116    Clear {
117        /// A path inside the project; the store is .htl/cache at the project root, the
118        /// nearest htl.toml or mlua-pkg.toml above
119        path: Option<PathBuf>,
120    },
121    /// Report what the store holds
122    Status {
123        /// A path inside the project; the store is .htl/cache at the project root, the
124        /// nearest htl.toml or mlua-pkg.toml above
125        path: Option<PathBuf>,
126        /// Output format
127        #[arg(long, value_enum, default_value_t = Format::Text)]
128        format: Format,
129        /// List every entry rather than counting them by kind
130        #[arg(long)]
131        entries: bool,
132    },
133}
134
135#[derive(Subcommand)]
136enum BundleCmd {
137    /// Print what a bundle records: format, the htl that built it, payload kind, the Lua
138    /// its bytecode was compiled for, entry, modules, host-provided names
139    Info {
140        /// The `.hb` file
141        file: PathBuf,
142        /// Output format
143        #[arg(long, value_enum, default_value_t = Format::Text)]
144        format: Format,
145    },
146}
147
148impl From<CacheModeArg> for cache::Mode {
149    fn from(m: CacheModeArg) -> Self {
150        match m {
151            CacheModeArg::PerModule => cache::Mode::PerModule,
152            CacheModeArg::WholeRun => cache::Mode::WholeRun,
153        }
154    }
155}
156
157use anyhow::{Context, Result, bail};
158use clap::{Parser, Subcommand};
159use htl::BuildTarget;
160use htl::Htl;
161use htl::bundle::Bundle;
162// The project layer: which files a check walks, what it replays from the run cache and
163// what it keeps there, and which of a run's findings are said. Shared with `include_tl!`,
164// which asks the same of the same store.
165use htl::project;
166use std::fs;
167use std::path::{Path, PathBuf};
168use std::process::ExitCode;
169
170#[derive(Parser)]
171#[command(
172    name = "htl",
173    version,
174    about = "Teal, hidden: run / check / build .tl on mlua",
175    long_about = "\
176Teal, hidden: run / check / build .tl on mlua.
177
178htl is a toolchain for Teal, and a way to embed one. It type-checks `.tl` sources with \
179Teal's own checker, runs and tests them on an embedded mlua state, formats them, and \
180links them into a single stripped-bytecode bundle. A Rust host embeds the same engine, \
181so the scripts it ships are checked when the host is built rather than when its user \
182first runs one.
183
184The guide, with every command and what a project looks like:
185  https://github.com/ynishi/htl
186
187The API a Rust host holds — `include_tl!`, `#[host_module]`, the run cache:
188  https://docs.rs/htl"
189)]
190struct Cli {
191    #[command(subcommand)]
192    cmd: Cmd,
193}
194
195#[derive(Subcommand)]
196enum Cmd {
197    /// Type-check .tl files or directories (htl lints are reported as `lint:`)
198    ///
199    /// A module reached through `require` is checked with the file that required it, and
200    /// what has not changed is replayed from `.htl/`. README, "Lints":
201    /// https://github.com/ynishi/htl#lints-htl-check-include_tl
202    #[command(after_long_help = "\
203Examples:
204  htl check src                  every .tl under src/
205  htl check src --strict         every warn counts as deny: warnings and lints fail
206  htl check src --lint nil-index=deny,no-any=warn
207                                 one rule fails the run, another is advice
208  htl check src --lint -tl:hint  a warning kind of the Teal compiler silenced
209  htl check --list-lints         every rule with its default level, then exit
210  htl check --explain union-exhaustive
211                                 why the rule exists and how to decide its cases
212  htl check src --statistics     how many findings each rule produced, not the findings
213
214The store is .htl/cache at the project root, the nearest htl.toml or mlua-pkg.toml above
215the paths; --no-cache skips it, --explain-cache says why a lookup missed.
216Caching: https://github.com/ynishi/htl#caching
217")]
218    Check {
219        paths: Vec<PathBuf>,
220        /// Treat every `warn` as `deny`: warnings and lints fail the run
221        #[arg(long)]
222        strict: bool,
223        /// Rule levels over the defaults, e.g. `nil-index=deny,no-any=warn` (`-rule` =
224        /// allow, `+rule` = warn)
225        // A spec that silences a rule starts with `-`, and without this clap reads
226        // `--lint -contract` as a cluster of short flags and answers `unexpected argument
227        // '-c'`: the documented way to turn one rule off never reached the spec parser.
228        #[arg(long, allow_hyphen_values = true)]
229        lint: Option<String>,
230        /// List every lint rule with its default level and exit
231        #[arg(long)]
232        list_lints: bool,
233        /// Print a rule's explanation — what it catches, why, the fix, the judgment call —
234        /// and exit; the name is the one a finding prints in `[htl <rule>]`
235        #[arg(long, value_name = "RULE")]
236        explain: Option<String>,
237        /// Output format
238        #[arg(long, value_enum, default_value_t = Format::Text)]
239        format: Format,
240        /// Check even if an identical run is cached, and do not store this one
241        #[arg(long)]
242        no_cache: bool,
243        /// How the cache is grained; overrides `[cache] mode` in htl.toml
244        #[arg(long, value_enum)]
245        cache_mode: Option<CacheModeArg>,
246        /// Say why the cache was not used, and what this run did with it
247        #[arg(long)]
248        explain_cache: bool,
249        /// Print how many findings each rule produced, instead of the findings
250        /// themselves: one row per rule with at least one, count first, `[*]` when every
251        /// finding of it has a fix `htl fix` applies, `[-]` when only some do or only
252        /// with `--unsafe`, `[ ]` when none has one; rules with no finding are not
253        /// listed. The summary line and the exit code are unchanged. With `--format
254        /// json`, `statistics` carries the same rows and `diagnostics` is empty
255        #[arg(long)]
256        statistics: bool,
257    },
258    /// Run tests: every `.tl` that requires the test library, one isolated state per file
259    ///
260    /// README, "Tests": https://github.com/ynishi/htl#tests
261    #[command(after_long_help = "\
262Examples:
263  htl test                       every .tl that requires htl.test
264  htl test tests --filter parser only tests whose \"suite > name\" contains it
265  htl test --coverage --coverage-lines
266                                 which lines of each module the suite never reached
267  htl test --junit report.xml    also write the run as a JUnit report, for a CI
268")]
269    Test {
270        paths: Vec<PathBuf>,
271        /// Only run tests whose "suite > name" contains this substring
272        #[arg(long)]
273        filter: Option<String>,
274        /// Assertion library module consulted for the verdict (must expose `run(filter)`)
275        #[arg(long, default_value = htl::testing::DEFAULT_LIB)]
276        lib: String,
277        /// Lint rules on top of the defaults, e.g. `+no-any`
278        #[arg(long, allow_hyphen_values = true)]
279        lint: Option<String>,
280        /// Stop at the first failure (within a file, and across files)
281        #[arg(long)]
282        fail_fast: bool,
283        /// Pass when no test file is found (the summary still says 0 files)
284        ///
285        /// Without it, finding nothing exits 1: a test file is found by what it loads, not
286        /// by its name, so a wrong `--lib` or a wrong directory finds nothing and would
287        /// otherwise pass silently. For a project whose gate runs `htl test` before its
288        /// first test exists; remove the flag when that test arrives. With test files
289        /// present it changes nothing.
290        #[arg(long)]
291        allow_empty: bool,
292        /// Print every test with its time (default: only failures and files)
293        #[arg(short, long)]
294        verbose: bool,
295        /// Only failures (with details), errors, and the summary line; no per-file `ok` lines
296        #[arg(short, long, conflicts_with = "verbose")]
297        quiet: bool,
298        /// Also print tests slower than this many milliseconds
299        #[arg(long, value_name = "MS")]
300        slow: Option<f64>,
301        /// Rewrite snapshots (`to_match_snapshot`) that differ instead of failing
302        #[arg(long)]
303        update: bool,
304        /// Report executed statements per `.tl` module the tests reached (slower: a line hook)
305        #[arg(long)]
306        coverage: bool,
307        /// With --coverage, also list the unexecuted line ranges of each module
308        #[arg(long, requires = "coverage")]
309        coverage_lines: bool,
310        /// Also write the coverage as an lcov tracefile here (implies --coverage)
311        #[arg(long, value_name = "FILE")]
312        lcov: Option<PathBuf>,
313        /// Also write the run as a JUnit XML report here, for a CI that reads test results
314        #[arg(long, value_name = "FILE")]
315        junit: Option<PathBuf>,
316        /// Seed the random stream tests draw from; printed every run, so a failure repeats
317        #[arg(long)]
318        seed: Option<u64>,
319        /// Output format
320        #[arg(long, value_enum, default_value_t = Format::Text)]
321        format: Format,
322        /// Check and generate every file even if a cached form is available, and store none
323        #[arg(long)]
324        no_cache: bool,
325        /// Say why the cache was not used, and what this run did with it
326        #[arg(long)]
327        explain_cache: bool,
328    },
329    /// Apply the fixes diagnostics carry (safe ones by default)
330    ///
331    /// The working tree is the undo: a file git reports as modified or staged is refused
332    /// (`--allow-dirty`), and so is a file outside a repository (`--allow-no-vcs`), since a
333    /// rewrite git could not give back is one nobody can review. `--dry-run` reports
334    /// without writing; `--diff` prints a unified diff per file instead, and a `suggest`
335    /// fix — never applied — is listed as skipped and printed there as a second diff
336    /// headed `<file> (suggested)`. The `.d.tl` declarations the project publishes are
337    /// regenerated first, as `htl check` regenerates them; a dry run works them out and
338    /// writes none.
339    ///
340    /// README, "Fixing": https://github.com/ynishi/htl#fixing-htl-fix
341    #[command(after_long_help = "\
342Examples:
343  htl fix src                    apply the safe fixes to every .tl under src/
344  htl fix src --diff --dry-run   what would change, as a unified diff per file
345  htl fix src --rule forward-ref only that rule's fixes
346  htl fix src --unsafe           also the fixes that may change what the program does
347")]
348    Fix {
349        paths: Vec<PathBuf>,
350        /// Only fixes of these rules: any rule `htl check --list-lints` names, or
351        /// `forward-ref` / `tl:error`, the classes an error's fix is filed under
352        #[arg(long, value_delimiter = ',')]
353        rule: Vec<String>,
354        /// Also apply `unsafe` fixes (may change what the program does)
355        #[arg(long = "unsafe")]
356        unsafe_fixes: bool,
357        /// Compute and report, write nothing
358        #[arg(long)]
359        dry_run: bool,
360        /// Like --dry-run, and print a unified diff per file that would change
361        #[arg(long)]
362        diff: bool,
363        /// Fix files that git reports as modified or staged
364        #[arg(long)]
365        allow_dirty: bool,
366        /// Fix files that are not inside a git repository
367        #[arg(long)]
368        allow_no_vcs: bool,
369        /// Exit 1 when any file was changed (for CI)
370        #[arg(long)]
371        exit_non_zero_on_fix: bool,
372        /// Output format
373        #[arg(long, value_enum, default_value_t = Format::Text)]
374        format: Format,
375    },
376    /// Write the `.d.tl` files this project declares: those `#[host_module(dts = ..)]` /
377    /// `#[teal(dts = ..)]` ask for in a Rust crate, without building it, and the module
378    /// each `---@contract` type is declared in (check / run / test / build do both)
379    ///
380    /// Each declaration is reported as `wrote`, `unchanged`, or `not written`, one line
381    /// each. The commands that generate before they work (`check` / `run` / `test` /
382    /// `build` / `fix` / `unused` / `adopt` / `resolve` / `gen`) do the same job first and print only
383    /// what moved, prefixed `dts:` — `dts: wrote …`, `dts: not written: …`, `dts: left in
384    /// place: …` — and never an `unchanged` line; a dependency's declarations land under
385    /// `types/<crate>/` from every one of them. The exit code is about `not written` and
386    /// nothing else: non-zero when a declaration this command was asked to write could
387    /// not be written. A file already under `types/` that no dependency ships any more is
388    /// reported as `left in place` — nothing was asked for, nothing is deleted, and the
389    /// exit code does not move.
390    Dts {
391        /// Crate root or any path inside it (default: current directory)
392        dir: Option<PathBuf>,
393    },
394    /// Write a run-time shape (an lshape schema) for each record and enum this project
395    /// declares, and the `.d.tl` that types it
396    ///
397    /// Reads the project's own `.tl` files under its source directory (a `.d.tl`, the test
398    /// root and `types/` are not read) and writes, per module that declares a record or an
399    /// enum, `<source>/shapes/<module>.lua` — a Lua module returning one shape per
400    /// declaration, written against `require("lshape")` — and `<types>/shapes/<module>.d.tl`,
401    /// which declares each as `lshape.Schema<module.Record>`; and once
402    /// `<types>/lshape.d.tl`, the declaration of lshape those are written against. A value
403    /// that arrives from outside is then narrowed once, at the boundary, with
404    /// `lshape.check.assert(v, S.Record)`, and read without a cast after it. The record is
405    /// the source: nothing generated is to be edited. What is lowered, how, and what is
406    /// not (the record a file returns, which is the module; `record R is I`; a union of
407    /// records) is the module doc of `htl::shapes`.
408    ///
409    /// Reports `shapes: wrote <path>` or `shapes: current <path>` for each file, on stderr;
410    /// a file whose text would not change is not touched. A target that exists and does
411    /// not begin with the line `htl shapes` writes is not one of its own and is never
412    /// overwritten or removed. A module that declares nothing to lower any more has the
413    /// files an earlier run wrote for it removed (`shapes: removed <path>`); one that is
414    /// refused keeps them, and each is reported as `left as it was and is stale`. The exit code is non-zero when a file fails its check (it is lowered
415    /// and written all the same, so a file that requires a shapes module before the first
416    /// run wrote it is clean on the second), when a declaration has no shape (named at its field, and nothing is written for that
417    /// module), when two modules need each other's shapes, when a module is named `shapes`
418    /// (the namespace the generated modules sit in), when a target is not its own to
419    /// overwrite, and when `require("lshape")` resolves to no Lua or Teal module — lshape is
420    /// not vendored or installed — in which case nothing is written.
421    Shapes {
422        /// Project root or any path inside it (default: current directory)
423        dir: Option<PathBuf>,
424    },
425    /// Write a Rust struct for each record and a Rust enum for each enum that the modules
426    /// listed in `[rust] modules` declare, and a client for each module in `[rust] exports`
427    ///
428    /// Reads the project's own `.tl` files, as `htl shapes` does, and writes one file,
429    /// `<source>/teal_types.rs` unless `[rust] out` says otherwise: one `pub mod` per module
430    /// segment, each record a `struct` and each enum a unit-only `enum` deriving
431    /// `::htl::TealRecord`, so that a host reads a Lua table as the struct and writes it
432    /// back. The record is the source: nothing generated is to be edited. A field is
433    /// `Option<T>` unless its record is marked `---@struct` and the field is neither
434    /// `---@optional` nor `T | nil`; `[rust.types] "ev.Event.at" = "u32"` gives one field
435    /// the Rust type written there. A module listed in `[rust] exports` gets a client for
436    /// its functions, called on an `htl::run` instance (the host builds `htl` with its
437    /// `async` feature). What is lowered, the mapping, and every case that is
438    /// refused (a function field, a generic, a union, a tuple, `---@extensible`, a type of
439    /// a module that is not listed, a name Rust cannot have, ...) is the module doc of
440    /// `htl::rsgen`; a run with any such problem names each at `file:line:col` and writes
441    /// nothing.
442    ///
443    /// Reports `htl rs: wrote <path>` or `htl rs: <path> is current` on stderr; a file
444    /// whose text would not change is not touched. A target that exists and does not begin
445    /// with the line `htl rs` writes is not one of its own and is never overwritten or
446    /// removed: it exits non-zero, saying so. With `[rust] modules` and `exports` empty (the
447    /// default) it writes nothing, and removes a file an earlier run wrote. A type error in any own
448    /// file, listed or not, is reported and nothing is written.
449    ///
450    /// `--check` writes nothing: it compares what would be written with the file, and
451    /// exits non-zero with `htl rs: <path> is stale; run htl rs` when they differ, the file
452    /// is missing, or `[rust] modules` and `exports` are empty and a file `htl rs` wrote is
453    /// still there.
454    /// The file is committed, and this is how CI says it has fallen behind the Teal.
455    Rs {
456        /// Project root or any path inside it (default: current directory)
457        dir: Option<PathBuf>,
458        /// Compare instead of write: exit non-zero when the file is not what `htl rs` would
459        /// write
460        #[arg(long)]
461        check: bool,
462    },
463    /// Create a new Teal project directory
464    ///
465    /// README, "Layout of a project": https://github.com/ynishi/htl#layout-of-a-project-htl-new
466    #[command(after_long_help = "\
467Examples:
468  htl new hello                    src/main.tl, a module, tests/, mlua-pkg.toml
469  htl new hello --lib              a library: no entry script
470  htl new hello --embed            the same, plus a Rust host (--target bin)
471  htl new hello --target cdylib --lib
472                                   a library behind a C ABI, for a caller that is not Rust
473  htl new hello --embed --htl main
474                                   built against the unreleased htl (a git pin on main)
475  htl new hello --embed --htl path:../htl
476                                   built against a local checkout of this repository
477  htl new hello --no-x             without the htlx dependency the manifest gets by default
478
479Build targets: https://docs.rs/htl/latest/htl/build_target/enum.BuildTarget.html
480Layout of a project: https://github.com/ynishi/htl#layout-of-a-project-htl-new
481")]
482    New {
483        name: String,
484        /// Library only (no src/main.tl)
485        #[arg(long)]
486        lib: bool,
487        /// Also emit a Rust host: shorthand for --target bin
488        #[arg(long)]
489        embed: bool,
490        /// What will run this project's output: a target writes Cargo.toml + src/lib.rs
491        /// (the #[host_module], the embedded module, preload) and, when there is an entry
492        /// script, a thin src/main.rs
493        #[arg(long, value_name = "NAME", value_parser = clap::builder::PossibleValuesParser::new(scaffold::target_names()))]
494        target: Option<String>,
495        /// The htl the project depends on: `release`, `main`, or `path:<checkout>`.
496        /// Without it, the htl this binary was built with — its version on crates.io, or
497        /// the checkout it was built in
498        #[arg(long, value_name = "REQ")]
499        htl: Option<String>,
500        /// Leave the htlx (htl-x collections) dependency out of mlua-pkg.toml
501        #[arg(long)]
502        no_x: bool,
503    },
504    /// Fill in the scaffold files that are missing in an existing directory
505    Init {
506        dir: Option<PathBuf>,
507        #[arg(long)]
508        lib: bool,
509        /// Shorthand for --target bin
510        #[arg(long)]
511        embed: bool,
512        /// Fill in this target's files, and report the ones that were already there
513        #[arg(long, value_name = "NAME", value_parser = clap::builder::PossibleValuesParser::new(scaffold::target_names()))]
514        target: Option<String>,
515        /// The htl the project depends on: `release`, `main`, or `path:<checkout>`.
516        /// Without it, the htl this binary was built with — its version on crates.io, or
517        /// the checkout it was built in
518        #[arg(long, value_name = "REQ")]
519        htl: Option<String>,
520        /// Leave the htlx (htl-x collections) dependency out of mlua-pkg.toml
521        #[arg(long)]
522        no_x: bool,
523    },
524    /// Move the htl a project `htl new` already wrote depends on
525    ///
526    /// Rewrites `Cargo.toml`'s `htl` line (and `htl-mq`'s, under `--target window`),
527    /// `mise.toml`, and `[toolchain] htl` in `htl.toml` when the project has one, then runs
528    /// `cargo update` so `Cargo.lock` agrees — the same four things `--htl` decides for a
529    /// project that does not exist yet (see `htl new`). `release` is this CLI's own
530    /// version, `main` its repository's branch, `path:<checkout>` a local clone — a
531    /// relative one resolved against the current directory, the way the shell reads it,
532    /// not against `dir`, and refused when there is no `crates/htl/Cargo.toml` under it;
533    /// a number is refused, the way `htl new --htl <number>` is, naming the release's own
534    /// CLI instead. `--no-update` writes the three files and prints the `cargo update` to
535    /// run by hand rather than running it.
536    ///
537    /// A `Cargo.toml` whose `htl` (or `htl-mq`) line this command does not recognise —
538    /// anything but a bare version, or a table naming exactly one of `version` / `git` +
539    /// `branch` / `path` plus an optional `features` list — is left untouched: the fallback
540    /// is the `[patch.crates-io]` block this refusal prints. README, "Running against an
541    /// unpublished htl": https://github.com/ynishi/htl#running-against-an-unpublished-htl
542    ///
543    /// Exit 0 once everything above is moved; 2 when `--htl` is not one of the three (or
544    /// names no checkout), there is no `Cargo.toml` to move, the line is not recognised,
545    /// or `cargo update` fails (the files are rewritten either way — only the lock is left
546    /// unresolved).
547    #[command(after_long_help = "\
548Examples:
549  htl pin path:../htl            from this project's own directory, move it onto a sibling
550                                  checkout, for a change that has to be built against it
551  htl pin release                move it back once that checkout's change is released
552")]
553    Pin {
554        /// `release`, `main`, or `path:<checkout>` — the same names `htl new --htl` takes
555        htl: String,
556        /// Project root or any path inside it (default: current directory)
557        dir: Option<PathBuf>,
558        /// Write the three files and print the `cargo update` to run, rather than running it
559        #[arg(long)]
560        no_update: bool,
561    },
562    /// Package management at the nearest `mlua-pkg.toml` project root: install / add /
563    /// update / clean / patch, through mlua-pkg's library rather than its binary
564    Pkg {
565        #[command(subcommand)]
566        cmd: PkgCmd,
567    },
568    /// Bring declarations for a library into `types/`
569    Types {
570        #[command(subcommand)]
571        cmd: TypesCmd,
572    },
573    /// Manage the check cache
574    ///
575    /// README, "Caching": https://github.com/ynishi/htl#caching
576    Cache {
577        #[command(subcommand)]
578        cmd: CacheCmd,
579    },
580    /// Format .tl files in place (indentation / blank lines / trailing whitespace)
581    Fmt {
582        paths: Vec<PathBuf>,
583        /// Do not write; exit 1 if any file would change
584        #[arg(long)]
585        check: bool,
586        /// Indent width in spaces (default: `[fmt] indent` in htl.toml, else 3)
587        #[arg(long)]
588        indent: Option<usize>,
589    },
590    /// Emit readable Lua for one .tl file (escape hatch)
591    ///
592    /// Line n of the output is line n of the .tl, so a run-time error names the .tl line.
593    /// A comment-only line (`--` or `---` after indentation, not a `--[[` opener) survives
594    /// verbatim at its line, `---` doc included, and so do the comment lines after the last
595    /// line of code (the `---` after a module's `return`): the output ends with the last of
596    /// them. A trailing comment (after code) and a block comment (`--[[ ... ]]`) do not
597    /// survive: the trailing one is dropped from its line, and every line of the block comes
598    /// out empty, a `--` line inside it included.
599    Gen {
600        file: PathBuf,
601        #[arg(short, long)]
602        out: Option<PathBuf>,
603    },
604    /// Run a .tl script or a .hb bundle
605    Run {
606        file: PathBuf,
607        #[arg(trailing_var_arg = true)]
608        args: Vec<String>,
609    },
610    /// Compile a directory of .tl into a stripped-bytecode bundle
611    ///
612    /// A bundle is the `hb` target, so this refuses a project whose `[build] target` is
613    /// another one — a `bin` or a `cdylib` is built with `cargo build`.
614    ///
615    /// README, "Bundles": https://github.com/ynishi/htl#bundles-htl-build
616    #[command(after_long_help = "\
617Examples:
618  htl build src/main.tl -o app.hb
619                                 the entry's require closure, as one bundle
620  htl build src/main.tl -o app.hb --debug
621                                 keep line numbers and local names in the bytecode
622  htl build src/main.tl -o app.hb --host mymod
623                                 leave a module the host provides out of the bundle
624  htl run app.hb                 run what was built
625
626Caching: https://github.com/ynishi/htl#caching
627")]
628    /// The closure is judged by the project's `[lint.rules]` as `htl check` judges it — a
629    /// rule the project turned off is not reported here either — and no bundle is written
630    /// when it fails. A project whose `[build] target` is not `hb` is refused, naming the
631    /// command that does build it: the key records a decision the project made rather
632    /// than a note about itself, and dropping it from `htl.toml` is how a project with
633    /// Rust in it asks for a bundle anyway.
634    Build {
635        /// Entry `.tl` file: it and everything it requires are bundled, replaying from
636        /// the run cache what still holds (a directory bundles every `.tl` under it, the
637        /// older snapshot form, which is not cached)
638        entry: PathBuf,
639        #[arg(short, long, default_value = "app.hb")]
640        out: PathBuf,
641        /// Entry module name when `entry` is a directory
642        #[arg(short, long, default_value = "main")]
643        main: String,
644        /// Keep debug info (line numbers, local names) in the bytecode
645        #[arg(long)]
646        debug: bool,
647        /// Store generated Lua source instead of bytecode: for a big-endian target, a Lua
648        /// with non-default number types, or a bundle that must outlive a Lua upgrade
649        #[arg(long)]
650        source: bool,
651        /// Modules to bundle that only a dynamic require reaches (also `[build] extra`)
652        #[arg(long, value_delimiter = ',')]
653        extra: Vec<String>,
654        /// Modules the host provides, besides the project's own list (`#[host_module]`, `[build] host`, `std.*`; `.d.tl`-only modules are implied)
655        #[arg(long, value_delimiter = ',')]
656        host: Vec<String>,
657        /// Generate every module even if its cached form still holds, and do not store
658        /// (the directory form is never cached)
659        #[arg(long)]
660        no_cache: bool,
661        /// Say why the cache was not used, and what this run did with it
662        #[arg(long)]
663        explain_cache: bool,
664    },
665    /// Report what no entry's `require` closure reaches: modules, and `mlua-pkg.toml`
666    /// dependencies
667    ///
668    /// README, "Unused": https://github.com/ynishi/htl#unused-htl-unused
669    #[command(after_long_help = "\
670Examples:
671  htl unused                     modules and dependencies no entry reaches
672  htl unused --exit-non-zero-on-unused
673                                 the same report, and a non-zero exit for a CI
674  htl unused --format json       the same report as one JSON document
675")]
676    Unused {
677        /// What to report on (default: the working directory). The walk is the project's
678        /// either way: a module reached only from `tests/` is reached
679        paths: Vec<PathBuf>,
680        /// Output format
681        #[arg(long, value_enum, default_value_t = Format::Text)]
682        format: Format,
683        /// Exit 1 when anything is reported (for CI)
684        #[arg(long)]
685        exit_non_zero_on_unused: bool,
686        /// Build the graph from a fresh check even if a cached one is available, and
687        /// store none
688        #[arg(long)]
689        no_cache: bool,
690        /// Say why the cache was not used, and what this run did with it
691        #[arg(long)]
692        explain_cache: bool,
693    },
694    /// Report how many declarations carry each of htl's nine markers, and where
695    ///
696    /// `applicable` is how many declarations a lint has found the evidence to call
697    /// candidates for a marker. Two rows have one so far: `---@struct`'s is what
698    /// `unmarked-struct` would report, a record built whole at every one of its
699    /// construction sites and left unmarked; `---@sealed`'s is what `unmarked-sealed`
700    /// would report, a record built and cast only in the file that declares it and left
701    /// unmarked. Every other row is empty (`-`), not `0`: a feature with no evidence
702    /// counted is a different claim from a feature nothing is applicable to, and this
703    /// command does not guess between them. `--detail` lists each candidate after the
704    /// row's marked declarations, with `(applicable: <reason>, N site(s))`. It is a
705    /// report, not a gate: the exit code is always 0.
706    /// README, "Adoption": https://github.com/ynishi/htl#adoption-htl-adopt
707    #[command(after_long_help = "\
708Examples:
709  htl adopt                      which of htl's nine markers this project writes, and how much
710  htl adopt --detail             the same, plus every marked declaration's file, line and name
711  htl adopt --format json        the same report as one JSON document
712")]
713    Adopt {
714        /// What to report on (default: the working directory). The walk behind the
715        /// census is always the whole project, so the check resolves and replays as
716        /// usual; the counts are of the files under the paths given here.
717        paths: Vec<PathBuf>,
718        /// Output format
719        #[arg(long, value_enum, default_value_t = Format::Text)]
720        format: Format,
721        /// List every marked declaration under the table, file:line and name, grouped by
722        /// feature, and each `applicable` candidate after them; the plain form prints
723        /// the table alone
724        #[arg(long)]
725        detail: bool,
726        /// Build the census from a fresh check even if a cached one is available, and
727        /// store none
728        #[arg(long)]
729        no_cache: bool,
730        /// Say why the cache was not used, and what this run did with it
731        #[arg(long)]
732        explain_cache: bool,
733    },
734    /// Which file `require("<module>")` resolves to, and what that hides
735    ///
736    /// The whole chain in search order: what is read, what is reachable and not read, and
737    /// which crate or dependency each one came from. An override on the search path is the
738    /// mechanism working, and this is how to see it. README, "Which file a name resolves
739    /// to": https://github.com/ynishi/htl#which-file-a-name-resolves-to-htl-resolve
740    #[command(after_long_help = "\
741Examples:
742  htl resolve mq                 the chain for require(\"mq\")
743  htl resolve socket.http        a name with dots, as a require spells it
744  htl resolve mq --format json   the same rows as one JSON document
745
746Exits 1 when the name resolves to nothing, when two files implement it, or when a file of
747the project implements a name the host provides, so a script can ask.
748
749`htl.test` is answered like a host-provided name: no file of the project implements it
750(`htl test` preloads it into the state it runs), and its one row is the declaration the
751binary carries, `provided by the environment`.
752")]
753    Resolve {
754        /// The module name a `require` would spell (`mq`, `socket.http`)
755        module: String,
756        /// A path inside the project (default: the working directory)
757        path: Option<PathBuf>,
758        /// Output format
759        #[arg(long, value_enum, default_value_t = Format::Text)]
760        format: Format,
761    },
762    /// Read a `.hb` bundle without running it
763    ///
764    /// README, "Bundles": https://github.com/ynishi/htl#bundles-htl-build
765    Bundle {
766        #[command(subcommand)]
767        cmd: BundleCmd,
768    },
769    /// A language server on stdio whose diagnostics are `htl check`'s
770    ///
771    /// Speaks the Language Server Protocol on stdin and stdout; an editor starts it as a
772    /// child process. A file is checked when it is opened and when it is saved, from disk,
773    /// under the project it belongs to: the same resolution rules, lint levels,
774    /// `-- htl: allow(..)` comments and `.d.tl` declarations `htl check` applies, and the
775    /// same messages and lines. Saving a file also re-checks the other open files that
776    /// require it. A change to `htl.toml`, `mlua-pkg.toml`, `mlua-pkg.lock`, a `.d.tl` under
777    /// `types/` or the Rust `htl dts` reads re-checks the open files of that project when the
778    /// client watches files (`didChangeWatchedFiles`); for any client, the three
779    /// manifests are noticed at the next open or save in the project. Diagnostics are not computed
780    /// while typing. Anything the server has to say about itself goes to stderr.
781    Lsp,
782}
783
784/// The command line as clap holds it, before any argument is parsed.
785///
786/// The help is documentation, and the tests that keep it from rotting read it from here
787/// rather than from a copy kept beside them: they walk this tree and ask each command,
788/// argument and value for the strings it would print.
789pub fn command() -> clap::Command {
790    <Cli as clap::CommandFactory>::command()
791}
792
793/// `htl::registry::register_installer("htl-std", htl_std::install, htl_std::PROVIDES)`,
794/// once.
795///
796/// This binary links both `htl-core` and `htl-std` at once, which is exactly the seam
797/// `htl_core::registry`'s own doc describes ("Why this exists"): `htl-core` cannot depend
798/// on `htl-std` back (`htl-std -> htl -> htl-core -> htl-std` would be a cycle), so only a
799/// binary that sits above both can hand `htl-core` the function pointer. Doing it here —
800/// in `run()`, before anything parses a command — rather than in `htl-core` itself is the
801/// whole reason the registry module exists; see that module's doc for the rest. The call
802/// goes through `htl::registry` rather than naming `htl-core` directly: `htl` already
803/// re-exports it (`pub use htl_core::*`), and this crate has no other reason to depend on
804/// `htl-core` itself.
805///
806/// Registering the same name twice is refused (`register_installer`'s own doc, "Order and
807/// duplicates"), so this is behind a `std::sync::Once`: `run()` is the entry both `htl` and
808/// `cargo-htl` call, once each per process, which is enough on its own, but an in-process
809/// caller could call it more than once without the guard.
810fn register_libraries() {
811    static ONCE: std::sync::Once = std::sync::Once::new();
812    ONCE.call_once(|| {
813        htl::registry::register_installer("htl-std", htl_std::install, htl_std::PROVIDES)
814            .expect("\"htl-std\" registered twice");
815    });
816}
817
818/// Parse the command line and run the command; the exit code.
819///
820/// An exit of 1 is a verdict — an error in a file, a finding at `deny`, a failing test, a
821/// name that resolves to nothing ([`htl::verdict`]). A command that could not get as far
822/// as a verdict — a directory in no project, an `htl.toml` that does not parse, a file it
823/// cannot read, a flag it does not take — says why and exits 2, whichever command it was
824/// (clap exits 2 on a bad flag, and an `Err` from any command lands on the same arm).
825pub fn run() -> ExitCode {
826    register_libraries();
827    // Invoked as `cargo htl ...` -> argv = ["cargo-htl", "htl", ...]; drop the "htl".
828    let mut argv: Vec<String> = std::env::args().collect();
829    let is_cargo = Path::new(&argv[0])
830        .file_stem()
831        .and_then(|s| s.to_str())
832        .map(|s| s == "cargo-htl")
833        .unwrap_or(false);
834    if is_cargo && argv.get(1).map(String::as_str) == Some("htl") {
835        argv.remove(1);
836    }
837    match real_main(Cli::parse_from(argv)) {
838        Ok(code) => code,
839        Err(e) => {
840            eprintln!("htl: {e:#}");
841            ExitCode::from(2)
842        }
843    }
844}
845
846fn real_main(cli: Cli) -> Result<ExitCode> {
847    match cli.cmd {
848        Cmd::Check {
849            paths,
850            strict,
851            lint,
852            list_lints,
853            explain,
854            format,
855            no_cache,
856            cache_mode,
857            explain_cache,
858            statistics,
859        } => cmd_check(
860            &paths,
861            lint.as_deref(),
862            CheckFlags {
863                strict,
864                list_lints,
865                explain_rule: explain,
866                json: format == Format::Json,
867                use_cache: !no_cache,
868                cache_mode: cache_mode.map(Into::into),
869                explain: explain_cache,
870                statistics,
871            },
872        ),
873        Cmd::Fmt {
874            paths,
875            check,
876            indent,
877        } => cmd_fmt(&paths, check, indent),
878        Cmd::Test {
879            paths,
880            filter,
881            lib,
882            lint,
883            fail_fast,
884            allow_empty,
885            verbose,
886            quiet,
887            slow,
888            update,
889            coverage,
890            coverage_lines,
891            lcov,
892            junit,
893            seed,
894            format,
895            no_cache,
896            explain_cache,
897        } => cmd_test(
898            &paths,
899            filter.as_deref(),
900            &lib,
901            lint.as_deref(),
902            TestFlags {
903                fail_fast,
904                allow_empty,
905                verbose,
906                quiet,
907                slow,
908                update,
909                coverage: coverage || lcov.is_some(),
910                coverage_lines,
911                lcov,
912                junit,
913                json: format == Format::Json,
914                no_cache,
915                explain: explain_cache,
916                seed,
917            },
918        ),
919        Cmd::Pkg { cmd } => match cmd {
920            PkgCmd::Install => cmd_pkg_install(),
921            PkgCmd::Add {
922                name,
923                git,
924                tag,
925                rev,
926                branch,
927                entry,
928                target_dir,
929            } => cmd_pkg_add(htl::pkg::mlua_pkg::ops::AddSpec {
930                name,
931                git,
932                tag,
933                rev,
934                branch,
935                entry,
936                target_dir,
937            }),
938            PkgCmd::Update {
939                name,
940                dry_run,
941                force,
942            } => cmd_pkg_update(htl::pkg::mlua_pkg::ops::UpdateOpts {
943                name,
944                dry_run,
945                force,
946            }),
947            PkgCmd::Clean { all } => cmd_pkg_clean(all),
948            PkgCmd::Patch { dep, force } => cmd_pkg_patch(&dep, force),
949        },
950        Cmd::Types { cmd } => match cmd {
951            TypesCmd::Add {
952                library,
953                from,
954                force,
955            } => cmd_types_add(&library, from.as_deref(), force),
956        },
957        Cmd::Cache { cmd } => match cmd {
958            CacheCmd::Clear { path } => cmd_cache_clear(path.as_deref()),
959            CacheCmd::Status {
960                path,
961                format,
962                entries,
963            } => cmd_cache_status(path.as_deref(), format == Format::Json, entries),
964        },
965        Cmd::Dts { dir } => cmd_dts(dir.as_deref()),
966        Cmd::Shapes { dir } => cmd_shapes(dir.as_deref()),
967        Cmd::Rs { dir, check } => cmd_rs(dir.as_deref(), check),
968        Cmd::New {
969            name,
970            lib,
971            embed,
972            target,
973            htl,
974            no_x,
975        } => cmd_new(&name, lib, embed, target.as_deref(), htl.as_deref(), no_x),
976        Cmd::Init {
977            dir,
978            lib,
979            embed,
980            target,
981            htl,
982            no_x,
983        } => cmd_init(
984            dir.as_deref(),
985            lib,
986            embed,
987            target.as_deref(),
988            htl.as_deref(),
989            no_x,
990        ),
991        Cmd::Pin {
992            htl,
993            dir,
994            no_update,
995        } => pin::cmd_pin(&htl, dir, no_update),
996        Cmd::Gen { file, out } => cmd_gen(&file, out.as_deref()),
997        Cmd::Run { file, args } => cmd_run(&file, &args),
998        Cmd::Fix {
999            paths,
1000            rule,
1001            unsafe_fixes,
1002            dry_run,
1003            diff,
1004            allow_dirty,
1005            allow_no_vcs,
1006            exit_non_zero_on_fix,
1007            format,
1008        } => cmd_fix(
1009            &paths,
1010            FixFlags {
1011                rule,
1012                unsafe_fixes,
1013                dry_run: dry_run || diff,
1014                diff,
1015                allow_dirty,
1016                allow_no_vcs,
1017                exit_non_zero_on_fix,
1018                json: format == Format::Json,
1019            },
1020        ),
1021        Cmd::Build {
1022            entry,
1023            out,
1024            main,
1025            debug,
1026            source,
1027            extra,
1028            host,
1029            no_cache,
1030            explain_cache,
1031        } => cmd_build(
1032            &entry,
1033            &out,
1034            &main,
1035            htl::link::LinkOptions {
1036                debug,
1037                source,
1038                extra,
1039                host,
1040                entry_name: None,
1041            },
1042            BuildCache {
1043                use_cache: !no_cache,
1044                explain: explain_cache,
1045            },
1046        ),
1047        Cmd::Unused {
1048            paths,
1049            format,
1050            exit_non_zero_on_unused,
1051            no_cache,
1052            explain_cache,
1053        } => cmd_unused(
1054            &paths,
1055            UnusedFlags {
1056                json: format == Format::Json,
1057                fail_on_unused: exit_non_zero_on_unused,
1058                use_cache: !no_cache,
1059                explain: explain_cache,
1060            },
1061        ),
1062        Cmd::Adopt {
1063            paths,
1064            format,
1065            detail,
1066            no_cache,
1067            explain_cache,
1068        } => cmd_adopt(
1069            &paths,
1070            AdoptFlags {
1071                json: format == Format::Json,
1072                detail,
1073                use_cache: !no_cache,
1074                explain: explain_cache,
1075            },
1076        ),
1077        Cmd::Resolve {
1078            module,
1079            path,
1080            format,
1081        } => cmd_resolve(&module, path.as_deref(), format == Format::Json),
1082        Cmd::Bundle { cmd } => match cmd {
1083            BundleCmd::Info { file, format } => cmd_bundle_info(&file, format == Format::Json),
1084        },
1085        Cmd::Lsp => lsp::serve(),
1086    }
1087}
1088
1089/// The reporting layer, for the commands that report without a `--format` of their own.
1090///
1091/// `htl check` and `htl test` hand their findings to a [`project::Sink`] over a
1092/// [`report::Out`]; `gen` / `run` / `build` used to loop `eprintln!` over the three
1093/// vectors themselves, so the same finding read differently depending on which verb was
1094/// typed. They come through here instead, and there is one renderer again.
1095///
1096/// One sink per command run, not per file: what the layer decides once per run — a
1097/// dependency's error said once, and never on behalf of a file the run checks itself —
1098/// is then once per *command*, which is what `htl build` over a closure of modules wants.
1099fn text_sink() -> project::Sink<report::Out> {
1100    project::Sink::new(report::Out::new(false, false))
1101}
1102
1103/// What else a verdict counted besides errors, for a summary line: a finding at `deny`,
1104/// and under `strict` every warning and lint. Empty when neither. Without it a run that
1105/// failed on a lint would end in `0 error(s)`.
1106fn judged(found: &htl::verdict::Findings, policy: &htl::verdict::Policy) -> String {
1107    let mut out = String::new();
1108    if policy.capped {
1109        return out;
1110    }
1111    if found.denied > 0 {
1112        out.push_str(&format!(", {} at deny", found.denied));
1113    }
1114    if policy.strict && found.warnings + found.lints > 0 {
1115        out.push_str(&format!(
1116            ", {} warning(s) and {} lint(s) under strict",
1117            found.warnings, found.lints
1118        ));
1119    }
1120    out
1121}
1122
1123/// Hand the checker the project's `[lang]`: whether `async` / `await` are keywords in the
1124/// files it is about to read. For a command that parses without a checker of the project's
1125/// ([`checker_for`] sets this itself).
1126fn config_lang(h: &Htl, cfg: &project::Config) -> Result<()> {
1127    h.set_lang(&project::lang_of(cfg))
1128}
1129
1130/// (Re)generate the `.d.tl` files this project declares: the ones a Rust crate's
1131/// `#[host_module]` / `#[derive(TealRecord)]` ask for, so the checker sees Rust-side
1132/// modules before any `cargo build`, and the module each `---@contract` type is declared
1133/// in, which is what an outside author writes their modules against. Quiet unless
1134/// something was written.
1135///
1136/// A contract that could not be published is said here, on every command that generates:
1137/// `htl check` reports it again as a lint (which `strict` makes fatal) and `htl dts`
1138/// exits non-zero on it, but `run` / `test` / `build` have neither, and a declaration
1139/// that is quietly not written is one an outside author finds missing later.
1140fn auto_dts(start: &Path) -> Result<()> {
1141    auto_dts_to(start, true)
1142}
1143
1144/// [`auto_dts`], writing only when `write` is set. A dry run (`htl fix --dry-run` /
1145/// `--diff`) works out every declaration the same way and says which it would write, and
1146/// what it then checks is the declarations as they are on disk — which is why it says so.
1147fn auto_dts_to(start: &Path, write: bool) -> Result<()> {
1148    let mut project = None;
1149    if let Some((root, _, cfg)) = load_config(start)? {
1150        // The contracts the project's model holds, published from there.
1151        let model = htl::model::Project::load(&root, cfg)?;
1152        let contracts: Vec<_> = model.contracts.iter().map(|c| c.terms.clone()).collect();
1153        let (results, problems) = htl::contract::publish_to(&root, &contracts, write);
1154        announce_dts_to(&results, &root, write);
1155        for p in &problems {
1156            eprintln!("dts: {p}");
1157        }
1158        project = Some(root);
1159    }
1160    let Some(root) = htl::dts::find_cargo_package_root(start) else {
1161        return Ok(());
1162    };
1163    let results =
1164        htl::dts::generate_crate_to(&root, write).map_err(|e| anyhow::anyhow!("htl dts: {e}"))?;
1165    announce_dts_to(&results, &root, write);
1166    let types_root = project.unwrap_or_else(|| root.clone());
1167    let report = dep_dts_to(&root, &types_root, write);
1168    announce_dts_to(&report.written, &types_root, write);
1169    announce_dep_report(&report, "dts: ");
1170    Ok(())
1171}
1172
1173/// What `htl dts` has to say about the declarations its dependencies ship. Three kinds,
1174/// kept apart because they mean three different things to the reader and to the exit code
1175/// — which is the distinction the single `[htl <rule>]` suffix they all used to carry was
1176/// hiding. None of them is a lint: no rule name, nothing to configure or silence, and
1177/// nothing that reaches the `Sink`, so `htl check` neither counts one nor carries one in
1178/// `--format json` — it prints them, prefixed `dts:`, exactly as this command does.
1179#[derive(Default)]
1180struct DepReport {
1181    /// `(target, written)` pairs, in the shape the rest of the report prints.
1182    written: Vec<(PathBuf, bool)>,
1183    /// Asked for and not written. This, and only this, is what `htl dts` exits non-zero on.
1184    not_written: Vec<String>,
1185    /// Under `types/` and no longer shipped by anything. Reported, never deleted, and it
1186    /// fails nothing: what the file is for is the project's to say.
1187    left_in_place: Vec<String>,
1188    /// The crate graph would not resolve, so nothing was asked for — cargo could not be
1189    /// run, or the project's lockfile does not cover its manifest and the graph is read
1190    /// with `--locked`. Either way the committed declarations stand and the check that
1191    /// follows names the module if one is missing, which is why this fails nothing.
1192    unresolved: Option<String>,
1193}
1194
1195/// Materialise the declarations this project's dependencies ship, under
1196/// `<declaration root>/<crate>/` — the declaration root of the project at `types_root`,
1197/// `types/` unless its `htl.toml` says otherwise — and report on what happened to each.
1198///
1199/// The graph comes from `cargo metadata`, so this costs a subprocess on every command that
1200/// generates. Nothing is built, and nothing is downloaded for dependencies already fetched.
1201fn dep_dts(cargo_root: &Path, types_root: &Path) -> DepReport {
1202    dep_dts_to(cargo_root, types_root, true)
1203}
1204
1205/// [`dep_dts`], writing only when `write` is set.
1206fn dep_dts_to(cargo_root: &Path, types_root: &Path, write: bool) -> DepReport {
1207    let decls = match htl::dep_dts::resolve(cargo_root) {
1208        Ok(d) => d,
1209        Err(e) => {
1210            return DepReport {
1211                unresolved: Some(e),
1212                ..DepReport::default()
1213            };
1214        }
1215    };
1216    // Orphans before materialising: the note beside a crate's declarations is what says
1217    // which crate they came from, and the write below rewrites it.
1218    let types = match decl_root(types_root) {
1219        Ok(t) => t,
1220        Err(e) => {
1221            return DepReport {
1222                unresolved: Some(format!("{e:#}")),
1223                ..DepReport::default()
1224            };
1225        }
1226    };
1227    let left_in_place = htl::dep_dts::orphans(&types, &decls);
1228    let (written, not_written) = htl::dep_dts::materialise_to(&types, &decls, write);
1229    DepReport {
1230        written,
1231        not_written,
1232        left_in_place,
1233        unresolved: None,
1234    }
1235}
1236
1237/// The three report lists, each said as what it is. `wrote` / `unchanged` name what
1238/// happened to a declaration, and so do these: a reader who has never heard the words
1239/// `shipped-declaration` or `orphaned-declaration` can still tell which line failed the
1240/// command and which one is a file sitting there to decide about.
1241fn announce_dep_report(report: &DepReport, prefix: &str) {
1242    for p in &report.not_written {
1243        eprintln!("{prefix}not written: {p}");
1244    }
1245    for p in &report.left_in_place {
1246        eprintln!("{prefix}left in place: {p}");
1247    }
1248    if let Some(e) = &report.unresolved {
1249        eprintln!("{prefix}{e}");
1250    }
1251}
1252
1253/// What generation wrote, or for a run that did not write (`wrote` unset) what it would
1254/// have.
1255fn announce_dts_to(results: &[(PathBuf, bool)], root: &Path, wrote: bool) {
1256    for (target, changed) in results {
1257        if *changed {
1258            let target = target.strip_prefix(root).unwrap_or(target).display();
1259            if wrote {
1260                eprintln!("dts: wrote {target}");
1261            } else {
1262                eprintln!(
1263                    "dts: would write {target} (dry run: not written; checked against the \
1264                     file on disk)"
1265                );
1266            }
1267        }
1268    }
1269}
1270
1271fn cmd_dts(dir: Option<&Path>) -> Result<ExitCode> {
1272    let start = match dir {
1273        Some(d) => d.to_path_buf(),
1274        None => std::env::current_dir()?,
1275    };
1276    // The contract types first: a project may publish one without having a Rust host at
1277    // all, and the `bail!` below would then be wrong about there being nothing to do.
1278    let mut results = Vec::new();
1279    let mut failed = false;
1280    let mut project = None;
1281    if let Some((croot, _, cfg)) = load_config(&start)? {
1282        let model = htl::model::Project::load(&croot, cfg)?;
1283        let contracts: Vec<_> = model.contracts.iter().map(|c| c.terms.clone()).collect();
1284        let (published, problems) = htl::contract::publish(&croot, &contracts);
1285        for p in &problems {
1286            eprintln!("  {p}");
1287        }
1288        // Asked to generate and did not: the command says so in its exit code, or a CI
1289        // step that regenerates declarations would pass having written nothing.
1290        failed = !problems.is_empty();
1291        results.extend(published);
1292        project = Some(croot);
1293    }
1294    let code = |failed: bool| {
1295        if failed {
1296            ExitCode::FAILURE
1297        } else {
1298            ExitCode::SUCCESS
1299        }
1300    };
1301    let Some(root) = htl::dts::find_cargo_package_root(&start) else {
1302        if results.is_empty() && !failed {
1303            bail!(
1304                "no Cargo.toml with a [package] section, and no ---@contract type to publish, \
1305                 at or above {}",
1306                start.display()
1307            );
1308        }
1309        report_dts(&results, &start);
1310        return Ok(code(failed));
1311    };
1312    results.extend(htl::dts::generate_crate(&root).map_err(|e| anyhow::anyhow!("{e}"))?);
1313    let types_root = project.unwrap_or_else(|| root.clone());
1314    let report = dep_dts(&root, &types_root);
1315    announce_dep_report(&report, "  ");
1316    // An orphan, and a graph that would not resolve, are reports. A declaration asked for
1317    // and not written is a failure, the same as a contract that could not be published.
1318    failed = failed || !report.not_written.is_empty();
1319    results.extend(report.written);
1320    report_dts(&results, &root);
1321    Ok(code(failed))
1322}
1323
1324fn report_dts(results: &[(PathBuf, bool)], root: &Path) {
1325    let mut written = 0usize;
1326    for (target, w) in results {
1327        let rel = target.strip_prefix(root).unwrap_or(target).display();
1328        eprintln!("  {} {}", if *w { "wrote    " } else { "unchanged" }, rel);
1329        written += usize::from(*w);
1330    }
1331    eprintln!(
1332        "htl dts: {} declaration(s) from {}, {} written",
1333        results.len(),
1334        root.display(),
1335        written
1336    );
1337}
1338
1339/// What became of one file a command that generates files (`htl shapes`, `htl rs`) writes.
1340enum Generated {
1341    Wrote,
1342    Current,
1343    /// It was its own and what it was generated for lowers to nothing now.
1344    Removed,
1345    /// It exists and does not start with the header the command writes: not its own.
1346    Foreign,
1347}
1348
1349/// The commands that write generated files, which share the rules for them (`written_by`,
1350/// `remove_generated`, `write_generated`) and say what became of a file in the words of
1351/// their own (`announce`).
1352#[derive(Clone, Copy)]
1353enum Writer {
1354    Shapes,
1355    Rs,
1356}
1357
1358impl Writer {
1359    /// What starts the first line of every file the command writes.
1360    fn header(self) -> &'static str {
1361        match self {
1362            Writer::Shapes => htl::shapes::HEADER,
1363            Writer::Rs => htl::rsgen::HEADER,
1364        }
1365    }
1366}
1367
1368/// Whether the file at `path` exists and starts with the header `who` writes: one `who`
1369/// wrote. No file is `false`; a file that is there and cannot be read is an error, not
1370/// "somebody else's", so a permission problem is reported as one.
1371fn written_by(path: &Path, who: Writer) -> Result<bool> {
1372    match fs::read_to_string(path) {
1373        Ok(cur) => Ok(cur.starts_with(who.header())),
1374        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(false),
1375        Err(e) => Err(e).with_context(|| format!("reading {}", path.display())),
1376    }
1377}
1378
1379/// The two files a module lowers to: `<source>/shapes/<module>.lua` and
1380/// `<types>/shapes/<module>.d.tl`.
1381fn shape_targets(source: &Path, types: &Path, module: &str) -> [PathBuf; 2] {
1382    let name = module.replace('.', "/");
1383    [
1384        source.join("shapes").join(format!("{name}.lua")),
1385        types.join("shapes").join(format!("{name}.d.tl")),
1386    ]
1387}
1388
1389/// Remove a file `who` wrote for what lowers to nothing now. `None` when there is no such
1390/// file; a file that is not its own is left (`Foreign`).
1391fn remove_generated(path: &Path, who: Writer) -> Result<Option<Generated>> {
1392    if !path.exists() {
1393        return Ok(None);
1394    }
1395    if !written_by(path, who)? {
1396        return Ok(Some(Generated::Foreign));
1397    }
1398    fs::remove_file(path).with_context(|| format!("removing {}", path.display()))?;
1399    Ok(Some(Generated::Removed))
1400}
1401
1402/// `path` as the table of shapes spells it: symlinks and `..` resolved.
1403fn canonical_path(p: &Path) -> PathBuf {
1404    fs::canonicalize(p).unwrap_or_else(|_| p.to_path_buf())
1405}
1406
1407/// Write `text` to `path` when it would change, unless the file is somebody's: a target
1408/// that exists and whose first line is not the header `who` writes is left as it is.
1409fn write_generated(path: &Path, text: &str, who: Writer) -> Result<Generated> {
1410    if path.exists() && !written_by(path, who)? {
1411        return Ok(Generated::Foreign);
1412    }
1413    let changed = htl::write_if_changed_when(path, text, true)
1414        .with_context(|| format!("writing {}", path.display()))?;
1415    Ok(if changed {
1416        Generated::Wrote
1417    } else {
1418        Generated::Current
1419    })
1420}
1421
1422/// `htl shapes`: the module doc of `htl::shapes` says what is lowered and how; this is the
1423/// part that reads and writes files.
1424///
1425/// Two passes over the project's sources, because a shape names the shapes of other files:
1426/// the first checks every file and collects where each declaration is ([`htl::shapes::RefTable`]),
1427/// the second lowers each file against that table and writes what came out. A file with a
1428/// problem is not written, the others are, and the exit code says so.
1429fn cmd_shapes(dir: Option<&Path>) -> Result<ExitCode> {
1430    let start = match dir {
1431        Some(d) => d.to_path_buf(),
1432        None => std::env::current_dir()?,
1433    };
1434    let ProjectChecker { h, cfg, model, .. } = checker_for(&start, true)?;
1435    let Some((root, _, _)) = cfg else {
1436        bail!(
1437            "no htl.toml at or above {}: `htl shapes` writes into a project",
1438            start.display()
1439        );
1440    };
1441    let Some(model) = model else {
1442        bail!("no project at or above {}", start.display());
1443    };
1444    // The generated shapes are written against lshape, which this project supplies. An
1445    // implementation, not a declaration: after a first run `types/lshape.d.tl` is a row of
1446    // its own, and says nothing about whether a Lua module is there to load.
1447    let lshape = htl::resolve::resolve(&h, "lshape", Some(&root), Some(&model))?;
1448    if htl::shapes::lshape_runtime(&lshape).is_none() {
1449        eprintln!(
1450            "shapes: lshape is not on the path (no Lua or Teal module answers require(\"lshape\")); vendor or install it, then rerun"
1451        );
1452        return Ok(ExitCode::FAILURE);
1453    }
1454    let own = model.own();
1455    let Some(source) = own.roots.source.clone() else {
1456        bail!("the project at {} has no source directory", root.display());
1457    };
1458    let types = own.roots.decl.clone().unwrap_or_else(|| root.join("types"));
1459    let shown = |p: &Path| p.strip_prefix(&root).unwrap_or(p).to_path_buf();
1460
1461    // The files, and the modules they answer to. A module called `shapes` is in the
1462    // namespace the generated modules are written under; that is a rule of this command, so
1463    // it is said here, before any file is checked.
1464    let modules = project::own_modules(&model)?;
1465    let mut collides = false;
1466    for (file, name) in &modules {
1467        if name == "shapes" || name.starts_with("shapes.") {
1468            eprintln!(
1469                "shapes: module `{}` ({}) is in the namespace the generated modules are written under (shapes.*); rename it, then rerun",
1470                name,
1471                shown(file).display()
1472            );
1473            collides = true;
1474        }
1475    }
1476    if collides {
1477        return Ok(ExitCode::FAILURE);
1478    }
1479
1480    // Pass 1: check every file, keeping the index.
1481    let mut sink = text_sink();
1482    let mut failed = false;
1483    let checked = project::check_own_modules(&h, &root, modules)?;
1484    for f in &checked {
1485        // A file whose check fails is reported, fails the run, and is lowered all the same:
1486        // the index is kept for any file that parsed, and a field whose type did not
1487        // resolve is refused at that field by the lowering itself. What this buys is the
1488        // first run. A file that requires `shapes.<m>` before that module exists fails its
1489        // check on that line and nothing else; written anyway, the second run is clean.
1490        // Skipped, a file that asserts its own records could never be written at all.
1491        if f.failed {
1492            sink.checkinfo(&f.info);
1493            failed = true;
1494        }
1495    }
1496
1497    // The table of declarations, and each file lowered against it.
1498    let sources: Vec<htl::shapes::Source> = checked
1499        .iter()
1500        .map(|f| htl::shapes::Source {
1501            module: &f.module,
1502            rel_path: &f.rel,
1503            info: &f.info,
1504        })
1505        .collect();
1506    let htl::shapes::ProjectShapes { lowered, cycles } =
1507        htl::shapes::lower_project(&sources, canonical_path);
1508    let in_cycle = |module: &str| cycles.iter().find(|g| g.iter().any(|m| m == module));
1509
1510    // A module that is refused keeps the files an earlier run wrote for it, which still
1511    // validate against the old shape: said, not left standing in silence.
1512    let say_stale = |module: &str| -> Result<()> {
1513        for target in shape_targets(&source, &types, module) {
1514            if written_by(&target, Writer::Shapes)? {
1515                eprintln!(
1516                    "shapes: {} left as it was and is stale: the module is refused above",
1517                    shown(&target).display()
1518                );
1519            }
1520        }
1521        Ok(())
1522    };
1523
1524    for (f, l) in checked.iter().zip(&lowered) {
1525        match l {
1526            htl::shapes::Lowered::Nothing => {
1527                // Its records are gone: so are the files that were written for them. Only
1528                // when the check kept an index; a file that did not parse says nothing about
1529                // its records, and its files stay.
1530                if f.info.types.declarations().is_some() {
1531                    for target in shape_targets(&source, &types, &f.module) {
1532                        if let Some(g) = remove_generated(&target, Writer::Shapes)? {
1533                            failed |= announce(Writer::Shapes, &shown(&target), g);
1534                        }
1535                    }
1536                }
1537            }
1538            htl::shapes::Lowered::Refused { problems, notes } => {
1539                notes
1540                    .iter()
1541                    .chain(problems)
1542                    .for_each(|d| sink.diagnostic(d));
1543                say_stale(&f.module)?;
1544                failed = true;
1545            }
1546            htl::shapes::Lowered::Written { output, notes, .. } => {
1547                notes.iter().for_each(|d| sink.diagnostic(d));
1548                if let Some(group) = in_cycle(&f.module) {
1549                    let named: Vec<String> =
1550                        group.iter().map(|m| format!("`shapes.{m}`")).collect();
1551                    let (last, init) = named.split_last().expect("a cycle has members");
1552                    let all = if init.is_empty() {
1553                        last.clone()
1554                    } else {
1555                        format!("{} and {last}", init.join(", "))
1556                    };
1557                    sink.diagnostic(&htl::Diagnostic::new(
1558                        htl::Severity::Error,
1559                        f.rel.display().to_string(),
1560                        1,
1561                        1,
1562                        format!(
1563                            "{all} require each other, a `require` loop Lua cannot load; move the records they share into one module"
1564                        ),
1565                        None,
1566                    ));
1567                    say_stale(&f.module)?;
1568                    failed = true;
1569                    continue;
1570                }
1571                let [lua, dtl] = shape_targets(&source, &types, &f.module);
1572                failed |= announce(
1573                    Writer::Shapes,
1574                    &shown(&lua),
1575                    write_generated(&lua, &output.lua, Writer::Shapes)?,
1576                );
1577                failed |= announce(
1578                    Writer::Shapes,
1579                    &shown(&dtl),
1580                    write_generated(&dtl, &output.dtl, Writer::Shapes)?,
1581                );
1582            }
1583        }
1584    }
1585    let lshape_dtl = types.join("lshape.d.tl");
1586    failed |= announce(
1587        Writer::Shapes,
1588        &shown(&lshape_dtl),
1589        write_generated(&lshape_dtl, htl::shapes::LSHAPE_DTL, Writer::Shapes)?,
1590    );
1591    Ok(if failed {
1592        ExitCode::FAILURE
1593    } else {
1594        ExitCode::SUCCESS
1595    })
1596}
1597
1598/// `htl rs`: the module doc of `htl::rsgen` says what is lowered and how; this is the part
1599/// that reads and writes files.
1600///
1601/// The project's own sources are checked (`project::own_sources`, which `htl shapes` walks
1602/// too) and handed to `htl::rsgen::generate`, whose answer is then written, or, under
1603/// `--check`, compared with the file. Nothing is written when any own file fails its check,
1604/// or when `generate` refuses.
1605fn cmd_rs(dir: Option<&Path>, check: bool) -> Result<ExitCode> {
1606    let start = match dir {
1607        Some(d) => d.to_path_buf(),
1608        None => std::env::current_dir()?,
1609    };
1610    // `--check` writes nothing, the `.d.tl` files every command refreshes first included.
1611    let ProjectChecker { h, cfg, model, .. } = checker_for(&start, !check)?;
1612    let Some((root, _, cfg)) = cfg else {
1613        bail!(
1614            "no htl.toml at or above {}: `htl rs` writes into a project",
1615            start.display()
1616        );
1617    };
1618    let Some(model) = model else {
1619        bail!("no project at or above {}", start.display());
1620    };
1621    let Some(source) = model.own().roots.source.clone() else {
1622        bail!("the project at {} has no source directory", root.display());
1623    };
1624    let out = match &cfg.rust.out {
1625        Some(p) => root.join(p),
1626        None => source.join("teal_types.rs"),
1627    };
1628    let shown = out.strip_prefix(&root).unwrap_or(&out).to_path_buf();
1629    let spec = htl::rsgen::Spec::from(&cfg.rust);
1630
1631    // Nothing is asked for: nothing is checked, and a file an earlier run wrote is no longer
1632    // wanted. One that is somebody's is none of this command's business.
1633    if spec.is_empty() {
1634        eprintln!("htl rs: nothing to write ([rust] modules and exports are empty)");
1635        if !written_by(&out, Writer::Rs)? {
1636            return Ok(ExitCode::SUCCESS);
1637        }
1638        if check {
1639            eprintln!("htl rs: {} is stale; run htl rs", shown.display());
1640            return Ok(ExitCode::FAILURE);
1641        }
1642        if let Some(g) = remove_generated(&out, Writer::Rs)? {
1643            announce(Writer::Rs, &shown, g);
1644        }
1645        return Ok(ExitCode::SUCCESS);
1646    }
1647
1648    // A file that fails its check is reported, and nothing is written: a record that does
1649    // not check is not one a Rust type can be generated from. (`htl shapes` lowers such a
1650    // file all the same, for a reason that is its own: it requires the module it is
1651    // generating, on the first run.) The listed modules are not the only ones that count:
1652    // a type of an unlisted module is what a listed one's field resolves against.
1653    let mut sink = text_sink();
1654    let checked = project::own_sources(&h, &root, &model)?;
1655    let mut failed = false;
1656    for f in checked.iter().filter(|f| f.failed) {
1657        sink.checkinfo(&f.info);
1658        failed = true;
1659    }
1660    if failed {
1661        eprintln!("htl rs: {} not written", shown.display());
1662        return Ok(ExitCode::FAILURE);
1663    }
1664
1665    let sources: Vec<htl::shapes::Source> = checked
1666        .iter()
1667        .map(|f| htl::shapes::Source {
1668            module: &f.module,
1669            rel_path: &f.rel,
1670            info: &f.info,
1671        })
1672        .collect();
1673    let text = match htl::rsgen::generate(&sources, &spec, canonical_path) {
1674        htl::rsgen::Rendered::Text { text, notes } => {
1675            notes.iter().for_each(|d| sink.diagnostic(d));
1676            text
1677        }
1678        htl::rsgen::Rendered::Refused { problems, notes } => {
1679            notes
1680                .iter()
1681                .chain(&problems)
1682                .for_each(|d| sink.diagnostic(d));
1683            eprintln!("htl rs: {} not written", shown.display());
1684            return Ok(ExitCode::FAILURE);
1685        }
1686        // `modules` and `exports` were not both empty above.
1687        htl::rsgen::Rendered::Nothing => return Ok(ExitCode::SUCCESS),
1688    };
1689
1690    // A target somebody else wrote is never touched, under `--check` as well: the answer
1691    // to "is it what htl rs would write" is no, and the way out is the same.
1692    if out.exists() && !written_by(&out, Writer::Rs)? {
1693        return Ok(announce_exit(Writer::Rs, &shown, Generated::Foreign));
1694    }
1695    if check {
1696        let stale = htl::write_if_changed_when(&out, &text, false)
1697            .with_context(|| format!("reading {}", out.display()))?;
1698        if stale {
1699            eprintln!("htl rs: {} is stale; run htl rs", shown.display());
1700            return Ok(ExitCode::FAILURE);
1701        }
1702        return Ok(announce_exit(Writer::Rs, &shown, Generated::Current));
1703    }
1704    Ok(announce_exit(
1705        Writer::Rs,
1706        &shown,
1707        write_generated(&out, &text, Writer::Rs)?,
1708    ))
1709}
1710
1711/// [`announce`], as the exit code of a command whose only file this is.
1712fn announce_exit(who: Writer, rel: &Path, g: Generated) -> ExitCode {
1713    if announce(who, rel, g) {
1714        ExitCode::FAILURE
1715    } else {
1716        ExitCode::SUCCESS
1717    }
1718}
1719
1720/// Say what became of one generated file, one line on stderr, in the words of the command
1721/// that wrote it. `true` when the file was not its to write, which fails the run.
1722fn announce(who: Writer, rel: &Path, g: Generated) -> bool {
1723    let rel = rel.display();
1724    match (who, g) {
1725        (Writer::Shapes, Generated::Wrote) => eprintln!("shapes: wrote {rel}"),
1726        (Writer::Shapes, Generated::Current) => eprintln!("shapes: current {rel}"),
1727        (Writer::Shapes, Generated::Removed) => eprintln!("shapes: removed {rel}"),
1728        (Writer::Shapes, Generated::Foreign) => {
1729            eprintln!("shapes: {rel} exists and was not written by htl shapes; move it aside");
1730            return true;
1731        }
1732        (Writer::Rs, Generated::Wrote) => eprintln!("htl rs: wrote {rel}"),
1733        (Writer::Rs, Generated::Current) => eprintln!("htl rs: {rel} is current"),
1734        (Writer::Rs, Generated::Removed) => eprintln!("htl rs: removed {rel}"),
1735        (Writer::Rs, Generated::Foreign) => {
1736            eprintln!("htl rs: {rel} is not written by htl rs; move it, or set [rust] out");
1737            return true;
1738        }
1739    }
1740    false
1741}
1742
1743/// What the run wrote, and — when a target was asked for by name — what it left alone. The
1744/// kept list is what makes `htl init --target bin` on an older project say which of that
1745/// target's files were already there instead of skipping them in silence.
1746fn report_scaffold(dir: &Path, written: &[PathBuf], kept: &[PathBuf]) {
1747    let rel = |p: &PathBuf| p.strip_prefix(dir).unwrap_or(p).display().to_string();
1748    for p in written {
1749        eprintln!("  created {}", rel(p));
1750    }
1751    for p in kept {
1752        eprintln!("  kept    {} (already there)", rel(p));
1753    }
1754    if kept.is_empty() {
1755        eprintln!(
1756            "htl: {} file(s) written under {}",
1757            written.len(),
1758            dir.display()
1759        );
1760    } else {
1761        eprintln!(
1762            "htl: {} file(s) written, {} kept under {}",
1763            written.len(),
1764            kept.len(),
1765            dir.display()
1766        );
1767    }
1768}
1769
1770fn cmd_new(
1771    name: &str,
1772    lib: bool,
1773    embed: bool,
1774    target: Option<&str>,
1775    htl: Option<&str>,
1776    no_x: bool,
1777) -> Result<ExitCode> {
1778    let dir = PathBuf::from(name);
1779    let pkg_name = dir
1780        .file_name()
1781        .and_then(|s| s.to_str())
1782        .ok_or_else(|| anyhow::anyhow!("invalid project name: {name}"))?
1783        .to_string();
1784    // Before the directory is touched: an unknown target, or one that disagrees with
1785    // --lib, fails here and leaves nothing behind. So does an htl this scaffold does not
1786    // write for — a release by number — so it is settled first too.
1787    let target = scaffold::resolve_target(target, embed, lib)?;
1788    let htl = scaffold::HtlPin::parse(htl)?;
1789    let opts = scaffold::Options {
1790        lib,
1791        target,
1792        htl,
1793        no_x,
1794    };
1795    let done = scaffold::scaffold(&dir, &pkg_name, &opts, true)?;
1796    report_scaffold(&dir, &done.written, &[]);
1797    // The manifest names a dependency: the fetch comes before the first test, or the
1798    // first test is a `module not found`.
1799    let fetch = if opts.writes_htlx() {
1800        "htl pkg install && "
1801    } else {
1802        ""
1803    };
1804    // The window target's first build needs two files nothing has written yet: `htl check`
1805    // materialises the dependency's declaration as `types/htl-mq/mq.d.tl` (from its
1806    // `[package.metadata.htl] dts`) and writes `src/fx.d.tl` from the host module, and
1807    // `cargo build` reads the first of them when `include_bundle!` links `mq`. So the
1808    // check comes before the run rather than after it.
1809    let then = match opts.target.map(|t| t.target) {
1810        Some(BuildTarget::Window) => "htl check . && cargo run",
1811        _ => "htl test",
1812    };
1813    eprintln!("next: cd {} && {fetch}{then}", dir.display());
1814    Ok(ExitCode::SUCCESS)
1815}
1816
1817fn cmd_init(
1818    dir: Option<&Path>,
1819    lib: bool,
1820    embed: bool,
1821    target: Option<&str>,
1822    htl: Option<&str>,
1823    no_x: bool,
1824) -> Result<ExitCode> {
1825    let dir = match dir {
1826        Some(d) => d.to_path_buf(),
1827        None => std::env::current_dir()?,
1828    };
1829    let abs = std::fs::canonicalize(&dir).unwrap_or(dir.clone());
1830    let name = abs
1831        .file_name()
1832        .and_then(|s| s.to_str())
1833        .ok_or_else(|| anyhow::anyhow!("cannot derive a project name from {}", abs.display()))?
1834        .to_string();
1835    let asked_for_a_target = target.is_some() || embed;
1836    let target = scaffold::resolve_target(target, embed, lib)?;
1837    let htl = scaffold::HtlPin::parse(htl)?;
1838    let opts = scaffold::Options {
1839        lib,
1840        target,
1841        htl,
1842        no_x,
1843    };
1844    let done = scaffold::scaffold(&dir, &name, &opts, false)?;
1845    // A target was named: say what it would have written and found already there. Without
1846    // one the old one-liner stands, so a plain re-run does not list the whole tree.
1847    let kept: &[PathBuf] = if asked_for_a_target { &done.kept } else { &[] };
1848    if done.written.is_empty() && kept.is_empty() {
1849        eprintln!("htl init: nothing to do, all scaffold files already exist");
1850    } else {
1851        report_scaffold(&dir, &done.written, kept);
1852    }
1853    Ok(ExitCode::SUCCESS)
1854}
1855
1856/// The project `htl pkg` acts on: the one above the working directory, found the way
1857/// every command finds it ([`htl::model::Project::find_root`]), with its `mlua-pkg.toml`.
1858///
1859/// mlua-pkg reports a missing manifest as an I/O error that does not name the file, and the
1860/// path htl looked for is the whole of the answer, so it is checked here.
1861fn pkg_project() -> Result<htl::pkg::MluaProject> {
1862    let cwd = std::env::current_dir()?;
1863    let root = htl::model::Project::find_root(&cwd)?.map(|r| r.root);
1864    root.filter(|r| r.join(htl::pkg::MANIFEST_NAME).is_file())
1865        .map(|r| htl::pkg::MluaProject::at(&r))
1866        .with_context(|| {
1867            format!(
1868                "no {} above {}: `htl pkg` runs in a project",
1869                htl::pkg::MANIFEST_NAME,
1870                cwd.display()
1871            )
1872        })
1873}
1874
1875/// The declaration root of the project at `root`, from its model: `[layout] types`, which
1876/// is `types/` unless `htl.toml` says otherwise — where the declarations htl brings into a
1877/// project are written.
1878fn decl_root(root: &Path) -> Result<PathBuf> {
1879    let cfg = load_config(root)?;
1880    Ok(project::model_of(&cfg, root)?
1881        .and_then(|m| m.own().roots.decl.clone())
1882        .unwrap_or_else(|| root.join("types")))
1883}
1884
1885/// `htl pkg install`: fetch what the manifest declares, then bring in what the deps publish.
1886fn cmd_pkg_install() -> Result<ExitCode> {
1887    let project = pkg_project()?;
1888    let report = project.install()?;
1889    report_install(&report, &project);
1890    // Re-read the project: install wrote the lockfile the two reports below are read from.
1891    // A dep publishes its declarations at `types/` in its package root, which is not where
1892    // `require` looks, so they are copied in for the checker to see.
1893    let project = htl::pkg::MluaProject::at(&project.root);
1894    report_types_sync(
1895        &project.sync_types(&decl_root(&project.root)?)?,
1896        &project.root,
1897    );
1898    report_patch_drift(&project);
1899    Ok(ExitCode::SUCCESS)
1900}
1901
1902/// What install did, in the shape the other reports use. The library prints nothing.
1903fn report_install(
1904    report: &htl::pkg::mlua_pkg::ops::InstallReport,
1905    project: &htl::pkg::MluaProject,
1906) {
1907    use htl::pkg::mlua_pkg::ops::Placement;
1908    for w in &report.warnings {
1909        // A patch that was not used is reported below in htl's own verbs, where both ways
1910        // out are named. The library's line points at `mlua-pkg patch --force`, which
1911        // rebuilds the copy without asking git whether what is in it was committed.
1912        if w.contains("patch_dir") && w.contains("not used") {
1913            continue;
1914        }
1915        eprintln!("warning: {w}");
1916    }
1917    let rel = |p: &Path| {
1918        p.strip_prefix(&project.root)
1919            .unwrap_or(p)
1920            .display()
1921            .to_string()
1922    };
1923    for p in &report.packages {
1924        let sha: String = p.sha.chars().take(7).collect();
1925        let where_it_is = match (&p.placement, p.patched) {
1926            (_, true) => format!("from {}", rel(p.root())),
1927            (Placement::Copied(dest), _) => format!("copied to {}", rel(dest)),
1928            (Placement::Symlink(_), _) => p.entry.display().to_string(),
1929        };
1930        eprintln!("  install {} {sha} ({where_it_is})", p.name);
1931    }
1932    let n = report.packages.len();
1933    if report.transitive > 0 {
1934        eprintln!(
1935            "htl pkg install: {n} package(s), {} of them transitive",
1936            report.transitive
1937        );
1938    } else {
1939        eprintln!("htl pkg install: {n} package(s)");
1940    }
1941}
1942
1943/// `htl pkg add <name> <git>`: the manifest entry, without fetching anything.
1944///
1945/// This is the one verb that may run outside a project: mlua-pkg writes a manifest when
1946/// there is none. It writes it at the project's root — beside `htl.toml`, when the working
1947/// directory is in a project that has one — and in the working directory only outside any
1948/// project. Written in a subdirectory, it would give the project a second root, which
1949/// every command then refuses.
1950fn cmd_pkg_add(spec: htl::pkg::mlua_pkg::ops::AddSpec) -> Result<ExitCode> {
1951    use htl::pkg::mlua_pkg::ops::AddOutcome;
1952    let cwd = std::env::current_dir()?;
1953    let root = htl::model::Project::find_root(&cwd)?
1954        .map(|r| r.root)
1955        .unwrap_or(cwd);
1956    let project = htl::pkg::MluaProject::at(&root);
1957    let name = spec.name.clone();
1958    let done = project.add(spec)?;
1959    let manifest = project
1960        .manifest
1961        .strip_prefix(&project.root)
1962        .unwrap_or(&project.manifest)
1963        .display();
1964    if done.report.manifest_created {
1965        eprintln!("  created {manifest}");
1966    }
1967    let verb = match done.report.outcome {
1968        AddOutcome::Added => "added",
1969        AddOutcome::Replaced => "updated",
1970    };
1971    eprintln!("  {verb}   {name} in {manifest}");
1972    if let Some(dir) = &done.kept_patch_dir {
1973        // `add` rewrites the entry, and its spec has no room for a patch. Putting the key
1974        // back is the difference between the project resolving that dependency from its own
1975        // copy and resolving it from upstream with the copy left unread in the tree.
1976        eprintln!(
1977            "  kept    patch_dir = {} ({name} is patched)",
1978            dir.display()
1979        );
1980    }
1981    eprintln!("htl pkg add: run `htl pkg install` to fetch it");
1982    Ok(ExitCode::SUCCESS)
1983}
1984
1985/// `htl pkg update [name]`: what each pin does next, then the install that follows.
1986fn cmd_pkg_update(opts: htl::pkg::mlua_pkg::ops::UpdateOpts) -> Result<ExitCode> {
1987    use htl::pkg::mlua_pkg::ops::UpdateOutcome;
1988    let project = pkg_project()?;
1989    let dry_run = opts.dry_run;
1990    let report = project.update(opts)?;
1991    if report.entries.is_empty() {
1992        eprintln!("htl pkg update: no dependency selected");
1993        return Ok(ExitCode::SUCCESS);
1994    }
1995    for (name, outcome) in &report.entries {
1996        match outcome {
1997            UpdateOutcome::TagBumped { old, new } => {
1998                eprintln!("  update  {name}: tag {old} -> {new}")
1999            }
2000            UpdateOutcome::PrefixResolved { pin, resolved } => eprintln!(
2001                "  update  {name}: prefix '{pin}' is {resolved} (the manifest keeps the prefix)"
2002            ),
2003            UpdateOutcome::Refresh => eprintln!("  update  {name}: refresh (branch or unpinned)"),
2004            UpdateOutcome::Skipped(why) => eprintln!("  skip    {name}: {why}"),
2005        }
2006    }
2007    if dry_run {
2008        eprintln!("htl pkg update: dry run; nothing was written");
2009        return Ok(ExitCode::SUCCESS);
2010    }
2011    if let Some(install) = &report.install {
2012        report_install(install, &project);
2013        let project = htl::pkg::MluaProject::at(&project.root);
2014        report_types_sync(
2015            &project.sync_types(&decl_root(&project.root)?)?,
2016            &project.root,
2017        );
2018        report_patch_drift(&project);
2019    }
2020    Ok(ExitCode::SUCCESS)
2021}
2022
2023/// `htl pkg clean`: the cache, which is machine-local and rebuilt by the next install.
2024fn cmd_pkg_clean(all: bool) -> Result<ExitCode> {
2025    use htl::pkg::mlua_pkg::ops::CleanReport;
2026    let project = pkg_project()?;
2027    match project.clean(all)? {
2028        CleanReport::CacheRemoved => eprintln!("htl pkg clean: removed every cached package"),
2029        CleanReport::NoLockfile => {
2030            eprintln!("htl pkg clean: no lockfile, so nothing was ever cached")
2031        }
2032        CleanReport::StaleRemoved { removed: 0 } => eprintln!("htl pkg clean: nothing to remove"),
2033        CleanReport::StaleRemoved { removed } => eprintln!(
2034            "htl pkg clean: removed {removed} cache entr{} the lockfile no longer refers to",
2035            if removed == 1 { "y" } else { "ies" }
2036        ),
2037    }
2038    Ok(ExitCode::SUCCESS)
2039}
2040
2041/// A patched copy the dependency is no longer resolved from, said after every install
2042/// until it is refreshed or removed.
2043///
2044/// A patch is bound to the revision it was taken from, and an upgrade moves the pin off it.
2045/// Install does not fail over that — the project builds against the new upstream — so the
2046/// only thing that keeps the copy from being forgotten in the tree is being told about it
2047/// each time. Both ways out are named, in htl's verbs: mlua-pkg's own warning points at
2048/// `mlua-pkg patch --force`, which skips the question htl asks git before overwriting.
2049fn report_patch_drift(project: &htl::pkg::MluaProject) {
2050    let short = |s: &str| s.chars().take(7).collect::<String>();
2051    for s in project.patch_status() {
2052        if s.in_use {
2053            continue;
2054        }
2055        let rel = s
2056            .dir
2057            .strip_prefix(&project.root)
2058            .unwrap_or(&s.dir)
2059            .display();
2060        let why = match (&s.base, &s.locked) {
2061            _ if !s.dir.is_dir() => "the copy is not there".to_string(),
2062            (None, _) => "the lockfile records no revision it was taken from".to_string(),
2063            (Some(b), Some(l)) => {
2064                format!("taken from {}, {} is now at {}", short(b), s.name, short(l))
2065            }
2066            (Some(b), None) => format!("taken from {}, and nothing is locked", short(b)),
2067        };
2068        eprintln!("  patch   {rel} is not in use ({why})");
2069        eprintln!(
2070            "          carry the change forward: commit it, then `htl pkg patch {}`",
2071            s.name
2072        );
2073        eprintln!("          drop it: remove patch_dir from mlua-pkg.toml and delete {rel}");
2074    }
2075}
2076
2077/// `htl pkg patch <dep>`: the dependency's source, taken into `patches/<dep>/` where the
2078/// project owns it. Not a passthrough — htl decides the directory, writes `patch_dir` into
2079/// the manifest and answers the "may this be overwritten" question against git; the copy
2080/// and the `patch_base` bookkeeping are mlua-pkg's. See `Project::patch`.
2081fn cmd_pkg_patch(dep: &str, force: bool) -> Result<ExitCode> {
2082    let project = pkg_project().context("a patch belongs to a project, so this runs in one")?;
2083    let done = project.patch(dep, force)?;
2084    let report = &done.report;
2085    let rel = report
2086        .patch_dir
2087        .strip_prefix(&project.root)
2088        .unwrap_or(&report.patch_dir);
2089    let verb = if report.created { "patched" } else { "rebuilt" };
2090    let base: String = report.base.chars().take(7).collect();
2091    eprintln!("  {verb} {} ({dep} at {base})", rel.display());
2092    // Only when there was something to drop: on a dependency whose repository holds
2093    // nothing but the package this line would be noise, and the reader would learn the
2094    // rule from a line that says nothing happened.
2095    if !done.dropped.is_empty() {
2096        eprintln!(
2097            "  dropped {} (the repository's, not the package's)",
2098            done.dropped.join(", ")
2099        );
2100    }
2101    eprintln!("htl: it is the project's code now — edit it, commit it, then `htl pkg install`.");
2102    Ok(ExitCode::SUCCESS)
2103}
2104
2105/// What the deps published, in the shape `htl init` reports its scaffold. A name that was
2106/// already taken is said out loud: nothing was overwritten, and the project is the one
2107/// that decides which declaration it wants.
2108fn report_types_sync(sync: &htl::pkg::TypesSync, root: &Path) {
2109    let rel = |p: &Path| p.strip_prefix(root).unwrap_or(p).display().to_string();
2110    for (path, dep) in &sync.written {
2111        eprintln!("  types   {} (from {dep})", rel(path));
2112    }
2113    for (path, dep) in &sync.taken {
2114        eprintln!("  kept    {} ({dep} publishes one too)", rel(path));
2115    }
2116}
2117
2118/// `htl types add <library>`: the declarations a library did not ship, from the collection
2119/// that has them. The revision is recorded because nothing else in that ecosystem does —
2120/// see `Project::add_types`.
2121fn cmd_types_add(library: &str, from: Option<&Path>, force: bool) -> Result<ExitCode> {
2122    let project = pkg_project().context("`types/` is a project's, so this runs in one")?;
2123    let types = decl_root(&project.root)?;
2124    let sync = match from {
2125        Some(dir) => project.add_types_from(dir, library, "local", force, &types)?,
2126        None => project.add_types(library, force, &types)?,
2127    };
2128    report_types_sync(&sync, &project.root);
2129    if sync.written.is_empty() && !sync.taken.is_empty() {
2130        eprintln!("htl: nothing written; --force replaces what is already there");
2131    }
2132    Ok(ExitCode::SUCCESS)
2133}
2134
2135/// What `htl unused` was asked for, beyond the paths.
2136struct UnusedFlags {
2137    json: bool,
2138    /// Exit 1 when anything was reported. Off by default: "unused" is a question about
2139    /// intent, so CI opts in rather than out.
2140    fail_on_unused: bool,
2141    use_cache: bool,
2142    explain: bool,
2143}
2144
2145/// What `htl adopt` was asked for, beyond the paths.
2146struct AdoptFlags {
2147    json: bool,
2148    /// List every marked declaration under the table, and each `applicable` candidate
2149    /// after them; the plain form prints the table alone.
2150    detail: bool,
2151    use_cache: bool,
2152    explain: bool,
2153}
2154
2155/// What `htl check` was asked for, beyond the paths and the lint selection.
2156struct CheckFlags {
2157    strict: bool,
2158    list_lints: bool,
2159    /// `--explain <rule>`: print the rule's explanation and exit.
2160    explain_rule: Option<String>,
2161    json: bool,
2162    use_cache: bool,
2163    cache_mode: Option<cache::Mode>,
2164    explain: bool,
2165    /// `--statistics`: the per-rule table in place of the findings.
2166    statistics: bool,
2167}
2168
2169struct TestFlags {
2170    fail_fast: bool,
2171    /// Finding no test file is a pass rather than a failure.
2172    allow_empty: bool,
2173    verbose: bool,
2174    quiet: bool,
2175    slow: Option<f64>,
2176    update: bool,
2177    coverage: bool,
2178    coverage_lines: bool,
2179    /// Where to write the lcov tracefile, if asked for.
2180    lcov: Option<PathBuf>,
2181    /// Where to write the JUnit XML report, if asked for.
2182    junit: Option<PathBuf>,
2183    json: bool,
2184    no_cache: bool,
2185    explain: bool,
2186    seed: Option<u64>,
2187}
2188
2189fn print_coverage(cov: &report::CoverageReport, with_lines: bool) {
2190    let width = cov
2191        .modules
2192        .iter()
2193        .map(|m| m.path.len())
2194        .max()
2195        .unwrap_or(4)
2196        .max(5);
2197    for m in &cov.modules {
2198        eprintln!(
2199            "coverage: {:<width$}  {:>5}/{:<5} {:5.1}%",
2200            m.path,
2201            m.executed,
2202            m.total,
2203            100.0 * m.executed as f64 / m.total as f64
2204        );
2205        if !m.never_ran.is_empty() {
2206            let names: Vec<String> = m
2207                .never_ran
2208                .iter()
2209                .map(|f| format!("{} ({})", f.name, f.line))
2210                .collect();
2211            eprintln!("          never ran: {}", names.join(", "));
2212        }
2213        if with_lines && !m.unexecuted.is_empty() {
2214            let spans: Vec<String> = m
2215                .unexecuted
2216                .iter()
2217                .map(|(a, b)| {
2218                    if a == b {
2219                        a.to_string()
2220                    } else {
2221                        format!("{a}-{b}")
2222                    }
2223                })
2224                .collect();
2225            eprintln!("          unexecuted: {}", spans.join(", "));
2226        }
2227    }
2228    if cov.total > 0 {
2229        eprintln!(
2230            "coverage: {:<width$}  {:>5}/{:<5} {:5.1}%  (statements)",
2231            "total",
2232            cov.executed,
2233            cov.total,
2234            100.0 * cov.executed as f64 / cov.total as f64
2235        );
2236    } else {
2237        eprintln!("coverage: no .tl module reached");
2238    }
2239}
2240
2241/// One file's report as a JUnit suite.
2242///
2243/// The assertion library reports a failure as `"<suite > test>: <message>"` and its tests
2244/// by the same composed name, so a failing case takes back the message printed under the
2245/// file by matching that prefix — including the traceback a runtime error carries, which
2246/// belongs in the report for the same reason it belongs on the terminal: it is the part
2247/// that says where.
2248fn junit_suite(rep: &htl::testing::FileReport) -> junit::Suite {
2249    let mut left: Vec<&str> = rep.failures.iter().map(String::as_str).collect();
2250    let cases = rep
2251        .tests
2252        .iter()
2253        .map(|t| {
2254            let failure = (!t.ok)
2255                .then(|| {
2256                    let head = format!("{}: ", t.name);
2257                    let at = left.iter().position(|m| m.starts_with(&head))?;
2258                    Some(left.remove(at)[head.len()..].to_string())
2259                })
2260                .flatten();
2261            junit::Case {
2262                name: t.name.clone(),
2263                ms: t.ms,
2264                // A failing test whose message could not be matched still failed: say so
2265                // rather than reporting it as passed.
2266                failure: failure.or_else(|| (!t.ok).then(|| "failed".to_string())),
2267            }
2268        })
2269        .collect();
2270    let error = if !rep.check.ok() {
2271        Some(junit::Error {
2272            message: "type check failed".to_string(),
2273            kind: "check",
2274            body: rep
2275                .check
2276                .error_items
2277                .iter()
2278                .map(|d| d.clone().spelled().to_string())
2279                .collect::<Vec<_>>()
2280                .join("\n"),
2281        })
2282    } else {
2283        rep.error.as_ref().map(|e| junit::Error {
2284            message: e.clone(),
2285            kind: "error",
2286            body: e.clone(),
2287        })
2288    };
2289    junit::Suite {
2290        file: htl::diagnostic::display_path(&rep.path),
2291        duration_ms: rep.duration_ms,
2292        error,
2293        cases,
2294    }
2295}
2296
2297fn cmd_test(
2298    paths: &[PathBuf],
2299    filter: Option<&str>,
2300    lib: &str,
2301    lint: Option<&str>,
2302    flags: TestFlags,
2303) -> Result<ExitCode> {
2304    let paths = if paths.is_empty() {
2305        vec![PathBuf::from(".")]
2306    } else {
2307        paths.to_vec()
2308    };
2309    if let Some(first) = paths.first() {
2310        auto_dts(first)?;
2311    }
2312    // A patched dependency's tests are its suite, not this project's: `htl pkg patch`
2313    // takes the whole package root, tests included, and running them here would report a
2314    // library's own failures as the project's.
2315    let cfg = load_config(&paths[0])?;
2316    let model = project::model_of(&cfg, &paths[0])?;
2317    let skip = project::not_walked(model.as_ref(), &paths, htl::model::Purpose::Test);
2318    let files = htl::testing::discover_tests_for(&paths, &skip, lib)?;
2319    // A test at the root of a project laid out flat without saying so would only fail on
2320    // its first `require`; say what is wrong instead, as `check` does.
2321    project::refuse_flat_root(model.as_ref(), &paths, &files)?;
2322    // Finding nothing goes through the same report as any run: under `--allow-empty` its
2323    // summary line, and under `--format json` its document whether allowed or not, so a
2324    // reader of stdout always gets one.
2325    let empty = files.is_empty();
2326    if empty {
2327        eprintln!("htl test: no test files found (looked for .tl files that require(\"{lib}\"))");
2328    }
2329    let opts = project::TestOptions {
2330        config: &cfg,
2331        model: model.as_ref(),
2332        lint,
2333        lib,
2334        filter,
2335        run: htl::testing::RunOptions {
2336            fail_fast: flags.fail_fast,
2337            update_snapshots: flags.update,
2338            coverage: flags.coverage,
2339            // Given, or drawn for the run and printed below, so that it can be given back.
2340            seed: flags.seed,
2341            // `project::test` fills it from the config it is handed.
2342            async_: Default::default(),
2343            lang: Default::default(),
2344        },
2345        cache: project::cache_options(
2346            !flags.no_cache,
2347            Some(cache::Mode::PerModule),
2348            &cfg,
2349            flags.explain,
2350        ),
2351    };
2352
2353    let mut sink = project::Sink::new(report::Out::new(flags.json, false));
2354    let mut json_files: Vec<report::TestFile> = Vec::new();
2355    let mut junit_suites: Vec<junit::Suite> = Vec::new();
2356    // What is left of the run here: how a file reads on a terminal, and what the document
2357    // says about it. Which files run, in what isolation, from what store — and what they
2358    // draw — is `project::test`'s.
2359    let rep = if empty {
2360        // Nothing to run, so no session to open and no store to touch: the run's report
2361        // with every count at zero, and no file having drawn from the seed.
2362        project::TestReport {
2363            files: Vec::new(),
2364            ran: 0,
2365            passed: 0,
2366            failed: 0,
2367            files_with_errors: 0,
2368            replayed: 0,
2369            seed: flags.seed.unwrap_or(0),
2370            duration_ms: 0.0,
2371            coverage: None,
2372        }
2373    } else {
2374        project::test(&mut sink, &files, &opts, &mut |rep, sink| {
2375            if flags.json {
2376                json_files.push(report::TestFile::from_report(rep, sink.out().take()));
2377            }
2378            if flags.junit.is_some() {
2379                junit_suites.push(junit_suite(rep));
2380            }
2381            // Spelled as `htl check` spells the same file, whatever path the walk was handed.
2382            let f = htl::diagnostic::display_path(&rep.path);
2383            let tag = if rep.ok() { "ok  " } else { "FAIL" };
2384            let detail = if !rep.check.ok() {
2385                "type check failed".to_string()
2386            } else if let Some(e) = &rep.error {
2387                // The cause on the file's own line, its frames under it: a traceback inside
2388                // the parenthesised summary would push `12 ms` past a screen of stack.
2389                format!("error: {}", e.lines().next().unwrap_or_default())
2390            } else if rep.file_level {
2391                "ran to completion (no test library used)".to_string()
2392            } else {
2393                format!("{} passed, {} failed", rep.passed, rep.failed)
2394            };
2395            // Quiet: a passing file is silence; failures, errors and slow tests still show.
2396            // JSON: nothing on stderr, the document carries it all.
2397            let show_file = !flags.json && (!flags.quiet || !rep.ok());
2398            if show_file {
2399                eprintln!("{tag} {f}  ({detail}, {:.0} ms)", rep.duration_ms);
2400                if let Some(e) = &rep.error {
2401                    for line in e.lines().skip(1) {
2402                        eprintln!("      {line}");
2403                    }
2404                }
2405            }
2406            for tr in &rep.tests {
2407                let slow = flags.slow.is_some_and(|ms| tr.ms >= ms);
2408                if !flags.json && (flags.verbose || slow) {
2409                    if flags.quiet && !show_file {
2410                        // The file line was skipped: name the file with the slow test.
2411                        eprintln!("slow {f}  {}  ({:.1} ms)", tr.name, tr.ms);
2412                        continue;
2413                    }
2414                    let mark = if tr.ok { "ok  " } else { "FAIL" };
2415                    let note = if slow && !flags.verbose {
2416                        "  [slow]"
2417                    } else {
2418                        ""
2419                    };
2420                    eprintln!("      {mark} {}  ({:.1} ms){note}", tr.name, tr.ms);
2421                }
2422            }
2423            if !flags.json {
2424                for m in &rep.failures {
2425                    eprintln!("      - {m}");
2426                }
2427                // A snapshot written or rewritten is a change on disk: always say so, even in -q.
2428                for p in &rep.snapshots_written {
2429                    eprintln!(
2430                        "snapshot written: {}",
2431                        htl::diagnostic::display_path(Path::new(p))
2432                    );
2433                }
2434                for p in &rep.snapshots_updated {
2435                    eprintln!(
2436                        "snapshot updated: {}",
2437                        htl::diagnostic::display_path(Path::new(p))
2438                    );
2439                }
2440            }
2441        })?
2442    };
2443
2444    if let Some(out) = &flags.junit {
2445        // The run's own total, not the sum of the files: it is the number the summary
2446        // line prints, and the report is there to agree with the summary line.
2447        std::fs::write(out, junit::document(&junit_suites, rep.duration_ms))
2448            .with_context(|| format!("writing {}", out.display()))?;
2449    }
2450    if let (Some(out), Some(cov)) = (&flags.lcov, &rep.coverage) {
2451        // Against the project root rather than the working directory: a tracefile is
2452        // uploaded from wherever CI ran the command and resolved against the repository.
2453        let root = match &cfg {
2454            Some((dir, _, _)) => dir.clone(),
2455            None => std::env::current_dir()?,
2456        };
2457        let root = std::fs::canonicalize(&root).unwrap_or(root);
2458        std::fs::write(out, cov.lcov(&root))
2459            .with_context(|| format!("writing {}", out.display()))?;
2460    }
2461    // An empty run is a pass only when asked for; the document's `ok` says what the exit
2462    // code says, so a reader of either sees the same refusal.
2463    let ok = rep.ok() && (!empty || flags.allow_empty);
2464    if flags.json {
2465        let summary = report::TestSummary {
2466            files: rep.files.len(),
2467            files_run: rep.ran,
2468            passed: rep.passed,
2469            failed: rep.failed,
2470            files_with_errors: rep.files_with_errors,
2471            replayed: rep.replayed,
2472            duration_ms: rep.duration_ms,
2473            ok,
2474            seed: rep.seed,
2475        };
2476        report::emit(&report::TestReport {
2477            files: json_files,
2478            summary,
2479            coverage: rep.coverage,
2480        })?;
2481    } else if !empty || flags.allow_empty {
2482        // A refused empty run says so with the notice alone, as it always has.
2483        if let Some(cov) = &rep.coverage {
2484            print_coverage(cov, flags.coverage_lines);
2485            if let Some(out) = &flags.lcov {
2486                eprintln!("coverage: lcov written to {}", out.display());
2487            }
2488        }
2489        eprintln!(
2490            "htl test: {} file(s), {} passed, {} failed, {} file(s) with errors{}{} ({:.0} ms)",
2491            rep.ran,
2492            rep.passed,
2493            rep.failed,
2494            rep.files_with_errors,
2495            if rep.skipped() > 0 {
2496                format!(", {} file(s) not run (--fail-fast)", rep.skipped())
2497            } else {
2498                String::new()
2499            },
2500            // Says the checking was reused, not the run: every one of these files ran.
2501            if rep.replayed > 0 {
2502                format!(", {} checked from cache", rep.replayed)
2503            } else {
2504                String::new()
2505            },
2506            rep.duration_ms
2507        );
2508        // Always, not only on failure: the seed of a run that passed is what reproduces
2509        // the run that passes, and a failure two commits later is compared against it.
2510        // A run of no files drew nothing, so there is nothing to repeat.
2511        if !empty {
2512            eprintln!(
2513                "htl test: seed {} (repeat with --seed {})",
2514                rep.seed, rep.seed
2515            );
2516        }
2517    }
2518    Ok(if ok {
2519        ExitCode::SUCCESS
2520    } else {
2521        ExitCode::FAILURE
2522    })
2523}
2524
2525/// Name the patched dependencies this walk enters, in the shape the other reports use.
2526///
2527/// Only the ones actually below a given root: `htl check src` walks the project's own
2528/// sources and nothing under `patches/`, and saying otherwise would be a claim about files
2529/// that were not read.
2530fn report_patched(paths: &[PathBuf]) {
2531    let roots: Vec<PathBuf> = paths
2532        .iter()
2533        .filter_map(|p| std::fs::canonicalize(p).ok())
2534        .collect();
2535    let cwd = std::env::current_dir().unwrap_or_default();
2536    // The project found the way every command finds it; a failure to find one was said by
2537    // the command itself, which ran first.
2538    let Some(project) = paths
2539        .first()
2540        .and_then(|p| htl::model::Project::find_root(p).ok().flatten())
2541        .map(|r| r.root)
2542        .filter(|r| r.join(htl::pkg::MANIFEST_NAME).is_file())
2543        .map(|r| htl::pkg::MluaProject::at(&r))
2544    else {
2545        return;
2546    };
2547    for p in &project.patches {
2548        let canon = std::fs::canonicalize(&p.dir).unwrap_or_else(|_| p.dir.clone());
2549        if !roots.iter().any(|r| canon.starts_with(r)) {
2550            continue;
2551        }
2552        let shown = p.dir.strip_prefix(&cwd).unwrap_or(&p.dir);
2553        eprintln!("  patched {} ({})", shown.display(), p.name);
2554    }
2555}
2556
2557/// Nearest `htl.toml` above the first path: `(dir holding it, path, config)`.
2558///
2559/// Where `[toolchain] htl` is answered, and the only place: every command that reads the
2560/// config comes through here, and the pin has to be settled before the command reads a
2561/// source file — which is a property of this function, not something each command could
2562/// be trusted to repeat. `htl new` / `htl init` do not call it, so a mismatch never stops
2563/// anyone from creating a project.
2564///
2565/// The version compared is this binary's, which is the one the pin is about. The `htl`
2566/// crate a Rust host builds against is Cargo's, pinned in `Cargo.toml` — a separate
2567/// question, and the one [`warn_cargo_htl_mismatch`] answers.
2568fn load_config(first: &Path) -> Result<project::Config> {
2569    let cfg = project::config_of(first)?;
2570    if let Some((_, path, c)) = &cfg {
2571        htl::config::check_toolchain(c, path, env!("CARGO_PKG_VERSION"))?;
2572    }
2573    Ok(cfg)
2574}
2575
2576/// Say so, once, when the `Cargo.toml` around this project asks for an `htl` crate this
2577/// command is not.
2578///
2579/// The two halves of htl are released together and a project uses both: the crate the host
2580/// links, and the command that checks the Teal beside it. A project left at `htl = "0.5.1"`
2581/// while the installed CLI had moved to 0.6.0 was checked by one and built against the
2582/// other, and nothing in either output mentioned the other one — which is the whole of the
2583/// failure, since either version alone was fine.
2584///
2585/// **A warning, not an error, and not one of the summary's `warning(s)`** — that count is
2586/// the checker's, and this is not about the sources. A project goes to a hard error over a
2587/// version skew for one of two reasons, and htl has neither: the format between the halves
2588/// is unstable, so a mismatched pair miscompiles rather than failing (wasm-bindgen refuses
2589/// a JS glue built by another version); or the diagnostic downstream is opaque, so the
2590/// person would otherwise read a type error from deep inside a dependency (cargo's
2591/// `rust-version`). Here both halves worked — the run that produced this report is the
2592/// evidence — and the line is worth printing only because the person has no other way to
2593/// notice. npm's `engines` is the same shape and warns by default; Prisma says nothing at
2594/// all, and its silence is filed as a bug.
2595///
2596/// Read from the `Cargo.toml` of the crate the project sits in, `[dependencies] htl` only:
2597/// a string, or a table with `version`. A table without one — `path`, `git`, or a
2598/// `workspace = true` inheritance — states no requirement here and is passed over without
2599/// a word, which is exactly what a scaffold written by a checkout-built CLI produces. No
2600/// `Cargo.toml`, no `[dependencies]`, no `htl` key, or a requirement cargo itself would
2601/// reject: nothing is printed, because there is nothing this can be surer about than cargo.
2602fn warn_cargo_htl_mismatch(first: &Path) {
2603    let Some(root) = htl::dts::find_cargo_package_root(first) else {
2604        return;
2605    };
2606    let Ok(text) = fs::read_to_string(root.join("Cargo.toml")) else {
2607        return;
2608    };
2609    let Ok(manifest) = text.parse::<toml::Table>() else {
2610        return;
2611    };
2612    let Some(dep) = manifest.get("dependencies").and_then(|d| d.get("htl")) else {
2613        return;
2614    };
2615    let req_text = match dep {
2616        toml::Value::String(s) => s.as_str(),
2617        toml::Value::Table(t) => match t.get("version").and_then(toml::Value::as_str) {
2618            Some(s) => s,
2619            None => return,
2620        },
2621        _ => return,
2622    };
2623    let running = env!("CARGO_PKG_VERSION");
2624    let (Ok(req), Ok(version)) = (
2625        semver::VersionReq::parse(req_text),
2626        semver::Version::parse(running),
2627    ) else {
2628        return;
2629    };
2630    if req.matches(&version) {
2631        return;
2632    }
2633    // Both ways out are named because either is the right one: the project may be the
2634    // thing that is current, in which case the command is what moves.
2635    eprintln!(
2636        "htl {running}; Cargo.toml asks for htl {req_text} — the crate and the CLI are \
2637         meant to move together (cargo install htl-cli --version {req_text}, or bump the \
2638         dependency)"
2639    );
2640}
2641
2642fn cmd_fmt(paths: &[PathBuf], check: bool, indent: Option<usize>) -> Result<ExitCode> {
2643    let paths = if paths.is_empty() {
2644        vec![PathBuf::from(".")]
2645    } else {
2646        paths.to_vec()
2647    };
2648    let cfg = load_config(&paths[0])?;
2649    let indent = indent
2650        .or_else(|| cfg.as_ref().and_then(|(_, _, c)| c.fmt.indent))
2651        .unwrap_or(3);
2652    let h = Htl::new()?;
2653    config_lang(&h, &cfg)?;
2654    // Not a dependency's files, a patched one included: formatting the copy would turn
2655    // every one of its files into a diff against the revision it was taken from, and bury
2656    // the project's own change somewhere inside that.
2657    let model = project::model_of(&cfg, &paths[0])?;
2658    let skip = project::not_walked(model.as_ref(), &paths, htl::model::Purpose::Own);
2659    let files = htl::collect_tl_skipping(&paths, &skip)?;
2660    let (mut changed, mut failed) = (0usize, 0usize);
2661    for f in &files {
2662        let before = fs::read_to_string(f).with_context(|| format!("reading {}", f.display()))?;
2663        let after = match h.format_file(f, indent) {
2664            Ok(s) => s,
2665            Err(e) => {
2666                eprintln!("error: {e}");
2667                failed += 1;
2668                continue;
2669            }
2670        };
2671        if after != before {
2672            changed += 1;
2673            if check {
2674                eprintln!("would reformat: {}", f.display());
2675            } else {
2676                fs::write(f, after).with_context(|| format!("writing {}", f.display()))?;
2677                eprintln!("reformatted: {}", f.display());
2678            }
2679        }
2680    }
2681    eprintln!(
2682        "htl fmt: {} file(s), {} {}, {} failed",
2683        files.len(),
2684        changed,
2685        if check { "would change" } else { "reformatted" },
2686        failed
2687    );
2688    let fail = failed > 0 || (check && changed > 0);
2689    Ok(if fail {
2690        ExitCode::FAILURE
2691    } else {
2692        ExitCode::SUCCESS
2693    })
2694}
2695
2696struct FixFlags {
2697    rule: Vec<String>,
2698    unsafe_fixes: bool,
2699    dry_run: bool,
2700    diff: bool,
2701    allow_dirty: bool,
2702    allow_no_vcs: bool,
2703    exit_non_zero_on_fix: bool,
2704    json: bool,
2705}
2706
2707fn cmd_fix(paths: &[PathBuf], flags: FixFlags) -> Result<ExitCode> {
2708    use htl::fix::{FixOptions, fix_file, git_dirty, unified_diff};
2709    let paths = if paths.is_empty() {
2710        vec![PathBuf::from(".")]
2711    } else {
2712        paths.to_vec()
2713    };
2714    // What `htl check` holds a file to, resolved the same way and read by the same checker,
2715    // so a file this run leaves reports what a check of it would. A dry run writes nothing,
2716    // the declarations generated before the check included.
2717    let ProjectChecker {
2718        h,
2719        cfg,
2720        model,
2721        scope,
2722    } = checker_for(&paths[0], !flags.dry_run)?;
2723    let opts = FixOptions {
2724        unsafe_fixes: flags.unsafe_fixes,
2725        promoted: cfg
2726            .as_ref()
2727            .map(|(_, _, c)| c.fix.unsafe_.clone())
2728            .unwrap_or_default(),
2729        disabled: cfg
2730            .as_ref()
2731            .map(|(_, _, c)| c.fix.disable.clone())
2732            .unwrap_or_default(),
2733        only: flags.rule.clone(),
2734        dry_run: flags.dry_run,
2735    };
2736    // Here as well as inside `fix_file`, so a misspelt rule is answered even when the
2737    // paths hold no `.tl` at all — the request is wrong either way.
2738    opts.validate()?;
2739    // Written as `htl fmt` walks, not as `htl check` does: this command rewrites files, so a
2740    // patched dependency is left alone whatever the fixes would be. An edit there belongs
2741    // in the diff the project makes against the revision it took, written by a person.
2742    let skip = project::not_walked(model.as_ref(), &paths, htl::model::Purpose::Own);
2743    // Only what a module of the project holds, as `htl check` walks it.
2744    let (files, outside) = project::held_by_modules(
2745        model.as_ref(),
2746        &paths,
2747        htl::collect_tl_skipping(&paths, &skip)?,
2748    )?;
2749    if let Some(note) = project::outside_modules_note(model.as_ref(), &outside, "fixed") {
2750        eprintln!("htl fix: {note}");
2751    }
2752    // But checked as `htl check` walks: the copy is still the project's code, and what is
2753    // wrong in it is what the two commands both judge the tree by. Only checked, never
2754    // handed to `fix_file`.
2755    let check_skip = project::not_walked(model.as_ref(), &paths, htl::model::Purpose::Check);
2756    let checked_only: Vec<PathBuf> = project::held_by_modules(
2757        model.as_ref(),
2758        &paths,
2759        htl::collect_tl_skipping(&paths, &check_skip)?,
2760    )?
2761    .0
2762    .into_iter()
2763    .filter(|f| !files.contains(f))
2764    .collect();
2765
2766    // The working tree is the undo: refuse to rewrite what git could not give back.
2767    if !flags.dry_run {
2768        let mut dirty = Vec::new();
2769        let mut no_vcs = Vec::new();
2770        for f in &files {
2771            match git_dirty(f)? {
2772                Some(true) => dirty.push(f.clone()),
2773                Some(false) => {}
2774                None => no_vcs.push(f.clone()),
2775            }
2776        }
2777        if !dirty.is_empty() && !flags.allow_dirty {
2778            bail!(
2779                "htl fix rewrites files in place and relies on git to undo it; these have uncommitted changes:\n  {}\ncommit or stash them, or pass --allow-dirty",
2780                dirty
2781                    .iter()
2782                    .map(|p| p.display().to_string())
2783                    .collect::<Vec<_>>()
2784                    .join("\n  ")
2785            );
2786        }
2787        if !no_vcs.is_empty() && !flags.allow_no_vcs {
2788            bail!(
2789                "htl fix rewrites files in place and relies on git to undo it; these are not in a git repository:\n  {}\npass --allow-no-vcs to proceed without that safety net",
2790                no_vcs
2791                    .iter()
2792                    .map(|p| p.display().to_string())
2793                    .collect::<Vec<_>>()
2794                    .join("\n  ")
2795            );
2796        }
2797    }
2798
2799    let mut sink = project::Sink::new(report::Out::new(flags.json, false));
2800    // Judged by the levels `htl check` judges by: a finding under a rule at `deny` fails.
2801    sink.judge_by(scope.lints.selection());
2802    // Dependencies are reported as `htl check` reports them and never rewritten: a fix
2803    // under `.htl/` goes at the next install, one under `[check] paths` is not this
2804    // project's. `fix_file` only ever writes the file it was given.
2805    let origins = project::Origins::new(model.as_ref());
2806    let walk = scope.walk(&cfg, model.as_ref(), &origins);
2807    let walked: Vec<PathBuf> = files.iter().chain(&checked_only).cloned().collect();
2808    sink.walking(&walked);
2809    let (mut applied, mut skipped, mut json_files) = (Vec::new(), Vec::new(), Vec::new());
2810    let (mut changed, mut deferred, mut reverted) = (0usize, 0usize, 0usize);
2811    let mut found = htl::verdict::Findings::default();
2812    let mut infos: Vec<(PathBuf, htl::CheckInfo)> = Vec::with_capacity(walked.len());
2813    for f in &files {
2814        // Put back after each file, as `htl check` does, so a file is fixed against what
2815        // it may read and not also against the directories of the files before it.
2816        let saved = h.search_path()?;
2817        project::file_view(&h, model.as_ref(), f)?;
2818        let before = if flags.diff {
2819            std::fs::read_to_string(f).ok()
2820        } else {
2821            None
2822        };
2823        let out = fix_file(&h, f, &opts)?;
2824        if out.contents.is_some() {
2825            changed += 1;
2826        }
2827        deferred += out.deferred;
2828        if out.reverted.is_some() {
2829            reverted += 1;
2830        }
2831        if !flags.json {
2832            for a in &out.applied {
2833                eprintln!(
2834                    "fixed: {}:{}: {} ({}{})",
2835                    project::display_path(f),
2836                    a.line,
2837                    a.rule,
2838                    a.applicability.as_str(),
2839                    if flags.dry_run { ", not written" } else { "" }
2840                );
2841            }
2842            for s in &out.skipped {
2843                eprintln!(
2844                    "skipped: {}:{}: {} — {}",
2845                    project::display_path(f),
2846                    s.line,
2847                    s.rule,
2848                    s.reason
2849                );
2850            }
2851            if let Some(r) = &out.reverted {
2852                eprintln!("reverted: {}: {r}", project::display_path(f));
2853            }
2854            if let Some(o) = &out.oscillation {
2855                eprintln!(
2856                    "stopped: {}: fixes of {o} undo each other",
2857                    project::display_path(f)
2858                );
2859            }
2860            if out.deferred > 0 {
2861                eprintln!(
2862                    "deferred: {}: {} edit(s) overlapped applied ones; run htl fix again",
2863                    project::display_path(f),
2864                    out.deferred
2865                );
2866            }
2867            if flags.diff
2868                && let (Some(b), Some(a)) = (&before, &out.contents)
2869            {
2870                print!("{}", unified_diff(&project::display_path(f), b, a));
2871            }
2872            // A suggestion is never written, so the diff is the only place it is shown.
2873            // Against what was applied, when something was: the two are one edit session.
2874            if flags.diff
2875                && let (Some(b), Some(s)) = (
2876                    out.contents.as_ref().or(before.as_ref()),
2877                    out.suggested.as_ref(),
2878                )
2879            {
2880                print!(
2881                    "{}",
2882                    unified_diff(&format!("{} (suggested)", project::display_path(f)), b, s)
2883                );
2884            }
2885        }
2886        // What the file says as it is left, the way `htl check` would say it: the checker's
2887        // result and this layer's lints, while the path it was checked under is in place.
2888        found.lints += project::file_findings(&h, &mut sink, f, &out.check, &walk)?;
2889        h.set_search_path(&saved)?;
2890        found.errors += out.check.errors.len();
2891        found.warnings += out.check.warnings.len();
2892        infos.push((f.clone(), out.check.clone()));
2893        if flags.json {
2894            applied.extend(out.applied.iter().map(|a| report::FixApplied {
2895                file: project::display_path(f),
2896                line: a.line,
2897                rule: a.rule.clone(),
2898                applicability: a.applicability.as_str(),
2899                pass: a.pass,
2900            }));
2901            skipped.extend(out.skipped.iter().map(|s| report::FixSkipped {
2902                file: project::display_path(f),
2903                line: s.line,
2904                rule: s.rule.clone(),
2905                reason: s.reason.clone(),
2906            }));
2907            json_files.push(report::FixFile {
2908                path: project::display_path(f),
2909                changed: out.contents.is_some(),
2910                deferred: out.deferred,
2911                reverted: out.reverted.clone(),
2912                oscillation: out.oscillation.clone(),
2913                diagnostics: sink.out().take(),
2914            });
2915        }
2916    }
2917    // A patched copy: checked as `htl check` checks it, and not fixed.
2918    for f in &checked_only {
2919        let m = project::check_one(&h, &mut sink, f, &walk)?;
2920        found.errors += m.errors;
2921        found.warnings += m.warnings;
2922        found.lints += m.lints;
2923        infos.push((f.clone(), m.requires_only()));
2924        if flags.json {
2925            json_files.push(report::FixFile {
2926                path: project::display_path(f),
2927                changed: false,
2928                deferred: 0,
2929                reverted: None,
2930                oscillation: None,
2931                diagnostics: sink.out().take(),
2932            });
2933        }
2934    }
2935    // What the project says about itself as a whole.
2936    // A dry run publishes nothing either.
2937    let mut whole = scope.whole(&cfg, model.as_ref());
2938    whole.publish = !flags.dry_run;
2939    whole.checker = Some(&h);
2940    let w = project::project_findings(&mut sink, &whole, &infos);
2941    found.errors += w.errors;
2942    found.lints += w.lints;
2943    let project_diagnostics = if flags.json {
2944        sink.out().take()
2945    } else {
2946        Vec::new()
2947    };
2948    // A broken dependency is an error `htl fix` cannot remove; it remains, as `htl check`
2949    // would count it.
2950    found.errors += sink.dependency_error_count();
2951    found.denied = sink.denied();
2952    // Judged as `htl check` judges the same tree: the same findings, the same policy.
2953    let policy = htl::verdict::Policy::resolve(cfg.as_ref().map(|(_, _, c)| c), false);
2954    let errors_remaining = found.errors;
2955    let n_applied = if flags.json { applied.len() } else { 0 };
2956    let fail =
2957        htl::verdict::verdict(&found, &policy) || (flags.exit_non_zero_on_fix && changed > 0);
2958    if flags.json {
2959        let n_skipped = skipped.len();
2960        report::emit(&report::FixReport {
2961            dry_run: flags.dry_run,
2962            applied,
2963            skipped,
2964            files: json_files,
2965            summary: report::FixSummary {
2966                files: files.len(),
2967                files_changed: changed,
2968                applied: n_applied,
2969                skipped: n_skipped,
2970                deferred,
2971                reverted,
2972                errors_remaining,
2973                warnings: found.warnings,
2974                lints: found.lints,
2975                denied: found.denied,
2976                strict: policy.strict,
2977                ok: !fail,
2978            },
2979            diagnostics: project_diagnostics,
2980        })?;
2981    } else {
2982        // What else the verdict counted, said only when it did: a finding at `deny`, and
2983        // under `strict` every warning and lint. Without it a run that failed on a lint
2984        // would end in `0 error(s) remaining`.
2985        let judged = judged(&found, &policy);
2986        eprintln!(
2987            "htl fix: {} file(s){}, {} changed{}, {} error(s) remaining{}{}",
2988            files.len(),
2989            if checked_only.is_empty() {
2990                String::new()
2991            } else {
2992                format!(" + {} checked in patched dependencies", checked_only.len())
2993            },
2994            changed,
2995            if flags.dry_run {
2996                " (dry run, nothing written)"
2997            } else {
2998                ""
2999            },
3000            errors_remaining,
3001            judged,
3002            if deferred > 0 {
3003                format!(", {deferred} deferred")
3004            } else {
3005                String::new()
3006            }
3007        );
3008    }
3009    Ok(if fail {
3010        ExitCode::FAILURE
3011    } else {
3012        ExitCode::SUCCESS
3013    })
3014}
3015
3016/// Type-check a tree, replaying the modules whose inputs have not moved.
3017///
3018/// The order here is load-bearing. Generating `.d.tl` and collecting the file list come
3019/// first, because both produce inputs the keys are built from. Every module is looked up
3020/// before any is checked, so that a run where nothing moved never builds a checker at all —
3021/// that costs about 13.5 ms (`crates/htl-core/benches/check.rs`), which is most of what a
3022/// fully replayed run has to save on a small project.
3023///
3024/// A module that misses re-checks its dependencies as part of its own check, since the
3025/// checker's store starts empty. So an edit costs the edited module, whatever depends on
3026/// it, and whatever those pull in — less than the project, more than the minimum.
3027fn cmd_check(paths: &[PathBuf], lint: Option<&str>, flags: CheckFlags) -> Result<ExitCode> {
3028    let CheckFlags {
3029        list_lints,
3030        json,
3031        use_cache,
3032        cache_mode,
3033        explain,
3034        statistics,
3035        ..
3036    } = flags;
3037    let mut sink = project::Sink::new(report::Out::new(json, statistics));
3038    let paths = if paths.is_empty() {
3039        vec![PathBuf::from(".")]
3040    } else {
3041        paths.to_vec()
3042    };
3043    // Listing the rules reports nothing about the project and shares nothing with a run —
3044    // and now not even a Lua state: the registry is Rust (`htl_core::lint::RULES`), which
3045    // is what lets the rules the project layer reports under be listed beside the ones
3046    // `lint.lua` implements.
3047    // `--explain <rule>`: the rule's explanation, and nothing else. The name is the one a
3048    // finding prints in its `[htl <rule>]` suffix, so a reader hands the flag what they
3049    // were shown; a name no check reports under — a typo, or a fix class — is refused the
3050    // way `--lint` refuses it, on stderr, with the exit code an unusable argument gets.
3051    if let Some(rule) = flags.explain_rule.as_deref() {
3052        let Some(r) = htl::lint::explained(rule) else {
3053            eprintln!("unknown lint rule: {rule}");
3054            return Ok(ExitCode::from(2));
3055        };
3056        println!("{}  (default: {})\n\n{}", r.name, r.default, r.explain);
3057        return Ok(ExitCode::SUCCESS);
3058    }
3059    if list_lints {
3060        // The name and the level a project that says nothing gets. Two columns rather than
3061        // one because the default is a level now, and the five rules at `allow` are
3062        // otherwise invisible: a reader would have to turn one on to find out it was off.
3063        // Still one rule per line, name first, so it reads and greps as it always did.
3064        let width = htl::lint::rule_names()
3065            .iter()
3066            .map(|r| r.len())
3067            .max()
3068            .unwrap_or(0);
3069        for (name, level) in htl::lint::rule_defaults() {
3070            println!("{name:width$}  {level}");
3071        }
3072        // No pointer to `--explain` here: every rule listed has an explanation (the
3073        // registry's test holds it to that), and the listing is name-level pairs that
3074        // tests and greps read line by line. `--help` and a finding's own hint carry it.
3075        return Ok(ExitCode::SUCCESS);
3076    }
3077    // htl.toml first, then --lint, so the flag wins; `strict` from the file unless flagged.
3078    let cfg = load_config(&paths[0])?;
3079    warn_cargo_htl_mismatch(&paths[0]);
3080    let policy = htl::verdict::Policy::resolve(cfg.as_ref().map(|(_, _, c)| c), flags.strict);
3081    // `.d.tl` written from Rust source is an input to the check, so it is regenerated
3082    // before anything hashes the tree: a hit computed over stale declarations would be a
3083    // hit on a different question from the one being asked.
3084    if let Some(first) = paths.first() {
3085        auto_dts(first)?;
3086    }
3087    // A patched dependency is walked with the project's own sources — it is the project's
3088    // code, and its errors are the project's to fix. Which dependency each directory
3089    // stands in for is said here, so that an error under it is read as that dependency's
3090    // without the reader having to know the manifest.
3091    let walk_model = project::model_of(&cfg, &paths[0])?;
3092    // A directory is checked as a project: which of its files is which module, and what
3093    // they may read, is the project's to say. With none there is no answer to give, and
3094    // checking each file as a thing on its own would answer a different question without
3095    // saying so. A file named on its own is that question, asked outright, and is checked.
3096    if walk_model.is_none()
3097        && let Some(dir) = paths.iter().find(|p| p.is_dir())
3098    {
3099        bail!(
3100            "no {} or {} in {} or any directory above it: a directory is checked as a \
3101             project. Run `htl init` there to make it one, or name the .tl files to check \
3102             each on its own",
3103            htl::config::CONFIG_NAME,
3104            htl::pkg::MANIFEST_NAME,
3105            // Absolute: where the search started is the whole of the answer, and `.`
3106            // relative to itself would say nothing.
3107            fs::canonicalize(dir)
3108                .unwrap_or_else(|_| dir.clone())
3109                .display()
3110        );
3111    }
3112    let skip = project::not_walked(walk_model.as_ref(), &paths, htl::model::Purpose::Check);
3113    let (files, outside) = project::held_by_modules(
3114        walk_model.as_ref(),
3115        &paths,
3116        htl::collect_tl_skipping(&paths, &skip)?,
3117    )?;
3118    if let Some(note) = project::outside_modules_note(walk_model.as_ref(), &outside, "checked") {
3119        eprintln!("htl check: {note}");
3120    }
3121    if !json {
3122        report_patched(&paths);
3123    }
3124
3125    // The walk, the store and every decision about them are the library's: `include_tl!`
3126    // asks the same questions of the same store, and the two answering them separately is
3127    // what let them disagree. What is left here is the flags, the summary and the exit code.
3128    let rep = project::check(
3129        &mut sink,
3130        &files,
3131        &project::Options {
3132            paths: &paths,
3133            config: &cfg,
3134            model: walk_model.as_ref(),
3135            lint,
3136            cache: project::cache_options(use_cache, cache_mode, &cfg, explain),
3137        },
3138    )?;
3139    let fail = report_check(
3140        sink.out(),
3141        json,
3142        statistics,
3143        &rep,
3144        &policy,
3145        patched_files(walk_model.as_ref(), &rep.files),
3146    )?;
3147    Ok(if fail {
3148        ExitCode::FAILURE
3149    } else {
3150        ExitCode::SUCCESS
3151    })
3152}
3153
3154/// Report what no entry's `require` closure reaches.
3155///
3156/// The graph is the check's — `htl check` resolves every `require` already, and the
3157/// `require-cycle` lint reads the same edges — so this is that walk plus the entries the
3158/// project declares (`htl::unused`). What is left here is the flags, the printing and the
3159/// exit code.
3160fn cmd_unused(paths: &[PathBuf], flags: UnusedFlags) -> Result<ExitCode> {
3161    let UnusedFlags {
3162        json,
3163        fail_on_unused,
3164        use_cache,
3165        explain,
3166    } = flags;
3167    let paths = if paths.is_empty() {
3168        vec![PathBuf::from(".")]
3169    } else {
3170        paths.to_vec()
3171    };
3172    let cfg = load_config(&paths[0])?;
3173    // A `.d.tl` written from Rust source is an input to the check the graph comes from,
3174    // exactly as it is for `htl check`.
3175    auto_dts(&paths[0])?;
3176    let model = project::model_of(&cfg, &paths[0])?;
3177    let rep = htl::unused::unused(&htl::unused::Options {
3178        paths: &paths,
3179        config: &cfg,
3180        model: model.as_ref(),
3181        cache: project::cache_options(use_cache, None, &cfg, explain),
3182    })?;
3183    let s = &rep.summary;
3184    if json {
3185        report::emit(&rep)?;
3186    } else if s.no_entry {
3187        eprintln!(
3188            "htl unused: nothing to start from, so nothing is reported. An entry is \
3189             main.tl in the source root ([layout] source) or beside the manifest, a test file, a module under a [[contract]] directory, or a name \
3190             in [build] extra / host"
3191        );
3192    } else {
3193        if s.check_errors > 0 {
3194            eprintln!(
3195                "htl unused: {} error(s) in the check this graph comes from — what those \
3196                 files require is missing from it (htl check)",
3197                s.check_errors
3198            );
3199        }
3200        for m in &rep.modules {
3201            match &m.module {
3202                Some(n) => eprintln!("module: {} ({n})", m.path),
3203                None => eprintln!("module: {}", m.path),
3204            }
3205        }
3206        for d in &rep.dependencies {
3207            eprintln!("dependency: {}", d.name);
3208        }
3209        eprintln!(
3210            "htl unused: {}, {} [{} considered, {} reached, {}]",
3211            count(s.modules, "module", "modules"),
3212            count(s.dependencies, "dependency", "dependencies"),
3213            s.considered,
3214            s.reached,
3215            count(s.entries, "entry", "entries"),
3216        );
3217    }
3218    Ok(if fail_on_unused && !s.ok {
3219        ExitCode::FAILURE
3220    } else {
3221        ExitCode::SUCCESS
3222    })
3223}
3224
3225/// Report how many declarations carry each of htl's nine markers, and where.
3226///
3227/// The census is the check's — `htl check` already read every marker by position while
3228/// checking a file, exactly as the lints it drives do — so this is that census folded into
3229/// the nine features (`htl::adopt`). What is left here is the flags, the table, and the
3230/// exit code, which never moves: a report, not a gate.
3231fn cmd_adopt(paths: &[PathBuf], flags: AdoptFlags) -> Result<ExitCode> {
3232    let AdoptFlags {
3233        json,
3234        detail,
3235        use_cache,
3236        explain,
3237    } = flags;
3238    let paths = if paths.is_empty() {
3239        vec![PathBuf::from(".")]
3240    } else {
3241        paths.to_vec()
3242    };
3243    let cfg = load_config(&paths[0])?;
3244    // A `.d.tl` written from Rust source is an input to the check the census comes from,
3245    // exactly as it is for `htl check` and `htl unused`.
3246    auto_dts(&paths[0])?;
3247    let model = project::model_of(&cfg, &paths[0])?;
3248    let rep = htl::adopt::adopt(&htl::adopt::Options {
3249        paths: &paths,
3250        config: &cfg,
3251        model: model.as_ref(),
3252        cache: project::cache_options(use_cache, None, &cfg, explain),
3253    })?;
3254    if json {
3255        report::emit(&rep)?;
3256    } else {
3257        print_adopt(&rep, detail);
3258    }
3259    // Always 0: `htl adopt` reports what the project has adopted, and does not judge it
3260    // (the module doc says why — a threshold invites marking records to move the number).
3261    Ok(ExitCode::SUCCESS)
3262}
3263
3264/// The marker column's width, in both the table and `--detail`'s lines: the longest of
3265/// htl's nine, `---@extensible`, plus two spaces.
3266fn adopt_marker_width() -> usize {
3267    htl::adopt::FEATURES
3268        .iter()
3269        .map(|m| format!("---@{m}").len())
3270        .max()
3271        .unwrap_or(0)
3272        + 2
3273}
3274
3275/// The table, `--detail`'s lines when asked for, and the summary line — the text form of
3276/// an [`htl::adopt::Report`].
3277fn print_adopt(rep: &htl::adopt::Report, detail: bool) {
3278    let width = adopt_marker_width();
3279    eprintln!(
3280        "{:<width$} {:>4}  {:>10}",
3281        "feature",
3282        "used",
3283        "applicable",
3284        width = width
3285    );
3286    for f in &rep.features {
3287        let applicable = match f.applicable {
3288            Some(n) => n.to_string(),
3289            None => "-".to_string(),
3290        };
3291        eprintln!(
3292            "{:<width$} {:>4}  {:>10}",
3293            format!("---@{}", f.marker),
3294            f.used,
3295            applicable,
3296            width = width
3297        );
3298    }
3299    if detail {
3300        // Padded to the longest `file:line` of every site and every candidate about to
3301        // be printed, not per feature: one column, so the names line up down the whole
3302        // list, a candidate's line included.
3303        let line_width = rep
3304            .features
3305            .iter()
3306            .flat_map(|f| {
3307                f.sites
3308                    .iter()
3309                    .map(|s| format!("{}:{}", s.file.display(), s.line))
3310                    .chain(
3311                        f.candidates
3312                            .iter()
3313                            .map(|c| format!("{}:{}", c.file.display(), c.line)),
3314                    )
3315            })
3316            .map(|s| s.len())
3317            .max()
3318            .unwrap_or(0);
3319        for f in &rep.features {
3320            for s in &f.sites {
3321                eprintln!(
3322                    "  {:<width$}{:<line_width$}  {}",
3323                    format!("---@{}", f.marker),
3324                    format!("{}:{}", s.file.display(), s.line),
3325                    s.name,
3326                    width = width,
3327                    line_width = line_width
3328                );
3329            }
3330            // A candidate's line ends with how many construction sites made it one, so
3331            // a reader can tell it from a marked declaration above it.
3332            for c in &f.candidates {
3333                let sites = if c.sites == 1 {
3334                    "1 site".to_string()
3335                } else {
3336                    format!("{} sites", c.sites)
3337                };
3338                eprintln!(
3339                    "  {:<width$}{:<line_width$}  {}  (applicable: {}, {sites})",
3340                    format!("---@{}", f.marker),
3341                    format!("{}:{}", c.file.display(), c.line),
3342                    c.name,
3343                    c.reason,
3344                    width = width,
3345                    line_width = line_width
3346                );
3347            }
3348        }
3349    }
3350    let s = &rep.summary;
3351    if s.check_errors > 0 {
3352        eprintln!(
3353            "htl adopt: {} error(s) in the project's check (htl check says which); a file \
3354             with a syntax error contributes no markers",
3355            s.check_errors
3356        );
3357    }
3358    if s.markers == 0 {
3359        eprintln!(
3360            "htl adopt: {} of {} features used, no markers",
3361            s.used, s.features
3362        );
3363    } else {
3364        eprintln!(
3365            "htl adopt: {} of {} features used, {} in {}",
3366            s.used,
3367            s.features,
3368            count(s.markers, "marker", "markers"),
3369            count(s.files, "file", "files"),
3370        );
3371    }
3372}
3373
3374/// Say which file a module name resolves to, and what that hides.
3375///
3376/// The chain comes from the library ([`htl::resolve`]), over a checker set up exactly as a
3377/// check of this project sets one up — the installed deps, then the config's search paths,
3378/// in that order, because `add_path` prepends and the order is the whole answer. Asking
3379/// any other way would report a path nothing else uses.
3380///
3381/// A report, so both forms go to stdout (README, "Machine-readable output").
3382fn cmd_resolve(module: &str, path: Option<&Path>, json: bool) -> Result<ExitCode> {
3383    let start = path.unwrap_or(Path::new("."));
3384    // The declarations a check generates before it reads anything are inputs to the
3385    // answer — `types/<crate>/` is written by `htl dts` — and a report without them would
3386    // describe a project nobody checks; `checker_for` writes them. The search order the
3387    // report prints is `project::checker`'s, the one `htl check` reads under.
3388    let ProjectChecker { h, cfg, model, .. } = checker_for(start, true)?;
3389    let rep = htl::resolve::resolve(
3390        &h,
3391        module,
3392        cfg.as_ref().map(|(r, _, _)| r.as_path()),
3393        model.as_ref(),
3394    )?;
3395    if json {
3396        report::emit(&rep)?;
3397    } else {
3398        print_resolution(&rep);
3399    }
3400    Ok(if rep.summary.ok {
3401        ExitCode::SUCCESS
3402    } else {
3403        ExitCode::FAILURE
3404    })
3405}
3406
3407/// The text form of a resolution: a table in search order, then who answered — the project
3408/// model, or the search path and the directories it consulted. The order column is the reason one row is read and the others are not, which
3409/// is why it is printed rather than left to be looked up.
3410fn print_resolution(r: &htl::resolve::Resolution) {
3411    let ambiguous = r
3412        .candidates
3413        .iter()
3414        .any(|c| c.status == htl::resolve::Status::Ambiguous);
3415    // A name the host provides: what answers it at run time is the host, and a row read
3416    // for it is only the declaration it is typed from. Refused when a file implements it
3417    // too, and then the header is the error, as a check reports it.
3418    let typed_by = r
3419        .read
3420        .as_ref()
3421        .map(|d| format!(", typed by {d}"))
3422        .unwrap_or_default();
3423    match (&r.read, &r.error, &r.provided_by) {
3424        (_, Some(e), _) => println!("htl resolve {}: error: {e}", r.module),
3425        // Declared and nothing else: the environment provides it — a library installed on
3426        // the machine, a module registered where the model cannot read it. The declaration
3427        // is the file read, and comes first, as any file the name resolves to does.
3428        (Some(read), None, Some(by)) if r.provider == Some(htl::model::Provider::Declared) => {
3429            println!(
3430                "htl resolve {}: {read}, provided by the environment ({by})",
3431                r.module
3432            )
3433        }
3434        (_, None, Some(by)) => {
3435            println!(
3436                "htl resolve {}: provided by the host ({by}){typed_by}",
3437                r.module
3438            )
3439        }
3440        (Some(read), None, None) => println!("htl resolve {}: {read}", r.module),
3441        (None, None, None) if ambiguous => println!(
3442            "htl resolve {}: more than one module implements it, and no order picks one",
3443            r.module
3444        ),
3445        (None, None, None) => println!(
3446            "htl resolve {}: nothing in the project or on the search path answers require(\"{}\")",
3447            r.module, r.module
3448        ),
3449    }
3450    if !r.candidates.is_empty() {
3451        let w = |f: fn(&htl::resolve::Candidate) -> usize, head: usize| {
3452            r.candidates.iter().map(f).max().unwrap_or(0).max(head)
3453        };
3454        let file = w(|c| c.path.len(), 4);
3455        let kind = w(|c| c.kind.as_str().len(), 4);
3456        let read_at = r
3457            .candidates
3458            .iter()
3459            .find(|c| c.status == htl::resolve::Status::Read)
3460            .map(|c| c.order);
3461        println!();
3462        println!("  order  {:file$}  {:kind$}  status", "file", "kind");
3463        for c in &r.candidates {
3464            let status = match (c.status, c.shadowed_by, read_at) {
3465                (htl::resolve::Status::Shadowed, Some(by), _) => format!("shadowed by {by}"),
3466                // Not hidden by the row that is read: typed by it, and loaded by the run.
3467                (htl::resolve::Status::Runtime, _, Some(by)) => format!("runtime, typed by {by}"),
3468                (s, _, _) => s.as_str().to_string(),
3469            };
3470            let origin = match &c.origin {
3471                Some(o) => format!("  ({})", o.describe()),
3472                None => String::new(),
3473            };
3474            println!(
3475                "  {:<5}  {:file$}  {:kind$}  {status}{origin}",
3476                c.order,
3477                c.path,
3478                c.kind.as_str()
3479            );
3480        }
3481    }
3482    println!();
3483    match r.answered_by {
3484        htl::resolve::AnsweredBy::Model => println!("  answered by the project model"),
3485        // The name is not the project's: where the search looked is half the answer, and
3486        // all of it when nothing was found.
3487        htl::resolve::AnsweredBy::Path => {
3488            println!("  searched, in order: {}", r.searched.join(", "))
3489        }
3490    }
3491}
3492
3493/// `1 module` / `2 modules`: a count whose noun agrees with it, for a line short enough
3494/// that `module(s)` would be the loudest thing on it.
3495fn count(n: usize, one: &str, many: &str) -> String {
3496    format!("{n} {}", if n == 1 { one } else { many })
3497}
3498
3499/// Delete this project's cache store.
3500///
3501/// The store sits beside `htl.toml`, which is not necessarily where anyone is standing:
3502/// `htl check src` run from anywhere in a repo writes to the project root. That is the
3503/// reason this exists rather than leaving people to work out which directory to remove.
3504///
3505/// Only `.htl/cache` goes. `.htl/` itself is left in place for whatever else may come to
3506/// live there, and the path is built here rather than taken from an argument, so there is
3507/// no spelling of the command that removes anything else.
3508fn cmd_cache_clear(path: Option<&Path>) -> Result<ExitCode> {
3509    let root = cache_root(path)?;
3510    let dir = root.join(".htl").join("cache");
3511    if !dir.is_dir() {
3512        eprintln!("htl cache: nothing stored at {}", dir.display());
3513        return Ok(ExitCode::SUCCESS);
3514    }
3515    let n = fs::read_dir(&dir)
3516        .map(|rd| {
3517            rd.flatten()
3518                .filter(|e| e.path().extension().is_some_and(|x| x == "json"))
3519                .count()
3520        })
3521        .unwrap_or(0);
3522    fs::remove_dir_all(&dir).with_context(|| format!("removing {}", dir.display()))?;
3523    eprintln!(
3524        "htl cache: removed {n} {} from {}",
3525        if n == 1 { "entry" } else { "entries" },
3526        dir.display()
3527    );
3528    Ok(ExitCode::SUCCESS)
3529}
3530
3531/// The directory a cache command works on: the project's root, as every command keeps its
3532/// store there ([`project::store_root`]), or the working directory outside a project.
3533fn cache_root(path: Option<&Path>) -> Result<PathBuf> {
3534    let start = path.unwrap_or(Path::new("."));
3535    let model = htl::model::Project::find_root(start)?.map(|r| r.root);
3536    Ok(model.unwrap_or_else(|| std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."))))
3537}
3538
3539/// Say what the store holds.
3540///
3541/// Answers "what is stored", not "what would be reused": an entry listed here can still miss
3542/// on the next run because a file it recorded has changed. The two are different questions
3543/// and conflating them would make this command lie in the more dangerous direction.
3544fn cmd_cache_status(path: Option<&Path>, json: bool, list_entries: bool) -> Result<ExitCode> {
3545    let c = cache::describe(&cache_root(path)?);
3546    if json {
3547        report::emit(&c)?;
3548        return Ok(ExitCode::SUCCESS);
3549    }
3550
3551    if c.entries.is_empty() {
3552        println!("htl cache: empty ({})", c.dir);
3553        return Ok(ExitCode::SUCCESS);
3554    }
3555    let mut by_kind: std::collections::BTreeMap<&str, (usize, u64)> = Default::default();
3556    for e in &c.entries {
3557        let slot = by_kind.entry(e.kind.as_str()).or_default();
3558        slot.0 += 1;
3559        slot.1 += e.bytes;
3560    }
3561    println!(
3562        "htl cache: {} entries, {} at {}",
3563        c.entries.len(),
3564        human_bytes(c.bytes),
3565        c.dir
3566    );
3567    for (kind, (n, bytes)) in &by_kind {
3568        let what = match *kind {
3569            cache::CHECK => "checked modules",
3570            cache::GEN => "checked and generated test files (htl test)",
3571            cache::MODULE => "generated modules (htl test / build, include_bundle!)",
3572            cache::RUN => "whole runs",
3573            cache::LSHAPE => "lshape-version verdicts",
3574            _ => "entries this build cannot read",
3575        };
3576        println!("  {n:>5} {what} ({})", human_bytes(*bytes));
3577    }
3578    if let (Some(min), Some(max)) = (
3579        c.entries.iter().map(|e| e.age_secs).min(),
3580        c.entries.iter().map(|e| e.age_secs).max(),
3581    ) {
3582        println!(
3583            "  last used between {} and {} ago",
3584            human_age(min),
3585            human_age(max)
3586        );
3587    }
3588    if list_entries {
3589        println!();
3590        for e in &c.entries {
3591            println!(
3592                "  {:<6} {:>8}  {}",
3593                e.kind,
3594                human_bytes(e.bytes),
3595                e.subjects.join(", ")
3596            );
3597        }
3598    }
3599    Ok(ExitCode::SUCCESS)
3600}
3601
3602fn human_bytes(n: u64) -> String {
3603    if n >= 1 << 20 {
3604        format!("{:.1} MB", n as f64 / (1u64 << 20) as f64)
3605    } else if n >= 1 << 10 {
3606        format!("{:.0} KB", n as f64 / (1u64 << 10) as f64)
3607    } else {
3608        format!("{n} B")
3609    }
3610}
3611
3612fn human_age(secs: u64) -> String {
3613    match secs {
3614        s if s < 90 => format!("{s}s"),
3615        s if s < 5400 => format!("{}m", s / 60),
3616        s if s < 172_800 => format!("{}h", s / 3600),
3617        s => format!("{}d", s / 86_400),
3618    }
3619}
3620
3621/// How many of the files a walk visited came out of a patched dependency: the files in the
3622/// home of a module the project owns as a patch ([`htl::model::Project::home_of`]) — its
3623/// tests included, which no name reaches. Zero outside a project and for a
3624/// project with no patch, which is what keeps the summary line below unchanged for
3625/// everyone who has never run `htl pkg patch`.
3626fn patched_files(model: Option<&htl::model::Project>, files: &[PathBuf]) -> usize {
3627    let Some(model) = model else {
3628        return 0;
3629    };
3630    if !model
3631        .modules
3632        .iter()
3633        .any(|m| m.owner == htl::model::Owner::Patched)
3634    {
3635        return 0;
3636    }
3637    files
3638        .iter()
3639        .filter(|f| {
3640            model
3641                .home_of(f)
3642                .is_some_and(|m| m.owner == htl::model::Owner::Patched)
3643        })
3644        .count()
3645}
3646
3647/// `htl check --statistics`'s table: one row per rule, count first, the rule names left
3648/// aligned on the longest of them. Nothing is printed for an empty slice — a run with no
3649/// finding leaves the summary line to say `0 error(s), 0 warning(s), 0 lint(s)` on its own.
3650fn print_statistics(rows: &[report::RuleStatistic]) {
3651    let width = rows.iter().map(|r| r.rule.len()).max().unwrap_or(0);
3652    for r in rows {
3653        eprintln!(
3654            "{:>5}  {:<width$}  {}",
3655            r.count,
3656            r.rule,
3657            statistics_marker(r)
3658        );
3659    }
3660}
3661
3662/// `[*]`: every finding of the rule carries a fix `htl fix` applies without being asked
3663/// (`safe`) or shows (`suggest`). `[ ]`: none does. `[-]`: the rest — some findings fixable
3664/// and some not, or every one fixable but only some `safe`/`suggest`, the remainder
3665/// needing `--unsafe`.
3666fn statistics_marker(r: &report::RuleStatistic) -> &'static str {
3667    if r.fixable == r.count {
3668        "[*]"
3669    } else if r.fixable + r.unsafe_fixable == 0 {
3670        "[ ]"
3671    } else {
3672        "[-]"
3673    }
3674}
3675
3676#[cfg(test)]
3677mod statistics_marker_tests {
3678    use super::statistics_marker;
3679    use crate::report::RuleStatistic;
3680
3681    fn stat(count: usize, fixable: usize, unsafe_fixable: usize) -> RuleStatistic {
3682        RuleStatistic {
3683            rule: "r".to_string(),
3684            count,
3685            fixable,
3686            unsafe_fixable,
3687        }
3688    }
3689
3690    /// Every finding fixable, and none of it `--unsafe`-only.
3691    #[test]
3692    fn full_safe_coverage_is_a_star() {
3693        assert_eq!(statistics_marker(&stat(2, 2, 0)), "[*]");
3694    }
3695
3696    /// No finding carries a fix at all.
3697    #[test]
3698    fn no_fix_at_all_is_blank() {
3699        assert_eq!(statistics_marker(&stat(2, 0, 0)), "[ ]");
3700    }
3701
3702    /// Some fixable, some not: a genuine mix.
3703    #[test]
3704    fn a_mix_of_fixable_and_not_is_a_dash() {
3705        assert_eq!(statistics_marker(&stat(3, 1, 0)), "[-]");
3706    }
3707
3708    /// Full coverage, but not every one of it `safe`/`suggest`: the `--unsafe` ones keep
3709    /// it from being a plain `[*]`.
3710    #[test]
3711    fn full_coverage_split_between_safe_and_unsafe_is_a_dash() {
3712        assert_eq!(statistics_marker(&stat(2, 1, 1)), "[-]");
3713    }
3714
3715    /// Full coverage, every one of it `--unsafe`-only.
3716    #[test]
3717    fn full_unsafe_only_coverage_is_a_dash() {
3718        assert_eq!(statistics_marker(&stat(2, 0, 2)), "[-]");
3719    }
3720}
3721
3722/// The one place a check reports its totals, so a replayed module and a checked one cannot
3723/// drift apart in how they are summarized. Returns whether the run counts as a failure.
3724///
3725/// `patched` is how many of those files are a patched dependency's ([`patched_files`]),
3726/// split out of the count rather than added to it. One `htl pkg patch` turned a project's
3727/// `15 file(s)` into `25 file(s)` with nothing said, and a file count that moves for a
3728/// reason the line does not give is a file count a reader cannot use: the dependency's
3729/// `tests/` are now in the walk, they are not the project's, and the line has to say so.
3730fn report_check(
3731    out: &mut report::Out,
3732    json: bool,
3733    statistics: bool,
3734    rep: &project::Report,
3735    policy: &htl::verdict::Policy,
3736    patched: usize,
3737) -> Result<bool> {
3738    let (files, replayed) = (rep.files.len(), rep.replayed);
3739    let (errors, warnings, lints) = (rep.errors, rep.warnings, rep.lints);
3740    let strict = policy.strict;
3741    let fail = htl::verdict::verdict(&rep.findings(), policy);
3742    let all_cached = rep.all_cached();
3743    if json {
3744        report::emit(&report::CheckReport {
3745            files,
3746            patched,
3747            diagnostics: out.take(),
3748            summary: report::CheckSummary {
3749                errors,
3750                warnings,
3751                lints,
3752                denied: rep.denied,
3753                strict,
3754                ok: !fail,
3755                cached: all_cached,
3756                replayed,
3757            },
3758            statistics: statistics.then(|| out.statistics()),
3759        })?;
3760    } else {
3761        if statistics {
3762            print_statistics(&out.statistics());
3763        }
3764        // Say nothing when nothing was replayed; say how much when it was only some.
3765        let cached = if all_cached {
3766            " [cached]".to_string()
3767        } else if replayed > 0 {
3768            format!(" [{replayed}/{files} cached]")
3769        } else {
3770            String::new()
3771        };
3772        // The three counts say what kinds of thing the run said; `at deny` says how much
3773        // of that it failed on, and is left out when it is none of it — its being there at
3774        // all is the news. A run with two warnings and one denied lint reads as
3775        // `0 error(s), 2 warning(s), 1 lint(s), 1 at deny`.
3776        let denied = match rep.denied {
3777            0 => String::new(),
3778            n => format!(", {n} at deny"),
3779        };
3780        // A project with no patch reads exactly as it read before the split existed: the
3781        // second number appears only when there is something on the other side of it, and
3782        // the two always add up to the one number that was there.
3783        let counted = match patched {
3784            0 => format!("{files} file(s)"),
3785            n => format!("{} file(s) + {n} in patched dependencies", files - n),
3786        };
3787        // Where the why is, once per rule this run said something under, after the
3788        // findings and before the summary — the way cargo names `cargo fix` once rather
3789        // than on every line. A finding's message names the site; the explanation names
3790        // the rule. Only rules that have one (every lint does; an error has no rule).
3791        for rule in out.rules_said() {
3792            if htl::lint::explained(rule).is_some() {
3793                eprintln!("htl check --explain {rule}");
3794            }
3795        }
3796        eprintln!(
3797            "htl check: {counted}, {errors} error(s), {warnings} warning(s), {lints} lint(s){denied}{}{cached}",
3798            if strict { " [strict]" } else { "" }
3799        );
3800    }
3801    Ok(fail)
3802}
3803
3804/// What [`checker_for`] set up, and what it set it up from.
3805struct ProjectChecker {
3806    /// The checker: the lint selection and `[lang]` of the project, its test library,
3807    /// `std.*`, the libraries this binary registers and `htl.task`, then the model's
3808    /// directories on the search path with its dependencies reachable.
3809    h: Htl,
3810    /// The config around the starting path; `None` outside a project.
3811    cfg: project::Config,
3812    /// The project model; `None` when there is neither an `htl.toml` nor an
3813    /// `mlua-pkg.toml`.
3814    model: Option<htl::model::Project>,
3815    /// What `htl check` holds a file to: the lint selection `h` was configured from
3816    /// (`scope.lints`), and the contracts and host modules a walk reads. A command
3817    /// that judges what it generates asks the same `Lints` for its levels, so the
3818    /// rules `h` runs and the rules the command reports under are one answer.
3819    scope: project::Scope,
3820}
3821
3822/// A checker set up for the project `start` is in, through the two library functions
3823/// `htl check` goes through: [`project::Scope::new`] for the lint input, and
3824/// [`project::checker`] for the checker built from it: declarations written, model
3825/// loaded, scope, checker. A command that parses `.tl` and resolves requires calls this
3826/// and does not assemble a checker itself, so a `require` the checker resolves for
3827/// `htl check` is one `htl gen`, `htl run`, `htl build`, `htl resolve`, `htl shapes` and
3828/// `htl fix` resolve too, at the same lint levels. They each used to spell the install
3829/// calls out, in an order of their own, and `htl check` agreed with none of them: `htl
3830/// gen` did not install `htl.task`, and found its declaration only when a check or a run
3831/// had left it in the temporary directory first.
3832///
3833/// `write_dts` is the one difference between callers: whether the declarations the
3834/// project publishes (`auto_dts`) are written before anything is read. `htl fix
3835/// --dry-run` is the only caller that passes `false`; what it then checks is the
3836/// declarations as they are on disk.
3837///
3838/// What one file may read beyond what the model gives — the test root, for a file under
3839/// it; its own directory, for a file in no project — is [`project::file_view`], asked per
3840/// file by the command that has one.
3841///
3842/// The sites that do not come through here, and why:
3843/// - `cmd_fmt` only parses, and resolves no `require`, so it has no search path to set up.
3844/// - `htl check` and the language server hold a [`project::Scope`] of their own across
3845///   many files and call [`project::checker`] directly.
3846/// - the proc macros in `htl-macros` (`include_tl!`, `include_bundle!`) cannot call
3847///   `htl-cli`, so their `checker_for` calls [`project::Scope::new`] and
3848///   [`project::checker`] directly (inside `rustc` [`Htl::install_registered`] installs
3849///   nothing: see the module doc of `htl_core::registry`).
3850fn checker_for(start: &Path, write_dts: bool) -> Result<ProjectChecker> {
3851    let cfg = load_config(start)?;
3852    auto_dts_to(start, write_dts)?;
3853    let model = project::model_of(&cfg, start)?;
3854    let scope = project::Scope::new(&cfg, model.as_ref(), start, None)?;
3855    let h = project::checker(
3856        model.as_ref(),
3857        scope.lints.selection(),
3858        &project::lang_of(&cfg),
3859    )?;
3860    Ok(ProjectChecker {
3861        h,
3862        cfg,
3863        model,
3864        scope,
3865    })
3866}
3867
3868fn cmd_gen(file: &Path, out: Option<&Path>) -> Result<ExitCode> {
3869    // The search path `htl check` gives this file, so `htl gen` resolves what `htl check`
3870    // resolved and a file the checker accepts is one this command can emit.
3871    let ProjectChecker { h, model, .. } = checker_for(file, true)?;
3872    project::file_view(&h, model.as_ref(), file)?;
3873    let (code, c) = h.gen_lua(file)?;
3874    text_sink().checkinfo(&c);
3875    // Judged on its errors alone (`Policy::ERRORS_ONLY`): the warnings and lints above are
3876    // reported, and `htl check` is where they are judged.
3877    let (Some(code), false) = (code, htl::verdict::fails_on_errors(&c)) else {
3878        return Ok(ExitCode::FAILURE);
3879    };
3880    // Written as it came back. This command used to append the final newline itself, which
3881    // made it the one consumer of `gen_lua` whose output was a whole file; the generator
3882    // does it for all of them now (`H.gen` in `prelude.lua` says why).
3883    match out {
3884        Some(p) => fs::write(p, code).with_context(|| format!("writing {}", p.display()))?,
3885        None => print!("{code}"),
3886    }
3887    Ok(ExitCode::SUCCESS)
3888}
3889
3890fn cmd_run(file: &Path, args: &[String]) -> Result<ExitCode> {
3891    let bytes = fs::read(file).with_context(|| format!("reading {}", file.display()))?;
3892    // The search path `htl check` gives this file, so `htl run` resolves what `htl check`
3893    // resolved rather than failing on a `require` the checker was happy with. Before the
3894    // bundle branch because a bundle carries its own modules and gains nothing from it
3895    // either way.
3896    let ProjectChecker { h, cfg, model, .. } = checker_for(file, true)?;
3897    // The executor's `[async]` is not part of what a check reads; nothing starts a task
3898    // before `load_bundle` / `run_root`, so setting it once the checker is up is early enough.
3899    h.configure_async(async_config(&cfg))?;
3900    if Bundle::is_bundle(&bytes) {
3901        let b = Bundle::decode(&bytes)?;
3902        // A bundle's frames are as good as its payload: stripped bytecode has no lines to
3903        // show, and `htl build --debug` is what keeps them.
3904        let main = h.load_bundle(&b, args)?;
3905        return run_root(&h, Entry::Main(main), args);
3906    }
3907    // Check first so lints/warnings are visible before the script runs.
3908    project::file_view(&h, model.as_ref(), file)?;
3909    h.install_searcher()?;
3910    h.set_arg(&file.to_string_lossy(), args)?;
3911    let (code, c) = h.gen_lua(file)?;
3912    text_sink().checkinfo(&c);
3913    // As `htl gen`: errors stop it, the rest is reported (`Policy::ERRORS_ONLY`).
3914    let (Some(code), false) = (code, htl::verdict::fails_on_errors(&c)) else {
3915        return Ok(ExitCode::FAILURE);
3916    };
3917    run_root(
3918        &h,
3919        Entry::Chunk {
3920            code,
3921            name: format!("@{}", file.display()),
3922        },
3923        args,
3924    )
3925}
3926
3927/// What `htl run` runs as the program's root: a generated chunk, or a bundle's entry.
3928enum Entry {
3929    Chunk { code: String, name: String },
3930    Main(htl::mlua::Function),
3931}
3932
3933/// The `[async]` of a loaded `htl.toml`, or the default when there is no file.
3934fn async_config(cfg: &project::Config) -> &htl::config::AsyncConfig {
3935    static DEFAULT: htl::config::AsyncConfig = htl::config::AsyncConfig {
3936        grace_ms: None,
3937        preempt: None,
3938    };
3939    match cfg {
3940        Some((_, _, c)) => &c.async_,
3941        None => &DEFAULT,
3942    }
3943}
3944
3945/// Run the program as a root coroutine on the executor, with Ctrl-C cancelling it.
3946///
3947/// The runtime is a current-thread tokio runtime with its time driver (the grace is a
3948/// tokio timeout) and a `LocalSet`, built for this run; `Htl::run_async` is awaited to
3949/// the end, so when it resolves nothing the program started is alive.
3950///
3951/// Ctrl-C is watched from a thread of its own rather than a task on this runtime: a
3952/// program in a CPU loop never yields to the runtime, so a task here would never get to
3953/// run, while the cancel hook reads the token from any thread at its next check. The
3954/// first Ctrl-C cancels the root — the program gets its grace to clean up — and a second
3955/// one ends the process, for a program that does not.
3956///
3957/// A cancelled run prints `htl run: interrupted` and exits 130, the shell's own code for
3958/// it; a program that raised prints the innermost cause and the frames that reached it
3959/// (`htl run` is a development command, so the frames are the default; `htl::user_message`
3960/// is what an embedding host shows people who did not write the Teal).
3961fn run_root(h: &Htl, entry: Entry, args: &[String]) -> Result<ExitCode> {
3962    let token = htl::mlua_isle::runtime::CancelToken::new();
3963    {
3964        let token = token.clone();
3965        std::thread::Builder::new()
3966            .name("htl-ctrl-c".into())
3967            .spawn(move || {
3968                let Ok(rt) = tokio::runtime::Builder::new_current_thread()
3969                    .enable_all()
3970                    .build()
3971                else {
3972                    return;
3973                };
3974                rt.block_on(async {
3975                    if tokio::signal::ctrl_c().await.is_ok() {
3976                        token.cancel();
3977                    }
3978                    if tokio::signal::ctrl_c().await.is_ok() {
3979                        std::process::exit(130);
3980                    }
3981                });
3982            })
3983            .context("starting the Ctrl-C watcher")?;
3984    }
3985    let rt = tokio::runtime::Builder::new_current_thread()
3986        .enable_all()
3987        .build()
3988        .context("building the executor's runtime")?;
3989    let local = tokio::task::LocalSet::new();
3990    let out = local.block_on(&rt, async {
3991        match entry {
3992            Entry::Chunk { code, name } => h.run_async(&code, &name, args, &token).await,
3993            Entry::Main(main) => {
3994                let va: htl::mlua::Variadic<String> = args.iter().cloned().collect();
3995                h.call_async(main, va, &token).await.map(|_| ())
3996            }
3997        }
3998    });
3999    Ok(match out {
4000        Ok(()) => ExitCode::SUCCESS,
4001        Err(e) if htl::is_cancelled(&e) => {
4002            eprintln!("htl run: interrupted");
4003            ExitCode::from(130)
4004        }
4005        Err(e) => {
4006            eprintln!("{}", htl::developer_message(&e));
4007            ExitCode::FAILURE
4008        }
4009    })
4010}
4011
4012/// The run cache as `htl build` was asked to use it: `--no-cache` and `--explain-cache`,
4013/// the two switches that mean something for one closure. There is no `--cache-mode`: a
4014/// build's entries are per module, as `htl test`'s are, since a build is many modules and
4015/// an edit to one should cost that one and its dependents rather than the closure.
4016struct BuildCache {
4017    use_cache: bool,
4018    explain: bool,
4019}
4020
4021fn cmd_build(
4022    entry: &Path,
4023    out: &Path,
4024    main: &str,
4025    mut opts: htl::link::LinkOptions,
4026    cache_flags: BuildCache,
4027) -> Result<ExitCode> {
4028    // `std.*` resolves to its declaration and nothing else, so the linker files it under
4029    // the host's modules — which is what it is: the binary that runs the bundle preloads
4030    // it, as `htl run` does before `run_bundle`.
4031    let ProjectChecker {
4032        h,
4033        cfg,
4034        model,
4035        scope,
4036    } = checker_for(entry, true)?;
4037    // The rules and levels `htl check` uses: a bundle is judged as a check of its closure
4038    // would be, and a rule the project turned off is not reported here either.
4039    let lints = scope.lints;
4040    let policy = htl::verdict::Policy::resolve(cfg.as_ref().map(|(_, _, c)| c), false);
4041    // The names the host provides are the model's — `#[host_module]`s in the crate around
4042    // the project, `[build] host`, `std.*` — so the bundle leaves out what the host
4043    // registers without anyone restating it; `--host` adds to them.
4044    if let Some(m) = &model {
4045        opts.host.extend(m.provided().map(|(n, _)| n.to_string()));
4046    }
4047    if let Some((_, _, cfg)) = &cfg {
4048        opts.extra.extend(cfg.build.extra.iter().cloned());
4049        opts.host.extend(cfg.build.host.iter().cloned());
4050        // The one thing `[build] target` changes: this command produces the `hb` target and
4051        // nothing else, so a project that records another is told which command does build
4052        // it rather than handed a bundle nothing in it was going to load. Here rather than
4053        // further down because both forms of `htl build` pass through — the directory form
4054        // returns a few lines below — and because nothing has been written yet.
4055        if let Some(t) = cfg.build.target.filter(|t| *t != BuildTarget::Hb) {
4056            eprintln!(
4057                "htl build: this project's target is `{}` — what runs its output is {} — and `htl build` writes a `.hb` bundle, which is the `hb` target. Build it with `cargo build`; to bundle its scripts anyway, drop `[build] target` from htl.toml.",
4058                t.name(),
4059                t.runs_it()
4060            );
4061            return Ok(ExitCode::FAILURE);
4062        }
4063    }
4064    if entry.is_dir() {
4065        if cache_flags.explain {
4066            eprintln!("htl cache: the directory form of `htl build` is not cached");
4067        }
4068        // Not into an installed or vendored copy — a dependency's files, which the model
4069        // knows — and into a patch, which is the project's code.
4070        let skip = project::not_walked(
4071            model.as_ref(),
4072            &[entry.to_path_buf()],
4073            htl::model::Purpose::Check,
4074        );
4075        return cmd_build_dir(&h, entry, out, main, &opts, &skip, &lints, &policy);
4076    }
4077    project::file_view(&h, model.as_ref(), entry)?;
4078    // The name the entry is served under: the one the project's model gives the file,
4079    // which is what a `require` of it elsewhere in the project writes.
4080    opts.entry_name = model.as_ref().and_then(|m| m.locate(entry).map(|p| p.name));
4081    // The store: `module` entries keyed the way `htl test` and the macros key them — the
4082    // file the module is and the lint selection `htl.toml` puts in force — so a module any
4083    // of them generated is one the build replays, and the reverse. Nothing is swept here:
4084    // a build sees one closure, and only `htl check`, which sees the project, bounds the
4085    // store (`cache.rs`).
4086    let root = project::store_root(model.as_ref());
4087    // `htl.toml`'s spec as the scope joined it, the one `lints` was parsed from.
4088    let lint = (!scope.spec.is_empty()).then_some(scope.spec.as_str());
4089    let cache_opts = project::cache_options(
4090        cache_flags.use_cache,
4091        Some(cache::Mode::PerModule),
4092        &cfg,
4093        cache_flags.explain,
4094    );
4095    let store = project::with_model(
4096        project::store(&root, cache_opts, None, "htl build"),
4097        model.as_ref(),
4098    );
4099    let link_store = store.as_ref().map(|c| htl::link::LinkStore {
4100        cache: c,
4101        lint,
4102        root: &root,
4103        config: cfg.as_ref().map(|(_, p, c)| (p.as_path(), c)),
4104    });
4105    let linked = htl::link::link_with(&h, entry, &opts, link_store)?;
4106    project::explain_cache(store.as_ref(), cache_opts);
4107    // One sink for the whole closure: a build is many modules, and what the layer says
4108    // once per run is said once for the build rather than once per module.
4109    let mut sink = text_sink();
4110    sink.judge_by(lints.selection());
4111    for (p, c) in &linked.checks {
4112        sink.checkinfo(&linked.reported(p, c));
4113    }
4114    let n_err = linked.errors.len();
4115    let found = htl::verdict::Findings {
4116        errors: n_err,
4117        warnings: linked.checks.iter().map(|(_, c)| c.warnings.len()).sum(),
4118        lints: linked.lints.len(),
4119        denied: sink.denied(),
4120    };
4121    // The checks' own errors went through the sink above; the linker's are its own list,
4122    // said through the same sink so they read as the checks' do.
4123    for d in &linked.link_errors {
4124        sink.diagnostic(d);
4125    }
4126    if htl::verdict::verdict(&found, &policy) {
4127        eprintln!(
4128            "htl build: {n_err} error(s){}, bundle not written",
4129            judged(&found, &policy)
4130        );
4131        return Ok(ExitCode::FAILURE);
4132    }
4133    let buf = linked.bundle()?.encode();
4134    fs::write(out, &buf).with_context(|| format!("writing {}", out.display()))?;
4135    let typed = linked.modules.iter().filter(|m| m.typed).count();
4136    // The same suffix `htl check` prints: everything from the store, some of it, or
4137    // nothing said when none was.
4138    let cached = if typed > 0 && linked.cached == typed {
4139        " [cached]".to_string()
4140    } else if linked.cached > 0 {
4141        format!(" [{}/{typed} cached]", linked.cached)
4142    } else {
4143        String::new()
4144    };
4145    eprintln!(
4146        "htl build: {} module(s) ({typed} typed, {} lua) -> {} ({} bytes{}{}){cached}",
4147        linked.modules.len(),
4148        linked.modules.len() - typed,
4149        out.display(),
4150        buf.len(),
4151        if opts.source {
4152            ", source"
4153        } else {
4154            ", bytecode"
4155        },
4156        if opts.debug { " with debug info" } else { "" }
4157    );
4158    if !linked.host_modules.is_empty() {
4159        eprintln!(
4160            "htl build: host must provide: {}",
4161            linked.host_modules.join(", ")
4162        );
4163    }
4164    Ok(ExitCode::SUCCESS)
4165}
4166
4167/// The older form: every `.tl` under a directory, module names from their paths.
4168// Eight because the two judgments `cmd_build` already holds are handed in rather than
4169// asked for again from the config.
4170#[allow(clippy::too_many_arguments)]
4171fn cmd_build_dir(
4172    h: &Htl,
4173    dir: &Path,
4174    out: &Path,
4175    entry: &str,
4176    opts: &htl::link::LinkOptions,
4177    skip: &[PathBuf],
4178    lints: &htl::lint::Lints,
4179    policy: &htl::verdict::Policy,
4180) -> Result<ExitCode> {
4181    // `lints` and `policy` are the file form's, passed in by `cmd_build`: `htl.toml`'s rules
4182    // and levels, its `strict`.
4183    h.add_path(dir)?;
4184    let files = htl::collect_tl_skipping(&[dir.to_path_buf()], skip)?;
4185    let mut b = Bundle {
4186        entry: entry.to_string(),
4187        htl_version: env!("CARGO_PKG_VERSION").into(),
4188        ..Default::default()
4189    };
4190    let mut found = htl::verdict::Findings::default();
4191    let mut sink = text_sink();
4192    sink.judge_by(lints.selection());
4193    for f in &files {
4194        // Named against the directory the bundle is built from, by the naming rule.
4195        let rel = f.strip_prefix(dir).unwrap_or(f);
4196        let name = htl::naming::name_of("", rel)
4197            .with_context(|| format!("cannot derive a module name for {}", f.display()))?;
4198        let (code, c) = h.gen_lua(f)?;
4199        sink.checkinfo(&c);
4200        found.errors += c.errors.len();
4201        found.warnings += c.warnings.len();
4202        found.lints += c.lints.len();
4203        let Some(code) = code else { continue };
4204        let (kind, payload) = if opts.source {
4205            (htl::bundle::Kind::Source, code.into_bytes())
4206        } else {
4207            (
4208                htl::bundle::Kind::Bytecode,
4209                h.compile_with(&name, &code, !opts.debug)?,
4210            )
4211        };
4212        b.modules.push(htl::bundle::Module {
4213            name,
4214            kind,
4215            payload,
4216        });
4217    }
4218    found.denied = sink.denied();
4219    if htl::verdict::verdict(&found, policy) {
4220        eprintln!(
4221            "htl build: {} error(s){}, bundle not written",
4222            found.errors,
4223            judged(&found, policy)
4224        );
4225        return Ok(ExitCode::FAILURE);
4226    }
4227    if b.module(entry).is_none() {
4228        bail!(
4229            "entry module '{entry}' not found among {} module(s)",
4230            b.modules.len()
4231        );
4232    }
4233    if !opts.source {
4234        b.fingerprint = h.fingerprint()?;
4235    }
4236    let buf = b.encode();
4237    fs::write(out, &buf).with_context(|| format!("writing {}", out.display()))?;
4238    eprintln!(
4239        "htl build: {} module(s) -> {} ({} bytes)",
4240        b.modules.len(),
4241        out.display(),
4242        buf.len()
4243    );
4244    Ok(ExitCode::SUCCESS)
4245}
4246
4247/// What `htl bundle info` reports: everything the file records and nothing it does not
4248/// (no Lua state is created, nothing is loaded), which is what a build step checks in and
4249/// a bug report pastes; `--format json` is the same fields. `lua` is the header the
4250/// bytecode was compiled for, in the fields the mismatch message names; `None` when the
4251/// bundle carries no fingerprint, which `payload` explains (`source`: the text says `any`)
4252/// or `format` does (`1`, before the fingerprint: `not recorded`).
4253#[derive(serde::Serialize)]
4254struct BundleInfo {
4255    file: String,
4256    format: u8,
4257    htl_version: Option<String>,
4258    /// `bytecode`, `source`, or `mixed` when modules disagree.
4259    payload: &'static str,
4260    lua: Option<htl::bundle::LuaHeader>,
4261    entry: String,
4262    modules: Vec<BundleModuleInfo>,
4263    host_modules: Vec<String>,
4264}
4265
4266#[derive(serde::Serialize)]
4267struct BundleModuleInfo {
4268    name: String,
4269    kind: &'static str,
4270    bytes: usize,
4271}
4272
4273fn cmd_bundle_info(file: &Path, json: bool) -> Result<ExitCode> {
4274    let bytes = fs::read(file).with_context(|| format!("reading {}", file.display()))?;
4275    let Some(format) = htl::bundle::format_version(&bytes) else {
4276        bail!("{} is not an htl bundle (bad magic)", file.display());
4277    };
4278    let b = Bundle::decode(&bytes)?;
4279    let kind_name = |k: htl::bundle::Kind| match k {
4280        htl::bundle::Kind::Bytecode => "bytecode",
4281        htl::bundle::Kind::Source => "source",
4282    };
4283    let payload = match (
4284        b.modules
4285            .iter()
4286            .any(|m| m.kind == htl::bundle::Kind::Bytecode),
4287        b.modules
4288            .iter()
4289            .any(|m| m.kind == htl::bundle::Kind::Source),
4290    ) {
4291        (true, true) => "mixed",
4292        (false, true) => "source",
4293        // Bytecode, or no modules at all: what the loader would treat it as.
4294        _ => "bytecode",
4295    };
4296    let info = BundleInfo {
4297        file: file.display().to_string(),
4298        format,
4299        htl_version: (!b.htl_version.is_empty()).then(|| b.htl_version.clone()),
4300        payload,
4301        lua: htl::bundle::LuaHeader::parse(&b.fingerprint),
4302        entry: b.entry.clone(),
4303        modules: b
4304            .modules
4305            .iter()
4306            .map(|m| BundleModuleInfo {
4307                name: m.name.clone(),
4308                kind: kind_name(m.kind),
4309                bytes: m.payload.len(),
4310            })
4311            .collect(),
4312        host_modules: b.host_modules.clone(),
4313    };
4314    if json {
4315        report::emit(&info)?;
4316        return Ok(ExitCode::SUCCESS);
4317    }
4318
4319    println!(
4320        "{}: htl bundle, format {}, built by {}",
4321        info.file,
4322        info.format,
4323        match &info.htl_version {
4324            Some(v) => format!("htl {v}"),
4325            None => "htl (version not recorded)".to_string(),
4326        }
4327    );
4328    println!("  payload:  {}", info.payload);
4329    let lua = match &info.lua {
4330        Some(h) => h.to_string(),
4331        None if !b.fingerprint.is_empty() => {
4332            format!("unreadable fingerprint ({} bytes)", b.fingerprint.len())
4333        }
4334        None if info.format == 1 => {
4335            "not recorded (a format 1 bundle carries no fingerprint)".into()
4336        }
4337        None => "any (source payload, no bytecode to bind)".into(),
4338    };
4339    println!("  lua:      {lua}");
4340    println!("  entry:    {}", info.entry);
4341    let modules: Vec<String> = info
4342        .modules
4343        .iter()
4344        .map(|m| {
4345            if info.payload == "mixed" {
4346                format!("{} ({})", m.name, m.kind)
4347            } else {
4348                m.name.clone()
4349            }
4350        })
4351        .collect();
4352    println!(
4353        "  modules:  {}",
4354        if modules.is_empty() {
4355            "(none)".to_string()
4356        } else {
4357            modules.join(", ")
4358        }
4359    );
4360    println!(
4361        "  host:     {}",
4362        if info.host_modules.is_empty() {
4363            "(none)".to_string()
4364        } else {
4365            info.host_modules.join(", ")
4366        }
4367    );
4368    Ok(ExitCode::SUCCESS)
4369}