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}