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