Skip to main content

htl_macros/
lib.rs

1//! htl proc macros.
2//!
3//! - `include_tl!("path.tl")`        -> `&'static str` generated Lua, Teal-checked at build time
4//! - `include_tl_bytes!("path.tl")`  -> `&'static [u8]` stripped Lua 5.4 bytecode, same check
5//! - `teal_types!()`                 -> the `pub mod ... { ... }` items `htl rs` writes, from `htl.toml`
6//! - `#[derive(TealRecord)]`         -> Teal `record` / `enum` / `type` decl + `IntoLua` / `FromLua`
7//! - `#[host_module(name = "...")]`  -> `UserData` impl + Teal `.d.tl` from a plain `impl` block
8//! - `#[c_export(prefix = "...")]`   -> `extern "C"` wrappers + C header from the same `impl` block
9//!
10//! Paths are relative to `CARGO_MANIFEST_DIR`. Teal type errors become `compile_error!`s,
11//! and so do the warnings and lints `htl check` would fail on — a rule at `deny`, or any
12//! under `[lint] strict` (`htl_core::verdict`); the rest are printed and the build goes on.
13//! `HTL_LINT=deny` makes every one fail, `HTL_LINT=warn` none. `HTL_LINTS` configures
14//! which rules run and at what level, as `--lint` does for the command; it is read after
15//! `htl.toml`'s `[lint]`, so the environment wins. Every `.tl` consulted is registered with
16//! `include_str!` so edits trigger a rebuild. Generated code refers to `::htl::...`, so
17//! use these through the `htl` umbrella crate.
18//!
19//! Declaration text (`.d.tl`) comes from `htl_core::dts`, the same code `htl dts` runs
20//! from the CLI, so the files can also be produced before any `cargo build`.
21//!
22//! Before checking, `include_tl!` / `include_tl_bytes!` / `include_bundle!` run the
23//! host-module half of that same scan over the whole crate and rewrite every one the
24//! scan can see (`regenerate_crate`), so a build sees each one current whichever of two
25//! `#[host_module]`s — or a `#[host_module]` and this scan — rustc happens to expand
26//! first. Without it, that order follows the crate's `mod` declarations, and a module
27//! declared after the one doing the `include_tl!` was checked against yesterday's
28//! declaration (#429). What the scan cannot see, because it reads `#[host_module(..)]`
29//! literally rather than evaluating Rust: the attribute written as
30//! `#[cfg_attr(.., host_module(..))]`, an impl a `macro_rules!` produces rather than one
31//! written out, an item reached only through `include!`, a module whose `#[path]` leaves
32//! `src/` / `examples/` / `tests/` / `benches/`, and the attribute under another name
33//! through `use htl::host_module as something_else`. Each of those is `#[host_module]`'s
34//! own expansion's to write, exactly as before this scan existed — this only widens
35//! *when* a declaration it can see lands, never what it writes, and never what it cannot
36//! see.
37//!
38//! The macros run the checker — htl-core and the vendored Lua that hosts `tl` — inside
39//! the proc macro, under `[profile.dev.build-override]`, whose default `opt-level = 0`
40//! makes a `cargo build` that touches a `.tl` about three times slower than the
41//! release-built CLI; `htl new --embed` writes `opt-level = 3` into that section. The
42//! `.tl` edit loop belongs to `htl check` / `htl test` in any case — an edit to a leaf
43//! module costs a few milliseconds from the cache — and `cargo build` to the Rust host
44//! and the binary.
45
46mod ty;
47
48use htl_core::dts;
49use proc_macro::TokenStream;
50use proc_macro2::Literal;
51use proc_macro2::TokenStream as TokenStream2;
52use quote::{format_ident, quote, quote_spanned};
53use std::collections::HashMap;
54use std::path::{Path, PathBuf};
55use std::sync::{Mutex, OnceLock};
56use syn::punctuated::Punctuated;
57use syn::spanned::Spanned;
58use syn::{
59    Item, ItemEnum, ItemImpl, ItemStruct, LitStr, Meta, Token, parse::Parser, parse_macro_input,
60};
61
62// ------------------------------------------------------------------ include_tl!
63
64/// `include_tl!("path.tl")` -> `&'static str`: the Lua `tl` (the vendored Teal checker)
65/// generates from `path.tl`, relative to `CARGO_MANIFEST_DIR`, Teal-checked at build time
66/// against the project's model and the crate's `#[host_module]`s. Before checking, it
67/// regenerates every `#[host_module]`'s `.d.tl` it can see from the Rust source
68/// (`regenerate_crate`), so the `#[host_module]` it checks against does not have to be
69/// declared before this in the crate's `mod` order — in the same file or another one
70/// (#429). A Teal type error, or a warning/lint the project's policy denies, becomes a
71/// `compile_error!` at this macro's call site; every `.tl` the check reads is
72/// `include_str!`-tracked, so an edit anywhere in the closure rebuilds. See the module
73/// doc for the lint policy and for what the regeneration cannot see.
74#[proc_macro]
75pub fn include_tl(input: TokenStream) -> TokenStream {
76    let lit = parse_macro_input!(input as LitStr);
77    match expand_include(&lit.value(), false) {
78        Ok(ts) => ts,
79        Err(msg) => quote! { compile_error!(#msg) }.into(),
80    }
81}
82
83/// [`include_tl!`], embedding stripped Lua 5.4 bytecode as `&'static [u8]` instead of the
84/// generated source — the same check, the same `.d.tl` regeneration, and the same
85/// tracking.
86#[proc_macro]
87pub fn include_tl_bytes(input: TokenStream) -> TokenStream {
88    let lit = parse_macro_input!(input as LitStr);
89    match expand_include(&lit.value(), true) {
90        Ok(ts) => ts,
91        Err(msg) => quote! { compile_error!(#msg) }.into(),
92    }
93}
94
95// ------------------------------------------------------------------ include_bundle!
96
97/// `include_bundle!("src/main.tl", host = ["host"], extra = ["modkit"], payload = "source", debug = true)`
98///
99/// Links the entry's `require` closure at `cargo build` (see `htl::link`) and embeds
100/// the encoded bundle as `&'static [u8]`; run it with
101/// `Htl::run_bundle(&Bundle::decode(BUNDLE)?, &args)` after registering host modules.
102///
103/// Every option is optional. The names the host provides are the project's model's: each
104/// `#[host_module]` in the crate around the project, `[build] host` in `htl.toml`, and
105/// `std.*` — none of them is bundled, and a file of the project under one of them is an
106/// error, since the host's module is what would run. `host = [..]` adds names the model
107/// cannot see (a module registered by hand, or by another crate); it does not need to
108/// restate a `#[host_module]` of this crate, which is the one list the model reads it from.
109/// Every linked file and every declaration the checker read is `include_bytes!`-tracked,
110/// so an edit rebuilds and a Teal type error is a compile error, like `include_tl!`.
111/// Before checking, also like `include_tl!`, it regenerates every `#[host_module]`'s
112/// `.d.tl` it can see from the Rust source, so a host module does not have to be
113/// declared before the entry this links in the crate's `mod` order (#429).
114/// `payload` is `"bytecode"` (default, stripped; `debug = true` keeps line info) or
115/// `"source"` (generated Lua: for a big-endian target, a Lua with non-default number
116/// types, or a bundle that must outlive a Lua upgrade; bytecode already loads on every
117/// 64-bit little-endian host, see `htl::bundle`).
118#[proc_macro]
119pub fn include_bundle(input: TokenStream) -> TokenStream {
120    let args = parse_macro_input!(input as BundleArgs);
121    match expand_bundle(&args) {
122        Ok(ts) => ts,
123        Err(msg) => quote! { compile_error!(#msg) }.into(),
124    }
125}
126
127struct BundleArgs {
128    entry: String,
129    opts: htl_core::link::LinkOptions,
130}
131
132impl syn::parse::Parse for BundleArgs {
133    fn parse(input: syn::parse::ParseStream) -> syn::Result<Self> {
134        let entry: LitStr = input.parse()?;
135        let mut opts = htl_core::link::LinkOptions::default();
136        while input.peek(Token![,]) {
137            input.parse::<Token![,]>()?;
138            if input.is_empty() {
139                break;
140            }
141            let key: syn::Ident = input.parse()?;
142            input.parse::<Token![=]>()?;
143            match key.to_string().as_str() {
144                "host" => opts.host = parse_str_list(input)?,
145                "extra" => opts.extra = parse_str_list(input)?,
146                "payload" => {
147                    let v: LitStr = input.parse()?;
148                    match v.value().as_str() {
149                        "bytecode" => opts.source = false,
150                        "source" => opts.source = true,
151                        other => {
152                            return Err(syn::Error::new(
153                                v.span(),
154                                format!(
155                                    "payload must be \"bytecode\" or \"source\", got {other:?}"
156                                ),
157                            ));
158                        }
159                    }
160                }
161                "debug" => {
162                    let v: syn::LitBool = input.parse()?;
163                    opts.debug = v.value();
164                }
165                other => {
166                    return Err(syn::Error::new(
167                        key.span(),
168                        format!(
169                            "unknown include_bundle! option `{other}` (host, extra, payload, debug)"
170                        ),
171                    ));
172                }
173            }
174        }
175        Ok(Self {
176            entry: entry.value(),
177            opts,
178        })
179    }
180}
181
182fn parse_str_list(input: syn::parse::ParseStream) -> syn::Result<Vec<String>> {
183    let content;
184    syn::bracketed!(content in input);
185    let items: Punctuated<LitStr, Token![,]> =
186        content.parse_terminated(<LitStr as syn::parse::Parse>::parse, Token![,])?;
187    Ok(items.iter().map(|l| l.value()).collect())
188}
189
190#[derive(Debug)]
191struct BundleOut {
192    bytes: Vec<u8>,
193    inputs: Vec<String>,
194    /// `htl.toml`, absolute, when the project has one: a setting the verdict came from.
195    config: Option<String>,
196    /// Typed modules replayed from the run cache, out of how many.
197    cached: (usize, usize),
198}
199
200/// Link `rel` (relative to `manifest_dir`) with the CLI's search paths and `[build]`
201/// settings from `htl.toml` merged into `opts`.
202fn resolve_bundle(
203    manifest_dir: &Path,
204    rel: &str,
205    opts: &htl_core::link::LinkOptions,
206) -> Result<BundleOut, String> {
207    let path = manifest_dir.join(rel);
208    if !path.is_file() {
209        return Err(format!("include_bundle!: no such file: {}", path.display()));
210    }
211    let ck = checker_for(
212        "include_bundle!",
213        manifest_dir,
214        &path,
215        std::env::var("HTL_LINTS").ok().as_deref(),
216    )?;
217    let (h, cfg) = (&ck.h, &ck.cfg);
218    let mut opts = opts.clone();
219    // The host's names come from the project's model, as for `htl build`: a
220    // `#[host_module]` in this crate is one without `host = [..]` naming it again.
221    if let Some(m) = &ck.model {
222        opts.host.extend(m.provided().map(|(n, _)| n.to_string()));
223    }
224    if let Some((_, _, c)) = cfg {
225        opts.extra.extend(c.build.extra.iter().cloned());
226        opts.host.extend(c.build.host.iter().cloned());
227    }
228    // The name the entry is served under, from the project's model, as `htl build` does:
229    // the one a `require` of the file elsewhere in the project writes.
230    opts.entry_name = ck
231        .model
232        .as_ref()
233        .and_then(|m| m.locate(&path).map(|p| p.name));
234    let store = ck.store();
235    let linked = htl_core::link::link_with(h, &path, &opts, ck.link_store(store.as_ref()))
236        .map_err(|e| format!("include_bundle!: {e:#}"))?;
237    let typed = linked.modules.iter().filter(|m| m.typed).count();
238    let cached = (linked.cached, typed);
239    let warnings: Vec<htl_core::Diagnostic> = linked
240        .checks
241        .iter()
242        .flat_map(|(_, ci)| ci.warning_items.iter().cloned())
243        .collect();
244    let lints: Vec<htl_core::Diagnostic> = linked
245        .checks
246        .iter()
247        .flat_map(|(_, ci)| ci.lint_items.iter().cloned())
248        .collect();
249    judge(
250        "include_bundle!",
251        &ck,
252        &warnings,
253        &lints,
254        std::env::var("HTL_LINT").ok().as_deref(),
255    )?;
256    let inputs: Vec<String> = linked
257        .inputs()
258        .into_iter()
259        .map(|p| {
260            if p.is_absolute() {
261                p
262            } else {
263                manifest_dir.join(p)
264            }
265        })
266        .filter(|p| p.is_file())
267        .map(|p| p.to_string_lossy().into_owned())
268        .collect();
269    let bundle = linked
270        .into_bundle()
271        .map_err(|e| format!("include_bundle!: {e:#}"))?;
272    Ok(BundleOut {
273        bytes: bundle.encode(),
274        inputs,
275        config: config_input(&ck),
276        cached,
277    })
278}
279
280/// `HTL_CACHE_DEBUG`: say what the store did for this expansion, the way the CLI's
281/// `--explain-cache` does at the end of a run. Build output is the only place a macro can
282/// say anything, and only when asked.
283fn explain_cache(tag: &str, cached: usize, of: usize) {
284    if std::env::var_os("HTL_CACHE_DEBUG").is_some() {
285        eprintln!("{tag}: {cached} of {of} module(s) replayed from the run cache");
286    }
287}
288
289fn expand_bundle(args: &BundleArgs) -> Result<TokenStream, String> {
290    let manifest_dir = manifest_dir()?;
291    regenerate_crate(&manifest_dir);
292    let out = resolve_bundle(&manifest_dir, &args.entry, &args.opts)?;
293    explain_cache("include_bundle!", out.cached.0, out.cached.1);
294    let lit = Literal::byte_string(&out.bytes);
295    let inputs = out.inputs;
296    let settings = settings_tracked(out.config.as_deref());
297    Ok(quote! {{
298        #( const _: &[u8] = include_bytes!(#inputs); )*
299        #settings
300        #lit as &[u8]
301    }}
302    .into())
303}
304
305/// What the expansion was decided by besides the `.tl` it read, declared so a change to
306/// it expands the macro again: `htl.toml` (the rules, their levels, `strict`) as a tracked
307/// file, and `HTL_LINT` / `HTL_LINTS` through `option_env!`, which rustc records as an
308/// environment dependency of the crate and cargo rebuilds on. Without them a build keeps
309/// the verdict of whichever expansion ran last, until something unrelated is edited.
310fn settings_tracked(config: Option<&str>) -> TokenStream2 {
311    let config = config.map(|c| quote! { const _: &str = include_str!(#c); });
312    quote! {
313        #config
314        const _: ::core::option::Option<&str> = ::core::option_env!("HTL_LINT");
315        const _: ::core::option::Option<&str> = ::core::option_env!("HTL_LINTS");
316    }
317}
318
319/// `htl.toml` as the expansion tracks it: absolute, since `include_str!` resolves relative
320/// to the Rust source file.
321fn config_input(ck: &Checker) -> Option<String> {
322    ck.cfg
323        .as_ref()
324        .map(|(_, p, _)| std::fs::canonicalize(p).unwrap_or_else(|_| p.clone()))
325        .map(|p| p.to_string_lossy().into_owned())
326}
327
328fn manifest_dir() -> Result<PathBuf, String> {
329    std::env::var("CARGO_MANIFEST_DIR")
330        .map(PathBuf::from)
331        .map_err(|_| "CARGO_MANIFEST_DIR is not set".to_string())
332}
333
334/// Rewrites every `#[host_module]`'s `.d.tl` the scan can see, from the Rust source —
335/// [`dts::regenerate_host_decls`], the host-only half of the scan `htl dts` runs — before
336/// `expand_include` / `expand_bundle` check a `.tl` against one of them (#429, see the
337/// module doc). Records are deliberately not rewritten here (S1 of the review that found
338/// this): `#[derive(TealRecord)]` sees `#[cfg]`-stripped input the way rustc always
339/// expands a derive, but a crate-wide scan of the raw `.rs` text does not evaluate
340/// `#[cfg]` on a field any more than on anything else, so a record with a
341/// `#[cfg(feature = ..)]` field would get two different declarations written in the same
342/// build depending on which of this scan and the derive's own expansion ran last — #429's
343/// class of bug, moved from host modules to records, had this not stayed host-only.
344///
345/// Best-effort and silent: [`dts::regenerate_host_decls`] skips whatever it cannot read,
346/// parse or write rather than failing, and never returns an error, so neither does this —
347/// an unparsable fixture under `tests/`, or a `.d.tl` directory this cannot write to, is
348/// that file's own problem to report when *it* is compiled, not a reason to fail every
349/// `include_tl!` of a lib that never touches it. See that function's doc for why this is
350/// safe to leave silent.
351///
352/// A change to `src/hostio.rs` needs no extra tracking to make `include_tl!` re-expand:
353/// rustc re-expands every proc macro on every recompile of the crate using it, and
354/// `hostio.rs` is already a source file of that same crate, so cargo already rebuilds on
355/// a change to it. `htl check` / `htl dts` are unaffected either way — they run their own
356/// scan already, and never read a `.d.tl` off disk to get here.
357///
358/// Re-running the write pass on every expansion would make a filesystem walk (plus one
359/// `read_to_string` per `.rs` file, to the `host_module`-substring prefilter) part of
360/// every `include_tl!` / `include_bundle!`, so this instead caches, by manifest dir, the
361/// [`dts::ScanFingerprint`] (a file count and a newest mtime — a stat walk, no reads) the
362/// write pass last saw, and only redoes the write pass when a fresh stat walk disagrees
363/// with that. "One process compiles one crate" is not the reason for the cache key: it
364/// is false under a long-lived proc-macro server (rust-analyzer's `proc-macro-srv` loads
365/// this dylib once and serves every crate of the workspace, for the whole editing
366/// session, from inside it), which is exactly why the fingerprint is re-checked on every
367/// call rather than trusted forever once computed — a single `OnceLock<bool>` would never
368/// refresh there, and a crate's `.d.tl`s would go stale after the first edit and stay
369/// stale until the IDE restarted. The dir-keyed map is what lets that one long-lived
370/// process hold one fingerprint per crate rather than one for whichever crate asked last.
371fn regenerate_crate(manifest_dir: &Path) {
372    static CACHE: OnceLock<Mutex<HashMap<PathBuf, dts::ScanFingerprint>>> = OnceLock::new();
373    let cache = CACHE.get_or_init(|| Mutex::new(HashMap::new()));
374    let mut cache = cache
375        .lock()
376        .unwrap_or_else(|poisoned| poisoned.into_inner());
377    let current = dts::scan_fingerprint(manifest_dir);
378    if cache.get(manifest_dir) == Some(&current) {
379        return;
380    }
381    dts::regenerate_host_decls(manifest_dir);
382    cache.insert(manifest_dir.to_path_buf(), current);
383}
384
385/// What `include_tl!` / `include_tl_bytes!` embed, computed without proc-macro types so
386/// it can be unit-tested.
387#[derive(Debug)]
388struct Included {
389    main_abs: String,
390    deps: Vec<String>,
391    /// `htl.toml`, absolute, when the project has one: a setting the verdict came from.
392    config: Option<String>,
393    payload: Payload,
394    /// Whether the check and the Lua came from the run cache.
395    cached: bool,
396}
397
398#[derive(Debug)]
399enum Payload {
400    Source(String),
401    Bytes(Vec<u8>),
402}
403
404/// A checker set up for one macro expansion, through the two library functions
405/// `htl check` and the CLI's `checker_for` go through: [`htl_core::project::Scope::new`]
406/// for the lint input, and [`htl_core::project::checker`] for the checker built from it,
407/// then [`htl_core::project::file_view`] for the file's own directory when it is not in a
408/// project — never the process cwd, which is cargo's and has nothing to do with the
409/// script. Carries what the run cache and [`judge`] need.
410struct Checker {
411    h: htl_core::Htl,
412    cfg: htl_core::project::Config,
413    /// The project root: beside `htl.toml` or `mlua-pkg.toml`, else the crate's manifest
414    /// directory. Where the store lives (`.htl/cache`), the same place the CLI keeps it.
415    root: PathBuf,
416    /// The scope the checker was configured from (`scope.lints`, `scope.spec`): what
417    /// [`judge`] and the cache key read, so the spec is parsed once.
418    scope: htl_core::project::Scope,
419    /// The project model the expansion was checked against, when the file is in a
420    /// project: what the store probes with.
421    model: Option<htl_core::model::Project>,
422}
423
424impl Checker {
425    /// The lint selection as a cache key takes it.
426    fn lint(&self) -> Option<&str> {
427        (!self.scope.spec.is_empty()).then_some(self.scope.spec.as_str())
428    }
429
430    /// The run cache, when there is a project to keep one in: a model was built — an
431    /// `htl.toml` or an `mlua-pkg.toml` above the file, either is enough, and `htl init` /
432    /// `htl new` write the first and gitignore `.htl/` — and its root is not build scratch — the copy `cargo publish` verifies under
433    /// `target/package/`, where a new file aborts the publish, or a registry checkout.
434    /// Otherwise `None`, silently: everything is generated, which is what happened before
435    /// there was a store. `HTL_CACHE_DEBUG` says which of the two it was.
436    ///
437    /// Both rules and the opening itself are `htl_core::project`'s, which is where
438    /// `htl check` opens the same store. An expansion and a check reading one store used
439    /// to answer this question with two pieces of code, and a fix to one was not a fix to
440    /// the other (#107).
441    ///
442    /// Per-module always, like `htl test`: an expansion is one closure, and an edit
443    /// anywhere in it should cost that module and its dependents rather than the closure.
444    /// Nothing is swept from here — an expansion sees one closure, and only `htl check`,
445    /// which sees the project, bounds the store.
446    fn store(&self) -> Option<htl_core::cache::Cache> {
447        htl_core::project::with_model(
448            htl_core::project::store(
449                &self.root,
450                htl_core::cache::Options::from_env(),
451                htl_core::project::store_refusal(&self.root, self.model.is_some()).as_deref(),
452                "the macro expansion",
453            ),
454            self.model.as_ref(),
455        )
456    }
457
458    fn link_store<'a>(
459        &'a self,
460        cache: Option<&'a htl_core::cache::Cache>,
461    ) -> Option<htl_core::link::LinkStore<'a>> {
462        cache.map(|c| htl_core::link::LinkStore {
463            cache: c,
464            lint: self.lint(),
465            root: &self.root,
466            config: self.cfg.as_ref().map(|(_, p, c)| (p.as_path(), c)),
467        })
468    }
469}
470
471fn checker_for(
472    tag: &str,
473    manifest_dir: &Path,
474    path: &Path,
475    htl_lints: Option<&str>,
476) -> Result<Checker, String> {
477    // The project the file is in, found the way every command finds it — the one walk up
478    // for a manifest, which refuses an `htl.toml` and an `mlua-pkg.toml` naming different
479    // roots — then `project::Scope::new` (`htl.toml` `[lint]` first, then `HTL_LINTS`, so
480    // the env var wins) and `project::checker`, the same two functions `htl check` and
481    // the CLI's `checker_for` go through.
482    let cfg = htl_core::project::config_of(path).map_err(|e| format!("{tag}: {e:#}"))?;
483    let model = htl_core::project::model_of(&cfg, path).map_err(|e| format!("{tag}: {e:#}"))?;
484    let scope = htl_core::project::Scope::new(&cfg, model.as_ref(), path, htl_lints)
485        .map_err(|e| format!("{tag}: {e:#}"))?;
486    let h = htl_core::project::checker(
487        model.as_ref(),
488        scope.lints.selection(),
489        &htl_core::project::lang_of(&cfg),
490    )
491    .map_err(|e| format!("{tag}: {e:#}"))?;
492    htl_core::project::file_view(&h, model.as_ref(), path).map_err(|e| format!("{tag}: {e:#}"))?;
493    // The project's root, where its store is — as for every command — and the crate's
494    // manifest directory for a crate in no project, which keeps no store.
495    let root = model
496        .as_ref()
497        .map(|m| m.root.clone())
498        .unwrap_or_else(|| manifest_dir.to_path_buf());
499    Ok(Checker {
500        h,
501        cfg,
502        root,
503        scope,
504        model,
505    })
506}
507
508/// Judge a build's warnings and lints as `htl check` judges a run's: the levels the
509/// checker was configured with, the policy of `htl.toml`, `HTL_LINT` (`htl_lint`, its value
510/// when set) on top. What fails the build is the error; what does not is printed and the
511/// build goes on.
512///
513/// The build and the check share one default so that a project quiet under `htl check`
514/// builds, and a rule the project put at `deny` stops both. A new release that adds a lint
515/// at `warn` therefore reports it here without breaking a build that passed before.
516fn judge(
517    tag: &str,
518    ck: &Checker,
519    warnings: &[htl_core::Diagnostic],
520    lints: &[htl_core::Diagnostic],
521    htl_lint: Option<&str>,
522) -> Result<(), String> {
523    use htl_core::verdict::{Findings, Policy, is_denied, verdict};
524    let levels = ck.scope.lints.selection();
525    let policy = Policy::resolve(ck.cfg.as_ref().map(|(_, _, c)| c), false)
526        .with_env(htl_lint)
527        .map_err(|e| format!("{tag}: {e}"))?;
528    if verdict(&Findings::of(warnings, lints, levels), &policy) {
529        let failing: Vec<String> = warnings
530            .iter()
531            .chain(lints)
532            .filter(|d| policy.strict || is_denied(d, levels))
533            .map(|d| d.clone().spelled().to_string())
534            .collect();
535        let why = if policy.strict {
536            "strict: every warning and lint fails the build"
537        } else {
538            "a rule at deny fails the build"
539        };
540        return Err(format!(
541            "htl lint failed ({why}; HTL_LINT=warn lets it through):\n{}",
542            failing.join("\n")
543        ));
544    }
545    for w in warnings {
546        eprintln!("{tag} warning: {}", w.clone().spelled());
547    }
548    for l in lints {
549        eprintln!("{tag} lint: {}", l.clone().spelled());
550    }
551    Ok(())
552}
553
554fn resolve_include(manifest_dir: &Path, rel: &str, bytes: bool) -> Result<Included, String> {
555    let path = manifest_dir.join(rel);
556    if !path.is_file() {
557        return Err(format!("include_tl!: no such file: {}", path.display()));
558    }
559    let ck = checker_for(
560        "include_tl!",
561        manifest_dir,
562        &path,
563        std::env::var("HTL_LINTS").ok().as_deref(),
564    )?;
565    let h = &ck.h;
566    // One module, through the same store the linker uses: its `gen` entry, if it still
567    // holds, is the check and the Lua.
568    let store = ck.store();
569    let htl_core::link::Generated {
570        code,
571        check: ci,
572        cached,
573    } = htl_core::link::generate(h, &path, ck.link_store(store.as_ref()))
574        .map_err(|e| format!("include_tl!: {e:#}"))?;
575
576    let Some(code) = code else {
577        // The path spelled as `htl check` spells it from where cargo runs the compiler,
578        // rather than as the checker was handed it (absolute, from the manifest dir).
579        let lines: Vec<String> = ci
580            .error_items
581            .iter()
582            .map(|d| d.clone().spelled().to_string())
583            .collect();
584        return Err(format!("Teal type check failed:\n{}", lines.join("\n")));
585    };
586    // The file checked, but something it required did not. The generated code would
587    // build, and the module's first `require` would raise at run time; the build is where
588    // that belongs, the same as for the file's own errors.
589    if !ci.dependency_errors.is_empty() {
590        let lines: Vec<String> = ci
591            .dependency_errors
592            .iter()
593            .map(|e| {
594                format!(
595                    "{}\n  (required by {})",
596                    e.diagnostic.clone().spelled(),
597                    htl_core::diagnostic::display_path(&e.required_by)
598                )
599            })
600            .collect();
601        return Err(format!(
602            "Teal type check failed in a required module:\n{}",
603            lines.join("\n")
604        ));
605    }
606    judge(
607        "include_tl!",
608        &ck,
609        &ci.warning_items,
610        &ci.lint_items,
611        std::env::var("HTL_LINT").ok().as_deref(),
612    )?;
613
614    let main_abs = path.to_string_lossy().into_owned();
615    // `include_str!` resolves relative to the *Rust* source file, so every tracked dep
616    // must be absolute. Drop anything that does not exist as a file (nothing to track).
617    let deps: Vec<String> = ci
618        .deps
619        .iter()
620        .filter_map(|d| {
621            let p = if d.is_absolute() {
622                d.clone()
623            } else {
624                manifest_dir.join(d)
625            };
626            let p = std::fs::canonicalize(&p).unwrap_or(p);
627            p.is_file().then(|| p.to_string_lossy().into_owned())
628        })
629        .collect();
630
631    let payload = if bytes {
632        let name = path
633            .file_stem()
634            .and_then(|s| s.to_str())
635            .unwrap_or("chunk")
636            .to_string();
637        let bc = h
638            .compile(&name, &code)
639            .map_err(|e| format!("include_tl_bytes!: {e:#}"))?;
640        Payload::Bytes(bc)
641    } else {
642        Payload::Source(code)
643    };
644
645    Ok(Included {
646        main_abs,
647        deps,
648        config: config_input(&ck),
649        payload,
650        cached,
651    })
652}
653
654fn expand_include(rel: &str, bytes: bool) -> Result<TokenStream, String> {
655    let manifest_dir = manifest_dir()?;
656    regenerate_crate(&manifest_dir);
657    let inc = resolve_include(&manifest_dir, rel, bytes)?;
658    explain_cache("include_tl!", usize::from(inc.cached), 1);
659    let main_abs = inc.main_abs;
660    let deps = inc.deps;
661    let settings = settings_tracked(inc.config.as_deref());
662    let payload = match inc.payload {
663        Payload::Bytes(bc) => {
664            let lit = Literal::byte_string(&bc);
665            quote! { #lit as &[u8] }
666        }
667        Payload::Source(code) => quote! { #code },
668    };
669
670    Ok(quote! {{
671        const _: &str = include_str!(#main_abs);
672        #( const _: &str = include_str!(#deps); )*
673        #settings
674        #payload
675    }}
676    .into())
677}
678
679// ------------------------------------------------------------------ teal_types!
680
681/// `teal_types!()` -> the `pub mod ... { ... }` items `htl rs` writes, generated at
682/// `cargo build` from `htl.toml` (`[rust] modules`, `exports` and `[rust.types]`) through
683/// [`htl_core::rsgen::generate`], for a project that does not commit generated Rust.
684///
685/// Every `.tl` source file checked (and every `.d.tl` or `.tl` it resolved) and
686/// `htl.toml` are `include_str!`-tracked, so editing a `.tl` record or `[rust.types]`
687/// triggers a rebuild without `cargo clean`. A Teal type error in any own source file, or
688/// a shape `rsgen::generate` refuses, becomes a `compile_error!` at the macro's span,
689/// naming the Teal file and line. Before checking, like [`include_tl!`], it regenerates
690/// every `#[host_module]`'s `.d.tl` it can see from the Rust source (`regenerate_crate`).
691#[proc_macro]
692pub fn teal_types(input: TokenStream) -> TokenStream {
693    let _ = parse_macro_input!(input as syn::parse::Nothing);
694    match expand_teal_types() {
695        Ok(ts) => ts,
696        // Item position (`htl::teal_types!();` at the crate root): `compile_error!` needs
697        // its trailing `;` for the same reason `derive_teal_record` does.
698        Err(msg) => quote! { compile_error!(#msg); }.into(),
699    }
700}
701
702/// What `teal_types!` expands from, computed without proc-macro types so it can be
703/// unit-tested and compared directly with [`htl_core::rsgen::generate`].
704#[derive(Debug)]
705struct TealTypesOut {
706    /// The Rust source text `rsgen::generate` produced, or empty when `[rust] modules` and
707    /// `exports` are empty.
708    code: String,
709    /// Every `.tl` file checked and every dependency it resolved (`include_str!` inputs),
710    /// canonical and absolute.
711    inputs: Vec<String>,
712    /// `htl.toml`, absolute: a setting the expansion came from.
713    config: Option<String>,
714    /// Notes `rsgen::generate` reported alongside the generated text.
715    notes: Vec<htl_core::Diagnostic>,
716}
717
718fn resolve_teal_types(manifest_dir: &Path) -> Result<TealTypesOut, String> {
719    let ck = checker_for(
720        "teal_types!",
721        manifest_dir,
722        manifest_dir,
723        std::env::var("HTL_LINTS").ok().as_deref(),
724    )?;
725    let Some((root, _, cfg)) = &ck.cfg else {
726        return Err(format!(
727            "teal_types!: no htl.toml at or above {}",
728            manifest_dir.display()
729        ));
730    };
731    let Some(model) = &ck.model else {
732        return Err(format!(
733            "teal_types!: no project at or above {}",
734            manifest_dir.display()
735        ));
736    };
737    let spec = htl_core::rsgen::Spec::from(&cfg.rust);
738    let config = config_input(&ck);
739    if spec.is_empty() {
740        return Ok(TealTypesOut {
741            code: String::new(),
742            inputs: Vec::new(),
743            config,
744            notes: Vec::new(),
745        });
746    }
747
748    let checked = htl_core::project::own_sources(&ck.h, root, model)
749        .map_err(|e| format!("teal_types!: {e:#}"))?;
750    let mut errors = Vec::new();
751    for f in checked.iter().filter(|f| f.failed) {
752        for d in &f.info.error_items {
753            errors.push(d.clone().spelled().to_string());
754        }
755        for e in &f.info.dependency_errors {
756            errors.push(format!(
757                "{}\n  (required by {})",
758                e.diagnostic.clone().spelled(),
759                htl_core::diagnostic::display_path(&e.required_by)
760            ));
761        }
762    }
763    if !errors.is_empty() {
764        return Err(format!("Teal type check failed:\n{}", errors.join("\n")));
765    }
766
767    let mut tracked = std::collections::BTreeSet::new();
768    for f in &checked {
769        for p in std::iter::once(&f.file).chain(f.info.deps.iter()) {
770            let abs = if p.is_absolute() {
771                p.clone()
772            } else {
773                manifest_dir.join(p)
774            };
775            let abs = std::fs::canonicalize(&abs).unwrap_or(abs);
776            if abs.is_file() {
777                tracked.insert(abs.to_string_lossy().into_owned());
778            }
779        }
780    }
781    let inputs: Vec<String> = tracked.into_iter().collect();
782
783    let sources: Vec<htl_core::shapes::Source> = checked
784        .iter()
785        .map(|f| htl_core::shapes::Source {
786            module: &f.module,
787            rel_path: &f.rel,
788            info: &f.info,
789        })
790        .collect();
791    let (code, notes) = match htl_core::rsgen::generate(&sources, &spec, |p| {
792        std::fs::canonicalize(p).unwrap_or_else(|_| p.to_path_buf())
793    }) {
794        htl_core::rsgen::Rendered::Text { text, notes } => (text, notes),
795        htl_core::rsgen::Rendered::Refused { problems, notes } => {
796            let lines: Vec<String> = notes
797                .into_iter()
798                .chain(problems)
799                .map(|d| d.spelled().to_string())
800                .collect();
801            return Err(format!("teal_types!: {}", lines.join("\n")));
802        }
803        htl_core::rsgen::Rendered::Nothing => (String::new(), Vec::new()),
804    };
805
806    Ok(TealTypesOut {
807        code,
808        inputs,
809        config,
810        notes,
811    })
812}
813
814fn expand_teal_types_from(out: &TealTypesOut) -> Result<TokenStream2, String> {
815    let items: TokenStream2 = out
816        .code
817        .parse()
818        .map_err(|e| format!("teal_types!: generated Rust did not parse: {e}"))?;
819    let inputs = &out.inputs;
820    let settings = settings_tracked(out.config.as_deref());
821    Ok(quote! {
822        #( const _: &str = include_str!(#inputs); )*
823        #settings
824        #items
825    })
826}
827
828fn expand_teal_types() -> Result<TokenStream, String> {
829    let manifest_dir = manifest_dir()?;
830    regenerate_crate(&manifest_dir);
831    let out = resolve_teal_types(&manifest_dir)?;
832    for n in &out.notes {
833        eprintln!("teal_types! note: {}", n.clone().spelled());
834    }
835    Ok(expand_teal_types_from(&out)?.into())
836}
837
838// ------------------------------------------------------------------ shared
839
840fn write_dts(rel: &str, text: &str) -> Result<(), String> {
841    let path = manifest_dir()?.join(rel);
842    htl_core::write_if_changed(&path, text)
843        .map_err(|e| format!("writing {}: {e}", path.display()))?;
844    Ok(())
845}
846
847// ------------------------------------------------------------------ #[derive(TealRecord)]
848
849/// Declare a struct or enum on the Teal side and convert it both ways: `TealRecord::DECL`
850/// (the `.d.tl` text), `IntoLua` / `FromLua` that produce and accept exactly what it
851/// declares, and `htl_preload`. What each Rust shape lowers to is the type table in
852/// [`htl::dts`](https://docs.rs/htl/latest/htl/dts/index.html), which is also what
853/// `htl dts` reads; the two cannot disagree.
854///
855/// The words `#[teal(..)]` takes, by where it is written (what each does, and what is
856/// refused, is in that module doc):
857///
858/// - on the type: `name` (the Teal name), `dts` (write the declaration to a path),
859///   `uses` (types from other `.d.tl` modules), `rename_all` (how variants or fields are
860///   spelled);
861/// - on a variant: `name` (that variant's word);
862/// - on a field: `as` (declare the field as given Teal text), `noyield` (a `Function`
863///   field the host calls without yielding), `serde` (cross the field through serde),
864///   `skip` (htl does not carry the field).
865///
866/// The type's `#[serde(..)]` is read too, so a type deriving `Serialize` / `Deserialize`
867/// beside `TealRecord` crosses under serde's names. Which `#[serde(..)]` words are read,
868/// which pass through and which are refused, with the escape each refusal names, is
869/// [*A type serde already describes*](https://docs.rs/htl/latest/htl/dts/index.html#a-type-serde-already-describes)
870/// and [*The field escapes*](https://docs.rs/htl/latest/htl/dts/index.html#the-field-escapes-tealas-tealserde-tealskip)
871/// in `htl::dts`.
872///
873/// ```rust,ignore
874/// #[derive(Serialize, Deserialize, TealRecord)]
875/// #[serde(rename_all = "camelCase")]
876/// struct Call {
877///     call_id: String,
878///     #[serde(alias = "msg")] message: String,
879///     #[teal(skip)] scratch: Vec<u8>,
880/// }
881/// // local record Call
882/// //    callId: string
883/// //    message: string
884/// // end
885/// ```
886#[proc_macro_derive(TealRecord, attributes(teal))]
887pub fn derive_teal_record(input: TokenStream) -> TokenStream {
888    let item = parse_macro_input!(input as Item);
889    match expand_record(&item) {
890        Ok(ts) => ts,
891        // In item position the `;` is part of the macro call: without it rustc adds "macros
892        // that expand to items must be delimited with braces or followed by a semicolon"
893        // and "proc-macro derive produced unparsable tokens" after every refusal. (The
894        // `include_*!` macros expand in expression position and must not have it.)
895        Err(msg) => quote! { compile_error!(#msg); }.into(),
896    }
897}
898
899/// What every kind gets: the `TealRecord` constants, `IntoLua` / `FromLua` around the
900/// per-kind bodies, and `htl_preload`. The declaration text and the kind come from
901/// `htl_core::dts`, the same code `htl dts` runs, so the `.d.tl` a build writes and the
902/// one the CLI writes cannot disagree.
903fn expand_record(item: &Item) -> Result<TokenStream, String> {
904    // A `#[serde(flatten)]` field's struct is declared from its source, which a derive is
905    // not handed: read this file for it, only when there is one (`dts::needs_source`).
906    let file = if dts::needs_source(item) {
907        current_file()
908    } else {
909        None
910    };
911    let rd = dts::record_decl_in(item, file.as_ref().map(|(items, _)| items.as_slice()))?;
912    if let Some(d) = &rd.attrs.dts {
913        write_dts(d, &rd.decl)?;
914    }
915    let name = rd.name.as_str();
916    let mut fields_impl = quote! {};
917    let (ident, into, from) = match (item, &rd.kind) {
918        (Item::Struct(st), dts::RecordKind::Record { .. }) => {
919            let ident = &st.ident;
920            let write = record_write(st, &rd.conversion)?;
921            let read = record_read(st, &rd.conversion)?;
922            fields_impl = quote! {
923                impl ::htl::teal::TealFields for #ident {
924                    #[allow(unused_variables)]
925                    fn write_fields(
926                        self,
927                        t: &::htl::mlua::Table,
928                        lua: &::htl::mlua::Lua,
929                        path: &str,
930                    ) -> ::htl::mlua::Result<()> {
931                        #write
932                        Ok(())
933                    }
934                    #[allow(unused_variables)]
935                    fn read_fields(
936                        t: &::htl::mlua::Table,
937                        lua: &::htl::mlua::Lua,
938                        path: &str,
939                    ) -> ::htl::mlua::Result<Self> {
940                        #read
941                    }
942                }
943            };
944            (ident, record_into(name), record_from(name))
945        }
946        (Item::Struct(st), dts::RecordKind::Alias { inner }) => match &st.fields {
947            syn::Fields::Named(_) => (
948                &st.ident,
949                transparent_into(st, &rd.conversion)?,
950                transparent_from(st, name, inner, &rd.conversion)?,
951            ),
952            _ => (&st.ident, alias_into(), alias_from(st, name, inner)),
953        },
954        (Item::Enum(en), dts::RecordKind::Enum { variants }) => (
955            &en.ident,
956            enum_into(en, variants),
957            enum_from(en, name, variants),
958        ),
959        (Item::Enum(en), dts::RecordKind::Union { variants, repr }) => (
960            &en.ident,
961            union_into(en, name, variants, repr),
962            union_from(en, name, variants, repr),
963        ),
964        _ => return Err("TealRecord: only structs and enums are supported".into()),
965    };
966    let decl = &rd.decl;
967    // A data-carrying enum is never a `.d.tl` module of its own (see `dts`), so there
968    // is no `require("NAME")` for it to satisfy.
969    let preload = if matches!(rd.kind, dts::RecordKind::Union { .. }) {
970        quote! {}
971    } else {
972        quote! {
973            impl #ident {
974                /// Make `require("NAME")` resolve at runtime: the record is types only, and a
975                /// declaration with nothing behind it fails the require, so put an empty table
976                /// under the name in `package.preload`.
977                pub fn htl_preload(h: &::htl::Htl) -> ::htl::mlua::Result<()> {
978                    let t = h.lua().create_table()?;
979                    h.preload_value(#name, t).map_err(::htl::mlua::Error::external)
980                }
981            }
982        }
983    };
984    Ok(quote! {
985        impl ::htl::teal::TealRecord for #ident {
986            const NAME: &'static str = #name;
987            const DECL: &'static str = #decl;
988        }
989        impl ::htl::mlua::IntoLua for #ident {
990            fn into_lua(self, lua: &::htl::mlua::Lua) -> ::htl::mlua::Result<::htl::mlua::Value> {
991                #into
992            }
993        }
994        impl ::htl::mlua::FromLua for #ident {
995            fn from_lua(value: ::htl::mlua::Value, lua: &::htl::mlua::Lua) -> ::htl::mlua::Result<Self> {
996                #from
997            }
998        }
999        #fields_impl
1000        #preload
1001    }
1002    .into())
1003}
1004
1005/// `field: { .. }` initializers reading each named field out of table `t`, in
1006/// declaration order, so `teal` (from `dts`, same order) pairs with the Rust types: the
1007/// key is the name `dts` declared (serde's, when serde renames it), then each
1008/// `#[serde(alias)]` in turn while what was read is nil. A failed field is reported under
1009/// `path` (`Record` or `Enum.Variant`) and the declared name.
1010fn field_reads(
1011    path: &str,
1012    named: &syn::FieldsNamed,
1013    teal: &[(String, String)],
1014) -> Vec<TokenStream2> {
1015    named
1016        .named
1017        .iter()
1018        .zip(teal)
1019        .map(|(f, (fname, fteal))| {
1020            let id = f.ident.as_ref().unwrap();
1021            let aliases = dts::serde_aliases(&f.attrs);
1022            let read = field_read(&quote!(#path), fname, &aliases, &f.ty, fteal, None, None);
1023            quote! { #id: #read }
1024        })
1025        .collect()
1026}
1027
1028/// A block reading key `fname` out of table `t` as `ty` — or, while that is nil, each of
1029/// `aliases` in turn — reporting a failure as `path.fname` (`path` an expression giving a
1030/// `&str`: a literal, or `read_fields`'s own `path`) with the Teal type `fteal` the
1031/// declaration promised. `nil`, when given, is what a key still nil after the aliases
1032/// reads as (a `#[serde(default)]`) instead of reaching the type's `FromLua`. `serde`, when
1033/// given (`#[teal(serde)]`), reads the value through `htl::teal::serde_field` instead of
1034/// `FromLua`, which reports at the same `path.fname`.
1035fn field_read(
1036    path: &TokenStream2,
1037    fname: &str,
1038    aliases: &[String],
1039    ty: &syn::Type,
1040    fteal: &str,
1041    nil: Option<TokenStream2>,
1042    serde: Option<&dts::SerdeCross>,
1043) -> TokenStream2 {
1044    let convert = match serde {
1045        None => quote! {
1046            {
1047                let got = v.type_name();
1048                <#ty as ::htl::mlua::FromLua>::from_lua(v, lua).map_err(|e| {
1049                    ::htl::teal::field_error(#path, #fname, #fteal, got, e)
1050                })?
1051            }
1052        },
1053        // Spanned at the field's type: without htl's `serde` feature the call's bound is
1054        // what rustc reports, and it is reported there.
1055        Some(sc) => {
1056            let empty = sc.empty_as_array;
1057            match &sc.de_with {
1058                None => quote_spanned! {ty.span()=>
1059                    ::htl::teal::serde_field::from_lua::<#ty>(lua, v, #path, #fname, #fteal, #empty)?
1060                },
1061                // `#[serde(with)]`: a local type whose `Deserialize` is the named function,
1062                // which serde itself calls only inside the struct's own `Deserialize`.
1063                Some(p) => {
1064                    let Ok(p) = syn::parse_str::<syn::ExprPath>(p) else {
1065                        return quote! { compile_error!("TealRecord: cannot read a `with` path"); };
1066                    };
1067                    quote_spanned! {ty.span()=>
1068                        {
1069                            struct __HtlDe(#ty);
1070                            impl<'de> ::htl::serde::Deserialize<'de> for __HtlDe {
1071                                fn deserialize<D: ::htl::serde::Deserializer<'de>>(
1072                                    d: D,
1073                                ) -> ::core::result::Result<Self, D::Error> {
1074                                    #p(d).map(__HtlDe)
1075                                }
1076                            }
1077                            ::htl::teal::serde_field::from_lua::<__HtlDe>(lua, v, #path, #fname, #fteal, #empty)?.0
1078                        }
1079                    }
1080                }
1081            }
1082        }
1083    };
1084    let value = match nil {
1085        None => convert,
1086        Some(d) => quote! { if v.is_nil() { #d } else #convert },
1087    };
1088    quote! {
1089        {
1090            // Take the field as a Value first: what arrived is half the message, and
1091            // the conversion consumes it.
1092            #[allow(unused_mut)]
1093            let mut v: ::htl::mlua::Value = t.get(#fname)?;
1094            #( if v.is_nil() { v = t.get(#aliases)?; } )*
1095            #value
1096        }
1097    }
1098}
1099
1100/// A path serde was given as a string (`default = "path"`, `skip_serializing_if =
1101/// "path"`), as tokens to call; `dts` checked it parses.
1102fn serde_path(p: &str) -> Result<syn::ExprPath, String> {
1103    syn::parse_str(p).map_err(|e| format!("TealRecord: cannot read the path {p:?}: {e}"))
1104}
1105
1106/// What a field that is nil (or skipped) is filled with, `None` for
1107/// [`dts::WhenNil::Convert`]. `Default::default()` is spanned at the field's type, so a type
1108/// without `Default` is reported there, by rustc, as serde's derive reports it.
1109fn nil_value(
1110    nil: &dts::WhenNil,
1111    id: &syn::Ident,
1112    ty: &syn::Type,
1113) -> Result<Option<TokenStream2>, String> {
1114    Ok(match nil {
1115        dts::WhenNil::Convert => None,
1116        dts::WhenNil::Own(dts::DefaultFrom::Trait) => Some(quote_spanned! {ty.span()=>
1117            <#ty as ::core::default::Default>::default()
1118        }),
1119        dts::WhenNil::Own(dts::DefaultFrom::Path(p)) => {
1120            let p = serde_path(p)?;
1121            Some(quote! { #p() })
1122        }
1123        dts::WhenNil::Struct => Some(quote! { __htl_default.#id }),
1124    })
1125}
1126
1127/// `let __htl_default: Self = ..;` for a struct with `#[serde(default)]`: the value its
1128/// fields are filled from ([`dts::WhenNil::Struct`]), built once up front as serde does.
1129/// Spanned at the struct, so a missing `Default` is reported there.
1130fn struct_default(st: &ItemStruct, conv: &dts::RecordConversion) -> Result<TokenStream2, String> {
1131    Ok(match &conv.default {
1132        None => quote! {},
1133        Some(dts::DefaultFrom::Trait) => quote_spanned! {st.ident.span()=>
1134            let __htl_default: Self = <Self as ::core::default::Default>::default();
1135        },
1136        Some(dts::DefaultFrom::Path(p)) => {
1137            let p = serde_path(p)?;
1138            quote! { let __htl_default: Self = #p(); }
1139        }
1140    })
1141}
1142
1143fn named_fields(st: &ItemStruct) -> &syn::FieldsNamed {
1144    match &st.fields {
1145        syn::Fields::Named(n) => n,
1146        _ => unreachable!("dts::record_decl classified this struct as a record"),
1147    }
1148}
1149
1150/// Record -> table: a table of its own, filled by the record's `TealFields`, a failure
1151/// named under the record.
1152fn record_into(name: &str) -> TokenStream2 {
1153    quote! {
1154        let t = lua.create_table()?;
1155        ::htl::teal::TealFields::write_fields(self, &t, lua, #name)?;
1156        Ok(::htl::mlua::Value::Table(t))
1157    }
1158}
1159
1160/// Table -> record: read by the record's `TealFields`, a failure named under the record.
1161fn record_from(name: &str) -> TokenStream2 {
1162    quote! {
1163        let t = <::htl::mlua::Table as ::htl::mlua::FromLua>::from_lua(value, lua)?;
1164        <Self as ::htl::teal::TealFields>::read_fields(&t, lua, #name)
1165    }
1166}
1167
1168/// `write_fields`' body: each field under the key `dts` declared it as (from the one
1169/// reading, [`dts::Crossing`], paired with the Rust fields by position). A skipped field
1170/// is left out, one whose `skip_serializing_if` holds is too (called as serde calls it,
1171/// `path(&self.field)`), and a flattened struct writes its own fields into this table under
1172/// the same `path`. A `#[teal(serde)]` field is written through `htl::teal::serde_field`, a
1173/// failure named `path.field` (`path` the record the table is declared as, as in
1174/// [`record_read`]).
1175fn record_write(st: &ItemStruct, conv: &dts::RecordConversion) -> Result<TokenStream2, String> {
1176    let mut out = Vec::new();
1177    for (f, c) in named_fields(st).named.iter().zip(&conv.fields) {
1178        let id = f.ident.as_ref().unwrap();
1179        let ty = &f.ty;
1180        out.push(match c {
1181            dts::Crossing::Key {
1182                name,
1183                skip_if,
1184                serde,
1185                ..
1186            } => {
1187                let value = match serde {
1188                    None => quote! { self.#id },
1189                    Some(sc) => {
1190                        let none_to_null = sc.none_to_null;
1191                        match &sc.ser_with {
1192                            None => quote_spanned! {ty.span()=>
1193                                ::htl::teal::serde_field::to_lua(lua, &self.#id, path, #name, #none_to_null)?
1194                            },
1195                            // `#[serde(with)]`: a local type whose `Serialize` is the named
1196                            // function (see `field_read`).
1197                            Some(p) => {
1198                                let p = serde_path(p)?;
1199                                quote_spanned! {ty.span()=>
1200                                    {
1201                                        struct __HtlSer<'a>(&'a #ty);
1202                                        impl ::htl::serde::Serialize for __HtlSer<'_> {
1203                                            fn serialize<S: ::htl::serde::Serializer>(
1204                                                &self,
1205                                                s: S,
1206                                            ) -> ::core::result::Result<S::Ok, S::Error> {
1207                                                #p(self.0, s)
1208                                            }
1209                                        }
1210                                        ::htl::teal::serde_field::to_lua(lua, &__HtlSer(&self.#id), path, #name, #none_to_null)?
1211                                    }
1212                                }
1213                            }
1214                        }
1215                    }
1216                };
1217                match skip_if {
1218                    None => quote! { t.set(#name, #value)?; },
1219                    Some(p) => {
1220                        let p = serde_path(p)?;
1221                        quote! { if !#p(&self.#id) { t.set(#name, #value)?; } }
1222                    }
1223                }
1224            }
1225            dts::Crossing::Skip { .. } => quote! {},
1226            dts::Crossing::Flatten { .. } => quote! {
1227                <#ty as ::htl::teal::TealFields>::write_fields(self.#id, t, lua, path)?;
1228            },
1229        });
1230    }
1231    Ok(quote! { #( #out )* })
1232}
1233
1234/// `read_fields`' body: every field checked and named on failure under `path` (the record
1235/// the table is declared as), a nil key read as its default where it has one, a skipped
1236/// field filled, and a flattened struct read from this same table under the same `path`.
1237fn record_read(st: &ItemStruct, conv: &dts::RecordConversion) -> Result<TokenStream2, String> {
1238    let mut inits = Vec::new();
1239    for (f, c) in named_fields(st).named.iter().zip(&conv.fields) {
1240        let id = f.ident.as_ref().unwrap();
1241        let ty = &f.ty;
1242        let value = match c {
1243            dts::Crossing::Key {
1244                name,
1245                teal,
1246                aliases,
1247                nil,
1248                serde,
1249                ..
1250            } => field_read(
1251                &quote!(path),
1252                name,
1253                aliases,
1254                ty,
1255                teal,
1256                nil_value(nil, id, ty)?,
1257                serde.as_ref(),
1258            ),
1259            dts::Crossing::Skip { nil } => nil_value(nil, id, ty)?
1260                .ok_or("TealRecord: a skipped field has to be filled from a default")?,
1261            dts::Crossing::Flatten { .. } => quote! {
1262                <#ty as ::htl::teal::TealFields>::read_fields(t, lua, path)?
1263            },
1264        };
1265        inits.push(quote! { #id: #value });
1266    }
1267    let default = struct_default(st, conv)?;
1268    Ok(quote! {
1269        #default
1270        Ok(Self { #( #inits, )* })
1271    })
1272}
1273
1274/// A skipped field of a transparent struct, and what it is filled from.
1275type Skipped<'a> = (&'a syn::Field, &'a dts::WhenNil);
1276
1277/// The one field a `#[serde(transparent)]` struct crosses as, and the others (skipped),
1278/// each with what it is filled from.
1279fn transparent_field<'a>(
1280    st: &'a ItemStruct,
1281    conv: &'a dts::RecordConversion,
1282) -> Result<(&'a syn::Field, Vec<Skipped<'a>>), String> {
1283    let mut kept = None;
1284    let mut skipped = Vec::new();
1285    for (f, c) in named_fields(st).named.iter().zip(&conv.fields) {
1286        match c {
1287            dts::Crossing::Skip { nil } => skipped.push((f, nil)),
1288            _ => kept = Some(f),
1289        }
1290    }
1291    // `dts::transparent_kind` refuses a struct without exactly one.
1292    let kept =
1293        kept.ok_or("TealRecord: a transparent struct needs one field that is not skipped")?;
1294    Ok((kept, skipped))
1295}
1296
1297/// Transparent struct -> whatever its one field converts to.
1298fn transparent_into(st: &ItemStruct, conv: &dts::RecordConversion) -> Result<TokenStream2, String> {
1299    let (f, _) = transparent_field(st, conv)?;
1300    let id = f.ident.as_ref().unwrap();
1301    Ok(quote! { ::htl::mlua::IntoLua::into_lua(self.#id, lua) })
1302}
1303
1304/// Value -> transparent struct: the one field through its own conversion, a refusal named
1305/// as an alias's is (`N: expected T, got ..`), the skipped fields filled.
1306fn transparent_from(
1307    st: &ItemStruct,
1308    name: &str,
1309    inner: &str,
1310    conv: &dts::RecordConversion,
1311) -> Result<TokenStream2, String> {
1312    let (f, skipped) = transparent_field(st, conv)?;
1313    let id = f.ident.as_ref().unwrap();
1314    let ty = &f.ty;
1315    let mut fills = Vec::new();
1316    for (sf, nil) in skipped {
1317        let sid = sf.ident.as_ref().unwrap();
1318        let v = nil_value(nil, sid, &sf.ty)?
1319            .ok_or("TealRecord: a skipped field has to be filled from a default")?;
1320        fills.push(quote! { #sid: #v });
1321    }
1322    let default = struct_default(st, conv)?;
1323    Ok(quote! {
1324        let got = value.type_name();
1325        let __htl_inner = <#ty as ::htl::mlua::FromLua>::from_lua(value, lua)
1326            .map_err(|e| ::htl::teal::value_error(#name, #inner, got, e))?;
1327        #default
1328        Ok(Self { #id: __htl_inner, #( #fills, )* })
1329    })
1330}
1331
1332/// Newtype -> whatever the inner value converts to.
1333fn alias_into() -> TokenStream2 {
1334    quote! { ::htl::mlua::IntoLua::into_lua(self.0, lua) }
1335}
1336
1337/// Value -> newtype, through the inner type's own conversion.
1338fn alias_from(st: &ItemStruct, name: &str, inner: &str) -> TokenStream2 {
1339    let ty = match &st.fields {
1340        syn::Fields::Unnamed(u) => &u.unnamed[0].ty,
1341        _ => unreachable!("dts::record_decl classified this struct as an alias"),
1342    };
1343    quote! {
1344        let got = value.type_name();
1345        let inner = <#ty as ::htl::mlua::FromLua>::from_lua(value, lua)
1346            .map_err(|e| ::htl::teal::value_error(#name, #inner, got, e))?;
1347        Ok(Self(inner))
1348    }
1349}
1350
1351fn variant_idents(en: &ItemEnum) -> Vec<&syn::Ident> {
1352    en.variants.iter().map(|v| &v.ident).collect()
1353}
1354
1355/// Unit enum -> the variant's word as a string: the one the declaration lists, which
1356/// `#[teal(rename_all)]` / `#[teal(name)]` may have spelled differently from Rust.
1357fn enum_into(en: &ItemEnum, words: &[String]) -> TokenStream2 {
1358    let idents = variant_idents(en);
1359    quote! {
1360        let s = match self { #( Self::#idents => #words, )* };
1361        Ok(::htl::mlua::Value::String(lua.create_string(s)?))
1362    }
1363}
1364
1365/// String -> unit enum; anything else, or a string that is no variant, names the enum
1366/// and lists what it accepts.
1367fn enum_from(en: &ItemEnum, name: &str, variants: &[String]) -> TokenStream2 {
1368    let idents = variant_idents(en);
1369    quote! {
1370        const VARIANTS: &[&str] = &[#( #variants ),*];
1371        match &value {
1372            ::htl::mlua::Value::String(s) => {
1373                // A string that is not UTF-8 is no variant either; it is reported by
1374                // its type rather than quoted, as there is nothing readable to quote.
1375                let Ok(s) = s.to_str() else {
1376                    return Err(::htl::teal::enum_error(#name, VARIANTS, "string"));
1377                };
1378                match &*s {
1379                    #( #variants => Ok(Self::#idents), )*
1380                    other => Err(::htl::teal::enum_error(#name, VARIANTS, &format!("\"{other}\""))),
1381                }
1382            }
1383            other => Err(::htl::teal::enum_error(#name, VARIANTS, other.type_name())),
1384        }
1385    }
1386}
1387
1388/// Data enum -> table: the tag (`kind`, or serde's `tag`) carries the variant's word (the
1389/// one its `where` clause tests); a newtype payload goes under `value` (htl's form) or the
1390/// content key (`tag` + `content`), or — under `tag` alone — writes its struct's fields
1391/// beside the tag through its `TealFields`; struct-variant fields go under the names `dts`
1392/// declared them as, beside the tag or in a table of their own under the content key. A
1393/// failure in a `tag` payload's fields is named `Enum.Variant.field`, as [`union_from`]
1394/// names it. An untagged enum is [`untagged_into`].
1395fn union_into(
1396    en: &ItemEnum,
1397    name: &str,
1398    variants: &[dts::UnionVariant],
1399    repr: &dts::UnionRepr,
1400) -> TokenStream2 {
1401    let Some(tag) = repr.tag() else {
1402        return untagged_into(en, variants);
1403    };
1404    let content = match repr {
1405        dts::UnionRepr::Adjacent { content, .. } => Some(content.as_str()),
1406        _ => None,
1407    };
1408    let arms: Vec<TokenStream2> = en
1409        .variants
1410        .iter()
1411        .zip(variants)
1412        .map(|(v, uv)| {
1413            let id = &v.ident;
1414            let vname = uv.word.as_str();
1415            match (&v.fields, &uv.shape) {
1416                (syn::Fields::Unit, _) => quote! {
1417                    Self::#id => { t.set(#tag, #vname)?; }
1418                },
1419                (syn::Fields::Unnamed(u), dts::VariantShape::Inline { .. }) => {
1420                    let ty = &u.unnamed[0].ty;
1421                    // The path `union_from` reads it under: `Enum.Variant`.
1422                    let path = format!("{name}.{}", uv.name);
1423                    quote! {
1424                        Self::#id(value) => {
1425                            t.set(#tag, #vname)?;
1426                            <#ty as ::htl::teal::TealFields>::write_fields(value, &t, lua, #path)?;
1427                        }
1428                    }
1429                }
1430                (syn::Fields::Unnamed(_), _) => {
1431                    let key = content.unwrap_or("value");
1432                    quote! {
1433                        Self::#id(value) => { t.set(#tag, #vname)?; t.set(#key, value)?; }
1434                    }
1435                }
1436                (syn::Fields::Named(n), shape) => {
1437                    let ids: Vec<_> = n.named.iter().map(|f| f.ident.as_ref().unwrap()).collect();
1438                    let dts::VariantShape::Struct(fields) = shape else {
1439                        unreachable!("dts::record_decl and this walk see the same variants")
1440                    };
1441                    let names: Vec<&str> = fields.iter().map(|(n, _)| n.as_str()).collect();
1442                    // Bound under prefixed names: a field called `t` or `lua` must not
1443                    // shadow the table or the state the arm writes through.
1444                    let binds: Vec<_> =
1445                        ids.iter().map(|i| format_ident!("__htl_f_{}", i)).collect();
1446                    match content {
1447                        None => quote! {
1448                            Self::#id { #( #ids: #binds ),* } => {
1449                                t.set(#tag, #vname)?;
1450                                #( t.set(#names, #binds)?; )*
1451                            }
1452                        },
1453                        Some(c) => quote! {
1454                            Self::#id { #( #ids: #binds ),* } => {
1455                                t.set(#tag, #vname)?;
1456                                let __htl_c = lua.create_table()?;
1457                                #( __htl_c.set(#names, #binds)?; )*
1458                                t.set(#c, __htl_c)?;
1459                            }
1460                        },
1461                    }
1462                }
1463            }
1464        })
1465        .collect();
1466    quote! {
1467        let t = lua.create_table()?;
1468        match self { #( #arms )* }
1469        Ok(::htl::mlua::Value::Table(t))
1470    }
1471}
1472
1473/// Table -> data enum: the tag picks the variant, then its payload is read as a record's
1474/// fields are, reported under `Enum.Variant` (`Enum.Variant.c` inside an adjacently tagged
1475/// struct payload). No table, no tag, or an unknown one names the enum and lists the
1476/// variants. An untagged enum is [`untagged_from`].
1477fn union_from(
1478    en: &ItemEnum,
1479    name: &str,
1480    variants: &[dts::UnionVariant],
1481    repr: &dts::UnionRepr,
1482) -> TokenStream2 {
1483    let Some(tag) = repr.tag() else {
1484        return untagged_from(en, name, variants);
1485    };
1486    let content = match repr {
1487        dts::UnionRepr::Adjacent { content, .. } => Some(content.as_str()),
1488        _ => None,
1489    };
1490    let vnames: Vec<&str> = variants.iter().map(|v| v.word.as_str()).collect();
1491    let arms: Vec<TokenStream2> = en
1492        .variants
1493        .iter()
1494        .zip(variants)
1495        .map(|(v, uv)| {
1496            let id = &v.ident;
1497            let vname = uv.word.as_str();
1498            // The path names the variant record the value failed to fill
1499            // (`Shape.Rect.h` for `record Shape_Rect`), which stays the Rust name.
1500            let path = format!("{name}.{}", uv.name);
1501            match (&v.fields, &uv.shape) {
1502                (syn::Fields::Unit, _) => quote! { #vname => Ok(Self::#id), },
1503                (syn::Fields::Unnamed(u), dts::VariantShape::Newtype(teal)) => {
1504                    let key = content.unwrap_or("value");
1505                    let read =
1506                        field_read(&quote!(#path), key, &[], &u.unnamed[0].ty, teal, None, None);
1507                    quote! { #vname => Ok(Self::#id(#read)), }
1508                }
1509                (syn::Fields::Unnamed(u), dts::VariantShape::Inline { .. }) => {
1510                    let ty = &u.unnamed[0].ty;
1511                    quote! {
1512                        #vname => Ok(Self::#id(
1513                            <#ty as ::htl::teal::TealFields>::read_fields(&t, lua, #path)?
1514                        )),
1515                    }
1516                }
1517                (syn::Fields::Named(n), dts::VariantShape::Struct(fields)) => match content {
1518                    None => {
1519                        let reads = field_reads(&path, n, fields);
1520                        quote! { #vname => Ok(Self::#id { #( #reads, )* }), }
1521                    }
1522                    Some(c) => {
1523                        let crec = format!("{name}_{}_Content", uv.name);
1524                        let reads = field_reads(&format!("{path}.{c}"), n, fields);
1525                        quote! {
1526                            #vname => {
1527                                let __htl_c: ::htl::mlua::Value = t.get(#c)?;
1528                                let got = __htl_c.type_name();
1529                                // The fields are read out of the content table, under
1530                                // `Enum.Variant.<content>`.
1531                                let t = <::htl::mlua::Table as ::htl::mlua::FromLua>::from_lua(__htl_c, lua)
1532                                    .map_err(|e| ::htl::teal::field_error(#path, #c, #crec, got, e))?;
1533                                Ok(Self::#id { #( #reads, )* })
1534                            }
1535                        }
1536                    }
1537                },
1538                _ => unreachable!("dts::record_decl and this walk see the same variants"),
1539            }
1540        })
1541        .collect();
1542    quote! {
1543        const VARIANTS: &[&str] = &[#( #vnames ),*];
1544        let t = match value {
1545            ::htl::mlua::Value::Table(t) => t,
1546            other => return Err(::htl::teal::enum_error(#name, VARIANTS, other.type_name())),
1547        };
1548        let kind: ::htl::mlua::Value = t.get(#tag)?;
1549        let kind = match &kind {
1550            ::htl::mlua::Value::String(s) => match s.to_str() {
1551                Ok(s) => s.to_string(),
1552                // Not UTF-8: no variant, reported by type (nothing readable to quote).
1553                Err(_) => return Err(::htl::teal::enum_error(#name, VARIANTS, "string")),
1554            },
1555            other => return Err(::htl::teal::enum_error(#name, VARIANTS, other.type_name())),
1556        };
1557        match kind.as_str() {
1558            #( #arms )*
1559            other => Err(::htl::teal::enum_error(#name, VARIANTS, &format!("\"{other}\""))),
1560        }
1561    }
1562}
1563
1564/// Untagged enum -> the payload alone: a newtype's value as its own type converts, a struct
1565/// variant's fields in a table, as serde writes `#[serde(untagged)]`.
1566fn untagged_into(en: &ItemEnum, variants: &[dts::UnionVariant]) -> TokenStream2 {
1567    let arms: Vec<TokenStream2> = en
1568        .variants
1569        .iter()
1570        .zip(variants)
1571        .map(|(v, uv)| {
1572            let id = &v.ident;
1573            match (&v.fields, &uv.shape) {
1574                (syn::Fields::Named(n), dts::VariantShape::Struct(fields)) => {
1575                    let ids: Vec<_> = n.named.iter().map(|f| f.ident.as_ref().unwrap()).collect();
1576                    let names: Vec<&str> = fields.iter().map(|(n, _)| n.as_str()).collect();
1577                    let binds: Vec<_> =
1578                        ids.iter().map(|i| format_ident!("__htl_f_{}", i)).collect();
1579                    quote! {
1580                        Self::#id { #( #ids: #binds ),* } => {
1581                            let t = lua.create_table()?;
1582                            #( t.set(#names, #binds)?; )*
1583                            Ok(::htl::mlua::Value::Table(t))
1584                        }
1585                    }
1586                }
1587                _ => quote! {
1588                    Self::#id(value) => ::htl::mlua::IntoLua::into_lua(value, lua),
1589                },
1590            }
1591        })
1592        .collect();
1593    quote! { match self { #( #arms )* } }
1594}
1595
1596/// Value -> untagged enum, by the value's Lua type, as Teal's `is` narrows: a string, a
1597/// number or a boolean goes to the newtype over that type, a table to the one variant that
1598/// crosses as a table (`dts` refuses two of either). A newtype over another type takes
1599/// whatever no primitive variant did, through its own `FromLua`. Anything left names the
1600/// enum and lists the union's members.
1601fn untagged_from(en: &ItemEnum, name: &str, variants: &[dts::UnionVariant]) -> TokenStream2 {
1602    let mut members: Vec<String> = Vec::new();
1603    let mut arms: Vec<TokenStream2> = Vec::new();
1604    let mut rest: Option<TokenStream2> = None;
1605    for (v, uv) in en.variants.iter().zip(variants) {
1606        let id = &v.ident;
1607        let path = format!("{name}.{}", uv.name);
1608        match (&v.fields, &uv.shape) {
1609            (syn::Fields::Named(n), dts::VariantShape::Struct(fields)) => {
1610                members.push(format!("{name}_{}", uv.name));
1611                let reads = field_reads(&path, n, fields);
1612                arms.push(quote! {
1613                    ::htl::mlua::Value::Table(t) => Ok(Self::#id { #( #reads, )* }),
1614                });
1615            }
1616            (syn::Fields::Unnamed(u), dts::VariantShape::Newtype(teal)) => {
1617                members.push(teal.clone());
1618                let ty = &u.unnamed[0].ty;
1619                let convert = quote! {
1620                    {
1621                        let got = v.type_name();
1622                        let x = <#ty as ::htl::mlua::FromLua>::from_lua(v, lua)
1623                            .map_err(|e| ::htl::teal::value_error(#path, #teal, got, e))?;
1624                        Ok(Self::#id(x))
1625                    }
1626                };
1627                let pat = match dts::untagged_lua_type(teal) {
1628                    Some("string") => quote! { v @ ::htl::mlua::Value::String(_) },
1629                    Some("number") => quote! {
1630                        v @ (::htl::mlua::Value::Integer(_) | ::htl::mlua::Value::Number(_))
1631                    },
1632                    Some(_) => quote! { v @ ::htl::mlua::Value::Boolean(_) },
1633                    None => {
1634                        rest = Some(quote! { v => #convert });
1635                        continue;
1636                    }
1637                };
1638                arms.push(quote! { #pat => #convert, });
1639            }
1640            _ => unreachable!("dts::record_decl refuses any other untagged variant"),
1641        }
1642    }
1643    let rest = rest.unwrap_or_else(|| {
1644        quote! { other => Err(::htl::teal::union_error(#name, MEMBERS, other.type_name())) }
1645    });
1646    quote! {
1647        #[allow(dead_code)]
1648        const MEMBERS: &[&str] = &[#( #members ),*];
1649        match value {
1650            #( #arms )*
1651            #rest
1652        }
1653    }
1654}
1655
1656// ------------------------------------------------------------------ #[host_module]
1657
1658/// Turn a plain `impl` block into a `mlua::UserData` impl, and write its Teal
1659/// declaration (`dts = "scripts/host.d.tl"`) when the macro expands, so a script sees
1660/// `host:scale(p: Point, k: number): Point` and `host.Point`. Change a Rust signature and
1661/// the next `cargo build` fails inside the `.tl` that relied on it: the declaration is
1662/// rewritten first, and `include_tl!` / `include_bundle!` check against it. The
1663/// breakdown is `htl_core::dts::host_decl`, which `htl dts` runs without building.
1664///
1665/// `name` may be dotted (`name = "std.fs"`): the whole string is `require`'s key and
1666/// what `htl_preload` registers in `package.preload` under, but a Teal declaration has
1667/// room for only one identifier where the module sits (`local record ..`, `self: ..`,
1668/// `return ..`), so that identifier is `name`'s last segment (`fs`) — the same split
1669/// `std.json`'s `local record json` and `require("std.json")` make
1670/// (`htl_core::batteries`). Every segment, including the ones before the last, has to be
1671/// a Teal identifier and not a Teal keyword; `name = "std"` (one segment) is the plain,
1672/// undotted case and renders exactly as before, and a `name` that is not a Teal
1673/// identifier (`name = "my-mod"`) is refused — by the macro at `cargo build`, and by
1674/// `htl dts`, which runs the same breakdown — so no declaration Teal itself would refuse
1675/// to parse is ever written.
1676///
1677/// `dts` still names wherever the `.d.tl` is written, but a dotted name's declaration
1678/// has to sit where the project model's path-based naming rule reads it back as that
1679/// name: `dts = "types/std/fs.d.tl"` for `name = "std.fs"`, the per-segment path under
1680/// the declaration root — the same place `std.json`'s own declaration sits, at
1681/// `std/json.d.tl`. `dts = "types/fs.d.tl"` would write a file the checker reads back as
1682/// `fs`, not `std.fs`: the project model learns from this attribute that the host
1683/// provides `std.fs`, but it finds the declaration of a name only by the file's path
1684/// under the declaration root, so a file at the wrong path declares a different name.
1685///
1686/// `&str`, `&[T]`, `&Record` and `&Lua` (see *The Lua state as a parameter*) parameters
1687/// are accepted (`&mut` is not); an `Option<T>`
1688/// parameter is declared `name?: T`, so a caller may write `api:find("x")`; another host
1689/// type comes in as `UserDataRef<T>` (`UserDataRefMut<T>` to mutate it, `UserDataOwned<T>`
1690/// to keep it) and is declared as `T`; types from other modules come in via `uses =
1691/// [Name]` (`local type Name = require("Name")`) — or, when the module a type lives in is
1692/// not its own name, `uses = [name = "module.path"]` (`local type name =
1693/// require("module.path")`), which is also how a Rust field or return whose type is
1694/// qualified by that same name (`name::Type`) crosses, as `name.Type`, ahead of any other
1695/// rule — a qualified type with no matching `uses` entry crosses under its own last
1696/// segment, same as a bare one. Nested `#[derive(TealRecord)]` types come in via
1697/// `records = [..]` — a bare name (`records = [Point]`) for one declared in this same
1698/// file, or a module path one level deep (`records = [geom::Point]`) for one in a `mod
1699/// geom;` declared here, read from the file Rust compiles it from: next to this file when
1700/// it is a crate root (`lib.rs` / `main.rs` / `mod.rs`, or a file directly under
1701/// `src/bin/`, `tests/`, `examples/` or `benches/`), otherwise in a directory named after
1702/// this file's own stem (not a `[lib] path` override or another custom crate root). Either
1703/// way the record nests as `host.Point`; `uses = [Point]` instead gives it a module of its own
1704/// (`local type Point = require("Point")`), so it is `Point` rather than `host.Point`,
1705/// and every `.tl` that wrote `host.Point` has to be rewritten to match. `Result<T, E>`
1706/// returns raise a Lua error on `Err` by default; with
1707/// `errors = "return"` on the attribute they come back Lua-style (`v, nil` / `nil, err`),
1708/// so `local ok, err = store:write(name, text)` needs no `pcall`. A parameter that may
1709/// see a value from outside checked Teal is a `Strict<T>` (`htl::teal::Strict`).
1710///
1711/// With the `async` feature a method may be `async`, in the same `impl` as the sync
1712/// ones:
1713///
1714/// ```rust,ignore
1715/// #[host_module(name = "api")]
1716/// impl Api {
1717///     pub fn seen(&self) -> u32 { self.calls }
1718///     pub async fn fetch(&self, path: String) -> String { /* … */ }
1719/// }
1720/// ```
1721///
1722/// The method runs inside a coroutine, and something has to drive it: `htl run` and
1723/// `htl test` do (the program is a root on the executor, `Htl::run_async`), a host
1724/// awaits `Htl::run_async` on its own runtime or calls `Htl::run_blocking`, or drives the
1725/// method itself with mlua's `call_async` / an `AsyncThread`; a plain `load(..).eval()`
1726/// raises rather than blocking. Under a root the body is wrapped in mlua-isle's
1727/// `cancellable`, so a cancel of the program (Ctrl-C in `htl run`, the host's token)
1728/// returns at the await instead of waiting out the grace (`[async]` in `htl.toml`,
1729/// `htl::config::AsyncConfig`). Two things follow from mlua: the receiver is borrowed
1730/// across every await (`add_async_method` hands over a `UserDataRef<T>` the future holds
1731/// until it resolves, so prefer `&self` over `&mut self`), and the future must be
1732/// `'static`, and `Send` as well when mlua's `send` feature is on.
1733///
1734/// # A Lua function as a parameter
1735///
1736/// A `Function` parameter (mlua's; an `Option<Function>` is declared `f?: function` when it
1737/// is trailing, as any `Option` parameter) is a
1738/// callback, and what matters about it under `[lang] async` is whether a suspension inside
1739/// it can reach an executor. That is decided by the body, not the signature: mlua's
1740/// `Function::call` runs it from C, where a yield fails with `attempt to yield across a
1741/// C-call boundary`, and `Function::call_async` runs it as a coroutine, where it may yield.
1742/// The declaration says which parameters are called from C with a trailing
1743/// `---@noyield(names)`, which the checker's `async-as-sync-callback` reads to report an
1744/// async function passed there (`htl::lint`), and the macro writes it from what the
1745/// signature does show:
1746///
1747/// ```rust,ignore
1748/// #[host_module(name = "api")]
1749/// impl Api {
1750///     pub fn each(&self, f: Function) -> String { /* f.call(..) */ }
1751///     pub async fn each_async(&self, f: Function) -> String { /* f.call_async(..).await */ }
1752/// }
1753/// // each: function(self: api, f: function): string ---@noyield(f)
1754/// // each_async: function(self: api, f: function): string ---@async
1755/// ```
1756///
1757/// - **A sync fn marks each of its `Function` parameters**, in parameter order
1758///   (`---@noyield(on_ok, on_err)`): it has no `call_async` to reach for, so `call` is the
1759///   only way it can run the function.
1760/// - **An `async fn` marks none**: its callback is to be called with `call_async`. Calling
1761///   it with the sync `call` inside an `async fn` compiles, and fails at run time the first
1762///   time the callback suspends; the signature does not show it, so the checker cannot.
1763///
1764/// The default is wrong in two cases, and an attribute on the parameter says so:
1765///
1766/// - `#[teal(yields)] f: Function` on a sync fn that stores `f` and calls it later with
1767///   `call_async` under an executor the host drives: `f` is left out of the marker.
1768/// - `#[teal(noyield)] f: Function` on an `async fn` that calls `f` with the sync `call` on
1769///   purpose: `f` is named, beside `---@async` (`... ---@async ---@noyield(f)`).
1770///
1771/// Either word states the fact, so it may be written where it matches the default as
1772/// well. Anything else in a parameter's `#[teal(..)]`, either word on a parameter that is
1773/// not a `Function`, or the attribute on a fn that is not `pub` is refused. The attribute
1774/// is removed from the impl the macro emits; `htl dts` reads it from the same source and
1775/// writes the same line.
1776///
1777/// A callback can also reach the host as a field of a table: the host is handed a table
1778/// (or reads one a module returned) and calls its fields itself, the shape of `htl-mq`'s
1779/// game table, whose `update` and `draw` run every frame through `Function::call`. There
1780/// the signature has nothing to go by, since the table arrives as a `Table` or a record,
1781/// so the declaration says it field by field: `#[teal(noyield)]` on a `Function` /
1782/// `Option<Function>` field of a `#[derive(TealRecord)]` struct writes a bare
1783/// `---@noyield` at the end of that field's line, and a table constructor the checker
1784/// types as the record (`local game: mq.Game = { update = .. }`, not `{ .. } as mq.Game`)
1785/// is reported at an async value bound to the field.
1786///
1787/// ```rust,ignore
1788/// #[derive(TealRecord)]
1789/// struct Game {
1790///     #[teal(noyield)] load: Option<Function>,
1791///     #[teal(noyield)] update: Function,
1792/// }
1793/// // record Game
1794/// //    load: function ---@noyield
1795/// //    update: function ---@noyield
1796/// // end
1797/// ```
1798///
1799/// `noyield` goes only on a `Function` / `Option<Function>` field of a struct (a data
1800/// variant's fields cannot take it; the one other word a field takes is `as`, see
1801/// `TealRecord`); a field has no default to turn around, so an unmarked one is simply not
1802/// a boundary. The derive re-emits nothing, so the
1803/// attribute stays on the struct, where rustc reads it as the derive's own.
1804///
1805/// # The Lua state as a parameter
1806///
1807/// A parameter of type `&Lua` (`&mlua::Lua`, `&htl::mlua::Lua`; matched behind a
1808/// reference by the last path segment, as every type here is) is filled from the
1809/// closure's own Lua handle rather than from the Lua arguments, and is left out of the
1810/// `.d.tl`, the way `&self` is — the method may be given whatever it needs the state for
1811/// (building a `htl::task::RecvChannel::new(lua, cap)`, a table, a function) inside the
1812/// call instead of having it built beforehand and stored on the host:
1813///
1814/// ```rust,ignore
1815/// #[host_module(name = "host")]
1816/// impl Host {
1817///     pub fn count(&self, lua: &htl::mlua::Lua) -> i64 { lua.used_memory() as i64 }
1818/// }
1819/// // count: function(self: host): integer
1820/// ```
1821///
1822/// At most one such parameter, in any position among the others; it takes no
1823/// `#[teal(..)]` (that word says how the host calls a Lua function it is handed, and this
1824/// is not one). Its name is free — any identifier, `_`, even `this` or `self`'s own
1825/// name — because the generated wrapper never reads it back: the value is bound to an
1826/// identifier of the macro's own choosing and spliced into the call positionally, the
1827/// parameter's declared name serving only the messages above.
1828///
1829/// A sync method's closure already receives `&Lua` (`add_method`, `add_method_mut`,
1830/// `add_function`), so this costs nothing; an `async fn`'s receives an owned `Lua` (mlua
1831/// hands over a value there, not a borrow), so the generated wrapper binds the parameter
1832/// to a reference into it at the top of the future — sound because an async block may
1833/// hold a reference to its own local across its own awaits, the same way it already holds
1834/// the receiver's `UserDataRef` across them.
1835#[proc_macro_attribute]
1836pub fn host_module(attr: TokenStream, item: TokenStream) -> TokenStream {
1837    let metas = match Punctuated::<Meta, Token![,]>::parse_terminated.parse(attr) {
1838        Ok(m) => m,
1839        Err(e) => {
1840            let msg = e.to_string();
1841            return quote! { compile_error!(#msg); }.into();
1842        }
1843    };
1844    let imp = parse_macro_input!(item as ItemImpl);
1845    match expand_host_module(metas, &imp) {
1846        Ok(ts) => ts,
1847        Err(msg) => quote! { compile_error!(#msg); }.into(),
1848    }
1849}
1850
1851/// The file this macro is expanding in: its items (needed for `records = [...]`) and its
1852/// own path (needed when one of those entries is module-qualified, `records =
1853/// [geom::Point]`, to find the module's file — [`dts::host_decl`]). `None` when the span
1854/// carries no local file (outside a real expansion: some IDE tooling, `cargo
1855/// expand`-style tools that lose it).
1856fn current_file() -> Option<(Vec<syn::Item>, PathBuf)> {
1857    let file = proc_macro::Span::call_site().local_file()?;
1858    let src = std::fs::read_to_string(&file).ok()?;
1859    let items = syn::parse_file(&src).ok()?.items;
1860    Some((items, file))
1861}
1862
1863/// A file read to resolve a `records = [module::Name]` entry, tracked with
1864/// `include_str!` on its absolute path, the same way `settings_tracked` tracks
1865/// `htl.toml`. Usually redundant: `geom.rs` is a source of this crate already (rustc
1866/// parses it to compile `mod geom;` at all), so it is already in the dep-info cargo
1867/// rebuilds from, and the macro re-expands on every recompile regardless — the belt is
1868/// for the one case that is not redundant (`mod geom;` behind a `#[cfg]` this build does
1869/// not take, so rustc never parses `geom.rs` on its own) and for keeping one rule
1870/// (`include_str!` every file this macro reads beyond the token stream it was handed)
1871/// rather than two. Pure (no `proc_macro` types), so it is unit-tested the same way
1872/// `settings_tracked` is.
1873fn record_files_tracked(files: &[PathBuf]) -> TokenStream2 {
1874    let files: Vec<String> = files
1875        .iter()
1876        .map(|p| p.to_string_lossy().into_owned())
1877        .collect();
1878    quote! {
1879        #( const _: &str = include_str!(#files); )*
1880    }
1881}
1882
1883fn expand_host_module(
1884    metas: Punctuated<Meta, Token![,]>,
1885    imp: &ItemImpl,
1886) -> Result<TokenStream, String> {
1887    let attrs = dts::parse_attr_metas(metas)?;
1888    let (file_items, file_path) = if attrs.records.is_empty() {
1889        (None, None)
1890    } else {
1891        match current_file() {
1892            Some((items, path)) => (Some(items), Some(path)),
1893            None => (None, None),
1894        }
1895    };
1896    let hd = dts::host_decl(imp, attrs, file_items.as_deref(), file_path.as_deref())?;
1897    let record_files_tracked = record_files_tracked(&hd.record_files);
1898    if let Some(d) = &hd.attrs.dts {
1899        write_dts(d, &hd.decl)?;
1900    }
1901
1902    // `#[teal(yields)]` / `#[teal(noyield)]` on a parameter is read by `host_decl` above and
1903    // means nothing to rustc, which knows no `teal` attribute outside `derive(TealRecord)`:
1904    // the impl is re-emitted without it. `host_decl` has refused every other use of it.
1905    let mut imp = imp.clone();
1906    for it in &mut imp.items {
1907        if let syn::ImplItem::Fn(f) = it {
1908            for a in &mut f.sig.inputs {
1909                if let syn::FnArg::Typed(pt) = a {
1910                    pt.attrs.retain(|a| !a.path().is_ident("teal"));
1911                }
1912            }
1913        }
1914    }
1915    let imp = &imp;
1916    let self_ty = &imp.self_ty;
1917    let module = &hd.module;
1918    let decl = &hd.decl;
1919    let mut registrations = Vec::new();
1920    for m in &hd.methods {
1921        let fname = format_ident!("{}", m.name);
1922        let fname_s = &m.name;
1923        let arg_pats: Vec<_> = m
1924            .params
1925            .iter()
1926            .map(|p| format_ident!("{}", p.name))
1927            .collect();
1928        let arg_tys: Vec<&syn::Type> = m.params.iter().map(|p| &p.owned_ty).collect();
1929        // A `&Lua` parameter is not among `m.params` (it is filled from the closure's own
1930        // Lua handle, not from the Lua arguments — see `dts::is_lua_ref`), so it is spliced
1931        // back into the call at the position it held in the original signature
1932        // (`LuaParam::index`), the way `&self` is passed as `this` rather than through
1933        // `#pat`. The binding is always this fixed internal identifier, never the user's
1934        // own parameter name (`LuaParam::name` is for error messages only): a call is
1935        // positional, so what the generated code binds the value to and what the Rust
1936        // signature calls its parameter need not be the same word, and the user's word may
1937        // collide with one of ours (`this`, a pattern-less `_` falling back to `a0`, two
1938        // parameters both named `a0`) without consequence.
1939        let htl_lua = format_ident!("__htl_lua");
1940        let total = m.params.len() + m.lua_param.is_some() as usize;
1941        let mut call_exprs: Vec<proc_macro2::TokenStream> = Vec::with_capacity(total);
1942        let mut pi = 0usize;
1943        for idx in 0..total {
1944            if m.lua_param.as_ref().is_some_and(|lp| lp.index == idx) {
1945                call_exprs.push(quote! { #htl_lua });
1946            } else {
1947                let p = &m.params[pi];
1948                pi += 1;
1949                let id = format_ident!("{}", p.name);
1950                call_exprs.push(if p.by_ref {
1951                    quote! { &#id }
1952                } else {
1953                    quote! { #id }
1954                });
1955            }
1956        }
1957        let call_args = quote! { #( #call_exprs ),* };
1958        let call = match m.receiver {
1959            Some(_) => quote! { this.#fname(#call_args) },
1960            None => quote! { <#self_ty>::#fname(#call_args) },
1961        };
1962        // An `async fn` returns a future; everything downstream — the error handling, the
1963        // `value, err` convention — is about the value it resolves to.
1964        let call = if m.is_async {
1965            quote! { #call.await }
1966        } else {
1967            call
1968        };
1969        let body = match (m.ret_is_result, hd.err_mode) {
1970            (false, _) => quote! { ::htl::mlua::Result::Ok(#call) },
1971            (true, dts::ErrMode::Raise) => quote! { #call.map_err(::htl::mlua::Error::external) },
1972            // `value, err` convention: Ok(v) -> (v, nil); Ok(()) -> (true, nil); Err(e) -> (nil, e).
1973            (true, dts::ErrMode::Return) if m.ret_is_unit => quote! {
1974                match #call {
1975                    Ok(()) => ::htl::mlua::Result::Ok((Some(true), None::<String>)),
1976                    Err(e) => ::htl::mlua::Result::Ok((None::<bool>, Some(e.to_string()))),
1977                }
1978            },
1979            (true, dts::ErrMode::Return) => quote! {
1980                match #call {
1981                    Ok(v) => ::htl::mlua::Result::Ok((Some(v), None::<String>)),
1982                    Err(e) => ::htl::mlua::Result::Ok((None, Some(e.to_string()))),
1983                }
1984            },
1985        };
1986        let pat = quote! { (#( #arg_pats, )*): (#( #arg_tys, )*) };
1987        // A sync closure's first argument is already `&Lua` (mlua's `add_method` /
1988        // `add_method_mut` / `add_function`), so a `&Lua` parameter is bound there directly
1989        // under the fixed internal name — `_lua`, unused, when the method takes none.
1990        let sync_lua = if m.lua_param.is_some() {
1991            htl_lua.clone()
1992        } else {
1993            format_ident!("_lua")
1994        };
1995        // An async closure's first argument is `Lua` *by value* (mlua hands over an owned
1996        // handle there, not a borrow — see the macro doc's async section), so it keeps the
1997        // fixed internal name and a `&Lua` parameter borrows from it inside the future with
1998        // a `let` at the top of the block: an async block may hold a reference to its own
1999        // local across its own awaits (the state the generator transform builds is exactly
2000        // what makes that sound), the way it holds the receiver's `UserDataRef` across them.
2001        let async_lua_bind = m
2002            .lua_param
2003            .as_ref()
2004            .map(|_| quote! { let #htl_lua = &_lua; });
2005        // The async variants differ in more than the name: they take the Lua by value and
2006        // the receiver as a borrow guard (`UserDataRef`) that the future holds across
2007        // every await, and the future itself must be `'static`. `async move` is what
2008        // makes it one — the arguments are moved in rather than borrowed from the call.
2009        // The future goes through mlua-isle's `cancellable`: under a root the executor
2010        // runs (`Htl::run_async`, `htl run`), a cancel of the program returns the cancel
2011        // error at this await instead of leaving the future pending until the grace runs
2012        // out; outside any root (a host driving the method with `call_async` itself) the
2013        // future runs unchanged.
2014        let wrap = |fut: proc_macro2::TokenStream| {
2015            quote! { ::htl::mlua_isle::runtime::cancellable(#fut) }
2016        };
2017        registrations.push(match (m.receiver, m.is_async) {
2018            (Some(false), false) => {
2019                quote! { m.add_method(#fname_s, |#sync_lua, this, #pat| #body); }
2020            }
2021            (Some(true), false) => {
2022                quote! { m.add_method_mut(#fname_s, |#sync_lua, this, #pat| #body); }
2023            }
2024            (None, false) => quote! { m.add_function(#fname_s, |#sync_lua, #pat| #body); },
2025            (Some(false), true) => {
2026                let fut = wrap(quote! { async move { #async_lua_bind #body } });
2027                quote! { m.add_async_method(#fname_s, |_lua, this, #pat| #fut); }
2028            }
2029            (Some(true), true) => {
2030                let fut = wrap(quote! { async move { #async_lua_bind #body } });
2031                quote! { m.add_async_method_mut(#fname_s, |_lua, mut this, #pat| #fut); }
2032            }
2033            (None, true) => {
2034                let fut = wrap(quote! { async move { #async_lua_bind #body } });
2035                quote! { m.add_async_function(#fname_s, |_lua, #pat| #fut); }
2036            }
2037        });
2038    }
2039
2040    Ok(quote! {
2041        #imp
2042        #record_files_tracked
2043        impl ::htl::mlua::UserData for #self_ty {
2044            fn add_methods<M: ::htl::mlua::UserDataMethods<Self>>(m: &mut M) {
2045                #( #registrations )*
2046            }
2047        }
2048        impl ::htl::teal::HostModule for #self_ty {
2049            const MODULE: &'static str = #module;
2050            const DECL: &'static str = #decl;
2051        }
2052        impl #self_ty {
2053            /// Register this instance as the `require("MODULE")` value.
2054            pub fn htl_preload(self, h: &::htl::Htl) -> ::htl::mlua::Result<()> {
2055                h.preload_value(#module, self).map_err(::htl::mlua::Error::external)
2056            }
2057        }
2058    }
2059    .into())
2060}
2061
2062// ------------------------------------------------------------------ #[c_export]
2063
2064/// `#[c_export(prefix = "hello", header = "include/hello.h")]` on an `impl` block ->
2065/// one `extern "C"` wrapper per `pub fn`, the handle lifecycle, and the C header.
2066///
2067/// The mirror of [`macro@host_module`]: the same breakdown of the `impl` block, said to
2068/// a caller that is not written in Rust. What is generated, what each wrapper's shape
2069/// is, and which signatures are refused is in `htl::cexport`; the runtime the generated
2070/// code calls is `htl::ffi`, which needs the `ffi` feature of the `htl` crate.
2071///
2072/// `prefix` defaults to the type name lowercased. Without `header` the text is still
2073/// `<Type>::HEADER`; with it, the file is written at expansion time relative to
2074/// `CARGO_MANIFEST_DIR` and only when its contents changed, exactly as
2075/// `#[host_module(dts = "..")]` writes its `.d.tl`.
2076#[proc_macro_attribute]
2077pub fn c_export(attr: TokenStream, item: TokenStream) -> TokenStream {
2078    let metas = match Punctuated::<Meta, Token![,]>::parse_terminated.parse(attr) {
2079        Ok(m) => m,
2080        Err(e) => {
2081            let msg = e.to_string();
2082            return quote! { compile_error!(#msg); }.into();
2083        }
2084    };
2085    let imp = parse_macro_input!(item as ItemImpl);
2086    match expand_c_export(metas, &imp) {
2087        Ok(ts) => ts,
2088        // The impl block is emitted even when the attribute refuses it, so that the one
2089        // error the reader has to act on is not buried under "no method named .." for
2090        // every call site.
2091        Err(msg) => quote! { #imp compile_error!(#msg); }.into(),
2092    }
2093}
2094
2095fn expand_c_export(
2096    metas: Punctuated<Meta, Token![,]>,
2097    imp: &ItemImpl,
2098) -> Result<TokenStream, String> {
2099    let attrs = htl_core::cexport::parse_c_export_metas(metas)?;
2100    if imp.trait_.is_some() {
2101        return Err("c_export: put it on the inherent `impl` block, not on a trait impl".into());
2102    }
2103    if !imp.generics.params.is_empty() {
2104        return Err(
2105            "c_export: the impl block is generic; there is one C symbol per method, and a \
2106             generic type has one per instantiation. Export a concrete type"
2107                .into(),
2108        );
2109    }
2110    let hd = dts::host_decl_for_c_export(imp, None, None)?;
2111    let plan = htl_core::cexport::plan(&hd, imp, attrs)?;
2112    let header = plan.header();
2113    if let Some(path) = &plan.header_path {
2114        write_dts(path, &header)?;
2115    }
2116
2117    let self_ty = &imp.self_ty;
2118    let prefix = plan.prefix.as_str();
2119    let mut fns = vec![c_runtime_fns(&plan, self_ty), c_open_fn(&plan, self_ty)];
2120    for m in &plan.methods {
2121        fns.push(c_method_fn(&plan, m, self_ty));
2122    }
2123    Ok(quote! {
2124        #imp
2125        impl ::htl::ffi::CExport for #self_ty {
2126            const PREFIX: &'static str = #prefix;
2127            const HEADER: &'static str = #header;
2128            const ABI_VERSION: ::core::ffi::c_int = ::htl::ffi::ABI_VERSION;
2129        }
2130        #( #fns )*
2131    }
2132    .into())
2133}
2134
2135/// The `# Safety` clause every generated pointer-taking function carries: one sentence
2136/// per pointer it is handed, because clippy asks for it and because it is the contract.
2137fn c_safety(what: &str) -> String {
2138    format!("# Safety\n\n{what}")
2139}
2140
2141/// The functions that do not come from a method: versions, the error slot, `free`, and
2142/// the two ends of the handle's life.
2143fn c_runtime_fns(plan: &htl_core::cexport::CPlan, self_ty: &syn::Type) -> TokenStream2 {
2144    let p = plan.prefix.as_str();
2145    let (abi, ver, ts) = (
2146        format_ident!("{p}_abi_version"),
2147        format_ident!("{p}_version"),
2148        format_ident!("{p}_threadsafe"),
2149    );
2150    let (le, lei, ls) = (
2151        format_ident!("{p}_last_error"),
2152        format_ident!("{p}_last_error_into"),
2153        format_ident!("{p}_last_status"),
2154    );
2155    let (free, close, int) = (
2156        format_ident!("{p}_free"),
2157        format_ident!("{p}_close"),
2158        format_ident!("{p}_interrupt"),
2159    );
2160    let d_le = "The last error on this thread, or NULL. Owned by this library and valid \
2161                until the next call on this thread; do not free it.";
2162    let d_lei = c_safety("`buf` must be writable for `len` bytes.");
2163    let d_free = c_safety(
2164        "`p` must be NULL or a pointer this library returned and has not taken back. \
2165         Freeing anything else, or the same pointer twice, is undefined behaviour.",
2166    );
2167    let d_close = c_safety(
2168        "`h` must be NULL or a handle from `_open` that has not been closed, and no call \
2169         may be in progress on it. Closing from another thread does nothing.",
2170    );
2171    let d_int = c_safety(
2172        "`h` must be NULL or a live handle. Callable from any thread; the caller keeps \
2173         the handle alive until it stops calling.",
2174    );
2175    quote! {
2176        #[doc = "The shape of this ABI. Compare it before calling anything else."]
2177        #[unsafe(no_mangle)]
2178        pub extern "C" fn #abi() -> ::core::ffi::c_int {
2179            ::htl::ffi::ABI_VERSION
2180        }
2181
2182        #[doc = "The version of the crate that was built, as a static string."]
2183        #[unsafe(no_mangle)]
2184        pub extern "C" fn #ver() -> *const ::core::ffi::c_char {
2185            concat!(env!("CARGO_PKG_VERSION"), "\0").as_ptr() as *const ::core::ffi::c_char
2186        }
2187
2188        #[doc = "0: one handle per thread (the convention of sqlite3_threadsafe)."]
2189        #[unsafe(no_mangle)]
2190        pub extern "C" fn #ts() -> ::core::ffi::c_int {
2191            0
2192        }
2193
2194        #[doc = #d_le]
2195        #[unsafe(no_mangle)]
2196        pub extern "C" fn #le() -> *const ::core::ffi::c_char {
2197            ::htl::ffi::last_error_ptr()
2198        }
2199
2200        #[doc = #d_lei]
2201        #[unsafe(no_mangle)]
2202        pub unsafe extern "C" fn #lei(
2203            buf: *mut ::core::ffi::c_char,
2204            len: ::core::ffi::c_int,
2205        ) -> ::core::ffi::c_int {
2206            unsafe { ::htl::ffi::last_error_into(buf, len) }
2207        }
2208
2209        #[doc = "The status that went with the last error."]
2210        #[unsafe(no_mangle)]
2211        pub extern "C" fn #ls() -> ::core::ffi::c_int {
2212            ::htl::ffi::last_status()
2213        }
2214
2215        #[doc = #d_free]
2216        #[unsafe(no_mangle)]
2217        pub unsafe extern "C" fn #free(p: *mut ::core::ffi::c_char) {
2218            unsafe { ::htl::ffi::free(p) }
2219        }
2220
2221        #[doc = #d_close]
2222        #[unsafe(no_mangle)]
2223        pub unsafe extern "C" fn #close(__handle: *mut ::core::ffi::c_void) {
2224            const MAGIC: u64 = ::htl::ffi::magic(#p);
2225            unsafe { ::htl::ffi::Handle::<#self_ty>::close(__handle, MAGIC) }
2226        }
2227
2228        #[doc = #d_int]
2229        #[unsafe(no_mangle)]
2230        pub unsafe extern "C" fn #int(__handle: *mut ::core::ffi::c_void) -> ::core::ffi::c_int {
2231            const MAGIC: u64 = ::htl::ffi::magic(#p);
2232            unsafe { ::htl::ffi::Handle::<#self_ty>::interrupt(__handle, MAGIC) }
2233        }
2234    }
2235}
2236
2237/// The signature fragments, the decoding of each argument, and the call arguments.
2238///
2239/// Arguments are decoded *before* the handle is entered: a NULL or non-UTF-8 argument is
2240/// the caller's mistake, not the handle's, and must not count as a failed call on it.
2241fn c_params(
2242    f: &htl_core::cexport::CFn,
2243    fail: &TokenStream2,
2244) -> (Vec<TokenStream2>, Vec<TokenStream2>, Vec<TokenStream2>) {
2245    use htl_core::cexport::ParamKind;
2246    let (mut sig, mut dec, mut call) = (Vec::new(), Vec::new(), Vec::new());
2247    for p in &f.params {
2248        if p.kind == ParamKind::Interrupt {
2249            call.push(quote! { __interrupt });
2250            continue;
2251        }
2252        let id = format_ident!("{}", p.name);
2253        let what = p.c_name.as_str();
2254        let ty = &p.ty;
2255        match p.kind {
2256            ParamKind::Text => {
2257                sig.push(quote! { #id: *const ::core::ffi::c_char });
2258                dec.push(quote! {
2259                    let #id: ::std::string::String = match unsafe { ::htl::ffi::arg_str(#id, #what) } {
2260                        ::core::option::Option::Some(__s) => ::std::string::String::from(__s),
2261                        ::core::option::Option::None => return #fail,
2262                    };
2263                });
2264            }
2265            ParamKind::Int => {
2266                sig.push(quote! { #id: ::core::ffi::c_int });
2267                dec.push(quote! { let #id: i32 = #id; });
2268            }
2269            ParamKind::Json => {
2270                sig.push(quote! { #id: *const ::core::ffi::c_char });
2271                dec.push(quote! {
2272                    let #id: #ty = match unsafe { ::htl::ffi::arg_str(#id, #what) } {
2273                        ::core::option::Option::Some(__s) => {
2274                            match ::htl::ffi::from_json::<#ty>(__s, #what) {
2275                                ::core::result::Result::Ok(__v) => __v,
2276                                ::core::result::Result::Err(__e) => {
2277                                    ::htl::ffi::set_error(::htl::ffi::Status::Err, __e);
2278                                    return #fail;
2279                                }
2280                            }
2281                        }
2282                        ::core::option::Option::None => return #fail,
2283                    };
2284                });
2285            }
2286            ParamKind::Interrupt => unreachable!("handled above"),
2287        }
2288        call.push(if p.by_ref {
2289            quote! { &#id }
2290        } else {
2291            quote! { #id }
2292        });
2293    }
2294    (sig, dec, call)
2295}
2296
2297/// `<prefix>_open`: decode the options, build the value, hand back the handle.
2298fn c_open_fn(plan: &htl_core::cexport::CPlan, self_ty: &syn::Type) -> TokenStream2 {
2299    use htl_core::cexport::ParamKind;
2300    let f = &plan.open;
2301    let p = plan.prefix.as_str();
2302    let name = format_ident!("{}", f.c_name);
2303    let rust = format_ident!("{}", f.rust_name);
2304    let fail = quote! { ::core::ptr::null_mut() };
2305    let (sig, dec, call) = c_params(f, &fail);
2306    // The flag exists whether or not the opener asked for it; naming it `_interrupt`
2307    // when it did not keeps the generated code warning-free in the caller's crate.
2308    let flag = if f.params.iter().any(|x| x.kind == ParamKind::Interrupt) {
2309        format_ident!("__interrupt")
2310    } else {
2311        format_ident!("_interrupt")
2312    };
2313    let make = if f.is_result {
2314        quote! {
2315            <#self_ty>::#rust(#( #call ),*)
2316                .map_err(|__e| ::std::string::ToString::to_string(&__e))
2317        }
2318    } else {
2319        quote! {
2320            ::core::result::Result::Ok::<_, ::std::string::String>(
2321                <#self_ty>::#rust(#( #call ),*)
2322            )
2323        }
2324    };
2325    let doc = c_safety(
2326        "Every `const char *` argument must be NULL or a NUL-terminated UTF-8 string \
2327         that stays alive for the call. The returned handle belongs to this thread and \
2328         is closed with `_close`; NULL means the call failed, and `_last_error` says why.",
2329    );
2330    quote! {
2331        #[doc = #doc]
2332        #[unsafe(no_mangle)]
2333        pub unsafe extern "C" fn #name(#( #sig ),*) -> *mut ::core::ffi::c_void {
2334            const MAGIC: u64 = ::htl::ffi::magic(#p);
2335            ::htl::ffi::clear_error();
2336            #( #dec )*
2337            ::htl::ffi::Handle::<#self_ty>::open(MAGIC, move |#flag| #make)
2338        }
2339    }
2340}
2341
2342/// One method: the wrapper whose shape `cexport::Shape` chose.
2343fn c_method_fn(
2344    plan: &htl_core::cexport::CPlan,
2345    m: &htl_core::cexport::CFn,
2346    self_ty: &syn::Type,
2347) -> TokenStream2 {
2348    use htl_core::cexport::Shape;
2349    let p = plan.prefix.as_str();
2350    let name = format_ident!("{}", m.c_name);
2351    let rust = format_ident!("{}", m.rust_name);
2352    let (ret, fail) = match m.shape {
2353        Shape::Void => (quote! {}, quote! {}),
2354        Shape::Text | Shape::Json => (
2355            quote! { -> *mut ::core::ffi::c_char },
2356            quote! { ::core::ptr::null_mut() },
2357        ),
2358        Shape::Status | Shape::IntOut => (
2359            quote! { -> ::core::ffi::c_int },
2360            quote! { ::htl::ffi::Status::Err.code() },
2361        ),
2362    };
2363    let (sig, dec, call) = c_params(m, &fail);
2364    let invoke = quote! { __this.#rust(#( #call ),*) };
2365    let ok = quote! { ::htl::ffi::Status::Ok.code() };
2366    let body = match (m.shape, m.is_result) {
2367        (Shape::Void, _) => quote! { #invoke; },
2368        (Shape::Text, false) => quote! { ::htl::ffi::give(#invoke) },
2369        (Shape::Text, true) => quote! {
2370            match #invoke {
2371                ::core::result::Result::Ok(__v) => ::htl::ffi::give(__v),
2372                ::core::result::Result::Err(__e) => {
2373                    ::htl::ffi::fail(__e);
2374                    ::core::ptr::null_mut()
2375                }
2376            }
2377        },
2378        (Shape::Json, false) => quote! { ::htl::ffi::give_json(&#invoke) },
2379        (Shape::Json, true) => quote! {
2380            match #invoke {
2381                ::core::result::Result::Ok(__v) => ::htl::ffi::give_json(&__v),
2382                ::core::result::Result::Err(__e) => {
2383                    ::htl::ffi::fail(__e);
2384                    ::core::ptr::null_mut()
2385                }
2386            }
2387        },
2388        (Shape::Status, _) => quote! {
2389            match #invoke {
2390                ::core::result::Result::Ok(()) => #ok,
2391                ::core::result::Result::Err(__e) => ::htl::ffi::fail(__e).code(),
2392            }
2393        },
2394        (Shape::IntOut, false) => quote! {
2395            let __v = #invoke;
2396            unsafe { *__out = __v as ::core::ffi::c_int };
2397            #ok
2398        },
2399        (Shape::IntOut, true) => quote! {
2400            match #invoke {
2401                ::core::result::Result::Ok(__v) => {
2402                    unsafe { *__out = __v as ::core::ffi::c_int };
2403                    #ok
2404                }
2405                ::core::result::Result::Err(__e) => ::htl::ffi::fail(__e).code(),
2406            }
2407        },
2408    };
2409    let (out_sig, out_check) = if m.shape == Shape::IntOut {
2410        (
2411            quote! { __out: *mut ::core::ffi::c_int, },
2412            quote! {
2413                if __out.is_null() {
2414                    ::htl::ffi::set_error(::htl::ffi::Status::Err, "argument `out` is NULL");
2415                    return ::htl::ffi::Status::Err.code();
2416                }
2417            },
2418        )
2419    } else {
2420        (quote! {}, quote! {})
2421    };
2422    let enter = match m.shape {
2423        Shape::Status | Shape::IntOut => quote! {
2424            unsafe {
2425                ::htl::ffi::Handle::<#self_ty>::enter_status(__handle, MAGIC, move |__this| { #body })
2426            }
2427        },
2428        Shape::Void => quote! {
2429            unsafe {
2430                ::htl::ffi::Handle::<#self_ty>::enter(__handle, MAGIC, (), move |__this| { #body })
2431            }
2432        },
2433        Shape::Text | Shape::Json => quote! {
2434            unsafe {
2435                ::htl::ffi::Handle::<#self_ty>::enter(
2436                    __handle, MAGIC, ::core::ptr::null_mut(), move |__this| { #body },
2437                )
2438            }
2439        },
2440    };
2441    let doc = c_safety(
2442        "`h` must be NULL or a handle from `_open`, used on the thread that opened it; \
2443         any `const char *` argument must be NULL or a NUL-terminated UTF-8 string alive \
2444         for the call, and any out-parameter must be writable.",
2445    );
2446    quote! {
2447        #[doc = #doc]
2448        #[unsafe(no_mangle)]
2449        pub unsafe extern "C" fn #name(
2450            __handle: *mut ::core::ffi::c_void,
2451            #( #sig, )*
2452            #out_sig
2453        ) #ret {
2454            const MAGIC: u64 = ::htl::ffi::magic(#p);
2455            ::htl::ffi::clear_error();
2456            #( #dec )*
2457            #out_check
2458            #enter
2459        }
2460    }
2461}
2462
2463/// `TempDir` and `tempdir` are implemented once, in
2464/// `crates/htl-core/tests/common/mod.rs`, and brought in here by `#[path]`: the workspace
2465/// shares test helpers by linking the one file rather than copying it. A `#[path]` `mod`
2466/// item names any file on disk regardless of crate boundary, which is how this reaches
2467/// `htl-core`'s file even though this crate's unit tests are a different compilation unit
2468/// from `htl-core`'s integration tests, with no dev-dependency between the two crates to
2469/// share it through otherwise. Declared at the crate root,
2470/// rather than nested inside `mod tests` below, because a `#[path]` on an item of an
2471/// *inline* module resolves relative to a directory named for that module (here,
2472/// `src/tests/`) that does not exist on disk, and the OS refuses to resolve a `..` through
2473/// a directory it cannot open — nested, the exact same attribute reads
2474/// `crates/htl-core/tests/common/mod.rs` as `src/tests/../../../htl-core/...` and fails to
2475/// find it. A top-level item has no such phantom segment.
2476#[cfg(test)]
2477#[allow(dead_code)]
2478#[path = "../../htl-core/tests/common/mod.rs"]
2479mod core_common;
2480
2481#[cfg(test)]
2482mod tests {
2483    use super::*;
2484
2485    /// A fresh directory under the system temp dir, removed when the returned guard
2486    /// drops. `TempDir` and the implementation are `htl-core`'s, reached through
2487    /// `core_common` (declared at the crate root, above) — see its doc for what the
2488    /// guard promises, the panic case included.
2489    fn tempdir(name: &str) -> core_common::TempDir {
2490        core_common::tempdir("htl-macros-test", name)
2491    }
2492
2493    fn write(path: &Path, text: &str) {
2494        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
2495        std::fs::write(path, text).unwrap();
2496    }
2497
2498    /// `include_tl!` and `htl check` resolve a name the same way: the file the macro's
2499    /// check read for `helper` is the one `htl check`'s read.
2500    ///
2501    /// The case is the one where they used to differ. A file in `src/sub/` requires
2502    /// `helper`, and there is a `helper.tl` beside it as well as in `src/`. `htl check`
2503    /// consulted the file's own directory first and read `src/sub/helper.tl`; the macro
2504    /// consulted it last and read `src/helper.tl`. Both set their checker up from the
2505    /// project model now, where `src/sub/helper.tl` is `sub.helper` and `helper` is
2506    /// `src/helper.tl`.
2507    #[test]
2508    fn include_tl_and_htl_check_read_the_same_file_for_a_name() {
2509        let root = tempdir("same-as-check");
2510        write(&root.join("htl.toml"), "");
2511        write(
2512            &root.join("src/helper.tl"),
2513            "local record helper\n   n: integer\nend\nreturn helper\n",
2514        );
2515        write(
2516            &root.join("src/sub/helper.tl"),
2517            "local record helper\n   s: string\nend\nreturn helper\n",
2518        );
2519        let main = root.join("src/sub/main.tl");
2520        write(
2521            &main,
2522            "local helper = require(\"helper\")\nprint(helper.n)\n",
2523        );
2524
2525        let inc = resolve_include(&root, "src/sub/main.tl", false).expect("the macro's check");
2526        let by_macro: Vec<PathBuf> = inc
2527            .deps
2528            .iter()
2529            .filter(|d| d.ends_with("helper.tl"))
2530            .map(|d| std::fs::canonicalize(d).unwrap())
2531            .collect();
2532
2533        let files = vec![main.clone()];
2534        let cfg = htl_core::project::config_of(&main).unwrap();
2535        let model = htl_core::project::model_of(&cfg, &main).unwrap();
2536        let mut sink = htl_core::project::Sink::new(htl_core::project::Collect::default());
2537        let checked = htl_core::project::check(
2538            &mut sink,
2539            &files,
2540            &htl_core::project::Options {
2541                paths: &files,
2542                config: &cfg,
2543                model: model.as_ref(),
2544                lint: None,
2545                cache: htl_core::project::cache_options(false, None, &cfg, false),
2546            },
2547        )
2548        .unwrap();
2549        let by_check: Vec<PathBuf> = checked
2550            .requires
2551            .iter()
2552            .flat_map(|(_, reqs)| reqs.iter())
2553            .filter(|r| r.module == "helper")
2554            .filter_map(|r| r.path.as_ref())
2555            .map(|p| std::fs::canonicalize(p).unwrap())
2556            .collect();
2557
2558        let expected = std::fs::canonicalize(root.join("src/helper.tl")).unwrap();
2559        assert_eq!(by_check, vec![expected.clone()], "htl check");
2560        assert_eq!(by_macro, vec![expected], "include_tl!");
2561    }
2562
2563    /// The macro must see the same tree as the CLI: an installed dependency, reached at its
2564    /// entry (`.htl/modules/entries/<name>/init.tl`), resolves from a script under the
2565    /// project.
2566    #[test]
2567    fn include_resolves_vendored_dep_from_mlua_pkg_project() {
2568        let root = tempdir("vendored");
2569        write(
2570            &root.join("mlua-pkg.toml"),
2571            "[package]\nname = \"t\"\nversion = \"0.1.0\"\n\n[deps]\n",
2572        );
2573        write(
2574            &root.join(".htl/modules/entries/mathx/init.tl"),
2575            "local record mathx\nend\nfunction mathx.twice(n: number): number\n   return n * 2\nend\nreturn mathx\n",
2576        );
2577        write(
2578            &root.join("scripts/main.tl"),
2579            "local mathx = require(\"mathx\")\nprint(mathx.twice(21))\n",
2580        );
2581
2582        let inc =
2583            resolve_include(&root, "scripts/main.tl", false).expect("vendored dep must resolve");
2584        assert!(inc.main_abs.ends_with("scripts/main.tl"));
2585        assert!(
2586            inc.deps
2587                .iter()
2588                .any(|d| d.ends_with("entries/mathx/init.tl")),
2589            "dep must be tracked for rebuilds: {:?}",
2590            inc.deps
2591        );
2592        assert!(
2593            inc.deps.iter().all(|d| Path::new(d).is_absolute()),
2594            "tracked deps must be absolute for include_str!: {:?}",
2595            inc.deps
2596        );
2597        match inc.payload {
2598            Payload::Source(code) => {
2599                assert!(code.contains("require(\"mathx\")"));
2600                // What `include_tl!` embeds is Lua source, and a host that writes it back
2601                // out as a file wants the terminator a file has. The producer appends it,
2602                // so exactly one is here however the code got generated.
2603                assert!(
2604                    code.ends_with('\n'),
2605                    "source payload is terminated: {code:?}"
2606                );
2607                assert!(
2608                    !code.ends_with("\n\n"),
2609                    "terminated once, not twice: {code:?}"
2610                );
2611            }
2612            Payload::Bytes(_) => panic!("expected source"),
2613        }
2614    }
2615
2616    /// `include_tl!` embeds the Lua `htl gen` prints, comment-only lines included, byte
2617    /// for byte. Both go through `Htl::gen_lua`; the macro through the run cache's `gen`
2618    /// entry as well, so it is expanded twice and the second may be a replay.
2619    #[test]
2620    fn include_tl_embeds_the_comment_lines_htl_gen_prints() {
2621        const DOC: &str = "\
2622--- Module header doc, line 1
2623--- line 2 of the header
2624local record M
2625end
2626
2627--- adds one
2628--- @param x the number
2629function M.inc(x: number): number
2630   -- a comment inside the body
2631   local y = x + 1 -- trailing comment
2632   return y
2633end
2634
2635--[[ a block
2636comment ]]
2637return M
2638";
2639        // The same sixteen lines `crates/htl-cli/tests/gen_comment_lines.rs` asserts
2640        // `htl gen` prints.
2641        const DOC_LUA: &str = "\
2642--- Module header doc, line 1
2643--- line 2 of the header
2644local M = {}
2645
2646
2647--- adds one
2648--- @param x the number
2649function M.inc(x)
2650   -- a comment inside the body
2651   local y = x + 1
2652   return y
2653end
2654
2655
2656
2657return M
2658";
2659        let root = tempdir("comment-lines");
2660        write(&root.join("src/doc2.tl"), DOC);
2661        let embedded = || match resolve_include(&root, "src/doc2.tl", false)
2662            .expect("the module checks")
2663            .payload
2664        {
2665            Payload::Source(code) => code,
2666            Payload::Bytes(_) => panic!("expected source"),
2667        };
2668        let first = embedded();
2669        let second = embedded();
2670        let (by_gen, _) = htl_core::Htl::new()
2671            .unwrap()
2672            .gen_lua(&root.join("src/doc2.tl"))
2673            .unwrap();
2674        assert_eq!(first, DOC_LUA, "include_tl!");
2675        assert_eq!(second, DOC_LUA, "include_tl!, expanded again");
2676        assert_eq!(
2677            by_gen.as_deref(),
2678            Some(DOC_LUA),
2679            "Htl::gen_lua, as htl gen calls it"
2680        );
2681    }
2682
2683    /// The same for a file whose block comment holds a `--` line and whose last line is
2684    /// doc after `return`: the line inside the block stays empty and the doc is appended at
2685    /// line 10, in both.
2686    #[test]
2687    fn include_tl_embeds_the_block_comment_and_trailing_doc_lines_htl_gen_prints() {
2688        const DOC: &str = "\
2689local record M
2690end
2691--[[ block comment line 1
2692-- a dash line inside the block
2693last block line ]]
2694function M.f(): integer
2695   return 1
2696end
2697return M
2698--- doc after return, last line of the file
2699";
2700        // The ten lines `crates/htl-cli/tests/gen_comment_lines.rs` asserts `htl gen`
2701        // prints.
2702        const DOC_LUA: &str = "\
2703local M = {}
2704
2705
2706
2707
2708function M.f()
2709   return 1
2710end
2711return M
2712--- doc after return, last line of the file
2713";
2714        let root = tempdir("comment-lines-tail");
2715        write(&root.join("src/doc5.tl"), DOC);
2716        let embedded = || match resolve_include(&root, "src/doc5.tl", false)
2717            .expect("the module checks")
2718            .payload
2719        {
2720            Payload::Source(code) => code,
2721            Payload::Bytes(_) => panic!("expected source"),
2722        };
2723        let first = embedded();
2724        let second = embedded();
2725        let (by_gen, _) = htl_core::Htl::new()
2726            .unwrap()
2727            .gen_lua(&root.join("src/doc5.tl"))
2728            .unwrap();
2729        assert_eq!(first, DOC_LUA, "include_tl!");
2730        assert_eq!(second, DOC_LUA, "include_tl!, expanded again");
2731        assert_eq!(
2732            by_gen.as_deref(),
2733            Some(DOC_LUA),
2734            "Htl::gen_lua, as htl gen calls it"
2735        );
2736    }
2737
2738    /// `target_dir` deps (physically vendored under the manifest) resolve too.
2739    #[test]
2740    fn include_resolves_target_dir_dep() {
2741        let root = tempdir("targetdir");
2742        write(
2743            &root.join("mlua-pkg.toml"),
2744            "[package]\nname = \"t\"\nversion = \"0.1.0\"\n\n[deps]\nmathx = { git = \"https://example.invalid/mathx\", tag = \"v1\", target_dir = \"lua/mathx\" }\n",
2745        );
2746        write(
2747            &root.join("lua/mathx/init.tl"),
2748            "local record mathx\nend\nfunction mathx.twice(n: number): number\n   return n * 2\nend\nreturn mathx\n",
2749        );
2750        write(
2751            &root.join("src/main.tl"),
2752            "local mathx = require(\"mathx\")\nprint(mathx.twice(1))\n",
2753        );
2754
2755        let inc = resolve_include(&root, "src/main.tl", true).expect("target_dir dep must resolve");
2756        assert!(matches!(inc.payload, Payload::Bytes(ref b) if !b.is_empty()));
2757    }
2758
2759    /// The copy `cargo package` verifies, expanded the way cargo expands it there.
2760    ///
2761    /// A crate that embeds its Teal ships `mlua-pkg.toml`, `mlua-pkg.lock` and the
2762    /// `patches/<dep>/` it committed, and never `.htl/` — `htl init` gitignores that, so
2763    /// no clone and no tarball has one. The `require` of the dependency must still
2764    /// resolve, from the copy and the manifest naming it alone; #266 is what it did
2765    /// instead, `module not found` inside `target/package/<crate>/`. And the expansion
2766    /// must leave the tree as it found it, or cargo refuses the tarball it just built
2767    /// (#267).
2768    #[test]
2769    fn include_resolves_a_patched_dep_in_the_copy_cargo_package_verifies() {
2770        let dir = tempdir("packaged-patch");
2771        let root = dir.join("target/package/p-0.1.0");
2772        write(
2773            &root.join("mlua-pkg.toml"),
2774            "[package]\nname = \"p\"\nversion = \"0.1.0\"\n\n[deps.mathx]\n\
2775             git = \"https://example.invalid/mathx\"\ntag = \"v1\"\npatch_dir = \"patches/mathx\"\n",
2776        );
2777        write(
2778            &root.join("patches/mathx/src/mathx.tl"),
2779            "local record mathx\nend\nfunction mathx.twice(n: number): number\n   return n * 2\nend\nreturn mathx\n",
2780        );
2781        write(
2782            &root.join("src/main.tl"),
2783            "local mathx = require(\"mathx\")\nprint(mathx.twice(21))\n",
2784        );
2785
2786        let inc = resolve_include(&root, "src/main.tl", true)
2787            .expect("the committed copy is the whole of what the require needs");
2788        assert!(matches!(inc.payload, Payload::Bytes(ref b) if !b.is_empty()));
2789        assert!(
2790            inc.deps
2791                .iter()
2792                .any(|d| d.ends_with("patches/mathx/src/mathx.tl")),
2793            "and the copy's file is tracked for rebuilds: {:?}",
2794            inc.deps
2795        );
2796        assert!(
2797            !root.join(".htl").exists(),
2798            "nothing was written into the tree cargo is verifying"
2799        );
2800    }
2801
2802    /// A flat package exposes its top-level module as `<name>/<name>.tl`.
2803    #[test]
2804    fn include_resolves_flat_package_module() {
2805        let root = tempdir("flat");
2806        write(
2807            &root.join("mlua-pkg.toml"),
2808            "[package]\nname = \"t\"\nversion = \"0.1.0\"\n\n[deps]\n",
2809        );
2810        write(
2811            &root.join(".htl/modules/entries/mathx/mathx.tl"),
2812            "local record mathx\nend\nfunction mathx.twice(n: number): number\n   return n * 2\nend\nreturn mathx\n",
2813        );
2814        write(
2815            &root.join("src/main.tl"),
2816            "local mathx = require(\"mathx\")\nprint(mathx.twice(1))\n",
2817        );
2818        resolve_include(&root, "src/main.tl", false).expect("flat package must resolve");
2819    }
2820
2821    /// The process cwd (cargo's, during a build) must not take part in resolution: a
2822    /// same-named module sitting there is neither picked up nor tracked by a relative path.
2823    #[test]
2824    fn include_ignores_modules_in_the_process_cwd() {
2825        let decoy = tempdir("cwd-decoy");
2826        write(
2827            &decoy.join("Tasks.tl"),
2828            "local record Tasks\nend\nreturn Tasks\n",
2829        );
2830        let root = tempdir("cwd-crate");
2831        write(
2832            &root.join("src/main.tl"),
2833            "local ok, t = pcall(require, \"Tasks\")\nprint(ok, t)\n",
2834        );
2835
2836        let prev = std::env::current_dir().unwrap();
2837        std::env::set_current_dir(&decoy).unwrap();
2838        let out = resolve_include(&root, "src/main.tl", false);
2839        std::env::set_current_dir(prev).unwrap();
2840
2841        let err = out.unwrap_err();
2842        assert!(
2843            err.contains("module not found: 'Tasks'"),
2844            "cwd decoy must not resolve: {err}"
2845        );
2846    }
2847
2848    /// `htl.toml` drives the macro as it drives `htl check`: a rule's level turns it on
2849    /// and says what it is worth, and `strict` promotes every finding. A lint at `warn` is
2850    /// advice in both; at `deny`, or under `strict`, it fails both.
2851    #[test]
2852    fn include_judges_by_htl_toml_levels_as_check_does() {
2853        let root = tempdir("htl-toml");
2854        // `no-any` is off by default; the script only trips when htl.toml enables it.
2855        write(&root.join("src/main.tl"), "local x: any = 1\nprint(x)\n");
2856        resolve_include(&root, "src/main.tl", false).expect("no-any is off by default");
2857
2858        write(&root.join("htl.toml"), "[lint.rules]\nno-any = \"warn\"\n");
2859        resolve_include(&root, "src/main.tl", false).expect("a lint at warn is advice");
2860
2861        write(&root.join("htl.toml"), "[lint.rules]\nno-any = \"deny\"\n");
2862        let err = resolve_include(&root, "src/main.tl", false).unwrap_err();
2863        assert!(
2864            err.contains("htl lint failed (a rule at deny") && err.contains("no-any"),
2865            "{err}"
2866        );
2867
2868        write(
2869            &root.join("htl.toml"),
2870            "[lint]\nstrict = true\n\n[lint.rules]\nno-any = \"warn\"\n",
2871        );
2872        let err = resolve_include(&root, "src/main.tl", false).unwrap_err();
2873        assert!(err.contains("htl lint failed (strict"), "{err}");
2874    }
2875
2876    /// What decides the verdict is declared as an input of the expansion: `htl.toml` as a
2877    /// tracked file, `HTL_LINT` / `HTL_LINTS` through `option_env!`, so changing any of
2878    /// them expands the macro again instead of keeping the last verdict.
2879    #[test]
2880    fn the_settings_a_verdict_comes_from_are_tracked() {
2881        let root = tempdir("settings-tracked");
2882        write(&root.join("htl.toml"), "[lint]\nstrict = true\n");
2883        write(&root.join("src/main.tl"), "print(1)\n");
2884        let toml = std::fs::canonicalize(root.join("htl.toml")).unwrap();
2885        let inc = resolve_include(&root, "src/main.tl", false).unwrap();
2886        assert_eq!(inc.config.as_deref(), Some(toml.to_str().unwrap()));
2887        let opts = htl_core::link::LinkOptions::default();
2888        let out = resolve_bundle(&root, "src/main.tl", &opts).unwrap();
2889        assert_eq!(out.config.as_deref(), Some(toml.to_str().unwrap()));
2890
2891        let tokens = settings_tracked(inc.config.as_deref()).to_string();
2892        assert!(tokens.contains("include_str !"), "{tokens}");
2893        assert!(tokens.contains(toml.to_str().unwrap()), "{tokens}");
2894        assert!(tokens.contains("option_env ! (\"HTL_LINT\")"), "{tokens}");
2895        assert!(tokens.contains("option_env ! (\"HTL_LINTS\")"), "{tokens}");
2896
2897        // No htl.toml: nothing to track but the environment.
2898        let bare = tempdir("settings-bare");
2899        write(&bare.join("src/main.tl"), "print(1)\n");
2900        assert!(
2901            resolve_include(&bare, "src/main.tl", false)
2902                .unwrap()
2903                .config
2904                .is_none()
2905        );
2906        assert!(!settings_tracked(None).to_string().contains("include_str"));
2907    }
2908
2909    /// A `records = [module::Name]` entry's file is already tracked as a module of the
2910    /// crate in the ordinary case (rustc parses it for `mod geom;` to compile the crate
2911    /// at all); `record_files_tracked` emits the same `include_str!` tracking
2912    /// `settings_tracked` emits for `htl.toml` regardless, as a belt for the `#[cfg]`-ed
2913    /// out case and to keep one rule rather than two (#428). No files: nothing to track,
2914    /// the same as `settings_tracked(None)`.
2915    #[test]
2916    fn record_files_are_tracked_with_include_str() {
2917        let geom = PathBuf::from("/abs/src/geom.rs");
2918        let tokens = record_files_tracked(std::slice::from_ref(&geom)).to_string();
2919        assert!(tokens.contains("include_str !"), "{tokens}");
2920        assert!(tokens.contains(geom.to_str().unwrap()), "{tokens}");
2921
2922        assert!(
2923            !record_files_tracked(&[])
2924                .to_string()
2925                .contains("include_str")
2926        );
2927    }
2928
2929    /// `HTL_LINT` on top of the file: `warn` lets a `deny` through, `deny` fails a `warn`,
2930    /// and anything else is refused. Passed as the value, not set in the environment,
2931    /// which the tests of this crate share.
2932    #[test]
2933    fn htl_lint_caps_raises_or_is_refused() {
2934        let root = tempdir("htl-lint-env");
2935        write(&root.join("src/main.tl"), "local x: any = 1\nprint(x)\n");
2936        let path = root.join("src/main.tl");
2937        let lints = vec![htl_core::Diagnostic::parse(
2938            htl_core::Severity::Lint,
2939            &format!("{}:1:7: x is any [htl no-any]", path.display()),
2940        )];
2941        let judged = |toml: &str, env: Option<&str>| {
2942            write(&root.join("htl.toml"), toml);
2943            let ck = checker_for("include_tl!", &root, &path, None).unwrap();
2944            judge("include_tl!", &ck, &[], &lints, env)
2945        };
2946        let deny = "[lint.rules]\nno-any = \"deny\"\n";
2947        let warn = "[lint.rules]\nno-any = \"warn\"\n";
2948        assert!(judged(deny, None).is_err());
2949        assert!(judged(deny, Some("warn")).is_ok());
2950        assert!(judged(warn, None).is_ok());
2951        assert!(judged(warn, Some("deny")).is_err());
2952        let err = judged(warn, Some("error")).unwrap_err();
2953        assert!(err.contains("HTL_LINT=\"error\""), "{err}");
2954    }
2955
2956    /// `HTL_LINTS` reaches `Scope::new`, on top of `htl.toml`'s `[lint]`: `no-any=deny`
2957    /// (or `+no-any` under `strict = true`) turns the rule on for both the checker
2958    /// (`project::checker`) and `judge` (`scope.lints`), `-no-any` turns off what
2959    /// `htl.toml` put at `deny`, and an unknown rule is refused when the scope is built.
2960    #[test]
2961    fn htl_lints_reaches_scope_and_checker() {
2962        let root = tempdir("htl-lints-env");
2963        let path = root.join("src/main.tl");
2964        write(&path, "local x: any = 1\nprint(x)\n");
2965        write(&root.join("htl.toml"), "");
2966
2967        let ck = checker_for("include_tl!", &root, &path, Some("no-any=deny")).unwrap();
2968        let ci = ck.h.check(&path).unwrap();
2969        assert_eq!(ci.lint_items.len(), 1, "{:?}", ci.lint_items);
2970        let err = judge("include_tl!", &ck, &[], &ci.lint_items, None).unwrap_err();
2971        assert!(
2972            err.contains("a rule at deny") && err.contains("no-any"),
2973            "{err}"
2974        );
2975
2976        write(&root.join("htl.toml"), "[lint]\nstrict = true\n");
2977        let ck = checker_for("include_tl!", &root, &path, Some("+no-any")).unwrap();
2978        let ci = ck.h.check(&path).unwrap();
2979        assert_eq!(ci.lint_items.len(), 1, "{:?}", ci.lint_items);
2980        let err = judge("include_tl!", &ck, &[], &ci.lint_items, None).unwrap_err();
2981        assert!(err.contains("strict") && err.contains("no-any"), "{err}");
2982
2983        write(&root.join("htl.toml"), "[lint.rules]\nno-any = \"deny\"\n");
2984        let ck = checker_for("include_tl!", &root, &path, Some("-no-any")).unwrap();
2985        let ci = ck.h.check(&path).unwrap();
2986        assert!(ci.lint_items.is_empty(), "{:?}", ci.lint_items);
2987        judge("include_tl!", &ck, &[], &ci.lint_items, None).unwrap();
2988
2989        let err = match checker_for("include_tl!", &root, &path, Some("+no-such-rule")) {
2990            Ok(_) => panic!("unknown rule must be refused"),
2991            Err(e) => e,
2992        };
2993        assert!(err.contains("unknown lint rule: +no-such-rule"), "{err}");
2994    }
2995
2996    /// `checker_for` goes through `project::checker`, not a sequence of its own: a
2997    /// declaration an installer registers on `htl-core` is visible to `include_tl!`, where
2998    /// the macro's hand-assembled `Htl` did not call `project::checker` and could not find
2999    /// it. (`provides` is empty so the test's registration does not enter any project
3000    /// model's `provided` list in the other tests of this binary.)
3001    #[test]
3002    fn checker_for_goes_through_project_checker() {
3003        let _ = htl_core::registry::register_installer(
3004            "htl-macros-test-reg",
3005            |h| {
3006                h.install_declarations(
3007                    "htl-macros-test-reg",
3008                    &[(
3009                        "htl_macros_reg_probe.d.tl",
3010                        "local record P\n   n: integer\nend\nreturn P\n",
3011                    )],
3012                )
3013                .map(|_| ())
3014            },
3015            &[],
3016        );
3017        let root = tempdir("through-project-checker");
3018        write(&root.join("htl.toml"), "");
3019        write(
3020            &root.join("src/main.tl"),
3021            "local p = require(\"htl_macros_reg_probe\")\nprint(p.n + 1)\n",
3022        );
3023        resolve_include(&root, "src/main.tl", false)
3024            .expect("project::checker runs install_registered");
3025    }
3026
3027    /// Both macros read the run cache under the project root: the second expansion
3028    /// replays what the first generated, an edit is a miss for the module and its
3029    /// dependents, and what comes out is the same either way.
3030    #[test]
3031    fn macros_replay_from_the_run_cache_on_the_second_expansion() {
3032        let root = tempdir("cache");
3033        write(&root.join("htl.toml"), "[check]\n");
3034        write(
3035            &root.join("src/main.tl"),
3036            "local util = require(\"util\")\nprint(util.twice(21))\n",
3037        );
3038        write(
3039            &root.join("src/util.tl"),
3040            "local record util\nend\nfunction util.twice(n: integer): integer\n   return n * 2\nend\nreturn util\n",
3041        );
3042        let opts = htl_core::link::LinkOptions::default();
3043        let first = resolve_bundle(&root, "src/main.tl", &opts).expect("links");
3044        assert_eq!(first.cached, (0, 2), "cold");
3045        let second = resolve_bundle(&root, "src/main.tl", &opts).expect("links");
3046        assert_eq!(second.cached, (2, 2), "warm");
3047        assert_eq!(first.bytes, second.bytes, "same bundle either way");
3048        assert!(
3049            root.join(".htl/cache").is_dir(),
3050            "the store is beside htl.toml"
3051        );
3052
3053        write(
3054            &root.join("src/main.tl"),
3055            "local util = require(\"util\")\nprint(util.twice(42))\n",
3056        );
3057        let edited = resolve_bundle(&root, "src/main.tl", &opts).expect("links");
3058        assert_eq!(edited.cached, (1, 2), "util replays, main does not");
3059
3060        // `include_tl!` on the entry alone: generated on the first expansion (the bundle
3061        // above keyed it by the same path and the same lints, so it is warm already), and
3062        // replayed once it is stored.
3063        let inc = resolve_include(&root, "src/main.tl", false).expect("checks");
3064        assert!(
3065            inc.cached,
3066            "the bundle's entry for main serves include_tl! too"
3067        );
3068        write(
3069            &root.join("src/main.tl"),
3070            "local util = require(\"util\")\nprint(util.twice(7))\n",
3071        );
3072        let inc = resolve_include(&root, "src/main.tl", false).expect("checks");
3073        assert!(!inc.cached, "edited: generated");
3074        let inc = resolve_include(&root, "src/main.tl", false).expect("checks");
3075        assert!(inc.cached, "and stored");
3076    }
3077
3078    /// No `htl.toml`: the crate has not opted into the layout, and the macro leaves no
3079    /// `.htl/` behind. Under `target/`: the copy `cargo publish` verifies, where a new
3080    /// file would abort the publish. Both generate everything and write nothing.
3081    #[test]
3082    fn macros_leave_no_store_without_a_project_or_under_target() {
3083        let opts = htl_core::link::LinkOptions::default();
3084        let sources = |root: &Path| {
3085            write(
3086                &root.join("src/main.tl"),
3087                "local util = require(\"util\")\nprint(util.twice(21))\n",
3088            );
3089            write(
3090                &root.join("src/util.tl"),
3091                "local record util\nend\nfunction util.twice(n: integer): integer\n   return n * 2\nend\nreturn util\n",
3092            );
3093        };
3094
3095        let bare = tempdir("nocfg");
3096        sources(&bare);
3097        for _ in 0..2 {
3098            let out = resolve_bundle(&bare, "src/main.tl", &opts).expect("links");
3099            assert_eq!(out.cached, (0, 2), "nothing replays without a project");
3100        }
3101        assert!(!bare.join(".htl").exists(), "no htl.toml, no store");
3102
3103        let published_dir = tempdir("publish");
3104        let published = published_dir.join("target/package/host-0.1.0");
3105        sources(&published);
3106        write(&published.join("htl.toml"), "[check]\n");
3107        for _ in 0..2 {
3108            let out = resolve_bundle(&published, "src/main.tl", &opts).expect("links");
3109            assert_eq!(out.cached, (0, 2), "nothing replays under target/");
3110        }
3111        assert!(
3112            !published.join(".htl").exists(),
3113            "cargo publish's verify copy is left exactly as it was"
3114        );
3115    }
3116
3117    /// `include_bundle!` with no `host = [..]`: the crate's `#[host_module]` names are the
3118    /// host's, from the project's model. A `.lua` beside the name's declaration was
3119    /// bundled in the host module's place before; it is the model's error now, and the
3120    /// expansion fails with it.
3121    #[test]
3122    fn bundle_takes_the_host_names_from_the_crates_host_modules() {
3123        let root = tempdir("bundle-host-module");
3124        write(&root.join("htl.toml"), "");
3125        write(
3126            &root.join("Cargo.toml"),
3127            "[package]\nname = \"p\"\nversion = \"0.1.0\"\nedition = \"2024\"\n",
3128        );
3129        write(
3130            &root.join("src/lib.rs"),
3131            "use htl::host_module;\npub struct Host;\n#[host_module(name = \"host\")]\n\
3132             impl Host {\n    \
3133             pub fn base(&self) -> i64 { 1 }\n}\n",
3134        );
3135        write(
3136            &root.join("src/host.d.tl"),
3137            "local record host\n   base: function(): integer\nend\nreturn host\n",
3138        );
3139        write(
3140            &root.join("src/main.tl"),
3141            "local host = require(\"host\")\nprint(host.base())\n",
3142        );
3143        let opts = htl_core::link::LinkOptions::default();
3144        let out = resolve_bundle(&root, "src/main.tl", &opts).expect("links");
3145        let b = htl_core::bundle::Bundle::decode(&out.bytes).unwrap();
3146        assert_eq!(b.host_modules, vec!["host".to_string()]);
3147
3148        write(
3149            &root.join("src/host.lua"),
3150            "return { base = function() return 2 end }\n",
3151        );
3152        let err = resolve_bundle(&root, "src/main.tl", &opts).expect_err("refused");
3153        assert!(
3154            err.contains(
3155                "'host' is provided by the host (#[host_module] in Cargo.toml's crate) \
3156                          and also implemented by src/host.lua"
3157            ),
3158            "{err}"
3159        );
3160    }
3161
3162    /// `include_bundle!`: the closure is linked, host modules are recorded, every input
3163    /// is tracked, and a type error anywhere in the closure is a compile error.
3164    #[test]
3165    fn bundle_links_closure_tracks_inputs_and_fails_on_type_errors() {
3166        let root = tempdir("bundle");
3167        write(
3168            &root.join("src/main.tl"),
3169            "local util = require(\"util\")\nlocal host = require(\"host\")\nprint(util.twice(host.base()))\n",
3170        );
3171        write(
3172            &root.join("src/util.tl"),
3173            "local record util\nend\nfunction util.twice(n: integer): integer\n   return n * 2\nend\nreturn util\n",
3174        );
3175        write(
3176            &root.join("src/host.d.tl"),
3177            "local record host\n   base: function(): integer\nend\nreturn host\n",
3178        );
3179        write(&root.join("htl.toml"), "[build]\nextra = [\"plugin\"]\n");
3180        write(&root.join("src/plugin.tl"), "return { plugged = true }\n");
3181
3182        let out = resolve_bundle(
3183            &root,
3184            "src/main.tl",
3185            &htl_core::link::LinkOptions::default(),
3186        )
3187        .expect("links");
3188        let b = htl_core::bundle::Bundle::decode(&out.bytes).unwrap();
3189        let names: Vec<&str> = b.modules.iter().map(|m| m.name.as_str()).collect();
3190        assert!(
3191            names.contains(&"main") && names.contains(&"util") && names.contains(&"plugin"),
3192            "{names:?}"
3193        );
3194        assert_eq!(b.host_modules, vec!["host".to_string()]);
3195        let has = |s: &str| out.inputs.iter().any(|p| p.ends_with(s));
3196        assert!(
3197            has("src/main.tl")
3198                && has("src/util.tl")
3199                && has("src/host.d.tl")
3200                && has("src/plugin.tl"),
3201            "{:?}",
3202            out.inputs
3203        );
3204
3205        let src_opts = htl_core::link::LinkOptions {
3206            source: true,
3207            ..Default::default()
3208        };
3209        let out = resolve_bundle(&root, "src/main.tl", &src_opts).expect("links as source");
3210        let b = htl_core::bundle::Bundle::decode(&out.bytes).unwrap();
3211        assert!(
3212            b.modules
3213                .iter()
3214                .all(|m| m.kind == htl_core::bundle::Kind::Source)
3215        );
3216
3217        write(
3218            &root.join("src/util.tl"),
3219            "local record util\nend\nfunction util.twice(n: integer): integer\n   return \"no\"\nend\nreturn util\n",
3220        );
3221        let err = resolve_bundle(
3222            &root,
3223            "src/main.tl",
3224            &htl_core::link::LinkOptions::default(),
3225        )
3226        .unwrap_err();
3227        assert!(
3228            err.contains("util.tl") && err.contains("expected integer"),
3229            "{err}"
3230        );
3231    }
3232
3233    /// `include_tl!`: the script checks, but a module it requires does not. The macro and
3234    /// the CLI share the checker, and the build is where the error belongs — the generated
3235    /// Lua would have raised at the module's first `require`.
3236    #[test]
3237    fn include_fails_on_a_dependency_type_error() {
3238        let root = tempdir("deperr");
3239        write(
3240            &root.join("mlua-pkg.toml"),
3241            "[package]\nname = \"t\"\nversion = \"0.1.0\"\n\n[deps]\n",
3242        );
3243        write(
3244            &root.join(".htl/modules/entries/mathx/init.tl"),
3245            "local record mathx\nend\nfunction mathx.twice(n: number): number\n   local s: number = \"no\"\n   return n * 2 + s\nend\nreturn mathx\n",
3246        );
3247        write(
3248            &root.join("scripts/main.tl"),
3249            "local mathx = require(\"mathx\")\nprint(mathx.twice(21))\n",
3250        );
3251        let err = resolve_include(&root, "scripts/main.tl", false).unwrap_err();
3252        assert!(
3253            err.contains("required module") && err.contains("mathx/init.tl:4:"),
3254            "{err}"
3255        );
3256        assert!(err.contains("required by"), "{err}");
3257    }
3258
3259    /// Without a project the same script fails: the dep is genuinely not on the path.
3260    #[test]
3261    fn include_without_project_does_not_see_vendored_dir() {
3262        let root = tempdir("noproject");
3263        write(
3264            &root.join(".htl/modules/entries/mathx/init.tl"),
3265            "return {}\n",
3266        );
3267        write(
3268            &root.join("scripts/main.tl"),
3269            "local mathx = require(\"mathx\")\nprint(mathx)\n",
3270        );
3271        let err = resolve_include(&root, "scripts/main.tl", false).unwrap_err();
3272        assert!(err.contains("module not found: 'mathx'"), "{err}");
3273    }
3274
3275    const EV_TL: &str = "local record M
3276   record Event
3277      kind: Kind
3278      at: integer
3279      note: string
3280   end
3281   enum Kind
3282      \"open\"
3283      \"close\"
3284   end
3285end
3286return M
3287";
3288
3289    /// #539 (Acceptances 1 & 3): `teal_types!` runs `rsgen::generate` on `[rust] modules`
3290    /// and `[rust.types]`, produces the exact text and `pub mod` items `rsgen::generate`
3291    /// writes, and tracks `htl.toml` and every checked `.tl` file with `include_str!`.
3292    #[test]
3293    fn teal_types_matches_rsgen_generate_and_tracks_sources_and_config() {
3294        let root = tempdir("teal-types-ev");
3295        write(&root.join("htl.toml"), "[rust]\nmodules = [\"ev\"]\n");
3296        write(&root.join("src/ev/init.tl"), EV_TL);
3297
3298        let out = resolve_teal_types(&root).expect("teal_types! resolves");
3299        let ck = checker_for("teal_types!", &root, &root, None).unwrap();
3300        let checked =
3301            htl_core::project::own_sources(&ck.h, &ck.root, ck.model.as_ref().unwrap()).unwrap();
3302        let sources: Vec<htl_core::shapes::Source> = checked
3303            .iter()
3304            .map(|f| htl_core::shapes::Source {
3305                module: &f.module,
3306                rel_path: &f.rel,
3307                info: &f.info,
3308            })
3309            .collect();
3310        let spec = htl_core::rsgen::Spec {
3311            modules: vec!["ev".to_string()],
3312            ..Default::default()
3313        };
3314        let htl_core::rsgen::Rendered::Text {
3315            text: rsgen_text, ..
3316        } = htl_core::rsgen::generate(&sources, &spec, |p| {
3317            std::fs::canonicalize(p).unwrap_or_else(|_| p.to_path_buf())
3318        })
3319        else {
3320            panic!("expected Rendered::Text");
3321        };
3322        assert_eq!(out.code, rsgen_text);
3323
3324        let expanded = expand_teal_types_from(&out).expect("parses as Rust items");
3325        let expanded_str = expanded.to_string();
3326        let ev_abs = std::fs::canonicalize(root.join("src/ev/init.tl")).unwrap();
3327        let toml_abs = std::fs::canonicalize(root.join("htl.toml")).unwrap();
3328        assert_eq!(out.inputs, vec![ev_abs.to_string_lossy().into_owned()]);
3329        assert_eq!(
3330            out.config.as_deref(),
3331            Some(toml_abs.to_str().unwrap()),
3332            "htl.toml is tracked"
3333        );
3334        assert!(expanded_str.contains(ev_abs.to_str().unwrap()));
3335        assert!(expanded_str.contains(toml_abs.to_str().unwrap()));
3336
3337        let expanded_file: syn::File = syn::parse2(expanded).unwrap();
3338        let expanded_mods: Vec<&Item> = expanded_file
3339            .items
3340            .iter()
3341            .filter(|i| matches!(i, Item::Mod(_)))
3342            .collect();
3343        let rsgen_file: syn::File = syn::parse_str(&rsgen_text).unwrap();
3344        let rsgen_mods: Vec<&Item> = rsgen_file.items.iter().collect();
3345        assert_eq!(expanded_mods, rsgen_mods);
3346    }
3347
3348    /// `[rust] exports` alone is something to write: the client of the module, as items
3349    /// that parse.
3350    #[test]
3351    fn teal_types_writes_the_client_of_an_exported_module() {
3352        let root = tempdir("teal-types-exports");
3353        write(&root.join("htl.toml"), "[rust]\nexports = [\"app\"]\n");
3354        write(
3355            &root.join("src/app.tl"),
3356            "local record app\n   add: function(integer, integer): integer\nend\nfunction app.add(a: integer, b: integer): integer\n   return a + b\nend\nreturn app\n",
3357        );
3358        let out = resolve_teal_types(&root).expect("teal_types! resolves");
3359        assert!(out.code.contains("pub struct App {"), "{}", out.code);
3360        assert!(
3361            out.code.contains("self.inst.call(\"add\", (a1, a2)).await"),
3362            "{}",
3363            out.code
3364        );
3365        expand_teal_types_from(&out).expect("parses as Rust items");
3366    }
3367
3368    /// The expansion and `htl rs` write the same text: the project of
3369    /// `htl-core/tests/fixtures/client` expands to the golden file there, which the
3370    /// `htl-cli` test of `htl rs` compares the command's file with as well.
3371    #[test]
3372    fn teal_types_expands_to_the_text_htl_rs_writes() {
3373        let root = tempdir("teal-types-client");
3374        write(
3375            &root.join("htl.toml"),
3376            include_str!("../../htl-core/tests/fixtures/client/htl.toml"),
3377        );
3378        write(
3379            &root.join("src/shop/types.tl"),
3380            include_str!("../../htl-core/tests/fixtures/client/src/shop/types.tl"),
3381        );
3382        write(
3383            &root.join("src/shop/app.tl"),
3384            include_str!("../../htl-core/tests/fixtures/client/src/shop/app.tl"),
3385        );
3386        let out = resolve_teal_types(&root).expect("teal_types! resolves");
3387        assert_eq!(
3388            out.code,
3389            include_str!("../../htl-core/tests/fixtures/client/teal_types.rs")
3390        );
3391        expand_teal_types_from(&out).expect("parses as Rust items");
3392    }
3393
3394    /// #539 (Acceptance 2): a type error in `src/ev/init.tl` fails `resolve_teal_types`
3395    /// naming the Teal file and line; a shape `rsgen::generate` refuses or a missing
3396    /// `htl.toml` is refused as well.
3397    #[test]
3398    fn teal_types_reports_type_error_with_teal_file_and_line_and_refuses_invalid_shapes() {
3399        let root = tempdir("teal-types-err");
3400        write(&root.join("htl.toml"), "[rust]\nmodules = [\"ev\"]\n");
3401        write(
3402            &root.join("src/ev/init.tl"),
3403            "local record M\n   record Event\n      at: integer\n   end\nend\nlocal bad: integer = \"not an integer\"\nreturn M\n",
3404        );
3405        let err = resolve_teal_types(&root).expect_err("type error must fail");
3406        assert!(
3407            err.contains("Teal type check failed:") && err.contains("init.tl:6:"),
3408            "{err}"
3409        );
3410
3411        // Function field refused by rsgen::generate at its line.
3412        write(
3413            &root.join("src/ev/init.tl"),
3414            "local record M\n   record Event\n      f: function(): integer\n   end\nend\nreturn M\n",
3415        );
3416        let err = resolve_teal_types(&root).expect_err("function field must fail");
3417        assert!(
3418            err.contains(
3419                "src/ev/init.tl:3:7: `M.Event.f`: a function or method field has no Rust type"
3420            ),
3421            "{err}"
3422        );
3423
3424        // Empty `[rust] modules` produces no module items and still tracks `htl.toml`.
3425        write(&root.join("htl.toml"), "[rust]\nmodules = []\n");
3426        let empty = resolve_teal_types(&root).expect("empty modules is ok");
3427        assert!(empty.code.is_empty());
3428        assert!(empty.config.is_some());
3429
3430        // Missing `htl.toml` is refused.
3431        let bare = tempdir("teal-types-bare");
3432        let err = resolve_teal_types(&bare).expect_err("no htl.toml must fail");
3433        assert!(err.contains("teal_types!: no htl.toml"), "{err}");
3434    }
3435}