htl-core 0.5.0

Engine of htl (Holistic Typed Lua): Teal check / gen / lint / fmt / test / bundle on an embedded mlua state. Use the `htl` crate.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
//! `---@contract` / `---@required`: the contract a directory of modules must satisfy,
//! declared where the type is declared.
//!
//! ```tl
//! local record defs
//!    record Mod              ---@contract("mods")
//!       name: string         ---@required
//!       monsters: {Monster}  ---@required
//!       factions: {Faction}
//!    end
//! end
//! return defs
//! ```
//!
//! Every module directly under `mods/` must return a value assignable to `defs.Mod` and
//! set `name` and `monsters`; `factions` is there for the mods that want it. That last
//! part is why the fields are marked rather than counted: a record cannot say which of
//! its own fields are mandatory (every Teal record field is nilable and there is no `?`
//! for them), and taking all of them would break every module written before the field
//! was added.
//!
//! `htl.toml` holds the directory and nothing else:
//!
//! ```toml
//! [[contract]]
//! dir = "mods"
//! ```
//!
//! A bare `---@contract` inherits it — one line in the file a reader opens first, saying
//! where this project accepts modules — and `---@contract("<dir>")` overrides it, which
//! is what a project with more than one contract writes.
//!
//! The markers are comments, so the file stays valid Teal and other tooling ignores them.
//! Reading them is a scan of the search paths, not a type-check: a record is found by the
//! line it is declared on, the way `---@struct` is (see `prelude.lua`).

use crate::config::{Contract, HtlConfig, RequireFields};
use anyhow::Result;
use std::path::{Path, PathBuf};

/// A contract as it applies: which directory, which type, which fields.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Resolved {
    /// Directory relative to the project root, `*` in one segment expanding to every
    /// subdirectory at that level (`"sites/*"`).
    pub dir: String,
    /// `"<module>.<Type>"`, e.g. `"defs.Mod"` — the module that declares the record and
    /// the path to it inside that module.
    pub type_path: String,
    /// The fields a module's returned table must set, from `---@required`.
    pub require_fields: RequireFields,
    /// Only this module name in each matched dir is held to the contract.
    pub module: Option<String>,
    /// Module names in the dir that are not held to the contract.
    pub exclude: Vec<String>,
    /// Where to publish the declaration, from `---@contract(dts = "…")`.
    pub dts: Option<String>,
    /// Where this contract is enforced when the scan cannot see it, from
    /// `[[contract]] enforced_by`. Not a marker argument: enforcement is the host's
    /// business, and the record is published to authors who have no use for the path.
    pub enforced_by: Option<String>,
    /// The file the marker is in: where to point when something about this contract is
    /// wrong. Not where the contract applies — that is [`dir`](Self::dir) — but where the
    /// sentence that set it up was written, which is the line a person has to edit.
    pub declared_in: PathBuf,
    /// The line of that marker, counted from 1.
    pub declared_at: usize,
}

impl Resolved {
    /// Concrete contract directories under `root` (expands one `*` segment). Missing
    /// directories are dropped; a literal `dir` that does not exist yields nothing.
    pub fn dirs(&self, root: &Path) -> Vec<PathBuf> {
        let mut acc = vec![root.to_path_buf()];
        for seg in self.dir.split('/').filter(|s| !s.is_empty() && *s != ".") {
            let mut next = Vec::new();
            for base in &acc {
                if seg == "*" {
                    if let Ok(rd) = std::fs::read_dir(base) {
                        let mut subs: Vec<PathBuf> = rd
                            .flatten()
                            .map(|e| e.path())
                            .filter(|p| p.is_dir() && !crate::is_skipped_dir(p, &[]))
                            .collect();
                        subs.sort();
                        next.extend(subs);
                    }
                } else {
                    let p = base.join(seg);
                    if p.is_dir() {
                        next.push(p);
                    }
                }
            }
            acc = next;
        }
        acc
    }

    /// Is `module` (a file stem under a contract dir) held to this contract? The module
    /// that declares the type is not held to it.
    pub fn applies_to(&self, module: &str) -> bool {
        if self
            .type_path
            .split_once('.')
            .is_some_and(|(m, _)| m == module)
        {
            return false;
        }
        if self.exclude.iter().any(|e| e == module) {
            return false;
        }
        match &self.module {
            Some(only) => only == module,
            None => true,
        }
    }
}

/// What the `---@contract` on one record says, before the directory is settled.
struct Marker {
    dir: Option<String>,
    module: Option<String>,
    exclude: Option<Vec<String>>,
    dts: Option<String>,
}

/// Contracts this project declares, and what is wrong with the ones it does not.
///
/// The scan covers [`HtlConfig::search_paths`] — where the checker resolves modules
/// from — one level deep, plus `<sub>/init.tl`, which is the shape Teal's own path
/// templates resolve. A marker anywhere else is not found, and the module name of a file
/// nested deeper cannot be written as `<module>.<Type>` anyway.
///
/// The second half of the pair is diagnostics: a bare marker with no `[[contract]]` to
/// inherit from, two markers claiming one directory, a marker on a record that is not
/// nested inside its module. They are returned rather than raised because one broken
/// contract should not take the other contracts of the project with it.
pub fn resolve(root: &Path, cfg: &HtlConfig) -> (Vec<Resolved>, Vec<String>) {
    let mut out = Vec::new();
    let mut problems = Vec::new();
    for file in scan_targets(root, cfg) {
        let Ok(src) = std::fs::read_to_string(&file) else {
            continue;
        };
        if !src.contains("---@contract") {
            continue;
        }
        match read_file(&file, &src, cfg) {
            Ok(found) => out.extend(found),
            Err(msgs) => problems.extend(msgs),
        }
    }
    // A published declaration carries the marker it was copied from, so the same record
    // is found twice — once in the source, once in the file written from it. That is one
    // record making one claim, and the source is the one to keep (a `.tl` beats a `.d.tl`
    // everywhere else too).
    out.sort_by_key(|c| crate::is_declaration(&c.declared_in));
    let mut kept: Vec<Resolved> = Vec::with_capacity(out.len());
    for c in out {
        if !kept.iter().any(|k| same_record(root, k, &c)) {
            kept.push(c);
        }
    }
    let out = kept;

    // Two *different* types for one directory would each have to be the one enforced
    // there.
    for i in 0..out.len() {
        if let Some(j) = out[..i].iter().position(|c| c.dir == out[i].dir) {
            problems.push(format!(
                "{}:{}:1: {} claims directory {:?}, which {} already claims at {}:{} \
                 [htl contract]",
                out[i].declared_in.display(),
                out[i].declared_at,
                out[i].type_path,
                out[i].dir,
                out[j].type_path,
                out[j].declared_in.display(),
                out[j].declared_at,
            ));
        }
    }
    (out, problems)
}

/// Where a contract publishes its declaration: `---@contract(dts = "…")` relative to the
/// project root, or `types/<module>.d.tl` by default — `types/` being the directory a
/// project keeps declarations for other people in, searched with no configuration.
pub fn dts_target(root: &Path, c: &Resolved) -> Option<PathBuf> {
    let module = c.type_path.split_once('.')?.0;
    Some(match &c.dts {
        Some(p) => crate::config::resolve_path(root, p),
        None => root.join("types").join(format!("{module}.d.tl")),
    })
}

/// Is `later` the record `earlier` already is, found a second time? The claim check is
/// between records, and a record's declaration is that record rather than a second
/// claimant of the directory.
///
/// Two ways one record turns up twice. It was published: `htl dts` writes the module a
/// `---@contract` type is declared in, and `types/` is on the search path, so the scan
/// reads the claim back out of the file it just wrote. Or the same file was reached
/// through two search paths. Which file a publication is is the publish's own answer
/// ([`dts_target`]) — nothing here recognises a `types/` directory or a `.d.tl` name, so
/// a project that publishes somewhere else is the same case — and the directory is what
/// says the two claims are one claim, since that is what the published marker carries.
///
/// A module of the same name in each of two contract directories is *not* this: a
/// contract directory is resolved as a directory ([`crate::pkg::TealResolver::for_contract_dir`]
/// roots one resolver at each) and is not on the project's search path, so `mods_a/one.tl`
/// and `mods_b/one.tl` are two modules, each held to the record its own directory is
/// under. There is nothing there for the claim check to report.
fn same_record(root: &Path, earlier: &Resolved, later: &Resolved) -> bool {
    if earlier.dir != later.dir {
        return false;
    }
    if crate::same_file(&earlier.declared_in, &later.declared_in) {
        return earlier.type_path == later.type_path;
    }
    dts_target(root, earlier).is_some_and(|t| crate::same_file(&t, &later.declared_in))
}

/// Publish each contract's declaration: the module that declares the contract type is
/// what an outside author writes against, so `htl` writes it out rather than leaving the
/// host to copy the file at run time. Returns the targets it wrote (`true`) or found
/// already current (`false`), and what it could not publish.
///
/// The declaring module is written out as a declaration: bodies removed, and each
/// function that was part of the module's interface folded into its record as a field
/// (`function m.f(a: integer): string` -> `f: function(a: integer): string`), which is
/// what a hand-written `.d.tl` says. A module of declarations is copied unchanged,
/// because there is nothing to remove.
///
/// One write per file, not one per contract. Two records in one module publish that one
/// module, and a pass per record would write the file twice over — each pass rewriting
/// its own marker and leaving the other's as the author left it, so the two passes
/// disagree, `dts: wrote` is said twice, and the file never settles. A file's markers are
/// made self-contained together, once.
pub fn publish(root: &Path, contracts: &[Resolved]) -> (Vec<(PathBuf, bool)>, Vec<String>) {
    let mut written = Vec::new();
    let mut problems = Vec::new();
    // Each file to write and the module it is written from, in the order the contracts
    // came in.
    let mut targets: Vec<(PathBuf, &Resolved)> = Vec::new();
    for c in contracts {
        let Some(target) = dts_target(root, c) else {
            continue;
        };
        // A contract already declared in a `.d.tl` is its own publication.
        if crate::same_file(&target, &c.declared_in) {
            continue;
        }
        match targets.iter().find(|(t, _)| crate::same_file(t, &target)) {
            // Two modules cannot both be one declaration: whichever was written last
            // would be the file, and the other would have been published and lost.
            Some((_, first)) if !crate::same_file(&first.declared_in, &c.declared_in) => problems
                .push(format!(
                    "{}:{}:1: {} publishes to {}, where {} is already published from {} \
                     [htl contract]",
                    c.declared_in.display(),
                    c.declared_at,
                    c.type_path,
                    target.display(),
                    first.type_path,
                    first.declared_in.display(),
                )),
            Some(_) => {}
            None => targets.push((target, c)),
        }
    }
    for (target, c) in targets {
        let Ok(src) = std::fs::read_to_string(&c.declared_in) else {
            continue;
        };
        // Every marker the file carries, not only the one that sent it here: what is
        // published has to stand on its own whichever record a reader opens it for.
        let src = contracts
            .iter()
            .filter(|o| crate::same_file(&o.declared_in, &c.declared_in))
            .fold(src, |s, o| self_contained_marker(&s, o));
        let text = match declaration_of(&src) {
            Ok(t) => t,
            Err(msgs) => {
                problems.extend(msgs.into_iter().map(|m| {
                    format!(
                        "{}:{m} publishing {} to {} [htl contract]",
                        c.declared_in.display(),
                        c.type_path,
                        target.display()
                    )
                }));
                continue;
            }
        };
        match crate::write_if_changed(&target, &text) {
            Ok(w) => written.push((target, w)),
            Err(e) => problems.push(format!(
                "{}:1:1: writing {}: {e} [htl contract]",
                c.declared_in.display(),
                target.display()
            )),
        }
    }
    (written, problems)
}

/// The source with its `---@contract` rewritten so the published copy stands on its own:
/// the directory written out (a bare marker inherits from an `htl.toml` the reader of the
/// declaration does not have), and `dts` dropped (the copy is not itself a publisher, and
/// the path was the publisher's).
fn self_contained_marker(src: &str, c: &Resolved) -> String {
    let mut args = format!("{:?}", c.dir);
    if let Some(m) = &c.module {
        args.push_str(&format!(", module = {m:?}"));
    }
    if !c.exclude.is_empty() {
        args.push_str(&format!(", exclude = {:?}", c.exclude.join(" ")));
    }
    let want = format!("---@contract({args})");
    let mut lines: Vec<String> = src.lines().map(str::to_string).collect();
    // The marker is on the record's line or the one above it, the same two places it was
    // read from.
    for i in [
        c.declared_at.saturating_sub(1),
        c.declared_at.saturating_sub(2),
    ] {
        let Some(line) = lines.get_mut(i) else {
            continue;
        };
        let Some(at) = line.find("---@contract") else {
            continue;
        };
        let tail = &line[at + "---@contract".len()..];
        let rest = match tail.split_once(')') {
            Some((_, after)) if tail.trim_start().starts_with('(') => after.to_string(),
            _ => tail.to_string(),
        };
        *line = format!("{}{want}{rest}", &line[..at]);
        break;
    }
    let mut out = lines.join("\n");
    out.push('\n');
    out
}

/// One `function` statement of a module: where it sits, what to write instead, and where
/// that goes.
struct Implementation {
    /// Lines to remove, `[first, last]`, zero-based, doc comment included.
    span: (usize, usize),
    /// The doc comment, trimmed, to reindent above the field.
    doc: Vec<String>,
    /// `Some((record path, field text))` for a function on the module's own table, `None`
    /// for a `local function` — module-local, and not part of what the module declares.
    field: Option<(Vec<String>, String)>,
}

/// The `.d.tl` for a module's source: every function body removed and its signature moved
/// into the record it belongs to. `Err` when a `function` statement cannot be placed,
/// rather than a file with a silently missing function in it.
pub fn declaration_of(src: &str) -> Result<String, Vec<String>> {
    let lines: Vec<&str> = src.lines().collect();
    let mut problems = Vec::new();
    let mut found: Vec<Implementation> = Vec::new();
    let mut i = 0;
    while i < lines.len() {
        let Some(kind) = function_start(lines[i]) else {
            i += 1;
            continue;
        };
        // The doc comment above a function is part of it, and belongs wherever it goes.
        let mut first = i;
        while first > 0 && lines[first - 1].trim_start().starts_with("--") {
            first -= 1;
        }
        let Some(end) = body_end(&lines, i) else {
            problems.push(format!(
                "{}:1: this function has no `end` at its own indentation, so its body \
                 cannot be told from what follows:",
                i + 1
            ));
            break;
        };
        match kind {
            FnKind::Local => found.push(Implementation {
                span: (first, end),
                doc: Vec::new(),
                field: None,
            }),
            FnKind::Exported => match signature(&lines, i) {
                Ok((path, field)) => found.push(Implementation {
                    span: (first, end),
                    doc: lines[first..i]
                        .iter()
                        .map(|l| l.trim().to_string())
                        .collect(),
                    field: Some((path, field)),
                }),
                Err(e) => problems.push(format!("{}:1: {e}:", i + 1)),
            },
        }
        i = end + 1;
    }
    if !problems.is_empty() {
        return Err(problems);
    }
    if found.is_empty() {
        // Already a declaration: nothing to strip, and copying it as it is keeps the
        // comments and the layout the author wrote.
        return Ok(src.to_string());
    }

    let mut out: Vec<Option<String>> = lines.iter().map(|l| Some(l.to_string())).collect();
    // Fields first, while the line numbers still mean what they meant.
    for imp in &found {
        let Some((path, field)) = &imp.field else {
            continue;
        };
        match record_close(&lines, path) {
            Some(at) => {
                // A record that already declares the field has the author's own version
                // of this signature; a second one would be a duplicate key.
                let name = field.split(':').next().unwrap_or_default();
                if declares_field(&lines, at, name) {
                    continue;
                }
                let indent = " ".repeat(indent_of(lines[at]) + 3);
                let existing = out[at].take().unwrap_or_default();
                let doc: String = imp.doc.iter().map(|l| format!("{indent}{l}\n")).collect();
                out[at] = Some(format!("{doc}{indent}{field}\n{existing}"));
            }
            None => problems.push(format!(
                "{}:1: nothing declares a record {} for this function to be a field of:",
                imp.span.0 + 1,
                path.join(".")
            )),
        }
    }
    if !problems.is_empty() {
        return Err(problems);
    }
    for imp in &found {
        let (first, last) = imp.span;
        for l in out.iter_mut().take(last + 1).skip(first) {
            *l = None;
        }
        // The blank line that separated this function from the next belongs to it: left
        // behind, every removal leaves a gap where a function used to be.
        if (first == 0 || lines[first - 1].trim().is_empty())
            && let Some(after) = out.get_mut(last + 1)
            && after.as_deref().is_some_and(|l| l.trim().is_empty())
        {
            *after = None;
        }
    }
    let mut text: String = out
        .into_iter()
        .flatten()
        .collect::<Vec<_>>()
        .join("\n")
        .trim_end()
        .to_string();
    text.push('\n');
    Ok(text)
}

enum FnKind {
    Exported,
    Local,
}

fn function_start(line: &str) -> Option<FnKind> {
    let t = line.trim_start();
    if t.starts_with("local function ") {
        Some(FnKind::Local)
    } else if t.starts_with("function ") {
        Some(FnKind::Exported)
    } else {
        None
    }
}

/// The line closing the function that starts at `i`: the first `end` indented no deeper
/// than the `function` itself.
fn body_end(lines: &[&str], i: usize) -> Option<usize> {
    let base = indent_of(lines[i]);
    (i + 1..lines.len()).find(|&j| {
        let t = lines[j].trim_start();
        (t == "end" || t.starts_with("end ") || t.starts_with("end-"))
            && indent_of(lines[j]) <= base
    })
}

/// `function m.f(a: integer): string` -> (`["m"]`, `f: function(a: integer): string`).
///
/// The signature is taken as written, over as many lines as it spans: a `.d.tl` names
/// parameters in a function type just as the implementation does, so there is nothing to
/// rewrite. A `:` method gains the `self` its definition left implicit.
fn signature(lines: &[&str], i: usize) -> Result<(Vec<String>, String), String> {
    let head = lines[i].trim_start().strip_prefix("function ").unwrap();
    let (name, rest) = head
        .split_once('(')
        .ok_or("a function with no parameter list")?;
    let method = name.contains(':');
    let mut path: Vec<String> = name
        .split(['.', ':'])
        .map(|s| s.trim().to_string())
        .collect();
    let field = path.pop().filter(|f| !f.is_empty()).ok_or("no name")?;
    if path.is_empty() {
        return Err("a function on no module table".into());
    }
    // Parameters may run over several lines; the signature ends with the line on which
    // the parentheses close, return type and all.
    let mut sig = rest.to_string();
    let mut depth = 1i32 + count(rest);
    let mut j = i;
    while depth > 0 {
        j += 1;
        let next = *lines.get(j).ok_or("a parameter list that never closes")?;
        depth += count(next);
        sig.push('\n');
        sig.push_str(next);
    }
    let sig = sig.trim_end();
    let self_arg = if !method {
        String::new()
    } else if sig.trim_start().starts_with(')') {
        // `function M:f()` takes only its receiver: no comma to separate it from.
        format!("self: {}", path.last().unwrap())
    } else {
        format!("self: {}, ", path.last().unwrap())
    };
    Ok((path, format!("{field}: function({self_arg}{sig}")))
}

/// Net change in parenthesis depth over a line, ignoring what is inside a comment.
fn count(line: &str) -> i32 {
    let code = line.split("--").next().unwrap_or(line);
    code.chars().filter(|c| *c == '(').count() as i32
        - code.chars().filter(|c| *c == ')').count() as i32
}

/// Does the record closed at `close` already declare a field called `name`? Its body is
/// what lies between its `record` line and that `end`, at one level of nesting.
fn declares_field(lines: &[&str], close: usize, name: &str) -> bool {
    let base = indent_of(lines[close]);
    for j in (0..close).rev() {
        let t = lines[j].trim_start();
        // Its own `record` line: the body is behind us, and a field of that name further
        // up belongs to some other record.
        if indent_of(lines[j]) <= base
            && (t.starts_with("record ") || t.starts_with("local record "))
        {
            return false;
        }
        if t.strip_prefix(name)
            .is_some_and(|r| r.trim_start().starts_with(':'))
        {
            return true;
        }
    }
    false
}

/// The `end` closing the record named by `path` (`["defs", "Mod"]` = `Mod` inside
/// `defs`), searched from the outside in.
fn record_close(lines: &[&str], path: &[String]) -> Option<usize> {
    let mut from = 0usize;
    let mut to = lines.len();
    for name in path {
        let at = (from..to).find(|&j| record_name(lines[j]).as_deref() == Some(name.as_str()))?;
        let base = indent_of(lines[at]);
        to = (at + 1..to)
            .find(|&j| lines[j].trim_start().starts_with("end") && indent_of(lines[j]) <= base)?;
        from = at + 1;
    }
    Some(to)
}

/// Files a marker can be found in: those directly under a search path, and the
/// `init.tl` of an immediate subdirectory (`require("sub")` resolves to `sub/init.tl`).
fn scan_targets(root: &Path, cfg: &HtlConfig) -> Vec<PathBuf> {
    let mut out = Vec::new();
    for dir in cfg.search_paths(root) {
        let Ok(entries) = std::fs::read_dir(&dir) else {
            continue;
        };
        let mut here: Vec<PathBuf> = Vec::new();
        for e in entries.flatten() {
            let p = e.path();
            if p.is_file() && is_teal(&p) {
                here.push(p);
            } else if p.is_dir() && !crate::is_skipped_dir(&p, &[]) {
                for name in ["init.tl", "init.d.tl"] {
                    let init = p.join(name);
                    if init.is_file() {
                        here.push(init);
                    }
                }
            }
        }
        here.sort();
        out.extend(here);
    }
    out.dedup();
    out
}

fn is_teal(p: &Path) -> bool {
    p.file_name()
        .and_then(|s| s.to_str())
        .is_some_and(|n| n.ends_with(".tl"))
}

/// The module name a `require` would use for `file`: its stem, or the directory name
/// when the file is an `init.tl`.
fn module_name(file: &Path) -> Option<String> {
    let stem = file.file_name()?.to_str()?.trim_end_matches(".tl");
    let stem = stem.strip_suffix(".d").unwrap_or(stem);
    if stem == "init" {
        return Some(file.parent()?.file_name()?.to_str()?.to_string());
    }
    Some(stem.to_string())
}

/// Every contract declared in one file. `Err` carries what is wrong with the markers it
/// does have, one message per marker, so a file with two of them reports both.
fn read_file(file: &Path, src: &str, cfg: &HtlConfig) -> Result<Vec<Resolved>, Vec<String>> {
    let lines: Vec<&str> = src.lines().collect();
    let Some(module) = module_name(file) else {
        return Ok(Vec::new());
    };
    let mut out = Vec::new();
    let mut problems = Vec::new();
    // A marker on its own line belongs to the line below it, so the record is what is
    // looked for first: asking about the marker line by line would attribute a trailing
    // `record Mod ---@contract` to the field declared under it as well.
    for (i, line) in lines.iter().enumerate() {
        let Some(record) = record_name(line) else {
            continue;
        };
        let Some(marker) = marker_on(&lines, i, "contract") else {
            continue;
        };
        let marker = match parse_marker(&marker) {
            Ok(m) => m,
            Err(e) => {
                problems.push(format!(
                    "{}:{}:1: {e} [htl contract]",
                    file.display(),
                    i + 1
                ));
                continue;
            }
        };
        let Some(path) = type_path(&lines, i, &module, &record) else {
            problems.push(format!(
                "{}:{}:1: {record} is the module {module} returns, not a type inside it: \
                 a contract type is written as <module>.<Type>, so declare it as a record \
                 within one [htl contract]",
                file.display(),
                i + 1
            ));
            continue;
        };
        let dir = match (marker.dir, cfg.contract.as_slice()) {
            (Some(d), _) => d,
            (None, [one]) => one.dir.clone(),
            (None, []) => {
                problems.push(format!(
                    "{}:{}:1: ---@contract names no directory and htl.toml declares none: \
                     write ---@contract(\"<dir>\") here, or a [[contract]] dir = \"<dir>\" \
                     in htl.toml [htl contract]",
                    file.display(),
                    i + 1
                ));
                continue;
            }
            (None, many) => {
                problems.push(format!(
                    "{}:{}:1: ---@contract names no directory and htl.toml declares {}: \
                     write the directory on the marker [htl contract]",
                    file.display(),
                    i + 1,
                    many.len()
                ));
                continue;
            }
        };
        let inherited: Option<&Contract> = cfg.contract.iter().find(|c| c.dir == dir);
        out.push(Resolved {
            dir,
            type_path: path,
            require_fields: required_fields(&lines, i),
            module: marker
                .module
                .or_else(|| inherited.and_then(|c| c.module.clone())),
            exclude: marker
                .exclude
                .or_else(|| inherited.map(|c| c.exclude.clone()))
                .unwrap_or_default(),
            dts: marker.dts,
            enforced_by: inherited.and_then(|c| c.enforced_by.clone()),
            declared_in: file.to_path_buf(),
            declared_at: i + 1,
        });
    }
    // A marker nothing picked up: it reads as a contract and does nothing, which is worse
    // than either being one or not being written.
    for (i, line) in lines.iter().enumerate() {
        if !line.contains("---@contract")
            || record_name(line).is_some()
            || lines.get(i + 1).and_then(|l| record_name(l)).is_some()
        {
            continue;
        }
        problems.push(format!(
            "{}:{}:1: ---@contract is not on a record declaration [htl contract]",
            file.display(),
            i + 1
        ));
    }
    if problems.is_empty() {
        Ok(out)
    } else {
        Err(problems)
    }
}

/// The text after `---@<name>` on line `i` or the line above it, `None` when the marker
/// is not there. `Some("")` for a bare marker; `Some("(…)")` when it has arguments.
///
/// The line above counts only when the marker is the whole of it. A marker trailing a
/// declaration belongs to that declaration, and reading it from the line below as well
/// would make one `---@required` mark two fields.
///
/// What is read stops at the next `---@`: a declaration may carry two markers on one line
/// (`record Mod   ---@contract ---@extensible`), and the second one is the other marker's
/// text rather than this one's argument list.
fn marker_on(lines: &[&str], i: usize, name: &str) -> Option<String> {
    let needle = format!("---@{name}");
    let above = i
        .checked_sub(1)
        .and_then(|p| lines.get(p))
        .filter(|l| l.trim_start().starts_with("---"));
    for line in [lines.get(i), above].into_iter().flatten() {
        if let Some(rest) = line.split(&needle).nth(1) {
            // `---@contracts` is not `---@contract`.
            if rest
                .chars()
                .next()
                .is_none_or(|c| !c.is_alphanumeric() && c != '_')
            {
                let mine = rest.split("---@").next().unwrap_or(rest);
                return Some(mine.trim().to_string());
            }
        }
    }
    None
}

/// `("dir", module = "X", dts = "path")` — every part optional, and the whole thing
/// optional. The first argument, if it is a bare string, is the directory.
fn parse_marker(rest: &str) -> Result<Marker, String> {
    let mut m = Marker {
        dir: None,
        module: None,
        exclude: None,
        dts: None,
    };
    if rest.is_empty() {
        return Ok(m);
    }
    let Some(args) = rest.strip_prefix('(').and_then(|r| r.split(')').next()) else {
        return Err(format!(
            "---@contract takes no arguments or a parenthesised list, got {rest:?}"
        ));
    };
    for (n, arg) in args.split(',').map(str::trim).enumerate() {
        if arg.is_empty() {
            continue;
        }
        match arg.split_once('=').map(|(k, v)| (k.trim(), v.trim())) {
            Some(("module", v)) => m.module = Some(unquote(v)?),
            // Space-separated inside one string: a Lua comment is not a place for a list
            // literal, and the names are module names, which have no spaces in them.
            Some(("exclude", v)) => {
                m.exclude = Some(unquote(v)?.split_whitespace().map(str::to_string).collect())
            }
            Some(("dts", v)) => m.dts = Some(unquote(v)?),
            Some((k, _)) => return Err(format!("---@contract has no {k:?} argument")),
            None if n == 0 => m.dir = Some(unquote(arg)?),
            None => return Err(format!("---@contract: {arg:?} is not <name> = <value>")),
        }
    }
    Ok(m)
}

fn unquote(v: &str) -> Result<String, String> {
    let t = v.trim();
    t.strip_prefix('"')
        .and_then(|t| t.strip_suffix('"'))
        .map(str::to_string)
        .ok_or_else(|| format!("---@contract: {v:?} is not a quoted string"))
}

/// The record declared on `line`, if it declares one.
fn record_name(line: &str) -> Option<String> {
    let after = line.split("record").nth(1)?;
    let name: String = after
        .trim_start()
        .chars()
        .take_while(|c| c.is_alphanumeric() || *c == '_')
        .collect();
    (!name.is_empty()).then_some(name)
}

fn indent_of(line: &str) -> usize {
    line.len() - line.trim_start().len()
}

/// `<module>.<Type>` for the record declared at `lines[i]`: the module, then every
/// record enclosing this one *except* the outermost, then the record itself. `None` when
/// the record is the outermost one — that is the module, and a contract type has to be a
/// type inside a module for `require("<module>")` to reach it.
fn type_path(lines: &[&str], i: usize, module: &str, record: &str) -> Option<String> {
    let mut names = vec![record.to_string()];
    let mut depth = indent_of(lines[i]);
    for line in lines[..i].iter().rev() {
        if line.trim().is_empty() {
            continue;
        }
        let d = indent_of(line);
        if d < depth
            && let Some(n) = record_name(line)
        {
            names.push(n);
            depth = d;
        }
    }
    // The outermost record is the module itself, whatever it is called.
    names.pop()?;
    if names.is_empty() {
        return None;
    }
    names.reverse();
    Some(format!("{module}.{}", names.join(".")))
}

/// Fields marked `---@required` in the record declared at `lines[i]`, in the order they
/// are declared. The record ends at the first `end` indented no deeper than it.
fn required_fields(lines: &[&str], i: usize) -> RequireFields {
    let base = indent_of(lines[i]);
    let mut names = Vec::new();
    for j in i + 1..lines.len() {
        let line = lines[j];
        if line.trim_start().starts_with("end") && indent_of(line) <= base {
            break;
        }
        let name: String = line
            .trim_start()
            .chars()
            .take_while(|c| c.is_alphanumeric() || *c == '_')
            .collect();
        if name.is_empty()
            || !line.trim_start()[name.len()..]
                .trim_start()
                .starts_with(':')
        {
            continue;
        }
        if marker_on(lines, j, "required").is_some() {
            names.push(name);
        }
    }
    RequireFields::Named(names)
}