htl-cli 0.19.0

htl command line (also `cargo htl`): check / run / test / fmt / build / pkg / new for Teal projects
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
//! The project-wide symbol index behind the workspace-symbol request ("Workspace symbols" in
//! the [`lsp`](super) module doc is the account of what is indexed and how it is kept
//! current; this is the structure that does it).
//!
//! One [`SymbolIndex`] per project, holding for each `.tl` the walk of `htl check` visits the
//! flat list of [`Sym`]s it declares and what it takes to tell whether they are still the
//! file's: its [`Stamp`] (modification time and length) and a hash of the text they were read
//! from. The index does no parsing and knows nothing of the checker: [`SymbolIndex::refresh`]
//! is handed the list of files and a function that makes a file's symbols from its text, so
//! the server decides where they come from (an open file's last check, else
//! [`Htl::declarations_of`](htl::Htl::declarations_of)).
//!
//! The reference index ("References" in the module doc) is kept in the same entries, so that
//! there is one list of files and one rule for when an entry is out of date: each [`Entry`]
//! may also hold the uses of its file ([`FileRefs`]), made by a references request and thrown
//! away when the entry is replaced, or when a file whose check it read changed
//! ([`SymbolIndex::moved`]), which a symbol alone never depends on.

use super::refs::{FileRefs, Place};
use super::{lines_of, position_at, read_lossy};
use htl::typeindex::{Decl, DeclKind};
use lsp_types::{Range, SymbolKind};
use std::collections::{BTreeMap, HashSet};
use std::hash::{DefaultHasher, Hash, Hasher};
use std::path::{Path, PathBuf};
use std::time::{Duration, SystemTime};

/// The most symbols one answer carries. The protocol has no paging for a workspace-symbol
/// request, so a project that has more matches than this gets the best ones: the order of
/// [`search`] puts the exact name matches first, so what is cut is the tail of the
/// substring matches, and a client that wants one of them narrows the query.
pub const MAX_RESULTS: usize = 1000;

/// One declaration, flattened out of a file's tree.
#[derive(Debug, Clone)]
pub struct Sym {
    /// The name as the file's outline shows it (`R.f` for a record function whose record
    /// is declared elsewhere).
    pub name: String,
    /// The name in lower case, without the `R.` of an `R.f`: what a query is matched with.
    pub lower: String,
    /// The whole name in lower case (`r.f`), matched too.
    pub full_lower: String,
    /// The name of the declaration this one is a child of: the record a field or a record
    /// function belongs to. `None` at the top of a file.
    pub container: Option<String>,
    pub kind: SymbolKind,
    /// The name, as LSP positions in the text the symbols were read from.
    pub range: Range,
    /// For a function whose definition and whose declaration in the record's body are one
    /// entry ([`Decl::body`]): the places (line, byte column) the checker names it by, the
    /// definition's and the body's. The uses of the function are of either, by where they
    /// are written, and are of one function.
    pub same: Option<[(usize, usize); 2]>,
    /// The declaration's extent as far as the index knows it (an unknown end is the end of
    /// its line), made to contain the name: where a call is *inside* a function.
    pub full: Range,
    /// Where the function's own code is ([`Decl::fn_body`]): what a call is inside of. `None`
    /// for a declaration with no code of its own, a variable that holds a function without
    /// a literal for it included (`local log = logger.make("x")`).
    pub body: Option<Range>,
    /// The declaration's type as Teal writes it, when the tree the symbols were read from
    /// had one (a parse alone knows none).
    pub detail: Option<String>,
    /// The places the checker names the declaration by, as (line, byte column) from 1: the
    /// declaration's first token (the `function` of a function, the `record`'s statement),
    /// and its name. For a function a record's body declares and the file does not define
    /// (`f: function(..)` alone), whose first token is its name, the first is where its type
    /// is written instead, which is where a use of it is declared. A use is declared at one of the two, or at the other place of a
    /// function a record's body also declares ([`same`](Self::same)): which one depends on
    /// what is declared (`htl::typeindex`, "Where it is declared"), so a lookup by place
    /// tries them all ([`find`]).
    pub at: [(usize, usize); 2],
}

impl Sym {
    /// Whether this is a function a call can be of: a function or a method.
    pub fn is_function(&self) -> bool {
        matches!(self.kind, SymbolKind::FUNCTION | SymbolKind::METHOD)
    }
}

/// The symbol that is declared at `place` (line, byte column), among those of one file:
/// the one whose name is there, else the one whose first token is, else the function whose
/// record's body wrote its type there. `None` for a declaration the tree does not hold (a
/// parameter, a local inside a function, which the tree does not enter).
pub fn find(syms: &[Sym], place: (usize, usize)) -> Option<usize> {
    let by = |f: &dyn Fn(&Sym) -> bool| syms.iter().position(f);
    by(&|s| s.at[1] == place)
        .or_else(|| by(&|s| s.at[0] == place))
        .or_else(|| by(&|s| s.same.is_some_and(|pair| pair.contains(&place))))
}

/// The LSP kind of a declaration. The same table as the outline's.
pub fn kind_of(kind: DeclKind) -> SymbolKind {
    match kind {
        DeclKind::Local => SymbolKind::VARIABLE,
        DeclKind::Function => SymbolKind::FUNCTION,
        DeclKind::Method => SymbolKind::METHOD,
        DeclKind::Field => SymbolKind::FIELD,
        DeclKind::Record => SymbolKind::STRUCT,
        DeclKind::Interface => SymbolKind::INTERFACE,
        DeclKind::Enum => SymbolKind::ENUM,
        DeclKind::Alias => SymbolKind::TYPE_PARAMETER,
    }
}

/// The declarations of a file as a flat list, children after their parent and each carrying
/// its parent's name. `text` is the text the tree was read from.
pub fn flatten(text: &str, decls: &[Decl]) -> Vec<Sym> {
    fn walk(lines: &[&str], decls: &[Decl], container: Option<&str>, out: &mut Vec<Sym>) {
        for d in decls {
            let start = position_at(lines, d.name_line, d.name_col);
            let end = position_at(
                lines,
                d.name_line,
                d.name_col.saturating_add(d.short_name().len()),
            );
            let start_decl = position_at(lines, d.line, d.col);
            let end_decl = position_at(lines, d.end_line, d.end_col.unwrap_or(usize::MAX));
            // A function the body declares and nothing defines starts at its name, and a use
            // of it is declared where its type is written after the `:`.
            let first = (d.line, d.col);
            let first = if matches!(d.kind, DeclKind::Function | DeclKind::Method)
                && container.is_some()
                && d.body.is_none()
                && first == (d.name_line, d.name_col)
            {
                type_after_name(lines, d).unwrap_or(first)
            } else {
                first
            };
            out.push(Sym {
                name: d.name.clone(),
                lower: d.short_name().to_lowercase(),
                full_lower: d.name.to_lowercase(),
                container: container.map(str::to_string),
                kind: kind_of(d.kind),
                range: Range::new(start, end),
                same: d.body.map(|b| [(d.line, d.col), b]),
                full: Range::new(start_decl.min(start), end_decl.max(end)),
                body: d.fn_body.map(|b| {
                    Range::new(
                        position_at(lines, b.line, b.col),
                        position_at(lines, b.end_line, b.end_col.unwrap_or(usize::MAX)),
                    )
                }),
                detail: d.detail.clone(),
                at: [first, (d.name_line, d.name_col)],
            });
            walk(lines, &d.children, Some(&d.name), out);
        }
    }
    /// Where the type of the field `d` is written: after its name and a `:` on the name's
    /// line (`htl::typeindex` finds a body-declared function's type the same way). `None`
    /// when the line has no `:` and a type after it there.
    fn type_after_name(lines: &[&str], d: &Decl) -> Option<(usize, usize)> {
        let row = lines.get(d.name_line.checked_sub(1)?)?;
        let rest = row.get(d.name_col.checked_sub(1)? + d.name.len()..)?;
        let rest = rest.trim_start().strip_prefix(':')?.trim_start();
        (!rest.is_empty()).then(|| (d.name_line, row.len() - rest.len() + 1))
    }
    let lines = lines_of(text);
    let mut out = Vec::new();
    walk(&lines, decls, None, &mut out);
    out
}

/// How well `query` (already lower case) matches a symbol: 0 for the name itself, 1 for a
/// name that starts with it, 2 for one that holds it, `None` for no match. An empty query
/// matches everything alike (2). The name is the short one (`f` of `R.f`), or the whole of
/// it (`R.f`), whichever matches better.
pub fn rank(query: &str, sym: &Sym) -> Option<u8> {
    if query.is_empty() {
        return Some(2);
    }
    [sym.lower.as_str(), sym.full_lower.as_str()]
        .into_iter()
        .filter_map(|n| {
            if n == query {
                Some(0)
            } else if n.starts_with(query) {
                Some(1)
            } else if n.contains(query) {
                Some(2)
            } else {
                None
            }
        })
        .min()
}

/// A symbol that matched, with where it is.
pub struct Hit<'a> {
    pub rank: u8,
    pub path: &'a Path,
    pub sym: &'a Sym,
}

/// The symbols of `files` that match `query` (case-insensitive substring), best first: exact
/// name, then prefix, then the rest; within a rank by path, then line, then column, so that
/// the same query on the same files is the same answer. At most [`MAX_RESULTS`]; the second
/// number is how many matched before the cut.
pub fn search<'a>(
    files: impl IntoIterator<Item = &'a Entry>,
    query: &str,
) -> (Vec<Hit<'a>>, usize) {
    let query = query.to_lowercase();
    let mut hits: Vec<Hit<'a>> = Vec::new();
    for e in files {
        for sym in &e.syms {
            if let Some(rank) = rank(&query, sym) {
                hits.push(Hit {
                    rank,
                    path: &e.path,
                    sym,
                });
            }
        }
    }
    let order = |h: &Hit<'a>| {
        (
            h.rank,
            h.path,
            h.sym.range.start.line,
            h.sym.range.start.character,
        )
    };
    let total = hits.len();
    // Only what is answered is put in order: an empty query matches every symbol.
    if total > MAX_RESULTS {
        hits.select_nth_unstable_by(MAX_RESULTS, |a, b| order(a).cmp(&order(b)));
        hits.truncate(MAX_RESULTS);
    }
    hits.sort_by(|a, b| order(a).cmp(&order(b)));
    (hits, total)
}

/// What the file system says of a file, cheaply: when it was last written and how long it
/// is. Two files with the same stamp are taken to hold the same text, except when the write
/// was too recent to tell (see [`Entry::settled`]).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Stamp {
    mtime: Option<SystemTime>,
    len: u64,
}

impl Stamp {
    /// `None` when the file is not there.
    pub fn of(path: &Path) -> Option<Self> {
        let m = std::fs::metadata(path).ok()?;
        Some(Self {
            mtime: m.modified().ok(),
            len: m.len(),
        })
    }

    /// Whether a text read now, under this stamp, will be told apart from a later write by
    /// the stamp alone. The file system's clock has a granularity (and a write and a read
    /// can fall in one tick of it), so a file written within the last two seconds could be
    /// written again with the same length and the same stamp. Git's index has the same
    /// problem ("racily clean" entries) and the same answer: such an entry is not trusted
    /// by its stamp, and the next refresh reads it and compares the text.
    fn settled(&self) -> bool {
        self.mtime
            .is_some_and(|t| t + Duration::from_secs(2) <= SystemTime::now())
    }
}

/// A hash of the text the symbols of an entry were read from.
pub fn hash_of(text: &str) -> u64 {
    let mut h = DefaultHasher::new();
    text.hash(&mut h);
    h.finish()
}

/// One file of the index.
#[derive(Debug, Clone)]
pub struct Entry {
    /// The file as the walk spelled it, which is how its URI is made.
    pub path: PathBuf,
    stamp: Stamp,
    /// A hash of the text `syms` were read from.
    hash: u64,
    /// Whether `stamp` alone is a reason to believe the file is unchanged ([`Stamp::settled`],
    /// worked out when the entry was made).
    settled: bool,
    /// Empty for a file that does not parse, and for one that declares nothing.
    pub syms: Vec<Sym>,
    /// The uses in the text `syms` were read from, once something made them (a reference
    /// request); `None` before, and after anything they depend on changed.
    pub refs: Option<FileRefs>,
    /// Set when `refs` was thrown away because a file the file's check read changed, and
    /// cleared by a check or a new entry: the last check of the file, if it is open, then
    /// describes a file that is no longer there, and is not to be used for the uses.
    distrust: bool,
    /// The files the check that made `refs` read, when one did: what [`SymbolIndex::moved`]
    /// compares a change with. `None` for an entry nothing has checked, and for one whose
    /// check failed: any change is then one it may depend on.
    deps: Option<HashSet<PathBuf>>,
}

impl Entry {
    /// An entry for `path` whose symbols were read from `text`, the text the stamp was taken
    /// of (a stamp taken *before* the text was read, so that a write between the two leaves
    /// the entry out of date and not wrongly current).
    pub fn new(path: PathBuf, stamp: Stamp, text: &str, syms: Vec<Sym>) -> Self {
        Self {
            path,
            stamp,
            hash: hash_of(text),
            settled: stamp.settled(),
            syms,
            refs: None,
            distrust: false,
            deps: None,
        }
    }
}

/// The symbols of one project's files, by canonical path (so a file is one entry however it
/// is spelled, and the order is the same every time).
#[derive(Debug)]
pub struct SymbolIndex {
    files: BTreeMap<PathBuf, Entry>,
    /// Files a watcher said changed since the last refresh.
    dirty: HashSet<PathBuf>,
    /// Set when the list of files may have changed: the first time, and when a watcher names
    /// a `.tl` the index does not hold (a file made, or one the walk does not visit).
    relist: bool,
    /// Whether the uses have been asked for before: the first time, an open file's last
    /// check may predate a change to a file the index never saw, so none is trusted
    /// ([`first_refs`](Self::first_refs)).
    refs_built: bool,
    /// A fingerprint of the files outside the walk that the checker resolves names against
    /// (`types/` declarations, the Rust `htl dts` reads), taken by a client that does not
    /// watch; a change to it takes the uses ([`inputs_changed`](Self::inputs_changed)).
    inputs: Option<u64>,
}

impl Default for SymbolIndex {
    /// An index of nothing yet, due for its first walk.
    fn default() -> Self {
        Self {
            files: BTreeMap::new(),
            dirty: HashSet::new(),
            relist: true,
            refs_built: false,
            inputs: None,
        }
    }
}

impl SymbolIndex {
    pub fn entries(&self) -> impl Iterator<Item = &Entry> {
        self.files.values()
    }

    /// Make the next refresh walk the project again: something the watchers did not name
    /// changed (a file of the index is gone, and the directory it was in may have moved).
    pub fn relist(&mut self) {
        self.relist = true;
    }

    /// A watcher says `canonical` was made, changed or deleted. Nothing is read now: a file
    /// the index holds is looked at again at the next refresh (and dropped if it is gone), and
    /// one it does not hold makes the next refresh walk the project again.
    pub fn event(&mut self, canonical: &Path) {
        if self.files.contains_key(canonical) {
            self.dirty.insert(canonical.to_path_buf());
        } else {
            self.relist = true;
        }
    }

    /// Put `entry` in for `canonical`, if the index holds that file: a file just checked,
    /// whose symbols are fresher than anything read from the disk (they carry the kinds
    /// types decide) and need not be read again. `deps` is what that check read through
    /// `require`.
    ///
    /// The uses of the file survive a check that read the same text; a check that read
    /// another is a change like any other ([`moved`](Self::moved)), and takes the uses of
    /// the files that depend on this one with it.
    pub fn put(&mut self, canonical: &Path, mut entry: Entry, deps: HashSet<PathBuf>) {
        let Some(slot) = self.files.get_mut(canonical) else {
            return;
        };
        // Spelled as the walk spelled it, whatever the client called the file.
        entry.path = slot.path.clone();
        let changed = slot.hash != entry.hash;
        if !changed {
            entry.refs = slot.refs.take();
        }
        entry.deps = Some(deps);
        *slot = entry;
        self.dirty.remove(canonical);
        if changed {
            self.moved(&[canonical.to_path_buf()], false);
        }
    }

    /// The files whose text changed, or (`structural`) the list of files did: whatever was
    /// worked out from them is no longer so. The uses of a file say where a name declared in
    /// another file is, so a change to a file takes the uses of every file whose check read
    /// it (and those of a file nothing is known about); one of the files of the project
    /// appearing or going can change what a `require` finds anywhere, and takes all of them.
    ///
    /// What is thrown away is marked: the last check of an open file, which the uses were
    /// to be made from, describes the files as they were.
    fn moved(&mut self, changed: &[PathBuf], structural: bool) {
        if changed.is_empty() && !structural {
            return;
        }
        for (path, e) in &mut self.files {
            let hit = structural
                || (!changed.contains(path)
                    && e.deps
                        .as_ref()
                        .is_none_or(|d| changed.iter().any(|c| d.contains(c))));
            if hit {
                e.refs = None;
                e.distrust = true;
            }
        }
    }

    /// Whether this is the first time the uses are asked for, and if so, mark every file's
    /// last check as not to be trusted (as after [`forget_refs`](Self::forget_refs)): a
    /// check made before the index existed may have read a file that changed since, and the
    /// index was not there to see it.
    pub fn first_refs(&mut self) -> bool {
        if self.refs_built {
            return false;
        }
        self.refs_built = true;
        self.moved(&[], true);
        true
    }

    /// Whether the index holds `canonical`: the walk visits it.
    pub fn holds(&self, canonical: &Path) -> bool {
        self.files.contains_key(canonical)
    }

    /// Take `fingerprint` as the state of the files outside the walk the checker reads, and
    /// say whether it differs from the one before (the first is not a change).
    pub fn inputs_changed(&mut self, fingerprint: u64) -> bool {
        self.inputs
            .replace(fingerprint)
            .is_some_and(|was| was != fingerprint)
    }

    /// Throw away every file's uses: the declarations a check resolves against changed
    /// without a file of the project changing (a `types/` declaration, a Rust source).
    pub fn forget_refs(&mut self) {
        self.moved(&[], true);
    }

    /// Whether the index holds `canonical` and has thrown its uses away because a file its
    /// check read changed ([`Entry`]): the last check of it, if there is one, is out of date.
    pub fn distrusts(&self, canonical: &Path) -> bool {
        self.files.get(canonical).is_some_and(|e| e.distrust)
    }

    /// The files whose uses are not known, and what making them needs to know.
    pub fn pending(&self) -> Vec<Pending> {
        self.files
            .iter()
            .filter(|(_, e)| e.refs.is_none())
            .map(|(canonical, e)| Pending {
                canonical: canonical.clone(),
                path: e.path.clone(),
                distrust: e.distrust,
            })
            .collect()
    }

    /// Keep `refs` as the uses of `canonical`, if the entry still holds the text with hash
    /// `hash`, the text they were made from.
    pub fn fill(&mut self, canonical: &Path, hash: u64, refs: FileRefs) {
        if let Some(e) = self.files.get_mut(canonical)
            && e.hash == hash
        {
            e.deps = refs.deps.clone();
            e.refs = Some(refs);
            e.distrust = false;
        }
    }

    /// The entry of the file with this canonical path.
    pub fn entry(&self, canonical: &Path) -> Option<&Entry> {
        self.files.get(canonical)
    }

    /// Every file, with its canonical path.
    pub fn iter(&self) -> impl Iterator<Item = (&PathBuf, &Entry)> {
        self.files.iter()
    }

    /// The places a use of `target` may name: itself, and for a function written in the
    /// record's body and defined below ([`Sym::same`]) the other of its two places.
    pub fn same_as(&self, target: &Place) -> Vec<Place> {
        let mut places = vec![target.clone()];
        let Some(e) = self.files.get(&*target.file) else {
            return places;
        };
        for pair in e.syms.iter().filter_map(|s| s.same.as_ref()) {
            if pair.contains(&(target.line, target.col)) {
                for &(line, col) in pair {
                    let p = Place {
                        file: target.file.clone(),
                        line,
                        col,
                    };
                    if !places.contains(&p) {
                        places.push(p);
                    }
                }
            }
        }
        places
    }

    /// Bring the index up to date.
    ///
    /// `sweep` is for a client that does not say when files change: the project is walked
    /// again (`list`) and every file is stamped, whether or not anything was said. Without
    /// it only what the watchers named is looked at, and the walk happens when they named a
    /// file the index does not hold. A file is read again only if its stamp moved, or it is
    /// not [settled](Stamp::settled), and its symbols are made again only if the text it
    /// holds is not the text they were made from.
    ///
    /// `build(canonical, path, text)` is the symbols of a file whose text is `text`. An error
    /// is the walk's (`list`), and leaves the index as it was.
    pub fn refresh(
        &mut self,
        sweep: bool,
        list: impl FnOnce() -> anyhow::Result<Vec<PathBuf>>,
        build: &mut dyn FnMut(&Path, &Path, &str) -> Vec<Sym>,
    ) -> anyhow::Result<()> {
        // What changed under the index's feet, for the uses that depend on it.
        let mut changed: Vec<PathBuf> = Vec::new();
        let mut structural = false;
        if sweep || self.relist {
            // A walk that fails leaves the index as it was, and still due for one.
            let listed = list()?;
            let first = self.files.is_empty();
            let mut kept = BTreeMap::new();
            for path in listed {
                let canonical = super::canonical(&path);
                let old = self.files.remove(&canonical);
                let had = old.as_ref().map(|e| e.hash);
                let force = self.dirty.contains(&canonical);
                match revalidate(old, &canonical, path, force, build) {
                    Some(e) => {
                        match had {
                            Some(h) if h != e.hash => changed.push(canonical.clone()),
                            None if !first => structural = true,
                            _ => {}
                        }
                        kept.insert(canonical, e);
                    }
                    None => structural = true,
                }
            }
            // A file of the index that the walk did not list is gone from the project.
            structural |= !self.files.is_empty();
            self.files = kept;
        } else {
            for canonical in std::mem::take(&mut self.dirty) {
                if let Some(old) = self.files.remove(&canonical) {
                    let (path, had) = (old.path.clone(), old.hash);
                    match revalidate(Some(old), &canonical, path, true, build) {
                        Some(e) => {
                            if e.hash != had {
                                changed.push(canonical.clone());
                            }
                            self.files.insert(canonical, e);
                        }
                        None => structural = true,
                    }
                }
            }
        }
        self.moved(&changed, structural);
        self.dirty.clear();
        self.relist = false;
        Ok(())
    }
}

/// A file of the index that has no uses yet ([`SymbolIndex::pending`]).
pub struct Pending {
    pub canonical: PathBuf,
    pub path: PathBuf,
    /// See [`Entry`]: its last check is not to be trusted.
    pub distrust: bool,
}

/// `old`, if it still describes the file; else a new entry; `None` if the file is gone.
fn revalidate(
    old: Option<Entry>,
    canonical: &Path,
    path: PathBuf,
    force: bool,
    build: &mut dyn FnMut(&Path, &Path, &str) -> Vec<Sym>,
) -> Option<Entry> {
    // The stamp before the text: a write between the two leaves the stamp older than the
    // text, and the next refresh sees it move.
    let stamp = Stamp::of(&path)?;
    if let Some(e) = &old
        && !force
        && e.stamp == stamp
        && e.settled
    {
        return old;
    }
    let text = read_lossy(&path);
    if let Some(mut e) = old
        && e.hash == hash_of(&text)
    {
        e.stamp = stamp;
        e.settled = stamp.settled();
        return Some(e);
    }
    let syms = build(canonical, &path, &text);
    Some(Entry::new(path, stamp, &text, syms))
}