Skip to main content

htl_core/
link.rs

1//! Linking: the `require` closure of one entry file, as a [`Bundle`].
2//!
3//! Starting at the entry, every `require("<literal>")` is followed (only string
4//! literals: a `require(expr)` cannot be resolved statically, list its targets under
5//! `extra`). `.tl` modules are type-checked and generated; plain `.lua` modules (a
6//! vendored dependency, say) are taken as they are. A name that runs from no file of the
7//! project — one the host provides, one only a `.d.tl` declares — is recorded as
8//! host-provided, as is anything listed in `host`. Any other unresolved `require` is an
9//! error: the point of a bundle is that "module not found" happens here, not on the
10//! first `require` at the customer's machine.
11//!
12//! # The host's names
13//!
14//! Which names the host provides is the project model's to say
15//! (`model::Project::provided`: `#[host_module]`s in the crate around the project,
16//! `[build] host`, `std.*`), and the callers that have a model — `htl build`,
17//! `include_bundle!` — put all of them in [`LinkOptions::host`]. A name there is not
18//! walked. When a file of the model implements it as well, the model refuses the name
19//! (its resolver's `HostShadowed`): the check reports that at a checked file's
20//! `require`, and the linker reports it at a plain `.lua`'s, which nothing checks — the
21//! same split as for a name two files implement. The file is never bundled: every run
22//! with the host loads the host's module, which `package.preload` answers first.
23//!
24//! # Declared names
25//!
26//! A name the model has only a declaration for — a `.d.tl` and no `.tl` or `.lua`, like
27//! `types/socket/http.d.tl` for a LuaSocket installed on the machine — is provided by the
28//! environment at run time, and is left out of the bundle the same way. That, too, is the
29//! model's answer (`model::Provider::Declared`, from its resolver's `provides`), which the
30//! linker asks through [`Htl::model_provides`] for a name that resolves to a declaration.
31//! It does not decide it from a lookup of its own, as it did before the model answered
32//! it (#321): only for a file in no project, or a name the model has nothing under, is a
33//! declaration with no `.lua` found behind it on the search path taken to be the host's —
34//! there is no model to ask. The outcome is the same either way; what changed is which of
35//! the two says so.
36//!
37//! A `require` the generator erased is not a dependency of anything that runs. Teal's
38//! `local type x = require("x")` is a type declaration when the alias is only ever used as
39//! a type, and the generator drops the whole statement; the checked file's census marks
40//! such a site ([`RequireSite::erased`], from the generator's own flag) and the linker
41//! skips it — not bundled, not the host's, not missing — so a bundle that imports a
42//! record of types from a `.d.tl` asks the host for nothing. The same alias read as a
43//! value keeps its `require`, and is counted like any other; so is a `global type`.
44//!
45//! # The store
46//!
47//! Generating a module is the expensive part of linking — the Teal check behind it costs
48//! about a second per few thousand lines, against milliseconds for Lua's own compiler to
49//! turn the result into bytecode — and it is the part the run cache already answers for.
50//! [`link_with`] takes a [`LinkStore`]: for every typed module it asks the store for the
51//! module's `gen` entry (the one `htl test` writes and replays), and an entry whose inputs
52//! and probes still hold stands in for the check, its generated Lua for `gen_lua`. A miss
53//! generates as before and writes the entry, so `htl build`, `htl test` and the
54//! `include_bundle!` / `include_tl!` macros feed one another (#100).
55//!
56//! Bytecode is never stored: compiling it is cheap, and an entry that carried it would
57//! have to be keyed on the strip and debug flags and on the Lua the bytecode is for, for
58//! no saving. What a bundle contains — module order, fingerprint, host modules — is the
59//! same whether a module was generated or replayed.
60//!
61//! # `htl build`, and the bundle from Rust
62//!
63//! `htl build src/main.tl -o app.hb` follows `require("<literal>")` from the entry and
64//! links everything it reaches into one file; `htl run app.hb` runs it, and a host does
65//! [`Htl::run_bundle`] after registering its modules. A missing `require` is said once,
66//! and the line says where to declare the module: in an `x.d.tl`, under `[build] host`,
67//! or under `[build] extra` for a dynamic `require` (`--extra`, `--host` on the command
68//! line). The payload is stripped bytecode unless `--debug` ([`LinkOptions::debug`]) or
69//! `--source` ([`LinkOptions::source`]); `htl bundle info app.hb` prints what the file
70//! records ([`crate::bundle`]). `htl build <dir>` is the older form, every `.tl` under a
71//! directory. A second [`Htl::install_bundle`] writes nothing; a newer bundle goes into a
72//! running state with [`Htl::replace_bundle`].
73//!
74//! From Rust, `include_bundle!` does the same at `cargo build`:
75//!
76//! ```rust,ignore
77//! const BUNDLE: &[u8] = htl::include_bundle!("src/main.tl", extra = ["modkit"]);
78//! // The host's names are the project's, as for `htl build`: `Host`'s `#[host_module]`, `[build]
79//! // host` and `std.*` are not bundled. `host = [..]` is optional, for a module the project
80//! // cannot see (registered by hand, or by another crate). payload = "source" for a target
81//! // whose Lua header differs (big-endian, non-default number types; see `bundle`);
82//! // debug = true keeps line numbers. [build] extra in htl.toml is merged in.
83//! Host { .. }.htl_preload(&h)?;
84//! h.run_bundle(&htl::bundle::Bundle::decode(BUNDLE)?, &args)?;
85//! ```
86//!
87//! From a `build.rs`, [`link`] does the same: take the bundle through [`Linked::bundle`]
88//! / [`Linked::into_bundle`], and emit `cargo:rerun-if-changed=<file>` for each of
89//! [`Linked::inputs`].
90use crate::bundle::{Bundle, Kind, Module};
91use crate::cache::{self, Cache};
92use crate::{CheckInfo, Htl, RequireSite};
93use anyhow::{Context, Result};
94use std::collections::{BTreeSet, HashSet, VecDeque};
95use std::path::{Path, PathBuf};
96
97/// What a link is asked for beyond the entry file: how modules are stored, and which ones
98/// the walk would otherwise miss or must not take.
99///
100/// Owned and `Default`, and it crosses the proc-macro boundary as a value — the borrowed
101/// half of a link's inputs is [`LinkStore`].
102#[derive(Debug, Clone, Default)]
103pub struct LinkOptions {
104    /// Keep debug info (line numbers, local names) in bytecode. Off = stripped, and
105    /// stripping takes the traceback with it: every frame of a run-time failure reads `?`,
106    /// with no line. On, a frame reads `depth:8` — the module the bundle knows, since a
107    /// bundle holds modules rather than files.
108    pub debug: bool,
109    /// Store generated Lua source instead of bytecode (portable across Lua builds):
110    /// larger and readable, bound to no Lua build, and named the same way as `debug`.
111    pub source: bool,
112    /// Modules to include even if no literal `require` reaches them.
113    pub extra: Vec<String>,
114    /// Modules the host provides at run time, besides those declared only by a `.d.tl`
115    /// (which the model answers for — see the module doc).
116    /// A name here is left out of the bundle and not walked, whether or not a file on
117    /// the search path could answer it — a library that bundles its own module names it
118    /// here in the binary's bundle so the two do not carry it twice.
119    ///
120    /// A caller with the project's model puts every name the model says the host provides
121    /// here (`model::Project::provided`), as `htl build` and `include_bundle!` do; what
122    /// else it lists is added to those. A file of the model under one of them is an error
123    /// of the model's, not something this list can override (see the module doc).
124    pub host: Vec<String>,
125    /// The module name the entry is served under in the bundle. `None` derives it from
126    /// the file alone: its stem, or its directory's name for an `init.tl`.
127    ///
128    /// A caller that has the project's model (`model::Project::locate`) passes the name it
129    /// gives the file, which is the one a `require` elsewhere in the project writes —
130    /// `src/app/main.tl` is `app.main` there, and a bundle serving it as `main` would
131    /// answer a name nothing asks for. The file alone cannot say which directory the
132    /// name starts from, so the default is right only for an entry at the top of the
133    /// source root.
134    pub entry_name: Option<String>,
135}
136
137/// The run cache as the linker uses it: the store, plus what the store needs to key and
138/// to validate an entry and that only the caller knows.
139///
140/// A borrowed view rather than part of [`LinkOptions`], which is owned and `Default` and
141/// crosses the proc-macro boundary as a value; the store lives for one command or one
142/// macro expansion, the options may not.
143#[derive(Clone, Copy)]
144pub struct LinkStore<'a> {
145    /// The store itself: where a typed module's generated Lua and its check are looked up
146    /// before the checker is asked, and written back after.
147    pub cache: &'a Cache,
148    /// The lint selection in force, as [`cache::gen_key`] takes it: an entry generated
149    /// under different lints reports different lints, and must not be reused.
150    pub lint: Option<&'a str>,
151    /// The project root, for the directories a `require` could resolve in.
152    pub root: &'a Path,
153    /// The project's `htl.toml` (its path) and what it says: its `[check] paths` are
154    /// probed, and the file itself is an input of every entry, since its lint selection is.
155    pub config: Option<(&'a Path, &'a crate::config::HtlConfig)>,
156}
157
158impl LinkStore<'_> {
159    /// Files an entry depends on besides the module and what it required.
160    fn extra_inputs(&self) -> Vec<PathBuf> {
161        self.config
162            .map(|(file, _)| vec![file.to_path_buf()])
163            .unwrap_or_default()
164    }
165
166    /// Directories a `require` from `file` could resolve in, for the entry's probes when
167    /// the store has no project model ([`cache::search_dirs`]).
168    fn probe_dirs(&self, file: &Path) -> Vec<PathBuf> {
169        cache::search_dirs(file)
170    }
171}
172
173/// One linked module: where it came from and how it was stored.
174#[derive(Debug, Clone)]
175pub struct LinkedModule {
176    /// The module name a `require` reaches it by, which is the name it takes in the
177    /// bundle — not its path.
178    pub name: String,
179    /// The file it was read from, for a report that wants to name something openable.
180    pub path: PathBuf,
181    /// `true` for a `.tl` that was checked and generated, `false` for a `.lua` taken as
182    /// it was. Only the typed ones have a store entry, so this is what
183    /// [`Linked::cached`] counts against.
184    pub typed: bool,
185}
186
187/// The result of a link: the bundle, and everything a reporter wants to say about how it
188/// was arrived at.
189///
190/// The bundle is private because an incomplete one must not escape — see
191/// [`errors`](Self::errors) and [`bundle`](Self::bundle). [`link`] itself returns `Ok`
192/// with the errors inside, so a caller (a `build.rs`, the macros) can show the whole list
193/// rather than the first one; the bundle is handed out only when the list is empty.
194#[derive(Debug, Default)]
195pub struct Linked {
196    bundle: Bundle,
197    /// Every module the walk took, in the order it took them.
198    pub modules: Vec<LinkedModule>,
199    /// Names the host is expected to provide at run time, so the bundle records them as
200    /// its own requirements rather than carrying code for them.
201    pub host_modules: Vec<String>,
202    /// Type errors and unresolved requires. A module with a type error is *absent* from
203    /// the bundle, so the bundle is only handed out ([`bundle`](Self::bundle)) when this
204    /// is empty: a program missing a module dies at its first `require`, far from here.
205    ///
206    /// Each is a [`Diagnostic`](crate::Diagnostic)'s text with its path spelled as
207    /// `htl check` spells it ([`spelled`](crate::Diagnostic::spelled)), so the error a
208    /// failed `include_bundle!` or `into_bundle` shows names a file the way the report does.
209    pub errors: Vec<String>,
210    /// The part of [`errors`](Self::errors) the linker found itself — a `require` nothing
211    /// answers, an `extra` module that is not there, a name two files claim — as values.
212    /// The rest of `errors` is the modules' own checks, which [`checks`](Self::checks)
213    /// carries. A reporter says these after the checks' diagnostics; it does not have to
214    /// tell the two apart by their text.
215    pub link_errors: Vec<crate::Diagnostic>,
216    /// Lints from every module, which do not stop a bundle: whether they stop the *run*
217    /// is the caller's, and the caller is what knows about `strict`.
218    pub lints: Vec<String>,
219    /// The full check of each module, for a reader that wants more than the flattened
220    /// [`errors`](Self::errors) and [`lints`](Self::lints) — the requires, the
221    /// dependencies, the per-file verdict.
222    pub checks: Vec<(PathBuf, CheckInfo)>,
223    /// How many typed modules came from the store rather than the checker. Zero without
224    /// a store. The total to say it against is the typed count of [`modules`](Self::modules).
225    pub cached: usize,
226    /// The checks' errors a linker error says instead: a `require` the checker could not
227    /// find is its `module not found`, and the linker's error at the same place says the
228    /// same thing and where to declare the module. One `require` is said once, by the
229    /// linker; [`errors`](Self::errors) carries that line in the check's place, and
230    /// [`reported`](Self::reported) leaves the check's out.
231    superseded: Vec<(PathBuf, usize, usize)>,
232}
233
234impl Linked {
235    /// The check of `path` as a report says it: `check` without the errors a linker error
236    /// at the same place says instead ([`link_errors`](Self::link_errors)). The checks in
237    /// [`checks`](Self::checks) are left as the checker made them.
238    pub fn reported(&self, path: &Path, check: &CheckInfo) -> CheckInfo {
239        let taken = |d: &crate::Diagnostic| {
240            self.superseded
241                .iter()
242                .any(|(p, l, c)| p == path && *l == d.line && *c == d.col)
243        };
244        let mut out = check.clone();
245        if !check.error_items.iter().any(taken) {
246            return out;
247        }
248        // `errors`, `error_fixes` and `error_items` are parallel: the i-th of each is one
249        // error, so they are filtered together.
250        out.errors.clear();
251        out.error_fixes.clear();
252        out.error_items.clear();
253        for (i, d) in check.error_items.iter().enumerate() {
254            if taken(d) {
255                continue;
256            }
257            out.errors.push(check.errors[i].clone());
258            out.error_fixes
259                .push(check.error_fixes.get(i).cloned().flatten());
260            out.error_items.push(d.clone());
261        }
262        out
263    }
264
265    /// `true` when every module linked cleanly (lints are not errors here).
266    pub fn ok(&self) -> bool {
267        self.errors.is_empty()
268    }
269
270    /// The bundle, or every error that makes it incomplete.
271    pub fn bundle(&self) -> Result<&Bundle> {
272        if self.errors.is_empty() {
273            Ok(&self.bundle)
274        } else {
275            Err(self.error())
276        }
277    }
278
279    /// The bundle by value, on the same condition as [`bundle`](Self::bundle): for a
280    /// caller that writes it out and is done with the report around it.
281    pub fn into_bundle(self) -> Result<Bundle> {
282        if self.errors.is_empty() {
283            Ok(self.bundle)
284        } else {
285            Err(self.error())
286        }
287    }
288
289    fn error(&self) -> anyhow::Error {
290        anyhow::anyhow!(
291            "link failed with {} error(s):\n  {}",
292            self.errors.len(),
293            self.errors.join("\n  ")
294        )
295    }
296
297    /// Every file the bundle was built from (entry, modules, and what the checker read
298    /// for them, e.g. `.d.tl`s): what a build script or macro should watch for changes,
299    /// one `cargo:rerun-if-changed=<file>` each. Files, not the directory: cargo compares
300    /// the mtime of the path it is given, and editing a file inside a directory does not
301    /// change the directory's.
302    pub fn inputs(&self) -> Vec<PathBuf> {
303        let mut out: Vec<PathBuf> = self.modules.iter().map(|m| m.path.clone()).collect();
304        for (_, ci) in &self.checks {
305            out.extend(ci.deps.iter().cloned());
306        }
307        out.sort();
308        out.dedup();
309        out
310    }
311}
312
313/// Link `entry` (a `.tl` file) and everything it requires. The checker's search path
314/// must already cover the project (`add_path` / `apply_project` / `apply_config`).
315pub fn link(h: &Htl, entry: &Path, opts: &LinkOptions) -> Result<Linked> {
316    link_with(h, entry, opts, None)
317}
318
319/// [`link`], replaying from the run cache what it can (see the module doc).
320///
321/// With `store` = `None` this is `link`. With a store, a typed module whose `gen` entry
322/// still holds is taken from it — its generated Lua, and what checking it reported — and
323/// counted in [`Linked::cached`]; every other typed module is generated and its entry
324/// written. Nothing about the store can fail the link: an unreadable or stale entry is a
325/// generate, an unwritable store is a generate next time too.
326pub fn link_with(
327    h: &Htl,
328    entry: &Path,
329    opts: &LinkOptions,
330    store: Option<LinkStore<'_>>,
331) -> Result<Linked> {
332    let mut out = Linked::default();
333    let entry_name = opts
334        .entry_name
335        .clone()
336        .unwrap_or_else(|| entry_module_name(entry));
337    let host_declared: HashSet<String> = opts.host.iter().cloned().collect();
338    let mut host: BTreeSet<String> = BTreeSet::new();
339    let mut queued: HashSet<String> = HashSet::new();
340    let mut queue: VecDeque<(String, PathBuf)> = VecDeque::new();
341    queue.push_back((entry_name.clone(), entry.to_path_buf()));
342    queued.insert(entry_name.clone());
343    for name in &opts.extra {
344        match classify(h, name, None)? {
345            Target::File(p) => {
346                if queued.insert(name.clone()) {
347                    queue.push_back((name.clone(), p));
348                }
349            }
350            Target::Host => {
351                host.insert(name.clone());
352            }
353            Target::Missing => out.link_error(positionless(format!(
354                "extra module '{name}' not found on the search path"
355            ))),
356            Target::Ambiguous(why) | Target::Shadowed(why) => {
357                out.link_error(positionless(format!("extra module {why}")))
358            }
359        }
360    }
361
362    while let Some((name, path)) = queue.pop_front() {
363        let typed = path.extension().is_none_or(|e| e != "lua");
364        let mut checked_errors: Option<(usize, Vec<(usize, usize)>)> = None;
365        let (code, requires) = if typed {
366            let Generated {
367                code,
368                check: ci,
369                cached,
370            } = generate(h, &path, store)?;
371            if cached {
372                out.cached += 1;
373            }
374            debug_assert_eq!(ci.error_items.len(), ci.errors.len());
375            // Where this file's errors start in `errors`, and where each sits: a linker
376            // error at one of those places says it instead (`superseded`).
377            let first = out.errors.len();
378            let at_positions: Vec<(usize, usize)> =
379                ci.error_items.iter().map(|d| (d.line, d.col)).collect();
380            checked_errors = Some((first, at_positions));
381            out.errors.extend(
382                ci.error_items
383                    .iter()
384                    .map(|d| d.clone().spelled().to_string()),
385            );
386            out.lints.extend(
387                ci.lint_items
388                    .iter()
389                    .map(|d| d.clone().spelled().to_string()),
390            );
391            let reqs = ci.requires.clone();
392            out.checks.push((path.clone(), ci));
393            (code, reqs)
394        } else {
395            let src = std::fs::read_to_string(&path)
396                .with_context(|| format!("reading {}", path.display()))?;
397            let reqs = h.lua_requires(&src, &path)?;
398            (Some(src), reqs)
399        };
400        for r in &requires {
401            // The value of a `local type` the generator erased: no `require` of the name is
402            // in the code just generated, so nothing runs it — not bundled, not the
403            // host's, not missing. The census keeps the site for the readers that want the
404            // check's dependencies (`htl unused`, the cycle lint); only the closure of what
405            // runs leaves it out.
406            if r.erased {
407                continue;
408            }
409            if queued.contains(&r.module) {
410                continue;
411            }
412            // A name the caller said the host provides is the host's before the search
413            // path is asked: a file that could answer it is not bundled and not walked.
414            // If a file of the model implements it all the same, the model refuses the
415            // name; a checked file's `require` of it is already an error of the check, a
416            // plain `.lua`'s is said here, where it would otherwise pass unseen — at every
417            // such `require`, including after a checked file has filed the name under the
418            // host's.
419            if host_declared.contains(&r.module) || host.contains(&r.module) {
420                if !typed && let Some(why) = h.host_shadowing(&r.module)? {
421                    out.link_error(at(&path, r, &why));
422                    continue;
423                }
424                host.insert(r.module.clone());
425                continue;
426            }
427            match classify(h, &r.module, r.path.as_deref())? {
428                Target::File(p) => {
429                    queued.insert(r.module.clone());
430                    queue.push_back((r.module.clone(), p));
431                }
432                Target::Host => {
433                    host.insert(r.module.clone());
434                }
435                Target::Missing => {
436                    let d = unresolved(&path, r);
437                    // The checker's own error at this `require`, when it has one, is
438                    // `module not found`: the same finding, said without where to declare
439                    // the module. The linker's line takes its place.
440                    let own = checked_errors.as_ref().and_then(|(first, at)| {
441                        at.iter()
442                            .position(|&(l, c)| l == r.line && c == r.col)
443                            .map(|i| first + i)
444                    });
445                    match own {
446                        Some(i) => {
447                            let d = d.spelled();
448                            out.errors[i] = d.to_string();
449                            out.superseded.push((path.clone(), r.line, r.col));
450                            out.link_errors.push(d);
451                        }
452                        None => out.link_error(d),
453                    }
454                }
455                // A checked file's `require` of it is already an error of the check, at
456                // the same place; a plain `.lua` is checked by nobody, so it is said here.
457                Target::Ambiguous(why) | Target::Shadowed(why) if !typed => {
458                    out.link_error(at(&path, r, &why))
459                }
460                Target::Ambiguous(_) => {}
461                // The check said it; the name is still the host's, and nothing is bundled.
462                Target::Shadowed(_) => {
463                    host.insert(r.module.clone());
464                }
465            }
466        }
467        let Some(code) = code else { continue };
468        let payload = if opts.source {
469            Module {
470                name: name.clone(),
471                kind: Kind::Source,
472                payload: code.into_bytes(),
473            }
474        } else {
475            let bc = h.compile_with(&name, &code, !opts.debug)?;
476            Module {
477                name: name.clone(),
478                kind: Kind::Bytecode,
479                payload: bc,
480            }
481        };
482        out.bundle.modules.push(payload);
483        out.modules.push(LinkedModule { name, path, typed });
484    }
485
486    out.host_modules = host.iter().cloned().collect();
487    out.bundle.entry = entry_name;
488    out.bundle.htl_version = env!("CARGO_PKG_VERSION").to_string();
489    out.bundle.host_modules = out.host_modules.clone();
490    if !opts.source {
491        out.bundle.fingerprint = h.fingerprint()?;
492    }
493    Ok(out)
494}
495
496/// One typed module, generated or replayed: see [`generate`].
497#[derive(Debug)]
498pub struct Generated {
499    /// The Lua; `None` when checking produced errors (see [`CheckInfo`]).
500    pub code: Option<String>,
501    /// What checking said — carried whether or not there is code, and the half a replay
502    /// needs as much as the Lua: the lints, the requires and the dependencies come out of
503    /// here.
504    pub check: CheckInfo,
505    /// Whether it came from the store rather than the checker.
506    pub cached: bool,
507}
508
509/// One typed module's generated Lua and what checking it said: from the store when its
510/// `gen` entry still holds, else from the checker, and then into the store. What
511/// [`link_with`] does per module, and what `include_tl!` does for its one file.
512///
513/// A hit needs both halves of the entry — the Lua, and the structured check it came with —
514/// since the reader wants the lints, the requires and the dependencies out of the second.
515/// `htl test` writes both; an entry missing either is a miss rather than a partial replay.
516pub fn generate(h: &Htl, path: &Path, store: Option<LinkStore<'_>>) -> Result<Generated> {
517    let key = store.map(|s| cache::module_gen_key(path, s.lint));
518    if let (Some(s), Some(k)) = (store, &key)
519        && let Some(m) = s.cache.lookup(k)
520        && let (Some(code), Some(check)) = (&m.code, &m.check)
521    {
522        return Ok(Generated {
523            code: Some(code.clone()),
524            check: check.to_check(),
525            cached: true,
526        });
527    }
528    let (code, ci) = h.gen_lua(path)?;
529    // Only when there is code: a module that failed to check has nothing to bundle, and
530    // storing that would replay the failure as if it were a result.
531    if let (Some(s), Some(k), Some(code)) = (store, &key, &code) {
532        // `gen_lua` can come back without requires for a module the checker already holds
533        // — it serves the generated code without walking the file again — and the requires
534        // are what the next run's validation and the linker's own walk are built from. Ask
535        // the checker separately, but only when the file could have any: a leaf that never
536        // says `require` is most of a project, and a check per leaf is the wrong price.
537        let stored = if ci.requires.is_empty() && mentions_require(path) {
538            match h.check(path) {
539                Ok(c) if !c.requires.is_empty() => CheckInfo {
540                    requires: c.requires,
541                    ..ci.clone()
542                },
543                _ => ci.clone(),
544            }
545        } else {
546            ci.clone()
547        };
548        let m = cache::Module::generated(&stored, code.clone());
549        s.cache
550            .store_module(k, path, &s.extra_inputs(), &s.probe_dirs(path), &m);
551    }
552    Ok(Generated {
553        code,
554        check: ci,
555        cached: false,
556    })
557}
558
559/// Whether `path`'s source says `require` anywhere ([`cache::source_mentions_require`]);
560/// an unreadable file is taken to, which costs a check rather than a wrong entry.
561pub fn mentions_require(path: &Path) -> bool {
562    std::fs::read_to_string(path)
563        .map(|s| cache::source_mentions_require(&s))
564        .unwrap_or(true)
565}
566
567fn is_decl(p: &Path) -> bool {
568    p.to_string_lossy().ends_with(".d.tl")
569}
570
571fn unresolved(from: &Path, r: &RequireSite) -> crate::Diagnostic {
572    at(
573        from,
574        r,
575        &format!(
576            "require(\"{}\") is not on the search path: nothing to bundle. If the host \
577             provides it, declare it in a `{}.d.tl` or list it under `[build] host` in \
578             htl.toml; if it is reached only through a dynamic require, list it under \
579             `[build] extra`",
580            r.module,
581            r.module.replace('.', "/")
582        ),
583    )
584}
585
586enum Target {
587    /// A file to bundle (`.tl` typed, or a plain `.lua`).
588    File(PathBuf),
589    /// Runs from no file of the project: the model says the host or the environment
590    /// provides it — declared only, by a `.d.tl` with no `.lua` behind it, or named by
591    /// one of the host's sources — or, with no model to ask, it resolves to a `.d.tl` and
592    /// the search path has no `.lua` behind it.
593    Host,
594    Missing,
595    /// More than one file implements the name: the model's message saying which. Nothing
596    /// is bundled for it, since no order picks one.
597    Ambiguous(String),
598    /// The host provides the name and a file of the model implements it too: the model's
599    /// message saying so. Nothing is bundled for it — the host's module is what runs — and
600    /// it is an error wherever it is required, as `Ambiguous` is. Reached for a name the
601    /// caller did not list in [`LinkOptions::host`] (a caller without the model's list);
602    /// a listed one is checked before the walk would classify it.
603    Shadowed(String),
604}
605
606/// A linker error at a `require`: `file:line:col: why`, the shape a check's error has.
607fn at(file: &Path, r: &RequireSite, why: &str) -> crate::Diagnostic {
608    crate::Diagnostic::new(
609        crate::Severity::Error,
610        file.display().to_string(),
611        r.line,
612        r.col,
613        why,
614        None,
615    )
616}
617
618/// A linker error about no place in a file: an `extra` module named in the config.
619fn positionless(message: String) -> crate::Diagnostic {
620    crate::Diagnostic::new(crate::Severity::Error, "", 0, 0, message, None)
621}
622
623impl Linked {
624    /// Record an error the linker found itself: as a value, and in the flattened
625    /// [`errors`](Self::errors) as its text.
626    fn link_error(&mut self, d: crate::Diagnostic) {
627        let d = d.spelled();
628        self.errors.push(d.to_string());
629        self.link_errors.push(d);
630    }
631}
632
633/// The module name an entry file answers to when the project model does not name it — an
634/// entry outside every project: the naming rule ([`crate::naming`]) against the file's own
635/// directory, so its stem, except that `<dir>/init.tl` is the module `<dir>` — the name a
636/// `require` of it is written as, and so the name a bundle has to serve it under once a
637/// host has installed the bundle and a program asks for it. An entry the model names is
638/// served under that name ([`LinkOptions::entry_name`]).
639fn entry_module_name(entry: &Path) -> String {
640    // Named against its own directory — the one place a file outside every project
641    // names by itself — which leaves `<dir>/init.tl` nothing to be named by but `<dir>`.
642    let file = entry.file_name().map(PathBuf::from).unwrap_or_default();
643    let rel = match (file.to_str(), entry.parent().and_then(|d| d.file_name())) {
644        (Some("init.tl"), Some(dir)) => Path::new(dir).join(&file),
645        _ => file,
646    };
647    crate::naming::name_of("", &rel).unwrap_or_else(|| "main".into())
648}
649
650/// What a `require(name)` points at for the linker. `found` is the checker's own
651/// resolution when already known (a require site); otherwise it is looked up.
652fn classify(h: &Htl, name: &str, found: Option<&Path>) -> Result<Target> {
653    let (found, lua) = match found {
654        Some(p) => (Some(p.to_path_buf()), None),
655        None => h.resolve_module(name)?,
656    };
657    // A refused name resolves to its declaration or to nothing, never to its file; either
658    // would read as the host's or as missing, so ask the model first.
659    if found.as_deref().is_none_or(is_decl)
660        && let Some(why) = h.host_shadowing(name)?
661    {
662        return Ok(Target::Shadowed(why));
663    }
664    let Some(p) = found else {
665        return Ok(match h.ambiguity(name)? {
666            Some(why) => Target::Ambiguous(why),
667            None => Target::Missing,
668        });
669    };
670    if !is_decl(&p) {
671        return Ok(Target::File(p));
672    }
673    // A declaration. Whether anything of the project runs behind it is the model's to
674    // say: a name it has only this declaration for is the environment's, one the host
675    // provides is the host's, and neither is bundled.
676    let model = h.model_provides(name)?;
677    if let crate::Provision::Provided(_) = model {
678        return Ok(Target::Host);
679    }
680    // Otherwise a `.lua` behind the declaration (a vendored dependency typed by a `.d.tl`)
681    // is what runs, and what gets bundled: the model's own, when it has the name.
682    let lua = match lua {
683        Some(l) => Some(l),
684        None => h.resolve_module(name)?.1,
685    };
686    Ok(match (lua, model) {
687        (Some(l), _) => Target::File(l),
688        // No model to ask, or a name it has nothing under (a `.d.tl` found on the search
689        // path, outside every root of the project): a declaration with nothing behind it
690        // on the path is taken to be the host's, as it was before the model answered.
691        (None, crate::Provision::Unknown) => Target::Host,
692        // The model has the name and says a file of the project runs for it, and the
693        // lookup found none: the two disagree, which a declared name never makes them
694        // do. Filed with the host's as before rather than failing a build over it.
695        (None, _) => Target::Host,
696    })
697}