Skip to main content

htl_core/
lib.rs

1//! htl: Teal, hidden.
2//!
3//! Embeds the Teal compiler (`tl.lua`) into an mlua state so `.tl` sources can be
4//! type-checked, generated and executed without any external toolchain.
5//!
6//! - [`Htl::check`] / [`Htl::gen_lua`]: type-check and generate Lua from a `.tl` file
7//! - [`Htl::install_searcher`]: strict `require` for `.tl` (type errors abort the require)
8//! - [`Htl::preload`]: register generated Lua (e.g. from `include_tl!`) under a module name
9//! - [`bundle`]: stripped-bytecode bundles produced by `htl build`
10//!
11//! A project — its own code, its dependencies, the declarations crates ship to it and the
12//! directories it accepts modules from — is described by the `model` module (compiled
13//! with the `pkg` and `dts` features): one `Module` per unit that owns a namespace, each
14//! with its source, test and declaration roots, and one rule for the name a file answers
15//! to.
16//!
17//! Three libraries ship inside the binary rather than on a project's search path, and all
18//! are installed the same way — a `package.preload` entry for the run, a `.d.tl` under
19//! [`lib_dir`] for the checker: `htl.test` ([`Htl::install_test_lib`], `describe` / `it` /
20//! `expect`); with the `std` feature, `std.*` — mlua-batteries' modules under the
21//! namespace that crate leaves to its host; and with the `async` feature, `htl.task` —
22//! tasks a program on the executor spawns and awaits (`spawn` / `await` / `<close>`,
23//! mlua-isle's task library under a declaration; the `task` module says what it promises).
24//! The methods that install the last two are named and linked below when the feature that
25//! compiles them is on; a link to an item that is not compiled is a broken one.
26#![cfg_attr(
27    feature = "std",
28    doc = "
29//! `std.*` is installed by [`Htl::install_std`]."
30)]
31#![cfg_attr(
32    feature = "async",
33    doc = "
34//! `htl.task` is installed by [`Htl::install_task_lib`]; the channels a host feeds a
35//! running program through are [`task::RecvChannel`] and [`task::SendChannel`]."
36)]
37//!
38//! A value the host puts into the Lua state reaches `.tl` code with a type in one of
39//! three ways, and the first is the one to reach for:
40//!
41//! 1. `#[host_module]` on the Rust side (the `htl-macros` crate): the host registers a
42//!    module in `package.preload` and the macro writes its `.d.tl`, so the `.tl` side
43//!    `require`s it like any module and the checker reads the declaration the build
44//!    keeps current.
45//! 2. When the Rust side stays as it is and sets the value as a global
46//!    (`lua.globals().set("knl", ..)`): one `.tl` module that reads it from `_G` and
47//!    returns it —
48//!    ```teal
49//!    local record Knl
50//!       open: function(): Session
51//!    end
52//!    local knl = (_G as {string:any})["knl"] as Knl
53//!    return knl
54//!    ```
55//!    — so no `global` is declared anywhere, the checker sees an ordinary module, and the
56//!    one line that reads the state is that one. Four files over such a module check
57//!    clean in either order, and `htl run` with the value set finds it.
58//! 3. A `global` declaration in a module, a `.d.tl` or a `.tl`. It is visible in the
59//!    files that require the declaring module, directly or through a chain of requires,
60//!    and nowhere else: the run checks each file in an environment of its own, and the
61//!    checked-module store hands a module's globals to the environments that require
62//!    it. The global namespace is one per project, so a second declaration of the name
63//!    at another site is [`global-redeclaration`](crate::lint#global-redeclaration),
64//!    whether or not the types agree (the checker's own `cannot redeclare global with a
65//!    different type` is raised only where one environment walks both, which depends on
66//!    the walk order; the lint does not). [`no-global`](crate::lint#no-global) is the
67//!    lint that asks for 1 or 2 instead.
68// Every public item here is `htl`'s public API: that crate is `pub use htl_core::*;`, and
69// `missing_docs` fires where an item is defined rather than where it is re-exported — so
70// the ratchet `htl` took in #224 does nothing for the half a reader actually meets unless
71// it is here too. It arrives with the change that took the count to zero, which is the
72// only moment it costs nothing and the only one at which it is true.
73#![deny(missing_docs)]
74
75pub use mlua;
76/// The owner of a state's debug hook (`mlua_isle::runtime::Vm`): `Interrupt`, coverage
77/// and a host's own instruction or line callback register with it rather than each
78/// taking the one hook slot a Lua thread has — see [`Htl::hook_owner`].
79pub use mlua_isle;
80/// serde, with its `derive` feature, as htl builds it: `htl::serde`. A host that already
81/// depends on `serde` itself changes nothing and keeps writing `#[derive(Serialize)]`
82/// against its own. A host that does not can derive through this one, but serde's derive
83/// writes `::serde::..` paths into the code it generates, which only resolve against a
84/// direct dependency, so the type also says where serde is:
85///
86/// ```rust,ignore
87/// #[derive(htl::serde::Serialize, htl::serde::Deserialize)]
88/// #[serde(crate = "htl::serde")]
89/// struct Call { id: String }
90/// ```
91pub use serde;
92/// serde_json, as htl builds it: `htl::serde_json`, for the host that reads or writes the
93/// JSON its `htl::serde` types describe without a dependency of its own.
94pub use serde_json;
95
96use anyhow::{Context, Result, anyhow, bail};
97use mlua::chunk::ChunkMode;
98use mlua::{Function, Lua, Table, Value, Variadic};
99use std::cell::RefCell;
100use std::collections::{HashMap, HashSet};
101use std::path::{Path, PathBuf};
102use std::rc::Rc;
103use std::sync::OnceLock;
104
105pub mod build_target;
106pub mod bundle;
107pub mod cache;
108#[cfg(feature = "dts")]
109pub mod cexport;
110pub mod config;
111pub mod contract;
112#[cfg(feature = "dts")]
113pub mod dep_dts;
114pub mod diagnostic;
115#[cfg(feature = "dts")]
116pub mod dts;
117#[cfg(feature = "ffi")]
118pub mod ffi;
119pub mod fix;
120// The rules there are, and which of them a run has on. Both halves of htl report under
121// these names, so the list is here rather than in `lint.lua`, which is one of the halves.
122pub mod link;
123pub mod lint;
124// The naming rule (a file's module name, and the files a name may be), shared by the
125// project model and a host's `TealResolver`, which is compiled without the model.
126pub mod naming;
127// Which modules a project is made of and what name each file answers to. Reads the
128// mlua-pkg manifest and the notes `htl dts` writes, so it carries the project layer's
129// features.
130#[cfg(all(feature = "pkg", feature = "dts"))]
131pub mod model;
132#[cfg(feature = "pkg")]
133pub mod pkg;
134// The project layer: a walk over many files, the run cache under it, and the decisions
135// both `htl check` and a macro expansion make about that store. It reaches the mlua-pkg
136// project a file belongs to and the Cargo package around it, so it asks for the two
137// features that provide them; every consumer that has a project to check has both.
138#[cfg(all(feature = "pkg", feature = "dts"))]
139pub mod project;
140// What one module name resolves to, and what that hides. Reads the project the same way
141// the project layer does — the installed deps, the config's search paths, the notes `htl
142// dts` leaves under `types/<crate>/` — so it carries the same features.
143#[cfg(all(feature = "pkg", feature = "dts"))]
144pub mod resolve;
145// `std.*`: mlua-batteries, preloaded and declared the way `htl.test` is. Its own module
146// rather than a corner of `testing.rs` because the two libraries are unrelated apart from
147// how they are installed, and that part they share through `lib_dir`. Named for the crate
148// and not for the namespace: a module called `std` at the crate root would shadow `::std`
149// in every path this file writes.
150#[cfg(feature = "std")]
151pub mod batteries;
152#[cfg(feature = "async")]
153pub mod run;
154#[cfg(feature = "async")]
155pub mod task;
156// The seam a binary adds its own libraries through, wherever this crate builds an `Htl`
157// for itself rather than the binary's own: no feature gate, since the mechanism is not
158// mlua-batteries' or the executor's — it exists for whatever else a binary links in,
159// outside this crate's own dependency graph.
160pub mod registry;
161// The run-time shape of each record and enum a checked file declares (`htl shapes`): pure,
162// from what a check produced to the text of the files that are written.
163pub mod shapes;
164// The Rust types of the records and enums a checked file declares (`htl rs`): pure, as
165// `shapes` is. It validates a Rust type in `[rust.types]` with `syn`, which `dts` brings.
166#[cfg(feature = "dts")]
167pub mod rsgen;
168pub mod teal;
169pub mod testing;
170// What the checker knows of each position of a file, kept for an editor's hover and
171// go-to-definition.
172pub mod typeindex;
173// How much of htl's marker vocabulary a project has written, and where. On the project
174// layer, whose check hands it the census, so it carries that layer's features — the same
175// two `unused` does, and for the same reason.
176#[cfg(all(feature = "pkg", feature = "dts"))]
177pub mod adopt;
178// The complement of the require closure: what no entry reaches. On the project layer,
179// whose check hands it the graph, so it carries that layer's features.
180#[cfg(all(feature = "pkg", feature = "dts"))]
181pub mod unused;
182// Whether a run fails: the one predicate every command's exit code comes from.
183pub mod verdict;
184
185pub use build_target::BuildTarget;
186pub use diagnostic::{Diagnostic, Severity};
187pub use teal::Strict;
188
189/// Registry key under which the prelude table is stored (lets `pkg::TealResolver`
190/// reach the compiler from a bare `&Lua`).
191pub(crate) const PRELUDE_REGISTRY_KEY: &str = "htl.prelude";
192
193const TL_SRC: &str = include_str!("../vendor/tl.lua");
194const LINT_SRC: &str = include_str!("lint.lua");
195const FMT_SRC: &str = include_str!("fmt.lua");
196/// The `_VERSION` reader behind [`shapes::runtime_version`] (`runtime_version.lua`).
197const RUNTIME_VERSION_SRC: &str = include_str!("runtime_version.lua");
198const PRELUDE: &str = include_str!("prelude.lua");
199/// `require` resolution shared by the checker prelude and a split runtime state's
200/// (`search.lua`, loaded by both `from_lua` and
201/// [`with_checker_lua`](Htl::with_checker_lua)).
202const SEARCH_SRC: &str = include_str!("search.lua");
203
204/// A hash of the Lua the checker is made of: the vendored `tl`, the lints, the formatter,
205/// the `_VERSION` reader, the search chunk and the prelude. Two builds with the same value generate the same Lua
206/// for the same input, whatever else differs about them.
207///
208/// The run cache stamps its entries with this ([`cache`]). The CLI also stamps them with
209/// its own binary, which moves on every rebuild; inside a proc macro the binary is
210/// `rustc`, which does not move when htl does, and this is what tells those entries apart
211/// from a checker that no longer exists.
212///
213/// `SEARCH_SRC` is in the array because it changes what a `require` does — generated Lua
214/// cached under one version of it is not safe to replay under another.
215pub fn checker_identity() -> &'static str {
216    static ID: std::sync::OnceLock<String> = std::sync::OnceLock::new();
217    ID.get_or_init(|| {
218        let mut h = blake3::Hasher::new();
219        for src in [
220            TL_SRC,
221            LINT_SRC,
222            FMT_SRC,
223            RUNTIME_VERSION_SRC,
224            SEARCH_SRC,
225            PRELUDE,
226        ] {
227            h.update(src.as_bytes());
228            h.update(b"\0");
229        }
230        h.finalize().to_hex().to_string()
231    })
232}
233
234/// Teal version vendored into this crate: `vendor/tl.lua`, verbatim. There is no fork;
235/// the compiler is swapped as a file when it moves.
236pub const TEAL_VERSION: &str = "0.24.8";
237
238/// Result of type-checking one `.tl` file.
239#[derive(Debug, Clone, Default)]
240pub struct CheckInfo {
241    /// `file:line:col: message` for syntax and type errors.
242    pub errors: Vec<String>,
243    /// How many syntax errors the parser reported. Their text is in `errors`, worded
244    /// however Teal's parser words it (`syntax error, expected ')'`, `expected an
245    /// expression`, `unexpected eof`), so this count, and not the text, is what says the
246    /// parser rejected the file.
247    pub syntax_errors: usize,
248    /// `file:line:col: message` for warnings (non-fatal).
249    pub warnings: Vec<String>,
250    /// Every file this check read through `require` (`.tl` / `.d.tl` / `.lua`): the
251    /// file's require closure, not only what it names itself. Sorted; the file itself is
252    /// not in it, even when a cycle leads back to it.
253    ///
254    /// The closure, because that is what the answer depends on. A check of `top.tl` that
255    /// requires `mid.tl` walks `mid.tl`, whose `require("host")` walks `host.d.tl`: the
256    /// globals `host.d.tl` declares are in scope in `top.tl`, and a record `mid.tl`
257    /// re-exports from it (`type Std = h.Std`) is `host.d.tl`'s record when `top.tl` reads
258    /// a field of it. Change `host.d.tl` and `top.tl` can report something else, though
259    /// `top.tl` never names it. Every reader of this list wants that answer — the cache
260    /// hashes it to decide whether a module's recorded result still holds (the direct
261    /// requires alone replayed `top.tl`'s old result over an edit to `host.d.tl`, #400),
262    /// [`link::Linked::inputs`] hands it to cargo as the files to watch, and `include_tl!`
263    /// tracks it for the same reason.
264    pub deps: Vec<PathBuf>,
265    /// For every member of [`deps`](Self::deps), the names that member required, as
266    /// `(member, name)`: the edges below the file, sorted by member, then name. A member's
267    /// names are its require sites — every `require("<literal>")` in it, resolved or not —
268    /// each once; a member whose result carries no AST gives the names that resolved. The
269    /// file's own requires are [`requires`](Self::requires), with their call sites.
270    ///
271    /// What the cache probes besides the hashes of `deps`. A hash says a file that was read
272    /// is unchanged; it cannot say that a name a member required still means that file. A
273    /// `mid.tl` appearing where `mid`'s own `require("host")` now finds it instead of
274    /// `host.d.tl` changes what `top.tl` sees exactly as an edit to `host.d.tl` does, and
275    /// every file the old entry hashed still matches. So an entry asks each of these names
276    /// again, from the member that asked it.
277    ///
278    /// The sites and not only the resolved names, because a name that resolved nowhere is a
279    /// question too. `mid.tl`'s `require("gone")` with no `gone.tl` leaves `mid`'s types
280    /// unknown in `top.tl`; write `gone.tl` and `mid.tl` misses on its own requires, but
281    /// `top.tl` hashes an unchanged `mid.tl`, and had the edge been left out it would replay
282    /// the errors it recorded while `gone` was missing (#410). A name that later resolves, or
283    /// resolves elsewhere, changes the answer to a question the entry asks.
284    pub closure_requires: Vec<(PathBuf, String)>,
285    /// htl lint findings (`nil-index`, `enum-exhaustive`). Advisory unless the caller
286    /// promotes them (`htl check --strict`, `include_tl!`).
287    pub lints: Vec<String>,
288    /// Every `require("<literal>")` in the file and where the checker resolved it.
289    /// Input to [`require_cycles`].
290    pub requires: Vec<RequireSite>,
291    /// `error_fixes[i]` is the fix for `errors[i]`, when the error has one.
292    pub error_fixes: Vec<Option<Fix>>,
293    /// `lint_fixes[i]` is the fix for `lints[i]`, when the lint has one.
294    pub lint_fixes: Vec<Option<Fix>>,
295    /// Type errors in the modules this check pulled in through `require`, transitively,
296    /// each dependency once. Not in `errors`, and not what [`ok`](Self::ok) answers: the
297    /// file itself checked, and generates; it is the `require` of that module that will
298    /// raise at run time ([`Htl::install_searcher`]), which is why a caller reporting on a
299    /// project treats these as errors too (`htl check`, `include_tl!`).
300    pub dependency_errors: Vec<DependencyError>,
301    /// [`errors`](Self::errors), [`warnings`](Self::warnings) and [`lints`](Self::lints)
302    /// as the checker produced them, in their parts: `error_items[i]` is `errors[i]`, its
303    /// fix attached. What [`diagnostics`](Self::diagnostics) hands out, so that no reader
304    /// takes the text apart to learn a position, a rule or which class of error it is.
305    pub error_items: Vec<Diagnostic>,
306    /// See [`error_items`](Self::error_items).
307    pub warning_items: Vec<Diagnostic>,
308    /// See [`error_items`](Self::error_items).
309    pub lint_items: Vec<Diagnostic>,
310    /// Every `global` declaration this check brought into scope, and where it is: the
311    /// file's own, and those of every module in its require closure. Input to
312    /// [`global_redeclarations`].
313    ///
314    /// The closure and not the file alone, for two reasons the lint would otherwise miss
315    /// the case it exists for. A `.d.tl` is never one of the files a directory check
316    /// walks, so a global declared there would appear on no check; and a run whose files
317    /// all replay from the cache builds no checker at all, so what a replayed check
318    /// carries is all the run has. Each site once per check; the lint dedups across
319    /// checks.
320    pub global_sites: Vec<GlobalSite>,
321    /// One entry per (marker, declaration) for htl's nine markers
322    /// ([`crate::adopt::FEATURES`]: `struct`, `optional`, `sealed`, `extensible`,
323    /// `nilable`, `contract`, `required`, `async`, `noyield`) this check found on a
324    /// declaration of the file, once each, ordered by line, then marker, then name, then
325    /// kind — not by [`crate::adopt::FEATURES`] order. What [`crate::adopt`] counts to say
326    /// how much of a project already writes a marker.
327    ///
328    /// Empty for a `.d.tl`: `htl dts` writes `---@async` / `---@noyield` into a
329    /// declaration itself, and this is a census of what the project's own authors wrote.
330    pub markers: Vec<MarkerSite>,
331    /// One entry per table literal this check found typed as a declared record and per
332    /// `as` cast to one — marked `---@struct` or `---@sealed` or neither, whole or not —
333    /// the input [`unmarked_structs`] and [`unmarked_sealeds`] group by declaration, and
334    /// `htl adopt`'s `---@struct` and `---@sealed` rows (#304) read the same way. An
335    /// inferred record (a bare `{ ... }` with no declaration anywhere) is not one of
336    /// these; see [`RecordSite::record_file`].
337    ///
338    /// Empty for a `.d.tl`, as [`CheckInfo::markers`] is: no literal or cast is built in
339    /// a declaration file either.
340    pub record_sites: Vec<RecordSite>,
341    /// The types and declarations of the file's names, by position: what an editor asks for
342    /// on hover and go-to-definition, and the tree of what the file declares for an outline
343    /// ([`typeindex`]). Empty unless the check was
344    /// [`Htl::check_indexed`], which is the only one that copies it out of the checker.
345    pub types: typeindex::TypeIndex,
346}
347
348/// One table literal or `as` cast a check found typed as a declared record (see
349/// [`CheckInfo::record_sites`]).
350#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
351pub struct RecordSite {
352    /// The declaring file, as the checker found it — a mod's literal names its SDK's
353    /// file here, not its own. Canonicalised where a caller compares it to another
354    /// file's spelling, the way [`global_redeclarations`] compares [`GlobalSite::file`].
355    pub record_file: String,
356    /// Line of the record's own declaration (`record Point`, or `type Point = record`),
357    /// in `record_file`.
358    pub record_line: usize,
359    /// The record's own name, as written on its declaration line.
360    pub record_name: String,
361    /// Whether the record carries `---@struct`, read from `record_file`'s own lines —
362    /// the same read [`crate`]'s `struct-fields` lint resolves a literal's spec from.
363    pub marked: bool,
364    /// Line of the site itself — the literal's or the `as` node's — in the file being
365    /// checked.
366    pub line: usize,
367    /// Column of the same.
368    pub col: usize,
369    /// `"literal"` for a table constructor, `"cast"` for an `as` expression — the two
370    /// ways a record is made, and the two [`crate`]'s `sealed-record` lint already
371    /// walks. [`unmarked_structs`] counts `"literal"` sites alone: a cast sets nothing,
372    /// so it is no evidence of what a construction site would set.
373    pub kind: String,
374    /// Whether the record carries `---@sealed`, with or without a function list, read
375    /// from `record_file`'s own lines — the same read [`crate`]'s `sealed-record` lint
376    /// resolves a site's spec from. [`unmarked_sealeds`] reads it to tell a record
377    /// already sealed apart from one free to be marked.
378    pub sealed: bool,
379    /// Whether this site sets every field the record's own body declares — the same
380    /// fields `struct-fields` would require if the record were marked, with no
381    /// `---@optional` exemption: a field that marker would exempt still has to be set
382    /// for this to be `true`. Always `false` for a `"cast"` site, which sets no field at
383    /// all; for a `"literal"` site, `false` also for a record whose body declares no
384    /// data field — nothing to set is not evidence that this literal, or any other, sets
385    /// everything.
386    pub complete: bool,
387}
388
389/// One marker the census found on a declaration (see [`CheckInfo::markers`]).
390#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
391pub struct MarkerSite {
392    /// The marker's name, without its `---@`: one of `struct`, `sealed`, `extensible`,
393    /// `contract`, `optional`, `required`, `nilable`, `async`, `noyield`.
394    pub marker: String,
395    /// What the marker is on: `"record"` for a record declaration, `"field"` for a record
396    /// field, `"function"` for a named function declaration.
397    pub kind: String,
398    /// Line of the declaration, counted from 1 — always the declaration's own line, never
399    /// the marker's: the marker itself is on that line (trailing) or on the line directly
400    /// above it (on a line of its own, the position `marker_on` reads), and either way
401    /// `line` is the declaration's.
402    pub line: usize,
403    /// The declaration's name: a type name (`Foo`, nested `Foo.Bar`) for a record, a
404    /// qualified field name (`Foo.field`) for a field, and a function's own name (`f`,
405    /// `M.f`, `M:f`) for a function.
406    pub name: String,
407}
408
409/// One `global` declaration a check saw (see [`CheckInfo::global_sites`]): the name and
410/// the site — file, line and column of the declared name — which is what tells two
411/// declarations of one name apart from one declaration seen through two requires.
412#[derive(Debug, Clone, PartialEq, Eq)]
413pub struct GlobalSite {
414    /// The declared name.
415    pub name: String,
416    /// The file declaring it, as the checker found it on the search path.
417    pub file: PathBuf,
418    /// Line of the declared name, counted from 1.
419    pub line: usize,
420    /// Byte-column of the same, counted from 1.
421    pub col: usize,
422}
423
424/// A type error in a module a check reached through `require` (see
425/// [`CheckInfo::dependency_errors`]).
426///
427/// The checker checks a required module into the same environment and hands the
428/// requirer its *type*; the module's own errors stay with the module's result. This is
429/// that result's error, said against the file that required it, so a report can name
430/// both — a dependency is only ever checked through a `require`, since its sources are
431/// not the project's to walk.
432#[derive(Debug, Clone, PartialEq, Eq)]
433pub struct DependencyError {
434    /// The file the error is in, as the checker found it on the search path.
435    pub file: PathBuf,
436    /// The file whose `require` (direct or through another dependency) pulled it in:
437    /// the first one on this check's walk.
438    pub required_by: PathBuf,
439    /// `file:line:col: message`, formatted as the file's own errors are.
440    pub text: String,
441    /// The same error in its parts, as the checker kept them: what a report reads rather
442    /// than the text.
443    pub diagnostic: Diagnostic,
444}
445
446/// How safely a [`Fix`] can be applied without a human looking at it.
447///
448/// Serializes as its [`as_str`](Applicability::as_str) name, which is what a stored fix
449/// and `--format json` both carry.
450#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
451#[serde(rename_all = "lowercase")]
452pub enum Applicability {
453    /// The rewrite does not change what the program does at run time.
454    Safe,
455    /// It may; applied only when asked (`htl fix --unsafe`).
456    Unsafe,
457    /// Shown, never applied (a placeholder to fill, a choice to make).
458    Suggest,
459}
460
461impl Applicability {
462    /// The lowercase word this is stored and printed as — the one spelling that crosses
463    /// between a run, `--format json`, and the cached fix a later run reads back.
464    pub fn as_str(self) -> &'static str {
465        match self {
466            Applicability::Safe => "safe",
467            Applicability::Unsafe => "unsafe",
468            Applicability::Suggest => "suggest",
469        }
470    }
471}
472
473/// One text replacement: `[start, end)` in 1-based line / byte-column coordinates;
474/// an insertion has `end == start`.
475#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
476pub struct Edit {
477    /// First line of the range to replace, counted from 1.
478    pub line: usize,
479    /// First byte-column, counted from 1. Bytes rather than characters, because that is
480    /// what the checker reports and what an applier slices with.
481    pub col: usize,
482    /// Line the range ends on. Equal to [`line`](Self::line) for an edit within one line.
483    pub end_line: usize,
484    /// Byte-column the range ends at, exclusive — so the character at `end_col` survives.
485    /// Equal to [`col`](Self::col) for an insertion, which replaces nothing.
486    pub end_col: usize,
487    /// What goes in the range's place. Empty deletes it.
488    pub text: String,
489}
490
491/// A mechanical rewrite attached to a diagnostic (see [`fix`]).
492///
493/// Serializes as [`cache::FixJson`] does, since the two describe the same thing and the
494/// store reads back what `--format json` prints.
495#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
496pub struct Fix {
497    /// Whether `htl fix` may apply this without being asked twice.
498    pub applicability: Applicability,
499    /// The rewrite, as one or more replacements. A fix is all of them or none: they are
500    /// applied together, because a rewrite that lands half-way is worse than one that did
501    /// not land.
502    pub edits: Vec<Edit>,
503}
504
505/// One literal `require` call in a checked file.
506#[derive(Debug, Clone)]
507pub struct RequireSite {
508    /// The name as the call spells it, before any separator or entry mapping.
509    pub module: String,
510    /// Resolved file, `None` when the checker could not find it.
511    pub path: Option<PathBuf>,
512    /// Line of the `require` call, counted from 1.
513    pub line: usize,
514    /// Byte-column of the call, counted from 1.
515    pub col: usize,
516    /// The call is the value of a `local type` declaration the generator erases, so no
517    /// `require` of the name is in the generated Lua: a dependency of the check — the
518    /// declaration is read, and `htl unused` counts it reached — and of nothing that runs,
519    /// so the linker bundles nothing for it and asks the host for nothing. The flag is the
520    /// generator's own (`elide_type`, set by the checker from how the alias is used): a
521    /// `local type` alias also read as a value keeps its `require`, and is not erased.
522    pub erased: bool,
523}
524
525/// A named function of a `.tl` file, for coverage (see [`Htl::coverage_spans`]).
526///
527/// The body is `line + 1 ..= last - 1`, strictly between the two: defining a function
528/// runs both ends of it, so neither says whether the function was ever entered. A
529/// never-called `function m.f()` spanning lines 12..15 comes back from the line hook
530/// with 12 and 15 executed and 13, 14 not. Functions with nothing in between (one
531/// line, or an empty body) have no such span and are not reported at all.
532#[derive(Debug, Clone)]
533pub struct FunctionSpan {
534    /// As the source writes it: `f`, `M.f`, `M:f`.
535    pub name: String,
536    /// The line the function is declared on.
537    pub line: usize,
538    /// The line its `end` is on. Always at least `line + 2`.
539    pub last: usize,
540}
541
542/// What one parse gives a coverage report: the statement ranges, and the functions
543/// those ranges sit in. See [`Htl::coverage_spans`].
544pub type CoverageSpans = (Vec<(usize, usize)>, Vec<FunctionSpan>);
545
546/// What a file on the search path is, for [`Htl::module_candidates`]. The three the
547/// searchers try, in the order they try them: a `.tl` source beats a `.d.tl` declaration
548/// wherever the two sit, and a plain `.lua` is what is left when neither is reachable.
549#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
550#[serde(rename_all = "lowercase")]
551pub enum ModuleKind {
552    /// A `.tl` the checker compiles and the program runs — the only kind that is both.
553    Source,
554    /// A `.d.tl`: types with no implementation. What a `require` of one gets at run time
555    /// when nothing implements the name depends on the resolver, and under
556    /// [`Htl::install_searcher`] on the caller:
557    ///
558    /// - [`Htl::install_searcher`], a `require` written in Teal (the calling chunk's
559    ///   source ends in `.tl`): an empty table that explains itself when indexed, which is
560    ///   why a checked module that resolves to a declaration and nothing else loads and
561    ///   then fails on first use. The checker typed it against the declaration; a module
562    ///   that calls its host in one function runs, and is tested, without the host.
563    /// - [`Htl::install_searcher`], a `require` from plain Lua (any other chunk, through
564    ///   `pcall` or not): the `require` fails naming the declaration, so
565    ///   `pcall(require, name)` is `false`. A `.lua` sees no declaration.
566    ///
567    ///   The table is never stored in `package.loaded`, where `require` would answer every
568    ///   later caller with it and a `.lua` asking after a `.tl` would find the module there.
569    ///   A metatable on `package.loaded` keeps it in a side table instead, keyed by name,
570    ///   and hands it back only to a read from Teal: a second Teal `require` gets the same
571    ///   table, a later `.lua` is still declined, and `rawget(package.loaded, name)` is
572    ///   `nil`. A real module stored under the name afterwards (a `preload_value` a Teal
573    ///   `require` then loads, a host's own assignment) replaces it for every caller. A
574    ///   `package.loaded` that already carries a metatable when the searcher is installed is
575    ///   the host's and is left alone; there the first caller's answer is every later
576    ///   caller's, as before this rule (the `pkg` module doc).
577    /// - a `pkg::TealResolver` in a `Registry`, any caller: the declaration steps aside and
578    ///   the `require` fails outright, with the same text, if nothing else implements the
579    ///   name.
580    Declaration,
581    /// A plain `.lua`, which the checker has nothing to say about. What is left when
582    /// neither of the other two is reachable.
583    Lua,
584}
585
586impl ModuleKind {
587    fn of(s: &str) -> Self {
588        match s {
589            "source" => Self::Source,
590            "declaration" => Self::Declaration,
591            _ => Self::Lua,
592        }
593    }
594
595    /// As a report says it.
596    pub fn as_str(self) -> &'static str {
597        match self {
598            Self::Source => "source",
599            Self::Declaration => "declaration",
600            Self::Lua => "lua",
601        }
602    }
603}
604
605impl std::fmt::Display for ModuleKind {
606    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
607        f.write_str(self.as_str())
608    }
609}
610
611/// What the project model says about a name that may run from no file of the project
612/// ([`Htl::model_provides`]).
613#[derive(Debug, Clone, PartialEq, Eq)]
614pub enum Provision {
615    /// The model has nothing to say: none is installed, or it has nothing under the name.
616    Unknown,
617    /// The model answers the name, and not as provided: a file of the project is what
618    /// runs for it — an implementation, or the `.lua` a declaration types — or two files
619    /// claim it and no order picks one.
620    Files,
621    /// Nothing of the project runs for the name, and this is who provides it, as the
622    /// model's `Provider` tags it: `host_module`, `build` and `std` for the host,
623    /// `declared` for the environment — a name the model has only a declaration for.
624    Provided(String),
625}
626
627/// One file `require(name)` could have resolved to. See [`Htl::module_candidates`].
628#[derive(Debug, Clone, PartialEq, Eq)]
629pub struct ModuleCandidate {
630    /// The file itself.
631    pub path: PathBuf,
632    /// Which of the three it is, which is what decides whether it wins over the ones
633    /// found after it.
634    pub kind: ModuleKind,
635    /// The search-path directory it was found under.
636    pub dir: PathBuf,
637}
638
639/// Result of a static contract check (see [`Htl::contract_check`]).
640#[derive(Debug, Clone, Default)]
641pub struct ContractResult {
642    /// Type errors from `local m: <T> = require("<mod>")`: each the checker's sentence
643    /// alone, without the position in the stub it was checked through, which says nothing
644    /// about the module.
645    pub errors: Vec<String>,
646    /// Declared fields absent from the module's returned table literal; `None` when the
647    /// return value is not a literal (not decidable statically).
648    pub missing: Option<Vec<String>>,
649    /// Line and column of the returned table literal, for the report about
650    /// [`missing`](Self::missing) to point at. `(1, 1)` when the checker gave no position,
651    /// so a message always has somewhere to point rather than none.
652    pub missing_at: (usize, usize),
653    /// Names `require_fields` asked for that the contract type does not declare. The
654    /// config is wrong about the type, which is a different finding from a module that
655    /// fails the contract, and no module can fix it.
656    pub bad_require_fields: Vec<String>,
657}
658
659impl Htl {
660    /// Make an `htl.toml` project's dirs visible to the checker: `root`, `root/src` and
661    /// `[check] paths`. `root` is the directory holding `htl.toml`.
662    ///
663    /// These go on `package.path` ([`search_paths`](config::HtlConfig::search_paths)),
664    /// which is read through Lua's templates rather than the naming rule every `htl`
665    /// command names files by. `types/` and each `types/<crate>/` are two roots there, so
666    /// a crate's `types/htl-mq/mq.d.tl` checks as `mq` and as `htl-mq.mq` — where `htl
667    /// check` and a model-derived resolver know it only as `mq` (#320).
668    ///
669    /// Kept for a host that does not describe a project. One that does sets its checker up
670    /// with `Htl::apply_model` (feature `dts`) on the project `htl` itself reads
671    /// (`model::Project::discover`, or `Project::for_host` for a host with no `htl.toml`)
672    /// and serves the run from the same project (`pkg::TealResolver::from_project`), so the
673    /// check and the run are one description rather than two kept in step by hand.
674    pub fn apply_config(&self, root: &Path, cfg: &config::HtlConfig) -> Result<()> {
675        self.add_search_paths(&cfg.search_paths(root))
676    }
677
678    /// Put `dirs` on the search path so they are consulted **in the order given** — the
679    /// order [`search_paths`](config::HtlConfig::search_paths) documents, and the one a
680    /// reader assumes from a list. [`add_path`](Self::add_path) prepends, so adding the
681    /// list front to back would leave its last entry first; this adds it back to front.
682    ///
683    /// It decides one thing: which of two declarations of the same module is read. A
684    /// `.tl` source beats a `.d.tl` wherever the two sit, so until neither is a source
685    /// the order is invisible.
686    ///
687    /// The order stated here stands: a directory already on the path is not moved by a
688    /// later [`add_path`](Self::add_path), nor by a [`TealResolver`](pkg::TealResolver)
689    /// putting its root there on its first resolve. A host that chains a resolver per
690    /// directory tier says this once, before the first `require`.
691    pub fn add_search_paths(&self, dirs: &[PathBuf]) -> Result<()> {
692        for p in dirs.iter().rev() {
693            self.add_path(p)?;
694        }
695        Ok(())
696    }
697
698    /// Static form of `TealResolver::expect_type` / `require_fields` for one module file:
699    /// `modname` is what a `require` would say (its stem), `type_path` is `"defs.Mod"`.
700    pub fn contract_check(
701        &self,
702        file: &Path,
703        modname: &str,
704        type_path: &str,
705        require_fields: &config::RequireFields,
706    ) -> Result<ContractResult> {
707        // `true` for "everything the type declares", the list itself when it names them —
708        // as a `Vec`, which the call converts in the checker's state, not as a table made in
709        // `self.lua()`, which a split state's checker could not take.
710        let wanted = match require_fields.named() {
711            Some(names) => mlua::Either::Right(names.to_vec()),
712            None => mlua::Either::Left(require_fields.is_on()),
713        };
714        let t: Table = self.checker_call(
715            "contract_check",
716            (path_str(file), modname, type_path, wanted),
717        )?;
718        let errors: Table = t.get("errors")?;
719        let errors = errors
720            .sequence_values::<String>()
721            .collect::<mlua::Result<_>>()?;
722        let missing = match t.get::<Option<Table>>("missing")? {
723            Some(m) => Some(
724                m.sequence_values::<String>()
725                    .collect::<mlua::Result<Vec<_>>>()?,
726            ),
727            None => None,
728        };
729        let missing_at = (
730            t.get::<Option<usize>>("missing_y")?.unwrap_or(1),
731            t.get::<Option<usize>>("missing_x")?.unwrap_or(1),
732        );
733        let bad_require_fields = match t.get::<Option<Table>>("bad_require_fields")? {
734            Some(b) => b
735                .sequence_values::<String>()
736                .collect::<mlua::Result<Vec<_>>>()?,
737            None => Vec::new(),
738        };
739        Ok(ContractResult {
740            errors,
741            missing,
742            missing_at,
743            bad_require_fields,
744        })
745    }
746}
747
748/// `contract` lint for one file: when a directory a contract holds serves `file` as a
749/// module ([`contract::held_name`]: anywhere under it, by the name `require` writes —
750/// `foo` for `foo/init.tl`, `sub.x` for `sub/x.tl`), check it against that contract
751/// statically, as the host's resolver for the directory holds it at run time. `root` is
752/// the directory holding `htl.toml`. Returns lint lines (empty when none applies).
753///
754/// `contracts` comes from [`contract::resolve`], which reads the `---@contract` markers;
755/// resolving once per run rather than once per file is the caller's job.
756pub fn contract_lints(
757    h: &Htl,
758    root: &Path,
759    cfg: &config::HtlConfig,
760    contracts: &[contract::Resolved],
761    file: &Path,
762) -> Result<Vec<Diagnostic>> {
763    let canon = |p: &Path| std::fs::canonicalize(p).unwrap_or_else(|_| p.to_path_buf());
764    let file_abs = canon(file);
765    let mut out = Vec::new();
766    if !is_tl_source(&file_abs) {
767        return Ok(out);
768    }
769    for c in contracts {
770        let Some((dir, modname)) = c
771            .dirs(root)
772            .into_iter()
773            .map(|d| canon(&d))
774            .find_map(|d| contract::held_name(&d, &file_abs).map(|n| (d, n)))
775        else {
776            continue;
777        };
778        if !c.applies_to(&modname) {
779            continue;
780        }
781        // Same visibility as `TealResolver::for_contract`: the contract dir, plus what
782        // `HtlConfig::search_paths` gives (the project root, its `src/` and `types/`,
783        // then `[check] paths`). Both sides go through that one function.
784        h.add_path(&dir)?;
785        h.apply_config(root, cfg)?;
786        let r = h.contract_check(&file_abs, &modname, &c.type_path, &c.require_fields)?;
787        if !r.bad_require_fields.is_empty() {
788            // A `---@required` the checker cannot see as a field of the record: the
789            // marker is on something else, and no module under the dir can satisfy it.
790            out.push(Diagnostic::new(
791                Severity::Lint,
792                c.declared_in.display().to_string(),
793                c.declared_at,
794                1,
795                format!(
796                    "---@required on field(s) {} does not declare: {}",
797                    c.type_path,
798                    r.bad_require_fields.join(", ")
799                ),
800                Some("contract"),
801            ));
802            continue;
803        }
804        for msg in &r.errors {
805            let msg = msg.trim();
806            out.push(Diagnostic::new(
807                Severity::Lint,
808                file.display().to_string(),
809                1,
810                1,
811                format!(
812                    "does not satisfy contract {} ({}): {msg}",
813                    c.type_path, c.dir
814                ),
815                Some("contract"),
816            ));
817        }
818        if let Some(missing) = &r.missing
819            && !missing.is_empty()
820        {
821            out.push(Diagnostic::new(
822                Severity::Lint,
823                file.display().to_string(),
824                r.missing_at.0,
825                r.missing_at.1,
826                format!(
827                    "returned table lacks declared field(s) of {}: {}",
828                    c.type_path,
829                    missing.join(", ")
830                ),
831                Some("contract"),
832            ));
833        }
834    }
835    Ok(out)
836}
837
838/// `duplicate-declaration` lint: a module `file` requires resolved to a `.d.tl` while
839/// another `.d.tl` for the same module was reachable further along the search path. One
840/// was read and the other was not, decided by position, and until now nothing said so —
841/// the case this catches is a host publishing a declaration into a project that also
842/// keeps a hand-written one for the same module.
843///
844/// Only declarations collide. A `.tl` source beats every `.d.tl` wherever the two sit
845/// (`prelude.lua` searches sources across the whole path first), so a require that
846/// landed on a source is not reported, and neither is a module declared once.
847///
848/// A require that landed on a source is where the other lint here lives.
849/// `host-module-shadowed`: `host_modules` are the names the surrounding crate registers
850/// in `package.preload` (from `#[host_module]`, scanned without a build), and Lua
851/// consults preload before any path searcher. So when a require of one of those names
852/// resolved to a file, the check read the file and the run will load the host: what was
853/// checked is not what runs, and the program fails at the first call of anything the two
854/// do not share. Both halves of that are already in hand at this point — the name the
855/// host registers, and the path the checker read — which is why it is asked here.
856///
857/// A require of a host module name that landed on a `.d.tl` is not reported: a
858/// declaration is how a host module is given types at all, and `htl dts` writes exactly
859/// that file, so the two agree by construction.
860///
861/// In a project this lint has nothing left to say, and says nothing. The model knows the
862/// names the host provides (`model::Project::provides`), and its resolver answers a name
863/// a file of the project implements as well with
864/// `model::Resolution::HostShadowed`: an error at the
865/// `require`, in the check and at run time, and a search that yields the name's
866/// declaration or nothing — never the file. So the require this lint looks for, one of a
867/// host module name that landed on a file, does not occur, and the error is what reports
868/// the state. The lint stays for a file in no project, which has no model: there
869/// `host_modules` is the scan of the crate around the file, and a warning is all that
870/// scan can back. The rule stays registered either way, since configs name it.
871///
872/// Call it with the search path the file was checked under: the answer depends on it.
873pub fn declaration_conflict_lints(
874    h: &Htl,
875    file: &Path,
876    info: &CheckInfo,
877    host_modules: &[String],
878) -> Result<Vec<Diagnostic>> {
879    let mut out = Vec::new();
880    let mut seen: Vec<&str> = Vec::new();
881    for site in &info.requires {
882        let Some(read) = site.path.as_ref() else {
883            continue;
884        };
885        // One report per module, not one per `require` of it.
886        if seen.contains(&site.module.as_str()) {
887            continue;
888        }
889        if !is_declaration(read) {
890            if host_modules.contains(&site.module) {
891                seen.push(&site.module);
892                out.push(Diagnostic::new(
893                    Severity::Lint,
894                    file.display().to_string(),
895                    site.line,
896                    site.col,
897                    format!(
898                        "{} is a host module of this crate and also {}: the check reads the \
899                         file, the run loads the host — package.preload is consulted before \
900                         any path searcher, so what is checked here is not what runs",
901                        site.module,
902                        read.display(),
903                    ),
904                    Some("host-module-shadowed"),
905                ));
906            }
907            continue;
908        }
909        let sites: Vec<String> = h
910            .checker_call::<Table>("declaration_sites", site.module.as_str())?
911            .sequence_values::<String>()
912            .collect::<mlua::Result<_>>()?;
913        let shadowed: Vec<&str> = sites
914            .iter()
915            .map(|s| s.as_str())
916            .filter(|s| !same_file(Path::new(s), read))
917            .collect();
918        if shadowed.is_empty() {
919            continue;
920        }
921        seen.push(&site.module);
922        out.push(Diagnostic::new(
923            Severity::Lint,
924            file.display().to_string(),
925            site.line,
926            site.col,
927            format!(
928                "{} is declared more than once: {} is read, {} {} not",
929                site.module,
930                read.display(),
931                shadowed.join(" and "),
932                if shadowed.len() == 1 { "is" } else { "are" },
933            ),
934            Some("duplicate-declaration"),
935        ));
936    }
937    Ok(out)
938}
939
940/// `contract-unenforced` lint: a contract only becomes a run-time guarantee when the
941/// host builds its resolver from it. Scan the host crate's Rust sources — `src/`,
942/// `examples/`, `tests/` and `benches/` under `cargo_root`, a directory that is absent
943/// skipped — for `contract_resolvers(`. No host crate (`cargo_root` = None) means a
944/// script-only project: nothing to enforce.
945///
946/// One call to look for, not four. `contract_resolvers(root, &config)` is the documented
947/// way and what keeps the host and `htl check` reading the same markers; a resolver
948/// assembled by hand from `expect_type` / `require_fields` now has to restate what the
949/// record already says, so recognising it would be recognising the drift this lint
950/// exists to prevent. Enforcement the scan cannot see at all — a Lua-side validator, a
951/// resolver in a sibling crate, generated code, or a resolver built by hand — is what
952/// `[[contract]] enforced_by` is for: it names the file the enforcement lives in, and
953/// that contract is then not held to the scan. The file has to exist, which is what
954/// separates the key from a per-contract off switch, and a name that points at nothing is
955/// reported under this same rule whether or not the call was found.
956pub fn contract_enforcement_lints(
957    cfg_path: &Path,
958    contracts: &[contract::Resolved],
959    cargo_root: Option<&Path>,
960) -> Vec<Diagnostic> {
961    let mut out = Vec::new();
962    if contracts.is_empty() {
963        return out;
964    }
965    let Some(root) = cargo_root else { return out };
966    let mut sources = String::new();
967    for sub in ["src", "examples", "tests", "benches"] {
968        let dir = root.join(sub);
969        if !dir.is_dir() {
970            continue;
971        }
972        for e in walkdir::WalkDir::new(&dir).into_iter().flatten() {
973            let p = e.path();
974            if p.is_file()
975                && p.extension().and_then(|s| s.to_str()) == Some("rs")
976                && let Ok(t) = std::fs::read_to_string(p)
977            {
978                sources.push_str(&t);
979                sources.push('\n');
980            }
981        }
982    }
983    let by_config = sources.contains("contract_resolvers(");
984    for c in contracts {
985        // A contract with nothing under it is not enforced by anyone; the dir may be
986        // populated later (glob dirs especially), so say nothing about the host.
987        if c.dirs(root_of(cfg_path)).is_empty() {
988            continue;
989        }
990        match &c.enforced_by {
991            // The path is the whole of what makes `enforced_by` a claim rather than an
992            // off switch, so it is checked whether or not the scan found the call: a name
993            // that points at nothing is a broken statement either way.
994            Some(p) => {
995                let at = config::resolve_path(root_of(cfg_path), p);
996                if !at.exists() {
997                    out.push(Diagnostic::new(
998                        Severity::Lint,
999                        cfg_path.display().to_string(),
1000                        1,
1001                        1,
1002                        format!(
1003                            "contract {} -> {} says it is enforced by {:?}, and there is no \
1004                             such file: name where the enforcement lives, or drop the key and \
1005                             let the scan look for htl::pkg::contract_resolvers(root, &config)",
1006                            c.dir, c.type_path, p,
1007                        ),
1008                        Some("contract-unenforced"),
1009                    ));
1010                }
1011            }
1012            None if !by_config => out.push(Diagnostic::new(
1013                Severity::Lint,
1014                c.declared_in.display().to_string(),
1015                c.declared_at,
1016                1,
1017                format!(
1018                    "contract {} -> {} is declared but the host does not enforce it: build \
1019                     resolvers with htl::pkg::contract_resolvers(root, &config), or say where \
1020                     it is enforced with [[contract]] enforced_by",
1021                    c.dir, c.type_path,
1022                ),
1023                Some("contract-unenforced"),
1024            )),
1025            None => {}
1026        }
1027    }
1028    out
1029}
1030
1031fn root_of(cfg_path: &Path) -> &Path {
1032    cfg_path.parent().unwrap_or(Path::new("."))
1033}
1034
1035/// One global name declared at two sites among what a set of checked files brought into
1036/// scope, one message per name, anchored at the later site (files sorted, then line and
1037/// column) and naming the earlier one. The checker keeps the first declaration it walks
1038/// and, when the second has the same type, says nothing (`add_global` in the vendored
1039/// compiler returns without a word), so two `.d.tl` that both declare a name were read
1040/// as one and nobody was told — the gap `duplicate-declaration` closes for two
1041/// declarations of one *module*, closed here for one *global*.
1042///
1043/// A second declaration of a different type is reported the same way, and on purpose.
1044/// The checker has an error for it, `cannot redeclare global with a different type`, but
1045/// it raises that only in an environment that walks both declarations; each file is
1046/// checked in an environment of its own, handed the globals of what it requires from the
1047/// store, so two files that require one declaration each are typed against two ideas of
1048/// the name and the checker never sees them meet. Whether the error appears depends on
1049/// the order the files were walked in; this does not, which is why it is not suppressed
1050/// when the error is there too.
1051///
1052/// Sites come from [`CheckInfo::global_sites`], each check's require closure, so a
1053/// declaration in a `.d.tl` (never a walked file) and a run replayed from the cache
1054/// (never a walk) both count; a site seen through several checks is one site.
1055pub fn global_redeclarations(infos: &[(PathBuf, CheckInfo)]) -> Vec<Diagnostic> {
1056    use std::collections::BTreeMap;
1057    let canon = |p: &Path| std::fs::canonicalize(p).unwrap_or_else(|_| p.to_path_buf());
1058    // name -> sites, each (canonical file, line, col) once, in the order the key sorts.
1059    let mut by_name: BTreeMap<&str, BTreeMap<(PathBuf, usize, usize), &GlobalSite>> =
1060        BTreeMap::new();
1061    for (_, ci) in infos {
1062        for s in &ci.global_sites {
1063            by_name
1064                .entry(s.name.as_str())
1065                .or_default()
1066                .entry((canon(&s.file), s.line, s.col))
1067                .or_insert(s);
1068        }
1069    }
1070    let mut out = Vec::new();
1071    for (name, sites) in by_name {
1072        if sites.len() < 2 {
1073            continue;
1074        }
1075        let mut it = sites.values();
1076        let first = it.next().unwrap();
1077        let second = it.next().unwrap();
1078        let more = sites.len() - 2;
1079        let also = if more == 0 {
1080            String::new()
1081        } else {
1082            format!(" and at {more} more")
1083        };
1084        out.push(Diagnostic::new(
1085            Severity::Lint,
1086            second.file.display().to_string(),
1087            second.line,
1088            second.col,
1089            format!(
1090                "global {name} is also declared at {}:{}:{}{also}; the checker keeps the \
1091                 first declaration it walks and says nothing about the second, so the two \
1092                 have to agree by hand (declare it in one module and require that from \
1093                 both)",
1094                crate::diagnostic::display_path(&first.file),
1095                first.line,
1096                first.col
1097            ),
1098            Some("global-redeclaration"),
1099        ));
1100    }
1101    out
1102}
1103
1104/// One record [`unmarked_structs`] found a candidate for `---@struct` (#304).
1105#[derive(Debug, Clone, PartialEq, Eq)]
1106pub struct UnmarkedStruct {
1107    /// The record's declaring file, as the walk that found it spelled it — not
1108    /// canonicalised, so a caller reports the path the project's own files use.
1109    pub file: PathBuf,
1110    /// Line of the record's own declaration.
1111    pub line: usize,
1112    /// The record's own name.
1113    pub name: String,
1114    /// How many construction sites the group has, every one of them already setting
1115    /// every field the record's own body declares — what made the record a candidate.
1116    pub sites: usize,
1117}
1118
1119/// One record [`unmarked_sealeds`] found a candidate for `---@sealed` (#304).
1120#[derive(Debug, Clone, PartialEq, Eq)]
1121pub struct UnmarkedSealed {
1122    /// The record's declaring file, as the walk that found it spelled it — not
1123    /// canonicalised, so a caller reports the path the project's own files use.
1124    pub file: PathBuf,
1125    /// Line of the record's own declaration.
1126    pub line: usize,
1127    /// The record's own name.
1128    pub name: String,
1129    /// How many sites the group has, literal and cast together, every one of them in
1130    /// the record's own declaring file — what made the record a candidate.
1131    pub sites: usize,
1132}
1133
1134/// One record's [`RecordSite`]s, grouped by `(canonicalised record_file, record_line)`
1135/// — the same two-part key [`global_redeclarations`] groups a global's sites by and for
1136/// the same reason: two spellings of one path are one record, and the line is what
1137/// tells two records of one file apart. Shared by [`unmarked_structs`] and
1138/// [`unmarked_sealeds`], whose four conditions each differ only in which of these
1139/// fields they read and what they ask of them.
1140struct RecordGroup {
1141    /// The record's file as the walk itself spelled it — whichever `checked` path
1142    /// canonicalises to the group's key — not the canonical form, so a caller reports a
1143    /// path that exists in the project's own tree.
1144    file: PathBuf,
1145    /// Line of the record's own declaration, in `file`.
1146    line: usize,
1147    /// The record's own name.
1148    name: String,
1149    /// How many sites of `checked`'s own passed `want` (below) and belong to this
1150    /// record.
1151    sites: usize,
1152    /// Whether every one of those sites is [`complete`](RecordSite::complete) — read
1153    /// by [`unmarked_structs`] alone; always `true` for a group no site of which `want`
1154    /// let through un-complete.
1155    every_site_complete: bool,
1156    /// Whether every one of those sites sits in the file that declares the record — the
1157    /// first element of the `checked` pair the site came from, not
1158    /// [`RecordSite::record_file`], which is the *site's* resolution of the declaring
1159    /// file and not necessarily the file being walked when the site was found. Read by
1160    /// [`unmarked_sealeds`] alone.
1161    every_site_here: bool,
1162    /// Whether the record carries `---@struct` ([`RecordSite::marked`]) — the same
1163    /// value at every site of one record, since it is read from the declaration once;
1164    /// kept from whichever site reached this group first. Read by [`unmarked_structs`]
1165    /// alone.
1166    marked: bool,
1167    /// Whether the record carries `---@sealed` ([`RecordSite::sealed`]), the same way
1168    /// `marked` is. Read by [`unmarked_sealeds`] alone.
1169    sealed: bool,
1170}
1171
1172/// [`RecordSite`]s of `checked` that pass `want`, grouped into a [`RecordGroup`] per
1173/// record and restricted to records declared in `declared_in` — condition 4 of both
1174/// [`unmarked_structs`] and [`unmarked_sealeds`], which is why it lives here rather
1175/// than in either: a record declared in a dependency's `.d.tl`, a patched dependency's
1176/// own copy, or a file named outright that no module claims, is not the project's to
1177/// mark, whichever marker is in question.
1178///
1179/// `declared_in` is canonical paths, compared as-is — the caller's to canonicalise, so
1180/// that two callers building it two different ways (the project's own module set, a
1181/// walk's own file list) still agree on what "the same path" means without this
1182/// function making that choice for them. `checked` is one entry per file the walk
1183/// *read sites from* — wider than `declared_in` can be, and has to be: a patched
1184/// dependency casting a project's own record, or a stray file doing the same, still
1185/// counts against that record's conditions 2 and 3 even though the dependency's or the
1186/// stray file's *own* records are not candidates (`checked` feeds sites, `declared_in`
1187/// gates candidacy, and the two are deliberately different questions). Paired with the
1188/// construction- and cast-site census found in each file ([`CheckInfo::record_sites`]
1189/// for each lint's own call; `htl adopt` (`crate::adopt::adopt`) pairs its own checked
1190/// files with the same census read back through the cache, [`cache::RecordSiteJson`],
1191/// so every caller shares this one grouping rather than each walking it again).
1192fn grouped_record_sites(
1193    checked: &[(PathBuf, Vec<RecordSite>)],
1194    declared_in: &std::collections::HashSet<PathBuf>,
1195    want: impl Fn(&RecordSite) -> bool,
1196) -> Vec<RecordGroup> {
1197    use std::collections::{BTreeMap, HashMap};
1198    let canon = |p: &Path| std::fs::canonicalize(p).unwrap_or_else(|_| p.to_path_buf());
1199    // Canonical -> the path as `checked` itself spells it (the walk's own spelling of
1200    // the file it checked), not a site's: `RecordSite::record_file` is a *requirer's*
1201    // resolution of the declaring file, read off `t.file` in whichever file built or
1202    // cast the site, and two requirers can spell the same declaring file two different
1203    // ways (`./src/geom.tl` from one directory, an absolute path from another, the
1204    // declaring file's own check spelling itself a third). Reading the file's own entry
1205    // in `checked` instead is what keeps every record of one file sorting together
1206    // under one spelling, rather than under whichever site happened to be seen first.
1207    // Whenever a canonical file is also in `declared_in` (condition 4, below), every
1208    // caller keeps `declared_in` a subset of `checked`'s own files, so this map always
1209    // has an entry to report the candidate's path from.
1210    let walked: HashMap<PathBuf, PathBuf> =
1211        checked.iter().map(|(f, _)| (canon(f), f.clone())).collect();
1212
1213    struct Acc {
1214        name: String,
1215        sites: usize,
1216        every_site_complete: bool,
1217        every_site_here: bool,
1218        marked: bool,
1219        sealed: bool,
1220    }
1221    let mut by_record: BTreeMap<(PathBuf, usize), Acc> = BTreeMap::new();
1222    for (container, sites) in checked {
1223        let container_canon = canon(container);
1224        for s in sites {
1225            if !want(s) {
1226                continue;
1227            }
1228            let record_canon = canon(Path::new(&s.record_file));
1229            let key = (record_canon.clone(), s.record_line);
1230            let c = by_record.entry(key).or_insert_with(|| Acc {
1231                name: s.record_name.clone(),
1232                sites: 0,
1233                every_site_complete: true,
1234                every_site_here: true,
1235                marked: s.marked,
1236                sealed: s.sealed,
1237            });
1238            // Always at least 1 here: a group exists in `by_record` only because this
1239            // loop just inserted or found an entry for a site that reached it.
1240            c.sites += 1;
1241            c.every_site_complete = c.every_site_complete && s.complete;
1242            c.every_site_here = c.every_site_here && container_canon == record_canon;
1243        }
1244    }
1245    let mut out = Vec::new();
1246    for ((canon_file, line), c) in by_record {
1247        // Condition 4, for both callers: the record's own file is one a candidate may
1248        // be declared in -- not merely one the walk read a site from, which `checked`
1249        // alone would ask (a patched dependency's or a stray file's own records are
1250        // not the project's to mark, however many project sites they hold).
1251        if !declared_in.contains(&canon_file) {
1252            continue;
1253        }
1254        let Some(file) = walked.get(&canon_file) else {
1255            continue;
1256        };
1257        out.push(RecordGroup {
1258            file: file.clone(),
1259            line,
1260            name: c.name,
1261            sites: c.sites,
1262            every_site_complete: c.every_site_complete,
1263            every_site_here: c.every_site_here,
1264            marked: c.marked,
1265            sealed: c.sealed,
1266        });
1267    }
1268    out
1269}
1270
1271/// A record declared among the project's own files, built whole at every one of its
1272/// construction sites, and left unmarked (#304; `htl adopt`'s `---@struct` row reads
1273/// the same list). A record is a candidate when all four hold:
1274///
1275/// 1. it is not marked `---@struct` ([`RecordSite::marked`]);
1276/// 2. it has at least one construction site — a record nobody builds says nothing
1277///    about itself, marked or not;
1278/// 3. every site of it is [`complete`](RecordSite::complete) — a record built short at
1279///    even one site is the open question `struct-fields` already answers once the
1280///    record carries the marker, not evidence either way for this rule;
1281/// 4. the record's own file is one of `declared_in` ([`RecordSite::record_file`],
1282///    canonicalised) — a record declared in a dependency's `.d.tl`, a patched
1283///    dependency's own copy, or a file named outright that no module claims, is not
1284///    the project's to mark, however many of the project's own sites it holds (which
1285///    still count toward conditions 2 and 3: `checked`, not `declared_in`, is where
1286///    sites come from).
1287///
1288/// Grouped by `grouped_record_sites`, restricted to `kind == "literal"` sites: a
1289/// cast sets nothing, so a record built nowhere and only cast has no construction
1290/// site, and a cast counted here would make condition 3 true of a record no literal
1291/// ever set a field of. Ordered by `(file, line)`.
1292pub fn unmarked_structs(
1293    checked: &[(PathBuf, Vec<RecordSite>)],
1294    declared_in: &std::collections::HashSet<PathBuf>,
1295) -> Vec<UnmarkedStruct> {
1296    let mut out: Vec<UnmarkedStruct> =
1297        grouped_record_sites(checked, declared_in, |s| s.kind == "literal")
1298            .into_iter()
1299            // Conditions 1-3: not marked, and (inherently, from `grouped_record_sites`'s
1300            // own loop) at least one site, every one of them complete.
1301            .filter(|g| !g.marked && g.every_site_complete)
1302            .map(|g| UnmarkedStruct {
1303                file: g.file,
1304                line: g.line,
1305                name: g.name,
1306                sites: g.sites,
1307            })
1308            .collect();
1309    out.sort_by(|a, b| (&a.file, a.line).cmp(&(&b.file, b.line)));
1310    out
1311}
1312
1313/// A record declared among the project's own files, built and cast only in the file
1314/// that declares it, and left unmarked `---@sealed` (#304; `htl adopt`'s `---@sealed`
1315/// row reads the same list). A record is a candidate when all four hold:
1316///
1317/// 1. no site of it has [`sealed`](RecordSite::sealed) — the record carries no
1318///    `---@sealed` yet;
1319/// 2. it has at least one site, literal or cast — a record nobody builds or casts says
1320///    nothing about itself, sealed or not;
1321/// 3. every site's own file — the first element of the `checked` pair the site came
1322///    from, read by `grouped_record_sites` into `every_site_here` — canonicalises to
1323///    the record's declaring file: the record is never built or cast anywhere else,
1324///    which is the whole of what `---@sealed` would say about it;
1325/// 4. the record's own file is one of `declared_in` ([`RecordSite::record_file`],
1326///    canonicalised) — a record declared in a dependency's `.d.tl`, a patched
1327///    dependency's own copy, or a file named outright that no module claims, is not
1328///    the project's to mark, however many of the project's own sites cast it (which
1329///    still count toward conditions 2 and 3: `checked`, not `declared_in`, is where
1330///    sites come from, so a project record a patched dependency casts is still ruled
1331///    out by that cast, even though the dependency's own records never become
1332///    candidates themselves).
1333///
1334/// 4 is independent of 2 and 3 in both this rule and [`unmarked_structs`], whenever
1335/// `checked` is wider than `declared_in`: a record declared, built and (for this rule)
1336/// cast only inside a patched dependency's own file, or a stray file's, meets 1-3
1337/// entirely on the evidence of that one file and is excluded only by 4 -- `declared_in`
1338/// not naming that file is the only reason it is not a candidate.
1339///
1340/// Grouped by `grouped_record_sites` over every site, literal and cast alike —
1341/// `sites` counts both. `sealed-record` with no function list treats any site inside
1342/// the declaring file as allowed, so marking a candidate this reports `---@sealed`
1343/// cannot make `sealed-record` report anything new on the spot: the same reason
1344/// [`unmarked_structs`]' census is not a prediction, and the issue's own reason for
1345/// this rule. Ordered by `(file, line)`.
1346pub fn unmarked_sealeds(
1347    checked: &[(PathBuf, Vec<RecordSite>)],
1348    declared_in: &std::collections::HashSet<PathBuf>,
1349) -> Vec<UnmarkedSealed> {
1350    let mut out: Vec<UnmarkedSealed> = grouped_record_sites(checked, declared_in, |_| true)
1351        .into_iter()
1352        // Conditions 1-3: not sealed, and (inherently, from `grouped_record_sites`'s own
1353        // loop) at least one site, every one of them in the declaring file.
1354        .filter(|g| !g.sealed && g.every_site_here)
1355        .map(|g| UnmarkedSealed {
1356            file: g.file,
1357            line: g.line,
1358            name: g.name,
1359            sites: g.sites,
1360        })
1361        .collect();
1362    out.sort_by(|a, b| (&a.file, a.line).cmp(&(&b.file, b.line)));
1363    out
1364}
1365
1366/// Cycles in the require graph of a set of checked files, one message per cycle,
1367/// anchored at the first edge's call site. Teal types a circular require as an opaque
1368/// `circular_require`, so a cycle shows up elsewhere as "cannot index" errors; naming
1369/// the loop is the useful part. Files outside `infos` are treated as leaves.
1370///
1371/// The graph is the one that runs. A `require` the generator erases — the value of a
1372/// `local type` used only as a type ([`RequireSite::erased`]) — leaves no `require` in the
1373/// output, so two files importing each other's records for annotations alone do not loop at
1374/// run time, and are not a cycle here; nor is a loop whose back edge is erased. The site
1375/// stays in the census for the readers that want the check's dependencies (`htl unused`).
1376pub fn require_cycles(infos: &[(PathBuf, CheckInfo)]) -> Vec<Diagnostic> {
1377    use std::collections::{HashMap, HashSet};
1378    let canon = |p: &Path| std::fs::canonicalize(p).unwrap_or_else(|_| p.to_path_buf());
1379    let mut edges: HashMap<PathBuf, Vec<(PathBuf, &RequireSite)>> = HashMap::new();
1380    let mut display: HashMap<PathBuf, PathBuf> = HashMap::new();
1381    for (file, ci) in infos {
1382        let from = canon(file);
1383        display.insert(from.clone(), file.clone());
1384        let list = edges.entry(from).or_default();
1385        for r in &ci.requires {
1386            if r.erased {
1387                continue;
1388            }
1389            if let Some(p) = &r.path {
1390                list.push((canon(p), r));
1391            }
1392        }
1393    }
1394    let nodes: Vec<PathBuf> = {
1395        let mut v: Vec<PathBuf> = edges.keys().cloned().collect();
1396        v.sort();
1397        v
1398    };
1399    let mut out = Vec::new();
1400    let mut reported: HashSet<Vec<PathBuf>> = HashSet::new();
1401    let mut state: HashMap<PathBuf, u8> = HashMap::new(); // 1 = on stack, 2 = done
1402    let mut stack: Vec<(PathBuf, Option<&RequireSite>)> = Vec::new();
1403
1404    fn dfs<'a>(
1405        node: PathBuf,
1406        edges: &HashMap<PathBuf, Vec<(PathBuf, &'a RequireSite)>>,
1407        state: &mut HashMap<PathBuf, u8>,
1408        stack: &mut Vec<(PathBuf, Option<&'a RequireSite>)>,
1409        reported: &mut HashSet<Vec<PathBuf>>,
1410        display: &HashMap<PathBuf, PathBuf>,
1411        out: &mut Vec<Diagnostic>,
1412    ) {
1413        state.insert(node.clone(), 1);
1414        if let Some(list) = edges.get(&node) {
1415            for (to, site) in list {
1416                match state.get(to).copied() {
1417                    Some(1) => {
1418                        // back edge: cycle = stack from `to` .. node, then back to `to`
1419                        let start = stack.iter().position(|(n, _)| n == to).unwrap_or(0);
1420                        let mut members: Vec<PathBuf> = stack[start..]
1421                            .iter()
1422                            .map(|(n, _)| n.clone())
1423                            .chain(std::iter::once(node.clone()))
1424                            .collect();
1425                        members.dedup();
1426                        let mut key = members.clone();
1427                        key.sort();
1428                        if reported.insert(key) {
1429                            let name = |p: &PathBuf| {
1430                                display
1431                                    .get(p)
1432                                    .unwrap_or(p)
1433                                    .file_name()
1434                                    .map(|s| s.to_string_lossy().into_owned())
1435                                    .unwrap_or_else(|| p.display().to_string())
1436                            };
1437                            let chain: Vec<String> = members
1438                                .iter()
1439                                .map(name)
1440                                .chain(std::iter::once(name(to)))
1441                                .collect();
1442                            let first_file = display
1443                                .get(&members[0])
1444                                .cloned()
1445                                .unwrap_or_else(|| members[0].clone());
1446                            // anchor: the edge leaving the cycle's first member
1447                            let anchor = stack.get(start + 1).and_then(|(_, s)| *s).unwrap_or(site);
1448                            out.push(Diagnostic::new(
1449                                Severity::Lint,
1450                                first_file.display().to_string(),
1451                                anchor.line,
1452                                anchor.col,
1453                                format!(
1454                                    "require cycle: {} (Teal types the back edge as an opaque \
1455                                     circular require; break it by moving shared types into a \
1456                                     module both sides require)",
1457                                    chain.join(" -> ")
1458                                ),
1459                                Some("require-cycle"),
1460                            ));
1461                        }
1462                    }
1463                    Some(2) => {}
1464                    _ => {
1465                        stack.push((to.clone(), Some(site)));
1466                        dfs(to.clone(), edges, state, stack, reported, display, out);
1467                        stack.pop();
1468                    }
1469                }
1470            }
1471        }
1472        state.insert(node, 2);
1473    }
1474
1475    for n in nodes {
1476        if !state.contains_key(&n) {
1477            stack.push((n.clone(), None));
1478            dfs(
1479                n,
1480                &edges,
1481                &mut state,
1482                &mut stack,
1483                &mut reported,
1484                &display,
1485                &mut out,
1486            );
1487            stack.pop();
1488        }
1489    }
1490    // In the order the text sorts, which is the order the report has always had.
1491    out.sort_by_cached_key(|d| d.to_string());
1492    out
1493}
1494
1495impl CheckInfo {
1496    /// `true` when nothing failed the check — errors only. Warnings and lints are the
1497    /// caller's to promote ([`clean`](Self::clean) is the stricter question), so this is
1498    /// what decides whether generated code may be run.
1499    pub fn ok(&self) -> bool {
1500        self.errors.is_empty()
1501    }
1502
1503    /// `true` when there are no errors, warnings or lints.
1504    pub fn clean(&self) -> bool {
1505        self.errors.is_empty() && self.warnings.is_empty() && self.lints.is_empty()
1506    }
1507
1508    /// Everything this check found about the file itself, structured, in the order the
1509    /// text output says it: warnings, then lints, then errors.
1510    ///
1511    /// Errors in what the file *required* are not here — they belong to the module they
1512    /// are in, and it is the reporting caller that decides how to say them
1513    /// ([`dependency_errors`](Self::dependency_errors)).
1514    pub fn diagnostics(&self) -> Vec<Diagnostic> {
1515        let mut out = self.warning_diagnostics();
1516        out.extend(self.lint_diagnostics());
1517        out.extend(self.error_diagnostics());
1518        out
1519    }
1520
1521    /// [`errors`](Self::errors) with their positions, their class and their fixes.
1522    pub fn error_diagnostics(&self) -> Vec<Diagnostic> {
1523        self.error_items.clone()
1524    }
1525
1526    /// [`warnings`](Self::warnings) with their positions and kinds. Warnings carry no fix.
1527    pub fn warning_diagnostics(&self) -> Vec<Diagnostic> {
1528        self.warning_items.clone()
1529    }
1530
1531    /// [`lints`](Self::lints) with their positions, their rule names and their fixes.
1532    pub fn lint_diagnostics(&self) -> Vec<Diagnostic> {
1533        self.lint_items.clone()
1534    }
1535}
1536
1537/// An mlua state with the Teal compiler loaded.
1538pub struct Htl {
1539    /// The program's state: `require`, preloads, `exec`, bundles.
1540    lua: Lua,
1541    /// The prelude (checker API), and this state's program in it. The prelude lives in
1542    /// `lua` unless this is a split state made by [`with_checker`](Self::with_checker),
1543    /// where it belongs to the checker. Reached through [`checker_call`](Self::checker_call)
1544    /// only.
1545    h: CheckerHandle,
1546    /// The state the prelude — and so the checker — lives in: `lua` itself, or the
1547    /// checker's for a split state. Weak, because the checker is kept alive by whoever
1548    /// made it, not by the program states that borrow it.
1549    checker: mlua::WeakLua,
1550}
1551
1552/// The checker's prelude as one program state reaches it: the prelude table, and the
1553/// program to enter for every call (`H.with_program` in `prelude.lua`, whose comment says
1554/// what a program holds and why it exists).
1555///
1556/// A split state ([`Htl::with_checker_lua`]) has a program of its own, made when the state
1557/// is; every call it makes into the prelude goes through [`call`](Self::call), which
1558/// enters that program first (a write, such as the project model's view, is a call too:
1559/// `H.set_model`). The checker used directly has none: its program is the prelude's
1560/// globals, and the call goes straight through, as it did before programs existed.
1561///
1562/// Also kept in a split state's app data, so the mlua-pkg resolvers there reach the checker
1563/// in the state's program (`pkg::TealResolver`).
1564#[derive(Clone)]
1565pub(crate) struct CheckerHandle {
1566    /// The prelude table, in the checker's state.
1567    h: Table,
1568    /// The program table `H.begin_program` made for a split state, in the checker's state.
1569    program: Option<Table>,
1570}
1571
1572impl CheckerHandle {
1573    /// A handle on the checker used directly: no program to enter.
1574    pub(crate) fn direct(h: Table) -> Self {
1575        Self { h, program: None }
1576    }
1577
1578    /// Call the prelude's function `name` with `args`, inside this handle's program.
1579    pub(crate) fn call<R: mlua::FromLuaMulti>(
1580        &self,
1581        name: &str,
1582        args: impl mlua::IntoLuaMulti,
1583    ) -> mlua::Result<R> {
1584        match &self.program {
1585            None => self.h.get::<Function>(name)?.call(args),
1586            // The name and not the function: `with_program` looks it up once the program is
1587            // in place, so a field the program holds (a model's `owns_file`) is its own.
1588            Some(program) => self
1589                .h
1590                .get::<Function>("with_program")?
1591                .call((program, name, args)),
1592        }
1593    }
1594
1595    /// Whether the prelude has a field `name`, as this handle's program sees it.
1596    pub(crate) fn has(&self, name: &str) -> mlua::Result<bool> {
1597        self.call("has", name)
1598    }
1599}
1600
1601const RUNTIME_REGISTRY_KEY: &str = "htl.runtime";
1602
1603/// Registry key under which a state remembers, per bundle entry, which `package.preload`
1604/// names that bundle wrote (`Htl::bundle_record`).
1605const BUNDLE_REGISTRY_KEY: &str = "htl.bundles";
1606
1607/// What [`Htl::replace_bundle`] did, so a host can say it rather than guess.
1608///
1609/// Three lists because three things happen to a name, and a host that logs "reloaded" for
1610/// all of them is hiding the two that matter: a module that went away for good, and one
1611/// whose live value was deliberately spared.
1612///
1613/// A module both bundles carry appears in `dropped` *and* in `added` — which is what
1614/// happened to it: the old one was taken out of `package.loaded`, and the new one is what
1615/// the next `require` will evaluate. Nothing is in both `dropped` and `kept`.
1616#[derive(Debug, Clone, Default, PartialEq, Eq)]
1617pub struct Replaced {
1618    /// Names the old bundle had installed that are now out of `package.preload` and
1619    /// `package.loaded`: the next `require` of one evaluates whatever answers it now, and
1620    /// for a name the new bundle does not carry there may be nothing left to answer.
1621    pub dropped: Vec<String>,
1622    /// Names from `keep` that the old bundle had actually installed, and whose evaluated
1623    /// value is still in `package.loaded`. Shorter than the `keep` that was asked for when
1624    /// a name in it was never this bundle's — the host's own module, or a typo — which is
1625    /// the only report of that.
1626    pub kept: Vec<String>,
1627    /// Names the new bundle wrote into `package.preload`. Not what it carries: a name the
1628    /// host had registered first is still the host's and is not here.
1629    pub added: Vec<String>,
1630}
1631
1632/// Why a `require` of `module` failed when `decl` declares it and nothing implements it,
1633/// as a searcher says it: a searcher that returns a string has not found the module, and
1634/// `require` concatenates the string into its "module 'x' not found" error.
1635///
1636/// One text for every place that declines a declaration: the `Registry`'s trailing
1637/// searcher (`pkg`), and [`Htl::install_searcher`]'s searcher when the `require` came from
1638/// plain Lua (both preludes, which are handed this as a function). Two remedies, because a
1639/// reader who gets here has made one of exactly two mistakes: they meant to supply the
1640/// module and did not, or they wanted the types and wrote the import that loads a module
1641/// rather than the one that does not.
1642pub(crate) fn declaration_only_message(module: &str, decl: &str) -> String {
1643    format!(
1644        "\n\tno module '{module}': '{decl}' declares it and nothing implements it. \
1645         If the host provides it, register it before the require (preload / \
1646         preload_value / htl_preload, or a resolver that serves it); if you only want \
1647         its types, write `local type {module} = require(\"{module}\")`, which the \
1648         generator erases."
1649    )
1650}
1651
1652/// The part of the prelude a runtime state needs when its checker lives elsewhere: the
1653/// search chunk's functions (`S`, received as this chunk's first argument — see
1654/// [`with_checker_lua`](Htl::with_checker_lua)), copied onto `R` so every name Rust looks
1655/// up on a split state's runtime table (`reset_path`, `drop_cwd_path`, `add_path`,
1656/// `install_searcher`) resolves exactly as it did when this chunk defined them itself;
1657/// plus `R.preload_generated`, which has no checker-side counterpart and stays here.
1658const RUNTIME_PRELUDE: &str = r#"
1659local S = ...
1660
1661local R = {}
1662for k, v in pairs(S) do R[k] = v end
1663
1664-- Put already-generated Lua in front of the searcher for one module name.
1665--
1666-- `package.preload` is searcher position 1 and R.install_searcher (S.install_searcher,
1667-- copied above) puts htl's at 2, so a preloaded module is never asked of the searcher —
1668-- which is the point: asking would check and generate it again. Loaded the same way the
1669-- searcher would have loaded it, so the module sees the same chunk name and the same
1670-- arguments.
1671function R.preload_generated(module_name, code, filename)
1672   -- Never displace what is already there. The test library and anything a host preloads are
1673   -- put in package.preload by whoever owns them, and Lua generated from a `.tl` of the same
1674   -- name is not the same module: preloading over `htl.test` gives the file a stand-in whose
1675   -- `run()` reports nothing, and every test silently stops counting.
1676   if package.preload[module_name] ~= nil then return end
1677   local chunk, lerr = load(code, "@" .. filename, "t")
1678   if not chunk then
1679      error("htl: cached Lua failed to load: " .. tostring(lerr), 0)
1680   end
1681   package.preload[module_name] = function(modname) return chunk(modname, filename) end
1682end
1683
1684return R
1685"#;
1686
1687/// A coverage recording in progress, in the state's app data: the callback's id on the
1688/// hook owner, and the lines it has seen (shared with the callback).
1689struct CoverageRun {
1690    id: mlua_isle::runtime::HookId,
1691    lines: Rc<RefCell<HashMap<String, HashSet<usize>>>>,
1692}
1693
1694/// Make `lua`'s debug hook mlua-isle's, so that everything that wants a callback on the
1695/// state registers with it. The first attach captures `xpcall`, which has to happen
1696/// before a host sandboxes the globals. The config it starts with is htl's default
1697/// `[async]` ([`config::AsyncConfig`]: a one-second grace, no preemption), so a program
1698/// run by a host that never reads an `htl.toml` is cancelled the way `htl run` cancels one.
1699fn attach_hook_owner(lua: &Lua) -> Result<mlua_isle::runtime::Vm> {
1700    mlua_isle::runtime::Vm::attach(lua, config::AsyncConfig::default().runtime())
1701        .context("attaching the debug hook owner to the state")
1702}
1703
1704/// The hook owner of `lua`, attached now if it was not yet (see [`Htl::hook_owner`]).
1705pub(crate) fn vm(lua: &Lua) -> Result<mlua_isle::runtime::Vm> {
1706    match mlua_isle::runtime::Vm::of(lua) {
1707        Some(vm) => Ok(vm),
1708        None => attach_hook_owner(lua),
1709    }
1710}
1711
1712impl Htl {
1713    /// New state. Opens every standard library — `debug`, `io` and `os` included — which
1714    /// is the right state for `htl run`, for the checker, and for a host running Teal it
1715    /// wrote. `debug` is why this comes from `Lua::unsafe_new` rather than a safe
1716    /// constructor: `Lua::new` builds with `StdLib::ALL_SAFE` and leaves `debug` out,
1717    /// `Lua::new_with` refuses it outright if asked, and a safe state refuses to load it
1718    /// later too. A host that does not need `debug` needs no `unsafe_new` either: see
1719    /// [`with_checker_lua`](Self::with_checker_lua). A host running Teal it did not write
1720    /// (a mods directory, a script a user dropped in) decides what that Teal may reach,
1721    /// and decides it on the `Lua` it builds itself:
1722    /// [`with_checker_lua`](Self::with_checker_lua) takes that state. The checker state
1723    /// this makes uses `string`, `table`, `math` and `package`, and `os.getenv` and
1724    /// `io.stderr` on its debug paths — and under the split it is not the state a mod
1725    /// runs in.
1726    pub fn new() -> Result<Self> {
1727        // SAFETY: unsafe_new opens `debug` and lets `package` load C modules; either
1728        // reaches past Rust's guarantees only through the Lua this state runs, which is
1729        // htl's own (tl, lint, fmt, the preludes) and the Teal or bytecode its caller
1730        // chose to run — not untrusted input, which a host runs in a state of its own
1731        // (`with_checker_lua`). A safe constructor is no option: it refuses
1732        // `StdLib::DEBUG`.
1733        let lua = unsafe { Lua::unsafe_new() };
1734        Self::from_lua(lua)
1735    }
1736
1737    /// A fresh program state that borrows `checker`'s compiler instead of loading its
1738    /// own: modules `checker` has already type-checked and generated are served from
1739    /// its store, so a run of many programs (the test runner: one state per file)
1740    /// checks each module once. The program state itself is as isolated as
1741    /// [`new`](Self::new): nothing but the checker is shared.
1742    ///
1743    /// The state gets a program of its own in the checker: its search path, its project
1744    /// model, its `[lang]`, deps and lint selection, and its module-name resolution, copied
1745    /// from the checker's own settings now and changed from then on only by this state's
1746    /// setters ([`add_path`](Self::add_path), `apply_model`, [`set_lang`](Self::set_lang),
1747    /// ...). Two states made from one checker, alive at the
1748    /// same time, never resolve or check by each other's settings, and neither changes the
1749    /// checker's. `prelude.lua` (`H.with_program`) says what a program holds.
1750    pub fn with_checker(checker: &Htl) -> Result<Self> {
1751        // SAFETY: as in `new`.
1752        let lua = unsafe { Lua::unsafe_new() };
1753        Self::with_checker_lua(checker, lua)
1754    }
1755
1756    /// [`with_checker`](Self::with_checker) with the program state supplied.
1757    ///
1758    /// This is the constructor for a host that decides what the program state is made of
1759    /// — which standard libraries it opens (`Lua::new_with` or `Lua::unsafe_new_with`),
1760    /// what its allocator is bounded to (`Lua::set_memory_limit`), what callback counts
1761    /// its instructions (below) — while the checker keeps running on a state of its own,
1762    /// with whatever it needs. Every such limit is mlua's and is set on `lua` by the
1763    /// host; htl adds none of its own and puts nothing in the way of them.
1764    ///
1765    /// What htl itself needs from `lua`: `package` (the searcher and `preload`), the base
1766    /// library's `load` and `xpcall`, and mlua's default `LuaOptions::catch_rust_panics`.
1767    /// None of that is `debug` or a C module: a safe constructor refuses `StdLib::DEBUG`
1768    /// (and on luajit `StdLib::FFI`) and, when `package` is open, replaces
1769    /// `package.loadlib` and the C-library searchers with ones that fail — nothing else.
1770    /// So the constructor for a state that will load bundles is the same one as for any
1771    /// other program state: `Lua::new_with` (or plain `Lua::new()`) when the host needs
1772    /// neither, `unsafe_new_with` when it does.
1773    ///
1774    /// A safe constructor governs libraries, not bytes: Lua 5.4 does not check a binary
1775    /// chunk, and its manual says a maliciously crafted one can crash the interpreter —
1776    /// so a bundle with bytecode modules is trusted input on any state, whichever
1777    /// constructor built it. A host loads bundles it built itself, and takes a bundle
1778    /// from elsewhere as source (`htl build --source`) rather than trusting its
1779    /// bytecode.
1780    ///
1781    /// The state's debug hook is owned: this constructor attaches
1782    /// [`mlua_isle`]'s [`Vm`](mlua_isle::runtime::Vm) to `lua`, one global hook that
1783    /// dispatches to registered callbacks, each at its own triggers. An
1784    /// `ffi::Interrupt` and [`coverage_start`](Self::coverage_start)
1785    /// register with it, and so does a host that counts instructions, through
1786    /// [`hook_owner`](Self::hook_owner):
1787    ///
1788    /// ```rust,ignore
1789    /// use htl::mlua::{HookTriggers, VmState};
1790    ///
1791    /// h.hook_owner()?.add_hook(HookTriggers::new().every_nth_instruction(1000), |_, _| {
1792    ///     Ok(VmState::Continue)                     // or `Err(..)` to stop the run
1793    /// })?;
1794    /// ```
1795    ///
1796    /// Do not call `Lua::set_global_hook` or `Lua::set_hook` on the state: a thread has
1797    /// one hook, either replaces the owner's, and every callback registered with it —
1798    /// the interrupt, coverage — stops firing. A script with the `debug` library can do
1799    /// the same with `debug.sethook`, so a state that runs Teal the host does not trust
1800    /// leaves `debug` out. Sandboxing the globals (`Lua::set_globals` with a whitelist,
1801    /// removing `xpcall`) is done *after* this constructor: the attach captures `xpcall`
1802    /// once, and an `xpcall` that is already gone fails the attach.
1803    ///
1804    /// The limits are mlua's, and so are their edges. An instruction callback fires only
1805    /// while Lua is executing Lua, so a host function that blocks is one instruction. A
1806    /// memory limit is checked after Lua's emergency collection, and `MemoryError` is what
1807    /// comes back. `htl check` settles what a module *is*; what it may *do* is settled
1808    /// here, by the host.
1809    ///
1810    /// ```rust,ignore
1811    /// use htl::Htl;
1812    /// use htl::mlua::{Lua, LuaOptions, StdLib};
1813    ///
1814    /// let checker = Htl::new()?;                     // the checker keeps everything it needs
1815    /// // No `debug`, no C module: a safe constructor is enough.
1816    /// let lua = Lua::new_with(StdLib::ALL_SAFE ^ StdLib::OS ^ StdLib::IO, LuaOptions::default())?;
1817    /// lua.set_memory_limit(8 << 20)?;                // mlua's: past it, an allocation is `MemoryError`
1818    /// let h = Htl::with_checker_lua(&checker, lua)?; // the program runs here; `os` and `io` are nil
1819    /// ```
1820    pub fn with_checker_lua(checker: &Htl, lua: Lua) -> Result<Self> {
1821        attach_hook_owner(&lua)?;
1822        let s: Table = lua
1823            .load(SEARCH_SRC)
1824            .set_name("=htl-search")
1825            .eval()
1826            .context("loading htl search chunk")?;
1827        let r: Table = lua
1828            .load(RUNTIME_PRELUDE)
1829            .set_name("=htl-runtime")
1830            .call(s)
1831            .context("loading htl runtime prelude")?;
1832        lua.set_named_registry_value(RUNTIME_REGISTRY_KEY, r)?;
1833        let program: Table = checker.checker_call("begin_program", ())?;
1834        let h = CheckerHandle {
1835            h: checker.h.h.clone(),
1836            program: Some(program),
1837        };
1838        lua.set_app_data(h.clone());
1839        Ok(Self {
1840            lua,
1841            h,
1842            checker: checker.checker.clone(),
1843        })
1844    }
1845
1846    /// `true` when the checker is another Lua state ([`with_checker`](Self::with_checker)),
1847    /// which is when this state has a program of its own.
1848    fn split(&self) -> bool {
1849        self.h.program.is_some()
1850    }
1851
1852    /// Call the checker prelude's function `name`, in this state's program: the one way
1853    /// this crate calls into the prelude ([`CheckerHandle::call`]).
1854    pub(crate) fn checker_call<R: mlua::FromLuaMulti>(
1855        &self,
1856        name: &str,
1857        args: impl mlua::IntoLuaMulti,
1858    ) -> Result<R> {
1859        Ok(self.h.call(name, args)?)
1860    }
1861
1862    /// The checker's Lua state: where a function the prelude calls has to be made.
1863    #[cfg_attr(not(all(feature = "pkg", feature = "dts")), allow(dead_code))]
1864    pub(crate) fn checker_lua(&self) -> Result<Lua> {
1865        self.checker
1866            .try_upgrade()
1867            .ok_or_else(|| anyhow!("the checker this state was made from has been dropped"))
1868    }
1869
1870    fn runtime(&self) -> Result<Table> {
1871        Ok(self
1872            .lua
1873            .named_registry_value::<Table>(RUNTIME_REGISTRY_KEY)?)
1874    }
1875
1876    /// Put Lua this checker generated for a `.tl` module in front of the searcher, in a
1877    /// program state.
1878    ///
1879    /// Distinct from [`preload`](Self::preload), which registers a source string as a module:
1880    /// this loads the way the searcher would have, so the module sees the same chunk name and
1881    /// the same arguments as if it had been generated during the run.
1882    ///
1883    /// Without it, a `require` in running code asks the searcher, which checks and generates
1884    /// the module then and there. With it, the module is already present. The two are the
1885    /// same thing only if `code` is what this checker would generate now — the caller's
1886    /// promise, and the reason anything serving this has to invalidate on the module's own
1887    /// content.
1888    pub fn preload_generated(&self, name: &str, code: &str, file: &Path) -> Result<()> {
1889        let f: Function = self.runtime()?.get("preload_generated")?;
1890        f.call::<()>((name, code, path_str(file)))?;
1891        Ok(())
1892    }
1893
1894    /// The owner of this state's debug hook: [`mlua_isle`]'s
1895    /// [`Vm`](mlua_isle::runtime::Vm), one global hook that dispatches to the callbacks
1896    /// registered with it (`add_hook`), each at its own triggers. A thread has one hook
1897    /// slot, so this is how more than one party gets a callback on the state — an
1898    /// `ffi::Interrupt`, [`coverage_start`](Self::coverage_start), and a
1899    /// host's own instruction counter — without any of them taking the slot from the
1900    /// others.
1901    ///
1902    /// A program state ([`with_checker`](Self::with_checker)) is attached from
1903    /// construction. The shared state ([`new`](Self::new), [`from_lua`](Self::from_lua))
1904    /// is attached the first time it is asked for a callback or runs a program
1905    /// ([`exec`](Self::exec), [`exec_bytes`](Self::exec_bytes)), and not before: the
1906    /// checker does most of its work on that state, and a count hook is a cost on every
1907    /// instruction Lua runs, so `htl check` does not pay it. Attaching captures the
1908    /// global `xpcall`, so on a state whose globals the host sandboxes this runs before
1909    /// the sandboxing.
1910    ///
1911    /// ```rust,ignore
1912    /// use htl::mlua::{HookTriggers, VmState};
1913    ///
1914    /// h.hook_owner()?.add_hook(HookTriggers::new().every_nth_instruction(1000), |_, _| {
1915    ///     Ok(VmState::Continue)                     // or `Err(..)` to stop the run
1916    /// })?;
1917    /// ```
1918    pub fn hook_owner(&self) -> Result<mlua_isle::runtime::Vm> {
1919        vm(&self.lua)
1920    }
1921
1922    /// Apply a project's `[async]` ([`config::AsyncConfig`]) to this state: the grace a
1923    /// cancelled program gets and whether a CPU-bound task is preempted. What `htl run`
1924    /// and `htl test` do with the `htl.toml` they read; a host that runs a program with
1925    /// [`run_async`](Self::run_async) applies the section itself, or keeps the default
1926    /// every state is attached with. Read at the start of a run and at each task's start,
1927    /// so it does not reach a program already running.
1928    pub fn configure_async(&self, cfg: &config::AsyncConfig) -> Result<()> {
1929        vm(&self.lua)?.set_config(cfg.runtime());
1930        Ok(())
1931    }
1932
1933    /// Start recording which lines of which chunk run in this state. The line hook slows
1934    /// the run. It is a callback on the state's hook owner ([`mlua_isle`]), so it reaches
1935    /// every coroutine the program creates from here on, and it leaves the other callbacks
1936    /// on the state — an `ffi::Interrupt`, the host's own — in place.
1937    /// Calling it while a recording is running discards that recording and starts over.
1938    pub fn coverage_start(&self) -> Result<()> {
1939        if let Some(run) = self.lua.remove_app_data::<CoverageRun>() {
1940            vm(&self.lua)?.remove_hook(run.id)?;
1941        }
1942        let lines: Rc<RefCell<HashMap<String, HashSet<usize>>>> = Rc::default();
1943        let recorded = lines.clone();
1944        // The line event is the hot path. One "S" lookup per function instead of per line,
1945        // keyed by the function's address; the `Function` is kept beside the answer so the
1946        // address cannot be handed to another function while the key is in use. A
1947        // call/return-event stack was measured slower on a call-heavy suite, since calls
1948        // are almost as frequent as lines there.
1949        let mut srcs: HashMap<*const std::ffi::c_void, (Function, Option<Rc<str>>)> =
1950            HashMap::new();
1951        let id =
1952            vm(&self.lua)?.add_hook(mlua::HookTriggers::new().every_line(), move |_, debug| {
1953                let f = debug.function();
1954                let src = &srcs
1955                    .entry(f.to_pointer())
1956                    .or_insert_with(|| {
1957                        let src = debug.source().source.map(|s| Rc::from(s.as_ref()));
1958                        (f, src)
1959                    })
1960                    .1;
1961                if let (Some(src), Some(line)) = (src, debug.current_line()) {
1962                    let mut recorded = recorded.borrow_mut();
1963                    match recorded.get_mut(&**src) {
1964                        Some(set) => {
1965                            set.insert(line);
1966                        }
1967                        None => {
1968                            recorded.insert(src.to_string(), HashSet::from([line]));
1969                        }
1970                    }
1971                }
1972                Ok(mlua::VmState::Continue)
1973            })?;
1974        self.lua.set_app_data(CoverageRun { id, lines });
1975        Ok(())
1976    }
1977
1978    /// Stop recording; `(chunk source, sorted executed lines)` per chunk, sorted by
1979    /// source. Sources are as Lua names them: `@<path>` for files loaded by the searcher
1980    /// and the entry. Nothing was being recorded: an empty list.
1981    pub fn coverage_stop(&self) -> Result<Vec<(String, Vec<usize>)>> {
1982        let Some(run) = self.lua.remove_app_data::<CoverageRun>() else {
1983            return Ok(Vec::new());
1984        };
1985        vm(&self.lua)?.remove_hook(run.id)?;
1986        let lines = std::mem::take(&mut *run.lines.borrow_mut());
1987        let mut out: Vec<(String, Vec<usize>)> = lines
1988            .into_iter()
1989            .map(|(src, set)| {
1990                let mut list: Vec<usize> = set.into_iter().collect();
1991                list.sort_unstable();
1992                (src, list)
1993            })
1994            .collect();
1995        out.sort();
1996        Ok(out)
1997    }
1998
1999    /// Statements of a `.tl` file as `(first line, last line)` ranges: what a coverage
2000    /// report counts as executable. The ranges come from the `.tl` syntax tree and are
2001    /// matched against Lua's line hook as they are: Teal keeps the input's line breaks
2002    /// when it generates Lua, so a `.tl` line is a Lua line and nothing is mapped back. A
2003    /// statement counts as executed when any line of its range ran (Lua attributes a
2004    /// multi-line statement's instructions to several lines).
2005    pub fn executable_ranges(&self, file: &Path) -> Result<Vec<(usize, usize)>> {
2006        Ok(self.coverage_spans(file)?.0)
2007    }
2008
2009    /// The statement ranges of [`executable_ranges`](Self::executable_ranges) and the
2010    /// file's named functions, from one parse: a coverage report wants both, and the
2011    /// second is what lets it say *which function* the missed statements belong to.
2012    pub fn coverage_spans(&self, file: &Path) -> Result<CoverageSpans> {
2013        let (ranges, funcs): (Option<Table>, Option<Table>) =
2014            self.checker_call("executable_ranges", path_str(file))?;
2015        let Some(ranges) = ranges else {
2016            return Ok((Vec::new(), Vec::new()));
2017        };
2018        let mut out = Vec::new();
2019        for r in ranges.sequence_values::<Table>() {
2020            let r = r?;
2021            out.push((r.get::<usize>(1)?, r.get::<usize>(2)?));
2022        }
2023        let mut fns = Vec::new();
2024        if let Some(funcs) = funcs {
2025            for f in funcs.sequence_values::<Table>() {
2026                let f = f?;
2027                fns.push(FunctionSpan {
2028                    name: f.get("name")?,
2029                    line: f.get("y")?,
2030                    last: f.get("last")?,
2031                });
2032            }
2033        }
2034        Ok((out, fns))
2035    }
2036
2037    /// The checker's `package.path` (what `require` inside `.tl` resolves through), as this
2038    /// state's program has it.
2039    pub fn search_path(&self) -> Result<String> {
2040        self.checker_call("get_path", ())
2041    }
2042
2043    /// Restore a checker `package.path` taken with [`search_path`](Self::search_path), in
2044    /// this state's program.
2045    pub fn set_search_path(&self, path: &str) -> Result<()> {
2046        self.checker_call("set_path", path)
2047    }
2048
2049    /// Attach the Teal compiler to an existing Lua state (the host's own `Lua`): the
2050    /// shared form, where the checker runs on the program's state too, so that state has
2051    /// to hold what the checker needs as well as what the program does — `tl.lua`,
2052    /// `lint.lua` and `fmt.lua` compiled into `package.preload` and the prelude evaluated,
2053    /// on every state this is called on. For a state that only runs code — a host's own,
2054    /// an `AsyncIsle`'s included — see [`with_checker_lua`](Self::with_checker_lua), the
2055    /// split form, where the host's state holds only what the program needs; the crate
2056    /// doc's Embedding section shows it on an `AsyncIsle`.
2057    pub fn from_lua(lua: Lua) -> Result<Self> {
2058        let tl_loader: Function = lua
2059            .load(TL_SRC)
2060            .set_name("=tl.lua")
2061            .into_function()
2062            .context("compiling vendored tl.lua")?;
2063        let lint_loader: Function = lua
2064            .load(LINT_SRC)
2065            .set_name("=htl-lint")
2066            .into_function()
2067            .context("compiling htl lint.lua")?;
2068        let package: Table = lua.globals().get("package")?;
2069        let preload: Table = package.get("preload")?;
2070        let fmt_loader: Function = lua
2071            .load(FMT_SRC)
2072            .set_name("=htl-fmt")
2073            .into_function()
2074            .context("compiling htl fmt.lua")?;
2075        let runtime_version_loader: Function = lua
2076            .load(RUNTIME_VERSION_SRC)
2077            .set_name("=htl-runtime-version")
2078            .into_function()
2079            .context("compiling htl runtime_version.lua")?;
2080        preload.set("tl", tl_loader)?;
2081        preload.set("htl.lint", lint_loader)?;
2082        preload.set("htl.fmt", fmt_loader)?;
2083        preload.set("htl.runtime_version", runtime_version_loader)?;
2084        // Not `package.preload["htl.search"]`: a project's own `require("htl.search")`
2085        // (a `src/htl/search.tl` of its own — nothing reserves that name) must reach its
2086        // module, in a shared state exactly as it does in a split one, where this chunk
2087        // is never put in `package.preload` either (`with_checker_lua` below). Evaluated
2088        // directly and handed to the prelude as its argument instead.
2089        let s: Table = lua
2090            .load(SEARCH_SRC)
2091            .set_name("=htl-search")
2092            .eval()
2093            .context("loading htl search chunk")?;
2094        let h: Table = lua
2095            .load(PRELUDE)
2096            .set_name("=htl-prelude")
2097            .call(s)
2098            .context("loading htl prelude")?;
2099        lua.set_named_registry_value(PRELUDE_REGISTRY_KEY, h.clone())?;
2100        let checker = lua.weak();
2101        let this = Self {
2102            lua,
2103            h: CheckerHandle::direct(h),
2104            checker,
2105        };
2106        // The defaults come from the registry, and this is where a state gets them: the
2107        // Lua side holds no rule list of its own, so a state nobody configures would
2108        // otherwise run no lints at all.
2109        this.select_lints(&lint::Selection::default())?;
2110        Ok(this)
2111    }
2112
2113    /// The Lua state this `Htl` runs programs in.
2114    ///
2115    /// Not always the one the checker is in: [`with_checker`](Self::with_checker) makes a
2116    /// fresh state for the program and leaves the prelude in the checker's. So a value
2117    /// built from this state must not be handed to a function that came from the other —
2118    /// that is `Lua instance passed Value created from a different main Lua state`.
2119    pub fn lua(&self) -> &Lua {
2120        &self.lua
2121    }
2122
2123    /// Type-check one file.
2124    pub fn check(&self, file: &Path) -> Result<CheckInfo> {
2125        let t: Table = self.checker_call("check", path_str(file))?;
2126        read_checkinfo(&t)
2127    }
2128
2129    /// Check what is on disk right now, ignoring the store and not adding to it.
2130    ///
2131    /// [`check`](Self::check) serves a module the checker already knows from its store, and
2132    /// the underlying `tl.check_file` returns early when the environment has the file
2133    /// loaded. That is what makes checking a project fast, and it is wrong for a caller that
2134    /// has just written the file: the answer describes the version from before the write.
2135    /// `htl fix` writes and then measures, and was reverting correct fixes because of it.
2136    ///
2137    /// Nothing is stored either, because the caller may be about to put the file back —
2138    /// leaving the result behind would have the store describing a file that no longer says
2139    /// that.
2140    ///
2141    /// Slower than `check`: a cold environment re-checks the modules this file requires.
2142    ///
2143    /// The two options it differs from `check` by are set in the prelude rather than in a
2144    /// table built here, for the reason [`set_deps`](Self::set_deps) gives: `h` is not
2145    /// always in `self.lua`, and a table that crossed that line would raise.
2146    pub fn check_written(&self, file: &Path) -> Result<CheckInfo> {
2147        let t: Table = self.checker_call("check_written", path_str(file))?;
2148        read_checkinfo(&t)
2149    }
2150
2151    /// [`check_written`](Self::check_written) that also keeps what the checker knows of the
2152    /// file's names, in [`CheckInfo::types`]: the type of what is at a position, and where
2153    /// it is declared ([`typeindex::TypeIndex::at`]).
2154    ///
2155    /// For a caller that answers questions about a position of a file it checked, which is
2156    /// `htl lsp`: the index is made once, by this check, and a hover or a go-to-definition
2157    /// is answered from it with no check of its own. A copy of part of the checker's type
2158    /// report is made at the end of the check (one pass over its positions; `HTL_PROFILE=1`
2159    /// shows it as `type_index`), so a caller that asks no such question has
2160    /// `check_written`.
2161    pub fn check_indexed(&self, file: &Path) -> Result<CheckInfo> {
2162        let t: Table = self.checker_call("check_indexed", path_str(file))?;
2163        read_checkinfo(&t)
2164    }
2165
2166    /// What a file declares, from its syntax alone: the tree [`typeindex::TypeIndex::declarations`]
2167    /// holds, without checking the file.
2168    ///
2169    /// For a caller that lists the declarations of many files and has no use for their
2170    /// types, which is the project-wide symbol search of `htl lsp`: a check type-checks the
2171    /// file and what it requires, and this parses the file and walks its top-level
2172    /// statements, so a project of hundreds of files is read in the time of a few checks.
2173    /// The structure, the kinds and the positions are the same as a check's
2174    /// ([`typeindex`] says what is in them and what is approximate); what is missing is the
2175    /// type strings, so every [`typeindex::Decl::detail`] is `None`. A record function whose
2176    /// record a `require` brought in stands at the top level as `R.f`, as it does after a
2177    /// check.
2178    ///
2179    /// `Ok(None)` when the file cannot be read or has a syntax error: the tree of a file
2180    /// that does not parse is not its declarations, and it is not the same answer as
2181    /// `Ok(Some)` of an empty list, a file that declares nothing. A type error does not
2182    /// matter, since nothing is type-checked. `[lang] async` is honoured: the file is read
2183    /// as the checker would read it.
2184    pub fn declarations_of(&self, file: &Path) -> Result<Option<Vec<typeindex::Decl>>> {
2185        let rows: Option<Table> = self.checker_call("declarations_of", path_str(file))?;
2186        rows.map(|rows| typeindex::read_decls(&rows)).transpose()
2187    }
2188
2189    /// Type-check and generate Lua source. `None` code means errors (see `CheckInfo`).
2190    ///
2191    /// The code is a whole file: it ends with exactly one newline, whether or not the `.tl`
2192    /// it came from did. `tl.generate` writes no terminator after its last line, and every
2193    /// caller here — `htl gen`, `include_tl!`, a `--source` bundle payload, the run cache —
2194    /// hands the string on as a Lua file, so it is terminated once at the generator rather
2195    /// than by whichever of them remembered to.
2196    ///
2197    /// Every line keeps its number: line *n* of the code is what line *n* of the `.tl`
2198    /// became, so a run-time error names the `.tl` line. A comment-only line (`--` or `---`
2199    /// after nothing but indentation, and not the opening of a `--[[` block) survives
2200    /// verbatim at its line, so the `---` doc above a record or a function is in the Lua a
2201    /// host hands on. That holds after the last line of code too: the comment lines there,
2202    /// the `---` after a module's `return` among them, are appended at their own numbers
2203    /// (the lines between them empty), and the code ends with the last of them. A trailing
2204    /// comment (after code on the same line) and a block comment (`--[[ ... ]]`) do not: the
2205    /// generator writes from the AST, which keeps no comments, and only a whole-line comment
2206    /// can be put back at its line without one. Every line of a block comment stays empty,
2207    /// a `--` line inside it included; a `--` line inside a multi-line long string is the
2208    /// string's and comes out as the string wrote it.
2209    pub fn gen_lua(&self, file: &Path) -> Result<(Option<String>, CheckInfo)> {
2210        let (code, t): (Option<String>, Table) = self.checker_call("gen", path_str(file))?;
2211        Ok((code, read_checkinfo(&t)?))
2212    }
2213
2214    /// [`gen_lua`](Self::gen_lua) without the lint pass: the check and the code the strict
2215    /// searcher's `require` asks for (`H.gen(found, { lints = false })`), for a caller that
2216    /// reports no lints. The options table is made in the checker's state, where `gen` is.
2217    #[cfg(feature = "async")]
2218    pub(crate) fn gen_lua_unlinted(&self, file: &Path) -> Result<(Option<String>, CheckInfo)> {
2219        let opts = self.checker_lua()?.create_table()?;
2220        opts.set("lints", false)?;
2221        let (code, t): (Option<String>, Table) =
2222            self.checker_call("gen", (path_str(file), opts))?;
2223        Ok((code, read_checkinfo(&t)?))
2224    }
2225
2226    /// Apply a project's `[lang]` ([`config::LangConfig`]) to this checker: whether
2227    /// `async` and `await` are keywords of the Teal it reads. Every file the checker
2228    /// parses from here on — the file checked, the ones its `require`s reach, what `htl
2229    /// fmt` and the lints parse — is read under the setting, so it is set once per
2230    /// project, where the lint selection is. A checker nobody calls it on reads plain Teal.
2231    pub fn set_lang(&self, lang: &config::LangConfig) -> Result<()> {
2232        self.checker_call("set_lang", lang.async_on())
2233    }
2234
2235    /// Configure lint rules: `"+no-any,-shadow-local"` on top of the defaults.
2236    ///
2237    /// The spec is resolved against [`lint::RULES`], so a name the project layer reports
2238    /// under is a name this takes; an unknown one is `unknown lint rule: <item>`.
2239    pub fn configure_lints(&self, spec: &str) -> Result<()> {
2240        self.select_lints(&lint::Selection::parse(spec)?)
2241    }
2242
2243    /// Hand the checker a selection resolved elsewhere — what a caller that also has to
2244    /// ask about the project-layer rules has in hand ([`lint::Lints`]), so that the file
2245    /// rules and the project rules of one run come from one resolution of one spec.
2246    ///
2247    /// Two selections cross, one per producer on the Lua side: the rules `lint.lua`
2248    /// implements, which it runs from, and Teal's warning kinds, which the prelude filters
2249    /// the checker's warnings by as it collects them. Neither keeps defaults of its own.
2250    ///
2251    /// Each side crosses as the names that are on and the names that are off, and the
2252    /// table is built on the other side — for the reason [`set_deps`](Self::set_deps)
2253    /// gives, and it applies here the harder way: `h` is not always in `self.lua`
2254    /// ([`with_checker`](Self::with_checker) keeps the prelude in the checker's), and a
2255    /// table made here and passed there is `Lua instance passed Value created from a
2256    /// different main Lua state`. Both lists, not just the on ones, because absent and
2257    /// `false` are not the same answer to the prelude: a Teal warning kind is said unless
2258    /// its entry is exactly `false`.
2259    pub fn select_lints(&self, sel: &lint::Selection) -> Result<()> {
2260        let split = |side| {
2261            let (mut on, mut off) = (Vec::new(), Vec::new());
2262            for (name, is_on) in sel.of_side(side) {
2263                if is_on { &mut on } else { &mut off }.push(name.to_string());
2264            }
2265            (on, off)
2266        };
2267        let (lua_on, lua_off) = split(lint::Side::Lua);
2268        let (tl_on, tl_off) = split(lint::Side::Tl);
2269        self.checker_call("set_lints", (lua_on, lua_off, tl_on, tl_off))
2270    }
2271
2272    /// Tell the checker which dependencies the project installed, by name.
2273    ///
2274    /// Read by the rules that are about a library the project has rather than about its own
2275    /// code — `htlx-available`, which is silent in a project without htl-x — and by nothing
2276    /// else. Called by [`Htl::apply_project`](crate::pkg::MluaProject) with what the lockfile
2277    /// linked; a state nobody calls it on has none, which is the answer a run outside a
2278    /// project should get.
2279    /// The names cross as a sequence and the set is built on the other side, rather than
2280    /// as a table built here. `h` is not always in `self.lua` — a split state
2281    /// ([`with_checker`](Self::with_checker)) keeps the prelude in the checker's — and a
2282    /// table made in one state and passed to a function in another is
2283    /// `Lua instance passed Value created from a different main Lua state`. A `Vec` is
2284    /// converted by the call itself, in the state the function belongs to.
2285    pub fn set_deps(&self, names: &[String]) -> Result<()> {
2286        self.checker_call("set_deps", names.to_vec())
2287    }
2288
2289    /// Names of all lint rules (enabled or not), the project layer's among them.
2290    pub fn lint_rules(&self) -> Result<Vec<String>> {
2291        Ok(lint::rule_names().into_iter().map(str::to_string).collect())
2292    }
2293
2294    /// The rules `lint.lua` implements, as it knows them. The registry is
2295    /// [`lint::RULES`]; this is the list to hold it to (`tests/lint_registry.rs`).
2296    pub fn lua_lint_rules(&self) -> Result<Vec<String>> {
2297        let t: Table = self.checker_call("lint_rules", ())?;
2298        Ok(t.sequence_values::<String>().collect::<mlua::Result<_>>()?)
2299    }
2300
2301    /// Format a `.tl` file (whitespace-only formatter). Returns the formatted text.
2302    pub fn format_file(&self, file: &Path, indent: usize) -> Result<String> {
2303        let (out, err): (Option<String>, Option<String>) =
2304            self.checker_call("format", (path_str(file), indent))?;
2305        out.ok_or_else(|| anyhow!("{}", err.unwrap_or_else(|| "format failed".into())))
2306    }
2307
2308    /// [`format_file`](Self::format_file) for text that is not (yet) a file: `text` is
2309    /// formatted as the file `file` would be if it held it, and `file` only names it in an
2310    /// error. For a caller that holds a buffer the file on disk does not match (`htl lsp`).
2311    pub fn format_text(&self, text: &str, file: &Path, indent: usize) -> Result<String> {
2312        let (out, err): (Option<String>, Option<String>) =
2313            self.checker_call("format_text", (text, path_str(file), indent))?;
2314        out.ok_or_else(|| anyhow!("{}", err.unwrap_or_else(|| "format failed".into())))
2315    }
2316
2317    /// The `_VERSION` field a module's source states, as the prelude's reader gives it
2318    /// (`runtime_version.lua`): `("found", Some(text))`, `("not_literal", None)`,
2319    /// `("missing", None)` or `("unparsable", Some(first parse error))`. The source is parsed, not run; `chunk` names it and decides
2320    /// whether it is read as Teal (`.tl`) or Lua. [`shapes::runtime_version`] is the typed
2321    /// reader of this and the one to call.
2322    pub(crate) fn version_field(&self, src: &str, chunk: &str) -> Result<(String, Option<String>)> {
2323        self.checker_call("runtime_version", (src, chunk))
2324    }
2325
2326    /// Drop Lua's default search path (cwd-relative `./?.lua` etc.) so only directories
2327    /// passed to [`add_path`](Self::add_path) are consulted by the checker and `require`.
2328    pub fn reset_search_path(&self) -> Result<()> {
2329        self.checker_call::<()>("reset_path", ())?;
2330        if self.split() {
2331            let f: Function = self.runtime()?.get("reset_path")?;
2332            f.call::<()>(())?;
2333        }
2334        Ok(())
2335    }
2336
2337    /// Drop the entries of Lua's default search path that are relative to the working
2338    /// directory (`./?.lua`, `./?/init.lua`), keeping the rest.
2339    ///
2340    /// What a name means must not depend on where the command was run. A checker set up
2341    /// from a project's model (`model::Project`, with the `pkg` and `dts` features) calls this: the names come from the
2342    /// project's roots, and the working directory is none of them. What stays are the
2343    /// directories Lua itself was built to search (`/usr/local/share/lua/5.4/…`), where a
2344    /// library installed for the machine is found at run time. A host that builds its own
2345    /// path from nothing calls [`reset_search_path`](Self::reset_search_path) instead.
2346    pub fn drop_cwd_search_path(&self) -> Result<()> {
2347        self.checker_call::<()>("drop_cwd_path", ())?;
2348        if self.split() {
2349            let f: Function = self.runtime()?.get("drop_cwd_path")?;
2350            f.call::<()>(())?;
2351        }
2352        Ok(())
2353    }
2354
2355    /// Prepend `dir` to `package.path` (Teal resolves requires through it) as a directory
2356    /// of modules mounted at the top: `dir/<a>/<b>.tl` is `a.b`, and `dir/<a>/init.tl` is
2357    /// `a`. A directory already on the path keeps its place.
2358    ///
2359    /// A file named after its directory is an ordinary submodule here — `dir/util/util.tl`
2360    /// is `util.util`, not `util` ([`naming`]). That spelling belongs to a directory of
2361    /// packages: [`add_package_path`](Self::add_package_path).
2362    pub fn add_path(&self, dir: &Path) -> Result<()> {
2363        self.add_path_as(dir, false)
2364    }
2365
2366    /// Prepend `dir` to `package.path` as a directory that holds packages by name — the
2367    /// dependency links under `.htl/modules/entries`, the parent of a vendored copy or a
2368    /// patch: `dir/<name>/init.tl` is `<name>`, and so is `dir/<name>/<name>.tl`, a flat
2369    /// package's entry ([`naming`]).
2370    ///
2371    /// The flat entry is the `?/?.lua` template, and a template substitutes the whole name
2372    /// for each `?`: `require("a.b")` also reaches `dir/a/b/a/b.tl`, a file the naming
2373    /// rule calls `a.b.a.b`. A run-time resolver over the same directory
2374    /// (`pkg::TealResolver::holding_packages`) does not serve it for `a.b`, so the check
2375    /// passes and the run fails (#320).
2376    ///
2377    /// Kept for a host that does not describe a project, and for
2378    /// [`apply_project`](Self::apply_project). A host's directory of packages is
2379    /// `model::HostDir::Packages` in a model built with `model::Project::for_host`; the
2380    /// checker is then `Htl::apply_model` and the run `pkg::TealResolver::from_project`
2381    /// (feature `dts`), both reading that one description.
2382    pub fn add_package_path(&self, dir: &Path) -> Result<()> {
2383        self.add_path_as(dir, true)
2384    }
2385
2386    fn add_path_as(&self, dir: &Path, packages: bool) -> Result<()> {
2387        self.checker_call::<()>("add_path", (path_str(dir), packages))?;
2388        if self.split() {
2389            // The program state resolves plain `.lua` (and `.d.tl` siblings) itself.
2390            let f: Function = self.runtime()?.get("add_path")?;
2391            f.call::<()>((path_str(dir), packages))?;
2392        }
2393        Ok(())
2394    }
2395
2396    /// Install the strict `.tl` searcher: `require` of a `.tl` with type errors fails.
2397    ///
2398    /// A name only a `.d.tl` declares, with no `.lua` behind it on `package.path`, is
2399    /// answered by the language of the chunk that asked ([`ModuleKind::Declaration`]): a
2400    /// `require` from a `.tl` gets a table that explains itself when indexed, and one from
2401    /// plain Lua fails naming the declaration, as through a `pkg` `Registry`. The caller is
2402    /// found with `debug.getinfo`; a state without the `debug` library gets the table for
2403    /// every caller.
2404    pub fn install_searcher(&self) -> Result<()> {
2405        // What the searcher answers a plain-Lua `require` of a declaration with: made in
2406        // the program state, where the searcher runs, from the one text the `Registry`'s
2407        // trailing searcher uses too.
2408        let decline = self
2409            .lua
2410            .create_function(|_, (module, decl): (String, String)| {
2411                Ok(declaration_only_message(&module, &decl))
2412            })?;
2413        if self.split() {
2414            // The searcher runs in the program state and asks the checker for code, in this
2415            // state's program.
2416            //
2417            // Both states are in hand here and nothing crosses: `bridge` is built in
2418            // `self.lua` and handed to `runtime()`, which is a table out of `self.lua`'s
2419            // own registry. The checker's `gen_for_require` is only ever *called* — its
2420            // arguments and results are Rust values on the way through, which is what a
2421            // value has to be to pass between two states.
2422            let checker = self.h.clone();
2423            let bridge = self.lua.create_function(move |_, name: String| {
2424                let (kind, a, b): (String, Option<String>, Option<String>) =
2425                    checker.call("gen_for_require", name)?;
2426                Ok((kind, a, b))
2427            })?;
2428            let f: Function = self.runtime()?.get("install_searcher")?;
2429            f.call::<()>((bridge, decline))?;
2430            return Ok(());
2431        }
2432        self.checker_call("install_searcher", decline)
2433    }
2434
2435    /// Register generated Lua source under a module name (`package.preload`).
2436    ///
2437    /// The chunk is named after the `.tl` a `require` of this name would have found —
2438    /// `foo.bar` becomes `@foo/bar.tl` — because that name is what a run-time failure
2439    /// shows, and a reader who has only the output needs something to open. Use
2440    /// [`Htl::preload_at`] when the source sits somewhere else (`@scripts/util.tl`), or
2441    /// when there is no file at all and a bare label is the honest answer (`=htl.test`).
2442    pub fn preload(&self, name: &str, lua_src: &str) -> Result<()> {
2443        self.preload_at(name, &module_chunk_name(name), lua_src)
2444    }
2445
2446    /// [`Htl::preload`] with the chunk name spelled out, the way [`Htl::exec`] takes one.
2447    /// `@<path>` is a source location and is what a host with a file should pass;
2448    /// `=<label>` is a literal label, for a module no file backs.
2449    pub fn preload_at(&self, name: &str, chunk_name: &str, lua_src: &str) -> Result<()> {
2450        let loader = self
2451            .lua
2452            .load(lua_src)
2453            .set_name(chunk_name)
2454            .into_function()
2455            .with_context(|| format!("compiling preloaded module {name}"))?;
2456        self.preload_table()?.set(name, loader)?;
2457        Ok(())
2458    }
2459
2460    /// Register stripped bytecode (e.g. from `include_tl_bytes!`) under a module name.
2461    ///
2462    /// A chunk name is worth less here than it is to [`Htl::preload`], and the reason is
2463    /// worth knowing before reading a failure from an embedded module: a compiled chunk
2464    /// carries its own name, given when it was compiled, and `lua_load`'s name is used
2465    /// only for the messages loading itself produces. Stripping drops the carried name
2466    /// along with the line numbers, so every frame from a stripped payload reads `?` —
2467    /// `?: in function 'sample.greet'`. Running the `.tl` under `htl run` or `htl test`
2468    /// is where those frames are; a bundle keeps them with `htl build --debug`.
2469    pub fn preload_bytes(&self, name: &str, bytecode: &[u8]) -> Result<()> {
2470        let loader = self
2471            .lua
2472            .load(bytecode)
2473            .set_name(module_chunk_name(name))
2474            .set_mode(ChunkMode::Binary)
2475            .into_function()
2476            .with_context(|| format!("loading bytecode for module {name}"))?;
2477        self.preload_table()?.set(name, loader)?;
2478        Ok(())
2479    }
2480
2481    /// Execute stripped bytecode with `...` = args.
2482    pub fn exec_bytes(&self, bytecode: &[u8], chunk_name: &str, args: &[String]) -> Result<()> {
2483        vm(&self.lua)?;
2484        let f = self
2485            .lua
2486            .load(bytecode)
2487            .set_name(chunk_name)
2488            .set_mode(ChunkMode::Binary)
2489            .into_function()?;
2490        let va: Variadic<String> = args.iter().cloned().collect();
2491        f.call::<()>(va)?;
2492        Ok(())
2493    }
2494
2495    /// Register a ready-made value (typically a Rust-built table) as a module.
2496    pub fn preload_value(&self, name: &str, value: impl mlua::IntoLua) -> Result<()> {
2497        let value = value.into_lua(&self.lua)?;
2498        let loader = self.lua.create_function(move |_, ()| Ok(value.clone()))?;
2499        self.preload_table()?.set(name, loader)?;
2500        Ok(())
2501    }
2502
2503    fn preload_table(&self) -> Result<Table> {
2504        let package: Table = self.lua.globals().get("package")?;
2505        Ok(package.get("preload")?)
2506    }
2507
2508    /// Set the global `arg` table like the `lua` CLI does — and like `htl run` does.
2509    /// [`exec`](Self::exec) passes its arguments to the script as `...` and nothing else,
2510    /// so a script that reads `arg[1]` needs this before `exec`; with it the same
2511    /// `main.tl` runs unchanged under `htl run` and embedded (`htl new --embed` writes
2512    /// both calls).
2513    pub fn set_arg(&self, script: &str, args: &[String]) -> Result<()> {
2514        let t = self.lua.create_table()?;
2515        t.set(0, script)?;
2516        for (i, a) in args.iter().enumerate() {
2517            t.set(i + 1, a.as_str())?;
2518        }
2519        self.lua.globals().set("arg", t)?;
2520        Ok(())
2521    }
2522
2523    /// Make arithmetic on a string a run-time error instead of a conversion.
2524    ///
2525    /// Lua 5.4 reads `"10" + 1` as `11`: the string library's metatable carries `__add`
2526    /// and the other seven arithmetic metamethods, and each one converts its string
2527    /// operands and retries. Checked Teal never gets there: the checker refuses the
2528    /// expression on a `string`, and on an `any` too, and `tonumber(...)` is a `number`
2529    /// that no `integer` accepts. It happens in what the checker did
2530    /// not see — the far side of a cast (`(v as integer) + 1` where `v` came from
2531    /// `std.json.decode` or `arg` as `"10"`), a function `load` built from a string, Lua
2532    /// source a host handed to [`exec`](Self::exec) — and there the conversion is
2533    /// silent. This removes the eight from the string metatable of the program state, so
2534    /// the same expression fails as `attempt to perform arithmetic on a string value`,
2535    /// naming the operand.
2536    ///
2537    /// What it does not cover, because Lua does those elsewhere: `10 .. ""` (number to
2538    /// string under concatenation is in the VM, behind Lua's `LUA_NOCVTN2S` build flag,
2539    /// which is the vendored Lua's to set); `"10" < "9"` (a string comparison, true, and
2540    /// not a conversion); and `tonumber` / `math.tointeger`, which convert because they
2541    /// were asked to. `__index` stays, so `s:upper()` and every other string method are
2542    /// untouched. Between this layer and the host's own arguments (`Strict<T>`) sits the
2543    /// program's: a value that arrives as `any` is converted once, where it arrives, by the
2544    /// program — `s:match("^%-?%d+$")` and `math.tointeger` when hex, an exponent and
2545    /// surrounding whitespace are not wanted, `tonumber` when they are — and never by a
2546    /// cast, which converts nothing and only tells the checker to stop looking.
2547    ///
2548    /// Opt-in, for a host's `preload` beside `install_std`; the CLI does not turn it on,
2549    /// since `htl run` and `htl test` run Teal the checker has passed. Calling it twice is
2550    /// the same as once. In a state that also holds the checker (the default; see
2551    /// [`with_checker`](Self::with_checker) for the split) the checker runs under it too,
2552    /// which it can: nothing in `tl` adds a string to a number.
2553    pub fn strict_strings(&self) -> Result<()> {
2554        self.lua
2555            .load(
2556                r#"
2557local mt = getmetatable("")
2558for _, k in ipairs { "__add", "__sub", "__mul", "__div", "__mod", "__pow", "__unm", "__idiv" } do
2559   mt[k] = nil
2560end
2561"#,
2562            )
2563            .set_name("=strict_strings")
2564            .exec()
2565            .context("removing arithmetic metamethods from the string metatable")?;
2566        Ok(())
2567    }
2568
2569    /// Execute Lua source with `...` = args. The global `arg` is not set here; that is
2570    /// [`set_arg`](Self::set_arg).
2571    ///
2572    /// `chunk_name` is the name every frame of a run-time failure inside the chunk is
2573    /// reported under. `@<path>` is a source location and prints as the path, so
2574    /// `@scripts/main.tl` gives a reader something to open; `=<label>` is a bare label,
2575    /// the honest answer for a chunk no file backs, which is how htl registers its own
2576    /// test library as `=htl.test`. [`preload`](Self::preload) derives the name from the
2577    /// module name; [`preload_at`](Self::preload_at) takes one, as this does.
2578    pub fn exec(&self, lua_src: &str, chunk_name: &str, args: &[String]) -> Result<()> {
2579        vm(&self.lua)?;
2580        let f = self
2581            .lua
2582            .load(lua_src)
2583            .set_name(chunk_name)
2584            .into_function()?;
2585        let va: Variadic<String> = args.iter().cloned().collect();
2586        f.call::<()>(va)?;
2587        Ok(())
2588    }
2589
2590    /// Run `f(args)` as a root coroutine on the executor, under `token`: what
2591    /// [`run_async`](Self::run_async) does once the chunk is loaded, for a function the
2592    /// caller already holds (a bundle's entry from [`load_bundle`](Self::load_bundle), the
2593    /// test library's `run`). Resolves to what `f` returned, or to the error it raised,
2594    /// or — when `token` was cancelled — to an error [`is_cancelled`] recognises.
2595    #[cfg(feature = "async")]
2596    pub async fn call_async(
2597        &self,
2598        f: Function,
2599        args: impl mlua::IntoLuaMulti,
2600        token: &mlua_isle::runtime::CancelToken,
2601    ) -> Result<mlua::MultiValue> {
2602        let vm = vm(&self.lua)?;
2603        vm.run(token, f, args).await.map_err(isle_error)
2604    }
2605
2606    /// Run `lua_src` (named `chunk_name`, with `...` = `args`) as a root coroutine on
2607    /// the executor, under `token`: the program may call a host's `async fn` — the call
2608    /// suspends the coroutine and resumes it with the value — where
2609    /// [`exec`](Self::exec) would fail with *attempt to yield from outside a coroutine*.
2610    /// This is how `htl run` and `htl test` run a program; a host that has a tokio
2611    /// runtime of its own awaits this inside its
2612    /// [`LocalSet`](https://docs.rs/tokio/latest/tokio/task/struct.LocalSet.html), and one
2613    /// that has none calls [`run_blocking`](Self::run_blocking).
2614    ///
2615    /// Two things the runtime it is awaited on has to be: current-thread or a `LocalSet`
2616    /// (the Lua state is not `Send`), and built with a time driver (`enable_all()`, or
2617    /// `enable_time()`): the grace a cancelled program gets is a tokio timeout, and a
2618    /// runtime without one panics at the first cancel. And one thing the caller does:
2619    /// await the future to the end rather than drop it. When it resolves, nothing the
2620    /// program started is alive — its tasks have finished or been dropped, on the cancel
2621    /// path too; a future dropped early only schedules them for abort.
2622    ///
2623    /// Cancelling `token` (from a Ctrl-C handler, a timeout, another thread) raises the
2624    /// cancel in the program at its next hook check or await; what happens then is the
2625    /// grace, [`config::AsyncConfig`]. The future then resolves to an error
2626    /// [`is_cancelled`] answers true for, whatever the program did with the cancel.
2627    ///
2628    /// The error of a program that raises is the same `mlua::Error` shape `exec` returns
2629    /// — message and `stack traceback:` block — so [`developer_message`] and
2630    /// [`user_message`] print it the same. The frames below the program's own are the
2631    /// executor's.
2632    #[cfg(feature = "async")]
2633    pub async fn run_async(
2634        &self,
2635        lua_src: &str,
2636        chunk_name: &str,
2637        args: &[String],
2638        token: &mlua_isle::runtime::CancelToken,
2639    ) -> Result<()> {
2640        let f = self
2641            .lua
2642            .load(lua_src)
2643            .set_name(chunk_name)
2644            .into_function()?;
2645        let va: Variadic<String> = args.iter().cloned().collect();
2646        self.call_async(f, va, token).await?;
2647        Ok(())
2648    }
2649
2650    /// [`call_async`](Self::call_async) driven to the end on a runtime of its own: a
2651    /// current-thread tokio runtime with its time driver and a `LocalSet`, built for this
2652    /// call and dropped after it. For a caller that is not itself async.
2653    #[cfg(feature = "async")]
2654    pub fn call_blocking(
2655        &self,
2656        f: Function,
2657        args: impl mlua::IntoLuaMulti,
2658        token: &mlua_isle::runtime::CancelToken,
2659    ) -> Result<mlua::MultiValue> {
2660        let rt = tokio::runtime::Builder::new_current_thread()
2661            .enable_all()
2662            .build()
2663            .context("building the executor's runtime")?;
2664        let local = tokio::task::LocalSet::new();
2665        local.block_on(&rt, self.call_async(f, args, token))
2666    }
2667
2668    /// [`run_async`](Self::run_async) driven to the end on a runtime of its own (see
2669    /// [`call_blocking`](Self::call_blocking)): what `htl test` does with each file.
2670    #[cfg(feature = "async")]
2671    pub fn run_blocking(
2672        &self,
2673        lua_src: &str,
2674        chunk_name: &str,
2675        args: &[String],
2676        token: &mlua_isle::runtime::CancelToken,
2677    ) -> Result<()> {
2678        let f = self
2679            .lua
2680            .load(lua_src)
2681            .set_name(chunk_name)
2682            .into_function()?;
2683        let va: Variadic<String> = args.iter().cloned().collect();
2684        self.call_blocking(f, va, token)?;
2685        Ok(())
2686    }
2687
2688    /// Check + gen + run a `.tl` script. If the check fails the script is not run and the
2689    /// returned `CheckInfo` carries the errors. Runtime errors come back as `Err`.
2690    pub fn run_file(&self, file: &Path, args: &[String]) -> Result<CheckInfo> {
2691        self.add_path(&parent_dir(file))?;
2692        self.install_searcher()?;
2693        self.set_arg(&file.to_string_lossy(), args)?;
2694        let (code, ci) = self.gen_lua(file)?;
2695        let Some(code) = code else { return Ok(ci) };
2696        self.exec(&code, &format!("@{}", file.display()), args)?;
2697        Ok(ci)
2698    }
2699
2700    /// Compile Lua source to stripped bytecode (Lua 5.4 format of this build).
2701    pub fn compile(&self, name: &str, lua_src: &str) -> Result<Vec<u8>> {
2702        self.compile_with(name, lua_src, true)
2703    }
2704
2705    /// Compile to bytecode; `strip` drops debug info — line numbers, local and upvalue
2706    /// names, and the chunk name, so every frame from the stripped payload reads `?`
2707    /// whatever name the load was given ([`preload_bytes`](Self::preload_bytes)).
2708    pub fn compile_with(&self, name: &str, lua_src: &str, strip: bool) -> Result<Vec<u8>> {
2709        let f = self
2710            .lua
2711            .load(lua_src)
2712            .set_name(format!("={name}"))
2713            .into_function()
2714            .with_context(|| format!("compiling generated Lua for {name}"))?;
2715        Ok(f.dump(strip))
2716    }
2717
2718    /// The Lua bytecode header this state produces (signature, version, format,
2719    /// `LUAC_DATA`, sizes of Instruction / Integer / Number, endianness probes): what
2720    /// another state must match to load this state's bytecode. Lua's own version byte
2721    /// is the same for every 5.4.x, so bundles carry this instead.
2722    pub fn fingerprint(&self) -> Result<Vec<u8>> {
2723        let bc = self.compile_with("fp", "return 0", true)?;
2724        // 4 signature + 1 version + 1 format + 6 LUAC_DATA + 3 sizes + 8 LUAC_INT + 8 LUAC_NUM
2725        Ok(bc.iter().take(31).copied().collect())
2726    }
2727
2728    /// The module names a Teal source `require`s by literal, read from its syntax alone —
2729    /// no type check and no resolution, so asking it of every file in a tree is cheap.
2730    /// `None` when the source does not parse: which names it requires is then not known,
2731    /// which is a different answer from requiring none.
2732    pub fn tl_require_names(&self, src: &str, file: &Path) -> Result<Option<Vec<String>>> {
2733        let t: Option<Table> = self.checker_call("tl_require_names", (src, path_str(file)))?;
2734        t.map(|t| {
2735            t.sequence_values::<String>()
2736                .collect::<mlua::Result<Vec<_>>>()
2737        })
2738        .transpose()
2739        .map_err(Into::into)
2740    }
2741
2742    /// Literal `require`s of a plain Lua source, resolved through the checker's path.
2743    pub fn lua_requires(&self, src: &str, file: &Path) -> Result<Vec<RequireSite>> {
2744        let t: Table = self.checker_call("lua_requires", (src, path_str(file)))?;
2745        read_requires(&t)
2746    }
2747
2748    /// Where `require(name)` resolves for the checker (`.tl`, `.d.tl` or `.lua`), and
2749    /// where a plain `.lua` implementation sits on the path (a `.d.tl` may only be
2750    /// typing it). Either may be `None`.
2751    pub fn resolve_module(&self, name: &str) -> Result<(Option<PathBuf>, Option<PathBuf>)> {
2752        let (found, lua): (Option<String>, Option<String>) =
2753            self.checker_call("resolve_module", name)?;
2754        Ok((found.map(PathBuf::from), lua.map(PathBuf::from)))
2755    }
2756
2757    /// Why `name` resolves to nothing although files answer to it: the project model's
2758    /// message when more than one of them implements it. `None` when it does not, or when
2759    /// no model is installed (`Htl::apply_model`).
2760    pub fn ambiguity(&self, name: &str) -> Result<Option<String>> {
2761        self.checker_call("ambiguity", name)
2762    }
2763
2764    /// Why `name` is refused although the host provides it: the project model's message
2765    /// when a file of the model implements the name as well (the model's
2766    /// `Resolution::HostShadowed`). `None` when no file
2767    /// does, when the host does not provide the name, or when no model is installed
2768    /// (`Htl::apply_model`).
2769    ///
2770    /// [`resolve_module`](Self::resolve_module) answers such a name with its declaration,
2771    /// or with nothing, never with the file — which on its own reads as a host module, or
2772    /// as a missing one. This is what says it is neither: an error wherever the name is
2773    /// required, the way [`ambiguity`](Self::ambiguity) says it for two implementations.
2774    pub fn host_shadowing(&self, name: &str) -> Result<Option<String>> {
2775        self.checker_call("host_shadowing", name)
2776    }
2777
2778    /// Whether `name` runs from no file of the project, as the project model says it: the
2779    /// model's resolver's `provides` (`model::Resolver::provides`) — a name the host
2780    /// provides, or one the model has only a declaration for, which the environment
2781    /// provides. [`Provision::Unknown`] when no model is installed (`Htl::apply_model`)
2782    /// or the model has nothing under the name; the caller's own search is then the one
2783    /// that answers, as it is for [`resolve_module`](Self::resolve_module).
2784    ///
2785    /// What the linker asks before it leaves a declared name out of a bundle, rather than
2786    /// deciding that from a lookup of its own ([`link`]).
2787    pub fn model_provides(&self, name: &str) -> Result<Provision> {
2788        if !self.h.has("provides_name")? {
2789            return Ok(Provision::Unknown);
2790        }
2791        let tag: Option<String> = self.checker_call("provides_name", name)?;
2792        Ok(match tag.as_deref() {
2793            None => Provision::Unknown,
2794            Some("none") => Provision::Files,
2795            Some(_) => Provision::Provided(tag.unwrap_or_default()),
2796        })
2797    }
2798
2799    /// Every file on the search path that could answer `require(name)`, in the order the
2800    /// searchers consult them — so the first is the one [`resolve_module`](Self::resolve_module)
2801    /// answers with, and the rest are what it hides.
2802    ///
2803    /// The same walk `declaration_sites` does for the `duplicate-declaration` lint, over
2804    /// all three kinds rather than declarations alone: a searcher answers with the first
2805    /// hit and says nothing about the others, and which of two files is read is decided by
2806    /// a position nobody wrote down. [`contract::resolve`] is what turns this into a report.
2807    pub fn module_candidates(&self, name: &str) -> Result<Vec<ModuleCandidate>> {
2808        let t: Table = self.checker_call("module_candidates", name)?;
2809        let mut out = Vec::new();
2810        for c in t.sequence_values::<Table>() {
2811            let c = c?;
2812            out.push(ModuleCandidate {
2813                path: PathBuf::from(c.get::<String>("path")?),
2814                kind: ModuleKind::of(&c.get::<String>("kind")?),
2815                dir: PathBuf::from(c.get::<String>("dir")?),
2816            });
2817        }
2818        Ok(out)
2819    }
2820
2821    /// The directories the search path consults, in order. One entry per directory,
2822    /// however many `package.path` templates it contributes.
2823    pub fn search_path_dirs(&self) -> Result<Vec<PathBuf>> {
2824        let t: Table = self.checker_call("search_dirs", ())?;
2825        Ok(t.sequence_values::<String>()
2826            .collect::<mlua::Result<Vec<_>>>()?
2827            .into_iter()
2828            .map(PathBuf::from)
2829            .collect())
2830    }
2831
2832    /// The names each bundle wrote into `package.preload`, keyed by the bundle's entry.
2833    ///
2834    /// In the registry rather than in the `Htl`: it is a fact about the Lua state, and a
2835    /// `&Htl` is shared, so a `RefCell` here would be a second place to keep the same
2836    /// thing in step with. What it is for is [`replace_bundle`](Self::replace_bundle) — a
2837    /// bundle can take back the names it installed only if something remembers which
2838    /// those were, and which belonged to the host all along.
2839    fn bundle_record(&self) -> Result<Table> {
2840        if let Value::Table(t) = self
2841            .lua
2842            .named_registry_value::<Value>(BUNDLE_REGISTRY_KEY)?
2843        {
2844            return Ok(t);
2845        }
2846        let t = self.lua.create_table()?;
2847        self.lua
2848            .set_named_registry_value(BUNDLE_REGISTRY_KEY, t.clone())?;
2849        Ok(t)
2850    }
2851
2852    /// The two questions asked before a bundle touches the state, so that a caller that
2853    /// is about to disturb what is already there can ask them first
2854    /// ([`replace_bundle`](Self::replace_bundle) drops modules, and a refusal after that
2855    /// would leave the host with neither the old ones nor the new).
2856    ///
2857    /// Both are reads. Running it twice — once by the caller, once by
2858    /// [`install_bundle`](Self::install_bundle), which stays correct on its own — costs a
2859    /// chunk dump and two table lookups and answers the same either way: the names it
2860    /// checks for are the host's, and a replace never removes one of those.
2861    fn check_installable(&self, b: &bundle::Bundle) -> Result<()> {
2862        // Bytecode from a Lua that disagrees with ours would fail with "bad binary
2863        // format" somewhere inside the first require; say what differs instead.
2864        // The header cannot tell one 5.4.x from another, so the htl versions go in the
2865        // message too: they are the only record of which Lua produced each side.
2866        if b.modules.iter().any(|m| m.kind == bundle::Kind::Bytecode) && !b.fingerprint.is_empty() {
2867            let mine = self.fingerprint()?;
2868            if mine != b.fingerprint {
2869                let built_by = if b.htl_version.is_empty() {
2870                    "an htl that did not record its version".to_string()
2871                } else {
2872                    format!("htl {}", b.htl_version)
2873                };
2874                bail!(
2875                    "bundle bytecode was compiled for {} by {built_by}, but this host runs {} on htl {}; \
2876                     rebuild the bundle here, or build it with --source",
2877                    bundle::describe_fingerprint(&b.fingerprint),
2878                    bundle::describe_fingerprint(&mine),
2879                    env!("CARGO_PKG_VERSION")
2880                );
2881            }
2882        }
2883        // Host-provided modules must already be registered, or the program's first
2884        // require of them fails with a message that points at the wrong place.
2885        let package: Table = self.lua.globals().get("package")?;
2886        let preload: Table = package.get("preload")?;
2887        let loaded: Table = package.get("loaded")?;
2888        let missing: Vec<&String> = b
2889            .host_modules
2890            .iter()
2891            .filter(|n| {
2892                matches!(preload.get::<Value>(n.as_str()), Ok(Value::Nil))
2893                    && matches!(loaded.get::<Value>(n.as_str()), Ok(Value::Nil))
2894            })
2895            .collect();
2896        if !missing.is_empty() {
2897            bail!(
2898                "bundle expects host-provided module(s) {} (declared only by a .d.tl or [build] host at link \
2899                 time): register them with preload / preload_value / htl_preload before running",
2900                missing
2901                    .iter()
2902                    .map(|m| format!("'{m}'"))
2903                    .collect::<Vec<_>>()
2904                    .join(", ")
2905            );
2906        }
2907        Ok(())
2908    }
2909
2910    /// Install a searcher serving modules from a bundle.
2911    ///
2912    /// Bundled modules become `package.preload` entries, the same place a host puts its
2913    /// own modules, so everything that already defers to preload — a `.d.tl` stepping
2914    /// aside for the implementation, an mlua-pkg resolver over a mods directory — sees
2915    /// them too, and files on disk do not override the bundle. A name the host preloaded
2916    /// first is left alone: the host wins.
2917    ///
2918    /// Idempotent, and deliberately so: a second call installs nothing, because every
2919    /// name is taken by the first. Putting a *newer* bundle into a state that is already
2920    /// running is [`replace_bundle`](Self::replace_bundle).
2921    pub fn install_bundle(&self, b: &bundle::Bundle) -> Result<()> {
2922        self.check_installable(b)?;
2923        let package: Table = self.lua.globals().get("package")?;
2924        let preload: Table = package.get("preload")?;
2925        // Bundled modules become `package.preload` entries: the same place a host puts
2926        // its own modules, so everything that already defers to preload (a `.d.tl`
2927        // stepping aside for the implementation, mlua-pkg resolvers ahead of Lua's
2928        // searchers) sees them without knowing about bundles. A name the host preloaded
2929        // first is left alone: the host wins. Loaders get (modname, ":preload:") as
2930        // Lua's preload searcher passes them.
2931        let mut written: Vec<String> = Vec::new();
2932        for m in &b.modules {
2933            if !matches!(preload.get::<Value>(m.name.as_str())?, Value::Nil) {
2934                continue;
2935            }
2936            let payload = m.payload.clone();
2937            let kind = m.kind;
2938            let name = m.name.clone();
2939            let loader =
2940                self.lua
2941                    .create_function(move |lua, (modname, origin): (String, Value)| {
2942                        let chunk = lua.load(payload.as_slice()).set_name(format!("={name}"));
2943                        let f = match kind {
2944                            bundle::Kind::Bytecode => {
2945                                chunk.set_mode(ChunkMode::Binary).into_function()?
2946                            }
2947                            bundle::Kind::Source => {
2948                                chunk.set_mode(ChunkMode::Text).into_function()?
2949                            }
2950                        };
2951                        f.call::<Value>((modname, origin))
2952                    })?;
2953            preload.set(m.name.as_str(), loader)?;
2954            written.push(m.name.clone());
2955        }
2956        // Only what this call wrote, and added to whatever the entry already had: a name
2957        // skipped above was the host's and is not this bundle's to take back, and a
2958        // second install of the same bundle writes nothing and must not erase the record
2959        // the first one made.
2960        let record = self.bundle_record()?;
2961        let names: Table = match record.get::<Value>(b.entry.as_str())? {
2962            Value::Table(t) => t,
2963            _ => {
2964                let t = self.lua.create_table()?;
2965                record.set(b.entry.as_str(), t.clone())?;
2966                t
2967            }
2968        };
2969        let already: Vec<String> = names
2970            .sequence_values::<String>()
2971            .collect::<mlua::Result<Vec<_>>>()?;
2972        for name in written {
2973            if !already.contains(&name) {
2974                names.push(name)?;
2975            }
2976        }
2977        Ok(())
2978    }
2979
2980    /// Put a newer bundle into a state that is already running: the modules the bundle
2981    /// recorded under the same entry go, `keep`'s loaded values stay, and the host's are
2982    /// untouched.
2983    ///
2984    /// Nothing is evaluated here. A dropped name is gone from `package.preload` and
2985    /// `package.loaded`, so the next `require` of it runs the new module; a name in
2986    /// `keep` keeps the value it already evaluated to, which is how a `world` or a `save`
2987    /// module carries state across the swap. The entry is not re-run either — what to do
2988    /// with it is the host's, and a frame loop holding a table asks for the entry again
2989    /// and swaps what it holds.
2990    ///
2991    /// A reference already taken is not reached by any of this. `local m = require
2992    /// "rules"` captured by a closure that is still running keeps the old table until that
2993    /// closure is gone. That is Lua, and no amount of bookkeeping here changes it.
2994    ///
2995    /// The bundle is checked before anything is dropped, so a refusal — a fingerprint
2996    /// that disagrees, a host module that was never registered — leaves the state as it
2997    /// was rather than holding neither bundle.
2998    pub fn replace_bundle(&self, b: &bundle::Bundle, keep: &[&str]) -> Result<Replaced> {
2999        self.check_installable(b)?;
3000        let package: Table = self.lua.globals().get("package")?;
3001        let preload: Table = package.get("preload")?;
3002        let loaded: Table = package.get("loaded")?;
3003        let record = self.bundle_record()?;
3004        let previous: Vec<String> = match record.get::<Value>(b.entry.as_str())? {
3005            Value::Table(t) => t
3006                .sequence_values::<String>()
3007                .collect::<mlua::Result<Vec<_>>>()?,
3008            _ => Vec::new(),
3009        };
3010        let (mut dropped, mut kept) = (Vec::new(), Vec::new());
3011        for name in &previous {
3012            // The preload entry goes either way: it is the old bundle's loader, and the
3013            // new bundle's belongs there. A kept name never reaches it — `package.loaded`
3014            // answers first — but if anything ever clears that, the next require should
3015            // find the module this state actually holds.
3016            preload.set(name.as_str(), Value::Nil)?;
3017            if keep.contains(&name.as_str()) {
3018                kept.push(name.clone());
3019            } else {
3020                loaded.set(name.as_str(), Value::Nil)?;
3021                dropped.push(name.clone());
3022            }
3023        }
3024        // Cleared, not merged into: a module the old bundle had and the new one does not
3025        // is gone, and a record that still named it would offer it to the next replace.
3026        record.set(b.entry.as_str(), Value::Nil)?;
3027        self.install_bundle(b)?;
3028        let added: Vec<String> = match record.get::<Value>(b.entry.as_str())? {
3029            Value::Table(t) => t
3030                .sequence_values::<String>()
3031                .collect::<mlua::Result<Vec<_>>>()?,
3032            _ => Vec::new(),
3033        };
3034        Ok(Replaced {
3035            dropped,
3036            kept,
3037            added,
3038        })
3039    }
3040
3041    /// Install the bundle and run its entry module with `...` = args. A host calls it
3042    /// after registering its own modules: a module the bundle records as host-provided
3043    /// that is not in `package.preload` is refused up front, naming it, rather than found
3044    /// missing at the first `require` inside the run.
3045    pub fn run_bundle(&self, b: &bundle::Bundle, args: &[String]) -> Result<()> {
3046        let main = self.load_bundle(b, args)?;
3047        vm(&self.lua)?;
3048        let va: Variadic<String> = args.iter().cloned().collect();
3049        main.call::<()>(va)?;
3050        Ok(())
3051    }
3052
3053    /// [`run_bundle`](Self::run_bundle) up to the call: install the bundle's modules, set
3054    /// `arg`, and hand back the entry as a function the caller runs — synchronously as
3055    /// `run_bundle` does, or on the executor with [`call_async`](Self::call_async) /
3056    /// [`call_blocking`](Self::call_blocking), which is what `htl run app.hb` does.
3057    pub fn load_bundle(&self, b: &bundle::Bundle, args: &[String]) -> Result<Function> {
3058        let entry = b
3059            .module(&b.entry)
3060            .cloned()
3061            .ok_or_else(|| anyhow!("entry module '{}' not in bundle", b.entry))?;
3062        self.install_bundle(b)?;
3063        self.set_arg(&b.entry, args)?;
3064        let chunk = self
3065            .lua
3066            .load(entry.payload.as_slice())
3067            .set_name(format!("={}", b.entry));
3068        Ok(match entry.kind {
3069            bundle::Kind::Bytecode => chunk.set_mode(ChunkMode::Binary).into_function()?,
3070            bundle::Kind::Source => chunk.set_mode(ChunkMode::Text).into_function()?,
3071        })
3072    }
3073}
3074
3075/// What the executor's error becomes on the way out: the shape `exec` returns, so the
3076/// two print the same. A Lua error is an `mlua::Error::RuntimeError` of the message and
3077/// the `stack traceback:` block mlua-isle took where it was raised (the innermost cause
3078/// for an error from Rust, as [`user_message`] would have found it); a cancel is
3079/// `mlua::Error::external(Cancelled)`, which [`is_cancelled`] recognises by value; the
3080/// rest (a setup failure) is the crate's own text.
3081#[cfg(feature = "async")]
3082fn isle_error(e: mlua_isle::IsleError) -> anyhow::Error {
3083    use mlua_isle::IsleError;
3084    match e {
3085        IsleError::Cancelled => mlua::Error::external(mlua_isle::Cancelled).into(),
3086        IsleError::Lua(f) => {
3087            // The runtime hands back the raised value's text, not the value: an
3088            // `Interrupt` (a Rust error the hook raised) has to be rebuilt as the type
3089            // `ffi::fail` recognises, and its message is htl's own constant.
3090            #[cfg(feature = "ffi")]
3091            if matches!(
3092                f.kind,
3093                mlua_isle::LuaErrorKind::External | mlua_isle::LuaErrorKind::Callback
3094            ) && f.message == ffi::Interrupted.to_string()
3095            {
3096                return mlua::Error::CallbackError {
3097                    traceback: f
3098                        .traceback
3099                        .as_deref()
3100                        .map(executor_frames_cut)
3101                        .unwrap_or_default(),
3102                    cause: std::sync::Arc::new(mlua::Error::external(ffi::Interrupted)),
3103                }
3104                .into();
3105            }
3106            let text = match &f.traceback {
3107                Some(tb) => format!("{}\n{}", f.message, executor_frames_cut(tb)),
3108                None => f.message.clone(),
3109            };
3110            match f.kind {
3111                mlua_isle::LuaErrorKind::Syntax => mlua::Error::SyntaxError {
3112                    message: text,
3113                    incomplete_input: false,
3114                }
3115                .into(),
3116                mlua_isle::LuaErrorKind::Memory => mlua::Error::MemoryError(text).into(),
3117                _ => mlua::Error::RuntimeError(text).into(),
3118            }
3119        }
3120        other => anyhow!("{other}"),
3121    }
3122}
3123
3124/// A traceback without the two frames every root has under it — the runtime's `xpcall`
3125/// and the wrapper that called it — which say nothing about the program and would tell a
3126/// reader of `htl run`'s output that something changed underneath it. Only the tail is
3127/// cut, and only when it is exactly those two lines.
3128#[cfg(feature = "async")]
3129fn executor_frames_cut(tb: &str) -> String {
3130    let lines: Vec<&str> = tb.trim_end().lines().collect();
3131    let n = lines.len();
3132    let is_executor = n >= 2
3133        && lines[n - 1].trim_start().starts_with("mlua_isle.root:")
3134        && lines[n - 2].trim_start() == "[C]: in function 'xpcall'";
3135    let keep = if is_executor {
3136        &lines[..n - 2]
3137    } else {
3138        &lines[..]
3139    };
3140    keep.join("\n")
3141}
3142
3143/// Whether `err` is the cancel of a run: what [`Htl::run_async`] and
3144/// [`Htl::call_async`] resolve to when their token was cancelled, however the program
3145/// took it — it is recognised by the value the runtime raised, never by its message. What
3146/// `htl run` reads to print `interrupted` instead of a traceback.
3147#[cfg(feature = "async")]
3148pub fn is_cancelled(err: &anyhow::Error) -> bool {
3149    err.downcast_ref::<mlua::Error>()
3150        .and_then(|e| e.downcast_ref::<mlua_isle::Cancelled>())
3151        .is_some()
3152}
3153
3154fn path_str(p: &Path) -> String {
3155    p.to_string_lossy().into_owned()
3156}
3157
3158/// The chunk name for a module registered without one: the `.tl` `require` would have
3159/// looked for, as a `@` source location. `htl.test` becomes `@htl/test.tl`, which is why
3160/// the test library asks for `=htl.test` instead — it ships inside the binary.
3161fn module_chunk_name(name: &str) -> String {
3162    format!("@{}.tl", name.replace('.', "/"))
3163}
3164
3165/// A message for the people an embedding host serves: the innermost cause without Lua's
3166/// `stack traceback:` block. A host function's `Err(e)` surfaces as `e`'s own text; a Lua
3167/// `error("msg")` surfaces as `file:line: msg`.
3168///
3169/// ```text
3170/// sgen: content/no-date.md: front matter: 'date' is required
3171/// ```
3172/// instead of that line followed by `stack traceback: [C]: in method 'pages' ...`.
3173///
3174/// This is the answer for a program whose users did not write the Teal and cannot act on
3175/// its frames — a static site generator telling an author which file is missing a date.
3176/// It is not the answer for whoever is developing the program: see
3177/// [`developer_message`], which is what `htl run` and `htl test` print.
3178pub fn user_message(err: &anyhow::Error) -> String {
3179    if let Some(e) = err.downcast_ref::<mlua::Error>() {
3180        return user_message_lua(e);
3181    }
3182    strip_traceback(&format!("{err:#}"))
3183}
3184
3185/// [`user_message`] for an error already held as mlua's own type, which is how a caller
3186/// that catches `mlua::Result` (the C ABI in `ffi`, say) has it.
3187pub fn user_message_lua(e: &mlua::Error) -> String {
3188    match e {
3189        mlua::Error::CallbackError { cause, .. } => user_message_lua(cause),
3190        mlua::Error::ExternalError(ext) => ext.to_string(),
3191        mlua::Error::WithContext { cause, .. } => user_message_lua(cause),
3192        other => strip_traceback(&other.to_string()),
3193    }
3194}
3195
3196/// A message for whoever is developing the program: [`user_message`]'s innermost cause,
3197/// followed by Lua's `stack traceback:` block when the error carries one.
3198///
3199/// ```text
3200/// depth.tl:8: attempt to index a nil value (local 'c')
3201/// stack traceback:
3202///     depth.tl:8: in function 'depth.field'
3203///     depth.tl:12: in function 'depth.describe'
3204///     boom.tl:3: in main chunk
3205/// ```
3206///
3207/// The innermost line says a value was nil; the frames say which caller passed it, and
3208/// they name Teal files and Teal lines because a generated chunk is loaded under its
3209/// source's own name. Nothing is mapped back: Teal keeps the input's line breaks when it
3210/// generates Lua, so a Lua frame is already a Teal frame. This is what `htl run` and
3211/// `htl test` print, for a failing test and for a file that raises while loading, and
3212/// what `--format json` carries unchanged in each file's `error` and `failures`. The
3213/// frames are absent
3214/// only where the debug information is: stripped bytecode, which is what a bundle without
3215/// `--debug` and `include_tl_bytes!` both hold.
3216pub fn developer_message(err: &anyhow::Error) -> String {
3217    let head = user_message(err);
3218    let full = match err.downcast_ref::<mlua::Error>() {
3219        Some(e) => e.to_string(),
3220        None => format!("{err:#}"),
3221    };
3222    match traceback_block(&full) {
3223        Some(tb) => format!("{head}\n{tb}"),
3224        None => head,
3225    }
3226}
3227
3228/// The `stack traceback:` block of an error text, trimmed, without the newline before it.
3229fn traceback_block(text: &str) -> Option<&str> {
3230    let at = text.find("\nstack traceback:")?;
3231    Some(text[at + 1..].trim_end())
3232}
3233
3234/// Remove a trailing Lua `stack traceback:` section from an error text.
3235pub fn strip_traceback(text: &str) -> String {
3236    let cut = text.find("\nstack traceback:").unwrap_or(text.len());
3237    text[..cut].trim_end().to_string()
3238}
3239
3240/// Write `text` to `path` only if the content differs. Returns `true` when written.
3241/// Used by the derive macros to emit `.d.tl` files without churning cargo's fingerprints.
3242pub fn write_if_changed(path: &Path, text: &str) -> std::io::Result<bool> {
3243    write_if_changed_when(path, text, true)
3244}
3245
3246/// [`write_if_changed`], writing only when `write` is set. Without it the answer is whether
3247/// the file would change — what a dry run reports — and nothing on disk is touched.
3248///
3249/// The write itself is atomic: a sibling temp file is written first and then renamed over
3250/// `path`, rather than truncating `path` in place. Two rustc processes can now write the
3251/// same `.d.tl` — a `#[host_module]`'s own expansion and `include_tl!`'s crate-wide scan
3252/// (`regenerate_crate` in `htl-macros`), each in the process building a different target
3253/// (the lib, a test) of the same crate — while a third reads it (`include_tl!` of some
3254/// other file, `htl check`); a plain `fs::write` lets that reader land between the
3255/// truncate and the write and see a half-written (or, briefly, empty) file. A rename onto
3256/// an existing path is atomic on the filesystems this runs on, so a reader always sees
3257/// either the old content or the new, never a mix.
3258pub fn write_if_changed_when(path: &Path, text: &str, write: bool) -> std::io::Result<bool> {
3259    if !write {
3260        return Ok(std::fs::read_to_string(path).map_or(true, |cur| cur != text));
3261    }
3262    if let Ok(cur) = std::fs::read_to_string(path)
3263        && cur == text
3264    {
3265        return Ok(false);
3266    }
3267    let dir = path.parent().unwrap_or_else(|| Path::new("."));
3268    std::fs::create_dir_all(dir)?;
3269    static COUNTER: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
3270    let n = COUNTER.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
3271    let name = path
3272        .file_name()
3273        .and_then(|n| n.to_str())
3274        .unwrap_or("htl-write");
3275    let tmp = dir.join(format!(".{name}.tmp-{}-{n}", std::process::id()));
3276    if let Err(e) = std::fs::write(&tmp, text) {
3277        let _ = std::fs::remove_file(&tmp);
3278        return Err(e);
3279    }
3280    if let Err(e) = std::fs::rename(&tmp, path) {
3281        let _ = std::fs::remove_file(&tmp);
3282        return Err(e);
3283    }
3284    Ok(true)
3285}
3286
3287/// Everything the libraries inside the binary write under [`lib_dir`]: the path each file
3288/// takes below that directory, and its source, sorted so that the order the parts are
3289/// collected in is not part of the answer.
3290///
3291/// The feature branch is here rather than in either library because this is the union, and
3292/// the union is what the directory is named after. Each library owns the half it writes
3293/// ([`testing::declarations`], [`batteries::declarations`]) and writes exactly that half,
3294/// so the name and the contents cannot drift apart.
3295fn bundled_declarations() -> Vec<(String, String)> {
3296    let mut out = testing::declarations();
3297    #[cfg(feature = "std")]
3298    out.extend(batteries::declarations());
3299    #[cfg(feature = "async")]
3300    out.extend(task::declarations());
3301    out.sort();
3302    out
3303}
3304
3305/// A directory name for a set of declarations: the first sixteen hex characters of a
3306/// blake3 over every path and source in it.
3307///
3308/// Sixteen because this is read by a person — in `htl resolve`'s searched-order line, in a
3309/// listing of the temp directory — and sixty-four bits is already far past what telling a
3310/// handful of builds on one machine apart asks for. Each part is length-prefixed so that
3311/// two different lists cannot hash alike by running together: `("ab", "c")` and
3312/// `("a", "bc")` are different keys.
3313///
3314/// Generic over the pair rather than `&[(String, String)]` so [`lib_dir`]'s own call
3315/// below and [`registry::Htl::install_declarations`](crate::Htl::install_declarations)'s
3316/// — which has no reason to allocate a `String` per path and source just to call this —
3317/// share the one hashing rule instead of each keeping a copy of it.
3318pub(crate) fn declarations_key<'a>(decls: impl IntoIterator<Item = (&'a str, &'a str)>) -> String {
3319    let mut h = blake3::Hasher::new();
3320    for (path, source) in decls {
3321        for part in [path, source] {
3322            h.update(&(part.len() as u64).to_le_bytes());
3323            h.update(part.as_bytes());
3324        }
3325    }
3326    h.finalize().to_hex()[..16].to_string()
3327}
3328
3329/// Where the libraries that ship inside the binary put their `.d.tl` so the checker can see
3330/// them: `<tmp>/htl-lib-<version>-<key>/`, with `htl/test.d.tl` and, under the `std`
3331/// feature, `std/*.d.tl` below it. The files are written on demand by the library that owns
3332/// them, only when their content changes.
3333///
3334/// The key is a hash over what this build would write, and not the version,
3335/// because the version does not tell two builds apart. `CARGO_PKG_VERSION` is the same on
3336/// the release and on every build from `main` after it, and those differ by exactly what
3337/// lands here: a binary with `std` writes `std/*.d.tl` that a binary without it cannot
3338/// preload, and one that found them on its search path type-checked a project against
3339/// modules it then failed to load (#220). Keyed by content, the two have different
3340/// directories and neither can see the other's; two builds that would write the same files
3341/// still share one, which is the case worth sharing.
3342///
3343/// The version stays in the name because that is what a person reading the path uses.
3344pub fn lib_dir() -> PathBuf {
3345    static DIR: OnceLock<PathBuf> = OnceLock::new();
3346    DIR.get_or_init(|| {
3347        let decls = bundled_declarations();
3348        let key = declarations_key(decls.iter().map(|(p, s)| (p.as_str(), s.as_str())));
3349        std::env::temp_dir().join(format!("htl-lib-{}-{key}", env!("CARGO_PKG_VERSION")))
3350    })
3351    .clone()
3352}
3353
3354/// Parent directory of a file, `.` when the path has none.
3355pub fn parent_dir(file: &Path) -> PathBuf {
3356    let dir = file.parent().unwrap_or(Path::new("."));
3357    if dir.as_os_str().is_empty() {
3358        PathBuf::from(".")
3359    } else {
3360        dir.to_path_buf()
3361    }
3362}
3363
3364fn read_checkinfo(t: &Table) -> Result<CheckInfo> {
3365    let seq = |key: &str| -> Result<Vec<String>> {
3366        let inner: Table = t.get(key)?;
3367        Ok(inner
3368            .sequence_values::<String>()
3369            .collect::<mlua::Result<_>>()?)
3370    };
3371    let requires = match t.get::<Table>("requires") {
3372        Ok(list) => read_requires(&list)?,
3373        Err(_) => Vec::new(),
3374    };
3375    let errors = seq("errors")?;
3376    let lints = seq("lints")?;
3377    let error_fixes = read_fixes(t, "error_fixes", errors.len())?;
3378    let lint_fixes = read_fixes(t, "lint_fixes", lints.len())?;
3379    let dependency_errors = match t.get::<Table>("dependency_errors") {
3380        Ok(list) => read_dependency_errors(&list)?,
3381        Err(_) => Vec::new(),
3382    };
3383    let warnings = seq("warnings")?;
3384    let global_sites = match t.get::<Table>("global_sites") {
3385        Ok(list) => list
3386            .sequence_values::<Table>()
3387            .map(|s| {
3388                let s = s?;
3389                Ok(GlobalSite {
3390                    name: s.get("name")?,
3391                    file: PathBuf::from(s.get::<String>("file")?),
3392                    line: s.get("y")?,
3393                    col: s.get("x")?,
3394                })
3395            })
3396            .collect::<Result<Vec<_>>>()?,
3397        Err(_) => Vec::new(),
3398    };
3399    // Absent from an older prelude's result (one built before `markers` existed), tolerated
3400    // the way `global_sites` above is: a missing table reads as no entries rather than an
3401    // error.
3402    let markers = match t.get::<Table>("markers") {
3403        Ok(list) => list
3404            .sequence_values::<Table>()
3405            .map(|s| {
3406                let s = s?;
3407                Ok(MarkerSite {
3408                    marker: s.get("marker")?,
3409                    kind: s.get("kind")?,
3410                    line: s.get("y")?,
3411                    name: s.get("name")?,
3412                })
3413            })
3414            .collect::<Result<Vec<_>>>()?,
3415        Err(_) => Vec::new(),
3416    };
3417    // Absent the same way `markers` above is, from a prelude built before this existed.
3418    let record_sites = match t.get::<Table>("record_sites") {
3419        Ok(list) => list
3420            .sequence_values::<Table>()
3421            .map(|s| {
3422                let s = s?;
3423                let record: Table = s.get("record")?;
3424                Ok(RecordSite {
3425                    record_file: record.get("file")?,
3426                    record_line: record.get("line")?,
3427                    record_name: record.get("name")?,
3428                    marked: s.get("marked")?,
3429                    line: s.get("y")?,
3430                    col: s.get("x")?,
3431                    kind: s.get("kind")?,
3432                    sealed: s.get("sealed")?,
3433                    complete: s.get("complete")?,
3434                })
3435            })
3436            .collect::<Result<Vec<_>>>()?,
3437        Err(_) => Vec::new(),
3438    };
3439    let closure_requires = match t.get::<Table>("closure_requires") {
3440        Ok(list) => list
3441            .sequence_values::<Table>()
3442            .map(|e| {
3443                let e = e?;
3444                Ok((
3445                    PathBuf::from(e.get::<String>("from")?),
3446                    e.get::<String>("name")?,
3447                ))
3448            })
3449            .collect::<Result<Vec<_>>>()?,
3450        Err(_) => Vec::new(),
3451    };
3452    let error_items = read_items(t, "error_items", Severity::Error, &error_fixes)?;
3453    let warning_items = read_items(t, "warning_items", Severity::Warning, &[])?;
3454    let lint_items = read_items(t, "lint_items", Severity::Lint, &lint_fixes)?;
3455    Ok(CheckInfo {
3456        errors,
3457        syntax_errors: t.get::<Option<usize>>("syntax_errors")?.unwrap_or(0),
3458        warnings,
3459        deps: seq("deps")?.into_iter().map(PathBuf::from).collect(),
3460        lints,
3461        requires,
3462        error_fixes,
3463        lint_fixes,
3464        dependency_errors,
3465        error_items,
3466        warning_items,
3467        lint_items,
3468        global_sites,
3469        markers,
3470        record_sites,
3471        closure_requires,
3472        // The index is an editor's extra and never what decides a check: one that cannot be
3473        // read is an empty one, not a check that failed.
3474        types: t
3475            .get::<Table>("type_index")
3476            .ok()
3477            .and_then(|index| typeindex::TypeIndex::read(&index).ok())
3478            .unwrap_or_default(),
3479    })
3480}
3481
3482/// The parts the checker kept beside each diagnostic's text (`item` in `prelude.lua`),
3483/// `fixes[i]` attached to the `i`th.
3484fn read_items(
3485    t: &Table,
3486    key: &str,
3487    severity: Severity,
3488    fixes: &[Option<Fix>],
3489) -> Result<Vec<Diagnostic>> {
3490    let Ok(list) = t.get::<Table>(key) else {
3491        return Ok(Vec::new());
3492    };
3493    let mut out = Vec::new();
3494    for (i, e) in list.sequence_values::<Table>().enumerate() {
3495        let e = e?;
3496        out.push(Diagnostic {
3497            severity,
3498            file: e.get("file")?,
3499            line: e.get("line")?,
3500            col: e.get("col")?,
3501            rule: e.get("rule")?,
3502            message: e.get("message")?,
3503            fix: fixes.get(i).and_then(|f| f.clone()),
3504            required_by: None,
3505            origin: None,
3506        });
3507    }
3508    Ok(out)
3509}
3510
3511fn read_dependency_errors(list: &Table) -> Result<Vec<DependencyError>> {
3512    let mut out = Vec::new();
3513    for e in list.sequence_values::<Table>() {
3514        let e = e?;
3515        let item: Table = e.get("item")?;
3516        out.push(DependencyError {
3517            file: PathBuf::from(e.get::<String>("file")?),
3518            required_by: PathBuf::from(e.get::<String>("required_by")?),
3519            text: e.get::<String>("text")?,
3520            diagnostic: Diagnostic {
3521                severity: Severity::Error,
3522                file: item.get("file")?,
3523                line: item.get("line")?,
3524                col: item.get("col")?,
3525                rule: item.get("rule")?,
3526                message: item.get("message")?,
3527                fix: None,
3528                required_by: None,
3529                origin: None,
3530            },
3531        });
3532    }
3533    Ok(out)
3534}
3535
3536/// `fixes[i]` is a fix table or `false`; missing entries are `None`.
3537fn read_fixes(t: &Table, key: &str, len: usize) -> Result<Vec<Option<Fix>>> {
3538    let mut out = vec![None; len];
3539    let Ok(list) = t.get::<Table>(key) else {
3540        return Ok(out);
3541    };
3542    for (i, slot) in out.iter_mut().enumerate() {
3543        let v: Value = list.get(i + 1)?;
3544        if let Value::Table(f) = v {
3545            let applicability = match f.get::<Option<String>>("applicability")?.as_deref() {
3546                Some("unsafe") => Applicability::Unsafe,
3547                Some("suggest") => Applicability::Suggest,
3548                _ => Applicability::Safe,
3549            };
3550            let mut edits = Vec::new();
3551            if let Ok(es) = f.get::<Table>("edits") {
3552                for e in es.sequence_values::<Table>() {
3553                    let e = e?;
3554                    edits.push(Edit {
3555                        line: e.get("line")?,
3556                        col: e.get("col")?,
3557                        end_line: e.get("end_line")?,
3558                        end_col: e.get("end_col")?,
3559                        text: e.get::<Option<String>>("text")?.unwrap_or_default(),
3560                    });
3561                }
3562            }
3563            *slot = Some(Fix {
3564                applicability,
3565                edits,
3566            });
3567        }
3568    }
3569    Ok(out)
3570}
3571
3572fn read_requires(list: &Table) -> Result<Vec<RequireSite>> {
3573    let mut requires = Vec::new();
3574    for r in list.sequence_values::<Table>() {
3575        let r = r?;
3576        requires.push(RequireSite {
3577            module: r.get::<String>("name")?,
3578            path: r.get::<Option<String>>("path")?.map(PathBuf::from),
3579            line: r.get::<Option<usize>>("y")?.unwrap_or(0),
3580            col: r.get::<Option<usize>>("x")?.unwrap_or(0),
3581            erased: r.get::<Option<bool>>("erased")?.unwrap_or(false),
3582        });
3583    }
3584    Ok(requires)
3585}
3586
3587/// `true` for `foo.tl` but not `foo.d.tl`.
3588pub fn is_tl_source(p: &Path) -> bool {
3589    let name = p.file_name().and_then(|s| s.to_str()).unwrap_or("");
3590    p.is_file() && name.ends_with(".tl") && !name.ends_with(".d.tl")
3591}
3592
3593/// The note `htl dts` writes beside the declarations it materialises from a dependency
3594/// crate, in `types/<crate>/`. The module that writes it is `dep_dts`, which the `dts`
3595/// feature compiles.
3596pub const DEP_TYPES_NOTE: &str = ".htl-dts";
3597
3598/// The immediate subdirectories of `types/` holding declarations materialised from a
3599/// dependency, in name order.
3600///
3601/// They go on the search path in their own right, so that a declaration keeps the module
3602/// name it was written under whatever the crate shipping it is called: `htl-mq`'s
3603/// `mq.d.tl` is `require("mq")`, not `require("htl-mq.mq")`. A directory a person laid out
3604/// under `types/` carries no note and goes on meaning what it has always meant — the path
3605/// below `types/` is the module name, as `socket/http.d.tl` is `require("socket.http")`.
3606pub fn materialised_types_dirs(types: &Path) -> Vec<PathBuf> {
3607    let Ok(entries) = std::fs::read_dir(types) else {
3608        return Vec::new();
3609    };
3610    let mut out: Vec<PathBuf> = entries
3611        .filter_map(Result::ok)
3612        .map(|e| e.path())
3613        .filter(|p| p.is_dir() && p.join(DEP_TYPES_NOTE).is_file())
3614        .collect();
3615    out.sort();
3616    out
3617}
3618
3619/// `true` for `foo.d.tl`: a declaration, with the implementation somewhere else.
3620pub fn is_declaration(p: &Path) -> bool {
3621    p.file_name()
3622        .and_then(|s| s.to_str())
3623        .is_some_and(|n| n.ends_with(".d.tl"))
3624}
3625
3626/// Directories never descended into when collecting sources under a root: build output,
3627/// installed packages, VCS and tool state. A root passed explicitly is always walked.
3628pub const SKIP_DIRS: &[&str] = &["target", "node_modules", ".mlua-pkgs", ".git"];
3629
3630/// `true` for a directory entry that source collection should not enter: a name in
3631/// [`SKIP_DIRS`], any dot-directory, or one of `extra` — named by path rather than by
3632/// name, for what the caller knows and a name cannot say.
3633pub fn is_skipped_dir(path: &Path, extra: &[PathBuf]) -> bool {
3634    if !path.is_dir() {
3635        return false;
3636    }
3637    let name = path.file_name().and_then(|s| s.to_str()).unwrap_or("");
3638    if SKIP_DIRS.contains(&name) || (name.starts_with('.') && name.len() > 1) {
3639        return true;
3640    }
3641    extra.iter().any(|e| same_file(path, e))
3642}
3643
3644/// The two paths name the same thing on disk, `..` and symlinks resolved. Falls back to
3645/// comparing them as written when either cannot be canonicalised (it does not exist).
3646pub(crate) fn same_file(a: &Path, b: &Path) -> bool {
3647    match (std::fs::canonicalize(a), std::fs::canonicalize(b)) {
3648        (Ok(x), Ok(y)) => x == y,
3649        _ => a == b,
3650    }
3651}
3652
3653/// Collect `.tl` sources from files and directories (sorted, recursive). Directories in
3654/// [`SKIP_DIRS`], dot-directories and the project's package dir are not entered unless
3655/// given as a root themselves.
3656pub fn collect_tl(paths: &[PathBuf]) -> Result<Vec<PathBuf>> {
3657    collect_tl_skipping(paths, &[])
3658}
3659
3660/// [`collect_tl`], not entering `skip` either — directories named by path rather than by
3661/// name, for what the caller knows and a name cannot say — the project model's
3662/// `Project::not_walked`.
3663pub fn collect_tl_skipping(paths: &[PathBuf], skip: &[PathBuf]) -> Result<Vec<PathBuf>> {
3664    let mut out = Vec::new();
3665    for p in paths {
3666        if p.is_dir() {
3667            let extra = skip.to_vec();
3668            let root = p.clone();
3669            let walker = walkdir::WalkDir::new(p)
3670                .sort_by_file_name()
3671                .into_iter()
3672                .filter_entry(move |e| e.path() == root || !is_skipped_dir(e.path(), &extra));
3673            for e in walker {
3674                let e = e?;
3675                if is_tl_source(e.path()) {
3676                    out.push(e.path().to_path_buf());
3677                }
3678            }
3679        } else if p.is_file() {
3680            out.push(p.clone());
3681        } else {
3682            bail!("no such file or directory: {}", p.display());
3683        }
3684    }
3685    Ok(out)
3686}
3687
3688/// The temp-directory guard this crate's unit tests share (the integration tests'
3689/// copy, `tests/common/mod.rs`, brought in by `#[path]` rather than duplicated): declared
3690/// once at the crate root, rather than once per file that needs it, so `dts.rs` /
3691/// `dep_dts.rs` / `model.rs` / `model/resolver.rs` / `cache.rs` / `batteries.rs` and this
3692/// file's own `mod tests` reach it as `crate::core_common` — a private item at the crate
3693/// root is visible to every module the crate has. Declared at the crate root rather than
3694/// nested inside a `mod tests` for the same reason `htl-macros` does: a `#[path]` on an
3695/// item of an *inline* module resolves relative to a directory named for that module that
3696/// does not exist on disk, and the OS refuses to resolve a `..` through a directory it
3697/// cannot open.
3698#[cfg(test)]
3699#[allow(dead_code)]
3700#[path = "../tests/common/mod.rs"]
3701mod core_common;
3702
3703#[cfg(test)]
3704mod tests {
3705    use super::*;
3706
3707    fn decl(path: &str, source: &str) -> (String, String) {
3708        (path.to_string(), source.to_string())
3709    }
3710
3711    /// [`declarations_key`] is generic over the pair ([`registry::Htl::install_declarations`]
3712    /// calls it with borrowed `&str`s), so the tests below — written against owned
3713    /// `(String, String)` pairs, the shape [`bundled_declarations`] returns — go through
3714    /// this to borrow each one.
3715    fn key(decls: &[(String, String)]) -> String {
3716        declarations_key(decls.iter().map(|(p, s)| (p.as_str(), s.as_str())))
3717    }
3718
3719    /// The reason the key exists: a build carrying one declaration more than another — a
3720    /// feature set, a newer mlua-batteries — lands somewhere else, so neither finds the
3721    /// other's files on its search path.
3722    #[test]
3723    fn a_different_set_of_declarations_is_a_different_key() {
3724        let base = vec![decl("htl/test.d.tl", "local record t end\nreturn t\n")];
3725        let mut more = base.clone();
3726        more.push(decl(
3727            "std/json.d.tl",
3728            "local record json end\nreturn json\n",
3729        ));
3730        assert_ne!(key(&base), key(&more));
3731
3732        // And a set of the same size whose content moved.
3733        let mut edited = base.clone();
3734        edited[0].1.push('\n');
3735        assert_ne!(key(&base), key(&edited));
3736    }
3737
3738    /// And the same set is the same key, so a build uses the directory it used last time
3739    /// and the files it wrote there are still its own.
3740    #[test]
3741    fn the_same_set_is_the_same_key() {
3742        let decls = vec![
3743            decl("htl/test.d.tl", "local record t end\nreturn t\n"),
3744            decl("std/json.d.tl", "local record json end\nreturn json\n"),
3745        ];
3746        assert_eq!(key(&decls), key(&decls.clone()));
3747    }
3748
3749    /// Length-prefixed: moving a character from a path into the source after it is a
3750    /// different set of files and reads as one.
3751    #[test]
3752    fn the_parts_cannot_run_together() {
3753        assert_ne!(key(&[decl("ab", "c")]), key(&[decl("a", "bc")]));
3754    }
3755
3756    /// The list is what this build writes: `htl.test`'s declaration whatever the features,
3757    /// and `std`'s exactly when the feature that installs them is on.
3758    #[test]
3759    fn the_list_holds_what_this_build_writes() {
3760        let decls = bundled_declarations();
3761        assert!(decls.iter().any(|(p, _)| p == "htl/test.d.tl"), "{decls:?}");
3762        assert_eq!(
3763            decls.iter().any(|(p, _)| p.starts_with("std/")),
3764            cfg!(feature = "std")
3765        );
3766    }
3767
3768    /// What the directory name is made of, and that asking twice gives one answer — the
3769    /// key is computed once and the path is a constant for the life of the process.
3770    #[test]
3771    fn the_directory_carries_the_version_and_the_key() {
3772        let dir = lib_dir();
3773        let name = dir.file_name().unwrap().to_string_lossy().into_owned();
3774        let prefix = format!("htl-lib-{}-", env!("CARGO_PKG_VERSION"));
3775        assert!(name.starts_with(&prefix), "{name}");
3776        assert_eq!(name[prefix.len()..], key(&bundled_declarations()));
3777        assert_eq!(dir, lib_dir());
3778    }
3779
3780    /// S6 of #429's review: the write is a temp-file-then-rename, not a `fs::write` that
3781    /// truncates `path` in place — a basic round trip still writes the content, reports
3782    /// `true`, and leaves no sibling temp file behind.
3783    #[test]
3784    fn write_if_changed_writes_new_content_and_leaves_no_temp_file() {
3785        let dir = core_common::tempdir("htl-core-wic", "default");
3786        let path = dir.join("out.d.tl");
3787
3788        assert!(write_if_changed(&path, "first\n").unwrap());
3789        assert_eq!(std::fs::read_to_string(&path).unwrap(), "first\n");
3790
3791        let siblings: Vec<_> = std::fs::read_dir(&dir)
3792            .unwrap()
3793            .map(|e| e.unwrap().file_name())
3794            .collect();
3795        assert_eq!(
3796            siblings,
3797            vec![std::ffi::OsString::from("out.d.tl")],
3798            "{siblings:?}"
3799        );
3800    }
3801
3802    /// Unchanged content is still a no-op: no write, no temp file, and the mtime is left
3803    /// alone (indirectly checked by `write_if_changed` returning `false` at all, which it
3804    /// only does after reading the existing content back and finding it equal).
3805    #[test]
3806    fn write_if_changed_is_a_no_op_when_the_content_already_matches() {
3807        let dir = core_common::tempdir("htl-core-wic", "noop");
3808        let path = dir.join("out.d.tl");
3809
3810        assert!(write_if_changed(&path, "same\n").unwrap());
3811        assert!(!write_if_changed(&path, "same\n").unwrap());
3812        assert_eq!(std::fs::read_to_string(&path).unwrap(), "same\n");
3813    }
3814
3815    /// Two writers of the same target in quick succession — the shape `regenerate_crate`
3816    /// and a `#[host_module]`'s own expansion can now be, in two different rustc
3817    /// processes — each complete a full write-then-rename rather than interleaving, so
3818    /// the file that lands is always wholly one writer's content or wholly the other's,
3819    /// never a splice of both. A single process can only interleave at Rust statement
3820    /// granularity, so this writes twice in a row rather than truly concurrently; the
3821    /// rename itself being atomic is what the real two-process case relies on, which this
3822    /// cannot exercise without two processes — it only confirms the no-splice property
3823    /// each individual call has.
3824    #[test]
3825    fn write_if_changed_never_leaves_a_half_written_file() {
3826        let dir = core_common::tempdir("htl-core-wic", "race");
3827        let path = dir.join("out.d.tl");
3828
3829        write_if_changed(&path, "aaaa\n").unwrap();
3830        write_if_changed(&path, "bbbbbb\n").unwrap();
3831        let text = std::fs::read_to_string(&path).unwrap();
3832        assert!(
3833            text == "aaaa\n" || text == "bbbbbb\n",
3834            "never a mix of the two: {text:?}"
3835        );
3836    }
3837
3838    /// A setter that raises halfway leaves its state's program as it was. `set_lints`
3839    /// writes the Lua side's selection, then raises on the Teal side's (`5` is no list):
3840    /// the Lua side's is not kept, in the program or in the checker.
3841    #[test]
3842    fn a_setter_that_fails_halfway_leaves_its_program_as_it_was() {
3843        let dir = core_common::tempdir("htl-core-program", "partial");
3844        let file = dir.join("m.tl");
3845        // `d[1]` — a `nil-index` lint, on by default.
3846        std::fs::write(
3847            &file,
3848            "local t: {{string:{string}}} = {}\nlocal d = t[\"a\"][1]\nreturn d\n",
3849        )
3850        .unwrap();
3851        let has = |h: &Htl| {
3852            h.check(&file)
3853                .unwrap()
3854                .lints
3855                .iter()
3856                .any(|l| l.contains("nil-index"))
3857        };
3858        let checker = Htl::new().unwrap();
3859        let program = Htl::with_checker(&checker).unwrap();
3860        let none: Vec<String> = Vec::new();
3861        let failed = program.checker_call::<()>(
3862            "set_lints",
3863            (none.clone(), vec!["nil-index".to_string()], 5, none),
3864        );
3865        assert!(failed.is_err());
3866        assert!(
3867            has(&program),
3868            "the half-written selection is not the program's"
3869        );
3870        assert!(has(&checker), "nor the checker's");
3871    }
3872
3873    /// The model's view goes in as one, under the names `H.set_model` keeps: a name it does
3874    /// not know is refused, and nothing of that model is installed.
3875    #[test]
3876    fn set_model_refuses_a_name_it_does_not_keep() {
3877        let checker = Htl::new().unwrap();
3878        let program = Htl::with_checker(&checker).unwrap();
3879        let lua = program.checker_lua().unwrap();
3880        let model = lua.create_table().unwrap();
3881        model
3882            .set("resolve_name", lua.create_function(|_, ()| Ok(())).unwrap())
3883            .unwrap();
3884        model.set("resolve_nmae", true).unwrap();
3885        let err = program
3886            .checker_call::<()>("set_model", model)
3887            .unwrap_err()
3888            .to_string();
3889        assert!(err.contains("unknown field resolve_nmae"), "{err}");
3890        assert!(!program.checker_call::<bool>("has", "resolve_name").unwrap());
3891    }
3892
3893    /// Entering the program already entered counts depth: the inner call sees the program,
3894    /// the outer leave writes the inner call's change back and restores the checker's own.
3895    /// Entering another program while one is entered is refused, and leaves the checker's
3896    /// own in place too.
3897    #[test]
3898    fn a_program_is_entered_once_at_a_time() {
3899        let checker = Htl::new().unwrap();
3900        let a = Htl::with_checker(&checker).unwrap();
3901        let b = Htl::with_checker(&checker).unwrap();
3902        let ok: bool = checker
3903            .lua()
3904            .load(
3905                r#"
3906                local H, pa, pb = ...
3907                local before = package.path
3908                H.with_program(pa, function()
3909                   H.with_program(pa, "add_path", "/nested")
3910                   assert(package.path:find("/nested", 1, true), "the inner call sees the program")
3911                end)
3912                assert(package.path == before, "the outer leave restored the checker's own")
3913                assert(pa.path:find("/nested", 1, true), "and wrote the inner call's change back")
3914                local ok, err = pcall(H.with_program, pa, function()
3915                   return H.with_program(pb, "get_path")
3916                end)
3917                assert(not ok and tostring(err):find("another one", 1, true), tostring(err))
3918                assert(package.path == before, "a refused enter restores too")
3919                assert(not pb.path:find("/nested", 1, true), "and b never had a's path")
3920                return true
3921                "#,
3922            )
3923            .call((
3924                checker.h.h.clone(),
3925                a.h.program.clone().unwrap(),
3926                b.h.program.clone().unwrap(),
3927            ))
3928            .unwrap();
3929        assert!(ok);
3930    }
3931}