@akanjs/devkit 2.4.1-rc.6 → 2.4.1

package/frontendBuild/clientEntryDiscovery.ts

@@ -14,6 +14,16 @@ const AKANJS_NODE_MODULE_RE = /[\\/]node_modules[\\/]akanjs[\\/]/;
 const NON_SOURCE_EXT_RE = /\.(css|scss|sass|less|json|svg|png|jpe?g|webp|gif|avif|ico|woff2?|ttf|otf|mp3|mp4|wav)$/i;
 type PackageResolver = Awaited<ReturnType<typeof createTsconfigPackageResolver>>;
 
+/**
+ * Everything the traversal ever asks of a file, which is why its text is not kept.
+ *
+ * `imports` is empty for a client entry: the walk stops there, so they are never scanned.
+ */
+interface FileFacts {
+  isClientEntry: boolean;
+  imports: ScannedImport[];
+}
+
 const shouldSkipNodeModule = (absPath: string) => NODE_MODULES_RE.test(absPath) && !AKANJS_NODE_MODULE_RE.test(absPath);
 
 /**
@@ -29,12 +39,23 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
   #analyzer: BarrelAnalyzer;
   #tsTranspiler = new Bun.Transpiler({ loader: "tsx" });
   #fileExistsCache = new Map<string, Promise<boolean>>();
-  #readCache = new Map<string, Promise<string | null>>();
-  #rewriteCache = new Map<string, Promise<string>>();
-  #importCache = new Map<string, Promise<ScannedImport[]>>();
+  /**
+   * Derived facts per file, never the source text.
+   *
+   * This instance lives as long as the builder process does — it is rebuilt only when the akan config
+   * changes — so caching whole source texts (and a second, barrel-rewritten copy of each) meant the
+   * watcher held every source file it had ever walked for the whole dev session. Nothing downstream
+   * wanted the text: the walk needs one boolean and one import list per file, and both were already
+   * cached separately under the same key.
+   */
+  #factsCache = new Map<string, Promise<FileFacts | null>>();
   #resolvedFileCache = new Map<string, Promise<string | null>>();
   #resolvedSpecifierCache = new Map<string, Promise<string | null>>();
   #reachableEntriesCache = new Map<string, Set<string>>();
+  /** Keys of the three caches above whose answer was "not there" — see `#forgetMissing`. */
+  #missingFiles = new Set<string>();
+  #unresolvedPaths = new Set<string>();
+  #unresolvedSpecifiers = new Set<string>();
 
   constructor(akanConfig: AkanConfig, resolvePackage: PackageResolver) {
     this.#akanConfig = akanConfig;
@@ -57,38 +78,88 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
   invalidate(files: string[]): void {
     for (const file of files) {
       const absPath = path.resolve(file);
-      this.#readCache.delete(absPath);
-      this.#rewriteCache.delete(absPath);
-      this.#importCache.delete(absPath);
+      this.#factsCache.delete(absPath);
+      this.#fileExistsCache.delete(absPath);
       this.#reachableEntriesCache.delete(absPath);
     }
+    if (files.length === 0) return;
     // Parent files cache the transitive result of their imports, so a changed
     // child can affect any reachable-entry cache above it.
-    if (files.length > 0) this.#reachableEntriesCache.clear();
+    this.#reachableEntriesCache.clear();
+    this.#forgetMissing();
+  }
+
+  /**
+   * Drop every "there is no such file" answer, because a batch may be what created it.
+   *
+   * These caches are keyed by extension-less path and by `dir\0specifier`, neither of which maps back
+   * to the path that just appeared, so a negative recorded before a module existed is unreachable any
+   * other way — and this instance lives as long as the builder process. Positive answers are kept:
+   * they are keyed by a real path, which arrives in `files` when it changes or goes away.
+   */
+  #forgetMissing(): void {
+    for (const key of this.#missingFiles) this.#fileExistsCache.delete(key);
+    for (const key of this.#unresolvedPaths) this.#resolvedFileCache.delete(key);
+    for (const key of this.#unresolvedSpecifiers) this.#resolvedSpecifierCache.delete(key);
+    this.#missingFiles.clear();
+    this.#unresolvedPaths.clear();
+    this.#unresolvedSpecifiers.clear();
   }
 
   async #fileExists(p: string): Promise<boolean> {
     const absPath = path.resolve(p);
     let cached = this.#fileExistsCache.get(absPath);
     if (!cached) {
-      cached = Bun.file(absPath).exists();
+      cached = Bun.file(absPath)
+        .exists()
+        .then((exists) => {
+          if (!exists) this.#missingFiles.add(absPath);
+          return exists;
+        });
       this.#fileExistsCache.set(absPath, cached);
     }
     return cached;
   }
 
-  #readFile(file: string): Promise<string | null> {
+  /**
+   * Read a file once and keep only what the traversal asks of it. The text itself is dropped as soon
+   * as the boolean and the import list are out of it — see `#factsCache`.
+   */
+  #facts(file: string): Promise<FileFacts | null> {
     const absPath = path.resolve(file);
-    let cached = this.#readCache.get(absPath);
+    let cached = this.#factsCache.get(absPath);
     if (!cached) {
-      cached = Bun.file(absPath)
-        .text()
-        .catch(() => null);
-      this.#readCache.set(absPath, cached);
+      cached = (async () => {
+        const content = await Bun.file(absPath)
+          .text()
+          .catch(() => null);
+        if (content === null) return null;
+        // A client entry ends the walk, so its imports are never needed.
+        if (USE_CLIENT_RE.test(content)) return { isClientEntry: true, imports: [] };
+        return { isClientEntry: false, imports: this.#scanImports(await this.#rewrite(content)) };
+      })();
+      this.#factsCache.set(absPath, cached);
     }
     return cached;
   }
 
+  async #rewrite(content: string): Promise<string> {
+    if (this.#akanConfig.barrelImports.length === 0) return content;
+    try {
+      return (await rewriteBarrelImports(content, this.#akanConfig.barrelImports, this.#analyzer)) ?? content;
+    } catch {
+      return content;
+    }
+  }
+
+  #scanImports(source: string): ScannedImport[] {
+    try {
+      return this.#tsTranspiler.scanImports(source);
+    } catch {
+      return [];
+    }
+  }
+
   async #resolveFileCandidate(absPathNoExt: string): Promise<string | null> {
     const cacheKey = path.resolve(absPathNoExt);
     let cached = this.#resolvedFileCache.get(cacheKey);
@@ -103,6 +174,7 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
         const f = path.join(cacheKey, `index${ext}`);
         if (await this.#fileExists(f)) return f;
       }
+      this.#unresolvedPaths.add(cacheKey);
       return null;
     })();
     this.#resolvedFileCache.set(cacheKey, cached);
@@ -120,45 +192,13 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
       }
       const pkg = await this.#resolvePackage(spec);
       if (pkg) return pkg.entryFile;
+      this.#unresolvedSpecifiers.add(cacheKey);
       return null;
     })();
     this.#resolvedSpecifierCache.set(cacheKey, cached);
     return cached;
   }
 
-  async #getRewrittenSource(file: string, content: string): Promise<string> {
-    const absPath = path.resolve(file);
-    let cached = this.#rewriteCache.get(absPath);
-    if (!cached) {
-      cached = (async () => {
-        if (this.#akanConfig.barrelImports.length === 0) return content;
-        try {
-          return (await rewriteBarrelImports(content, this.#akanConfig.barrelImports, this.#analyzer)) ?? content;
-        } catch {
-          return content;
-        }
-      })();
-      this.#rewriteCache.set(absPath, cached);
-    }
-    return cached;
-  }
-
-  async #getImports(file: string, source: string): Promise<ScannedImport[]> {
-    const absPath = path.resolve(file);
-    let cached = this.#importCache.get(absPath);
-    if (!cached) {
-      cached = Promise.resolve().then(() => {
-        try {
-          return this.#tsTranspiler.scanImports(source);
-        } catch {
-          return [];
-        }
-      });
-      this.#importCache.set(absPath, cached);
-    }
-    return cached;
-  }
-
   async #discoverFromFile(file: string, visiting: Set<string>): Promise<Set<string>> {
     const absPath = path.resolve(file);
     const cached = this.#reachableEntriesCache.get(absPath);
@@ -167,18 +207,16 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
 
     visiting.add(absPath);
     const entries = new Set<string>();
-    const content = await this.#readFile(absPath);
-    if (content === null) return this.#finishDiscovery(absPath, visiting, entries);
+    const facts = await this.#facts(absPath);
+    if (!facts) return this.#finishDiscovery(absPath, visiting, entries);
 
-    if (USE_CLIENT_RE.test(content)) {
+    if (facts.isClientEntry) {
       entries.add(absPath);
       return this.#finishDiscovery(absPath, visiting, entries);
     }
 
-    const source = await this.#getRewrittenSource(absPath, content);
-    const imports = await this.#getImports(absPath, source);
     const importerDir = path.dirname(absPath);
-    for (const imp of imports) {
+    for (const imp of facts.imports) {
       const spec = imp.path;
       if (!spec) continue;
       if (NON_SOURCE_EXT_RE.test(spec)) continue;

package/frontendBuild/cssCandidateCache.ts

@@ -0,0 +1,109 @@
+import { stat } from "node:fs/promises";
+
+/** Every identifier-ish token in a source file is a potential tailwind class. */
+const CANDIDATE_RE = /-?[\w@][\w:/.-]*(?:\[[^\]]+\][\w:/.-]*)*/g;
+
+interface CachedFile {
+  mtimeMs: number;
+  size: number;
+  candidates: string[];
+}
+
+interface CacheFile {
+  version: number;
+  files: Record<string, CachedFile>;
+}
+
+/**
+ * Tailwind candidate tokens per source file, cached on disk across builds.
+ *
+ * The scan reads the **full text** of every source file on every CSS rebuild — measured at 385-508ms
+ * per save on `apps/akan`. Phase 2 moved css compilation into a per-generation batch worker, so an
+ * in-memory cache (what `03-phase3-topology-and-trim.md` §3.4 originally proposed) buys nothing: the
+ * process that would hold it exits before the next save. Disk is what survives the worker, a builder
+ * recycle and a dev-host restart alike, which is the same reasoning §3.3 used for the font cache.
+ *
+ * Keyed on (mtime, size) per file, so a save re-reads only the files in that batch.
+ */
+export class CssCandidateCache {
+  /** Bump when the token regex or the entry shape changes, so stale extractions are not reused. */
+  static readonly #version = 1;
+  readonly #path: string;
+  readonly #entries = new Map<string, CachedFile>();
+  #dirty = false;
+  #reused = 0;
+  #rescanned = 0;
+
+  constructor(cachePath: string) {
+    this.#path = cachePath;
+  }
+
+  get reused(): number {
+    return this.#reused;
+  }
+
+  get rescanned(): number {
+    return this.#rescanned;
+  }
+
+  /** A cache that cannot be read or is a version behind simply starts empty — it is only an optimisation. */
+  async load(): Promise<this> {
+    const raw = (await Bun.file(this.#path)
+      .json()
+      .catch(() => null)) as CacheFile | null;
+    if (!raw || raw.version !== CssCandidateCache.#version || typeof raw.files !== "object") return this;
+    for (const [file, entry] of Object.entries(raw.files)) {
+      if (typeof entry?.mtimeMs !== "number" || !Array.isArray(entry.candidates)) continue;
+      this.#entries.set(file, entry);
+    }
+    return this;
+  }
+
+  /**
+   * The file's candidate tokens, read from disk only when its (mtime, size) no longer matches.
+   *
+   * Read errors propagate, as they did before this cache existed: a source file the compiler cannot
+   * read is a broken build, not a cache miss to paper over.
+   */
+  async candidatesFor(file: string): Promise<string[]> {
+    const stats = await stat(file).catch(() => null);
+    const cached = this.#entries.get(file);
+    if (stats && cached && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size) {
+      this.#reused += 1;
+      return cached.candidates;
+    }
+    const content = await Bun.file(file).text();
+    const candidates = [...new Set(Array.from(content.matchAll(CANDIDATE_RE), (m) => m[0]))];
+    this.#rescanned += 1;
+    if (stats) {
+      this.#entries.set(file, { mtimeMs: stats.mtimeMs, size: stats.size, candidates });
+      this.#dirty = true;
+    }
+    return candidates;
+  }
+
+  /**
+   * Persist, dropping files the scan no longer reaches so a renamed or deleted module does not keep
+   * feeding its classes to the compiler forever.
+   *
+   * A rebuild that re-read nothing writes nothing: the boot double-build and any CSS rebuild triggered
+   * by something other than a source edit would otherwise rewrite the whole file for no change.
+   */
+  async save(present: Set<string>): Promise<void> {
+    for (const file of [...this.#entries.keys()]) {
+      if (present.has(file)) continue;
+      this.#entries.delete(file);
+      this.#dirty = true;
+    }
+    if (!this.#dirty) return;
+    this.#dirty = false;
+    const files: Record<string, CachedFile> = {};
+    for (const [file, entry] of this.#entries) files[file] = entry;
+    // A cache that cannot be written is a slow build, not a failed one — a read-only checkout must
+    // still compile.
+    await Bun.write(
+      this.#path,
+      JSON.stringify({ version: CssCandidateCache.#version, files } satisfies CacheFile),
+    ).catch(() => undefined);
+  }
+}

package/frontendBuild/cssCompiler.ts

@@ -4,6 +4,7 @@ import { compile } from "tailwindcss";
 import type { App } from "../commandDecorators";
 import { BarrelAnalyzer } from "../transforms/barrelAnalyzer";
 import { createTsconfigPackageResolver, rewriteBarrelImports } from "../transforms/barrelImportsPlugin";
+import { CssCandidateCache } from "./cssCandidateCache";
 import { CssImportResolver } from "./cssImportResolver";
 
 const SOURCE_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"] as const;
@@ -25,8 +26,54 @@ export class CssCompiler {
     this.#app = app;
   }
 
+  /**
+   * Beside the sources rather than in `dist`, because the cache is keyed on source mtimes: a build and
+   * the dev server describe the same files, so they should share it rather than each pay the first scan.
+   */
+  get #candidateCachePath() {
+    return path.join(this.#app.cwdPath, ".akan/cache/cssCandidates.json");
+  }
+
   #cssText: string | null = null;
   #cssTextByBasePath: Record<string, string> | null = null;
+  /**
+   * Import resolution memoised for the life of one compiler, which is one rebuild.
+   *
+   * The discovery BFS resolves the same specifier from every directory that imports it, and each miss
+   * costs up to 13 sequential `exists()` calls — the bare path, six extensions, six `index.*`. Nothing
+   * here outlives the rebuild, so there is no invalidation to get wrong.
+   */
+  #fileExistsCache = new Map<string, Promise<boolean>>();
+  #resolvedFileCache = new Map<string, Promise<string | null>>();
+  #resolvedSpecifierCache = new Map<string, Promise<string | null>>();
+
+  #fileExists(absPath: string): Promise<boolean> {
+    let cached = this.#fileExistsCache.get(absPath);
+    if (!cached) {
+      cached = Bun.file(absPath).exists();
+      this.#fileExistsCache.set(absPath, cached);
+    }
+    return cached;
+  }
+
+  #resolveSourceFileCandidate(absPathNoExt: string): Promise<string | null> {
+    let cached = this.#resolvedFileCache.get(absPathNoExt);
+    if (cached) return cached;
+    cached = (async () => {
+      if (await this.#fileExists(absPathNoExt)) return isSourceFile(absPathNoExt) ? absPathNoExt : null;
+      for (const ext of SOURCE_EXTS) {
+        const filePath = `${absPathNoExt}${ext}`;
+        if (await this.#fileExists(filePath)) return filePath;
+      }
+      for (const ext of SOURCE_EXTS) {
+        const filePath = path.join(absPathNoExt, `index${ext}`);
+        if (await this.#fileExists(filePath)) return filePath;
+      }
+      return null;
+    })();
+    this.#resolvedFileCache.set(absPathNoExt, cached);
+    return cached;
+  }
   async getCss({ refresh }: { refresh?: boolean } = {}) {
     if (this.#cssText !== null && !refresh) return this.#cssText;
     const { cssPaths, sourcePaths } = await this.discoverCssAndSources({ refresh });
@@ -197,14 +244,31 @@ export class CssCompiler {
     const mod = await import(p);
     return { path: p, base: path.dirname(p), module: mod.default ?? mod };
   }
-  async #resolveSourceImport(
+  #resolveSourceImport(
+    id: string,
+    fromBase: string,
+    resolvePackage: Awaited<ReturnType<typeof createTsconfigPackageResolver>>,
+  ): Promise<string | null> {
+    // Keyed by importer directory even for bare specifiers: the tsconfig resolver is
+    // directory-independent, but the `Bun.resolveSync` / `require.resolve` fallbacks below are not.
+    // The expensive part — the `exists()` probes — is deduplicated by absolute path instead, which is
+    // shared across every importer.
+    const cacheKey = `${fromBase}\0${id}`;
+    let cached = this.#resolvedSpecifierCache.get(cacheKey);
+    if (cached) return cached;
+    cached = this.#resolveSourceImportUncached(id, fromBase, resolvePackage);
+    this.#resolvedSpecifierCache.set(cacheKey, cached);
+    return cached;
+  }
+
+  async #resolveSourceImportUncached(
     id: string,
     fromBase: string,
     resolvePackage: Awaited<ReturnType<typeof createTsconfigPackageResolver>>,
   ): Promise<string | null> {
     if (id.startsWith(".") || id.startsWith("/")) {
       const abs = id.startsWith("/") ? id : path.resolve(fromBase, id);
-      return resolveSourceFileCandidate(abs);
+      return this.#resolveSourceFileCandidate(abs);
     }
 
     const pkg = await resolvePackage(id);
@@ -217,7 +281,6 @@ export class CssCompiler {
     return null;
   }
   async #scanCandidates(sourcePaths: string[], dirs: string[]): Promise<string[]> {
-    const CANDIDATE_RE = /-?[\w@][\w:/.-]*(?:\[[^\]]+\][\w:/.-]*)*/g;
     const candidates = new Set<string>();
     const glob = new Bun.Glob("**/*.{tsx,ts,jsx,js,html}");
     const files = new Set<string>(sourcePaths);
@@ -229,29 +292,18 @@ export class CssCompiler {
         }
       }),
     );
+    const cache = await new CssCandidateCache(this.#candidateCachePath).load();
     await Promise.all(
       [...files].map(async (file) => {
-        const content = await Bun.file(file).text();
-        for (const m of content.matchAll(CANDIDATE_RE)) candidates.add(m[0]);
+        for (const candidate of await cache.candidatesFor(file)) candidates.add(candidate);
       }),
     );
+    await cache.save(files);
+    this.#logger.verbose(`css candidate cache reused=${cache.reused} rescanned=${cache.rescanned}`);
     return [...candidates];
   }
 }
 
-async function resolveSourceFileCandidate(absPathNoExt: string): Promise<string | null> {
-  if (await Bun.file(absPathNoExt).exists()) return isSourceFile(absPathNoExt) ? absPathNoExt : null;
-  for (const ext of SOURCE_EXTS) {
-    const filePath = `${absPathNoExt}${ext}`;
-    if (await Bun.file(filePath).exists()) return filePath;
-  }
-  for (const ext of SOURCE_EXTS) {
-    const filePath = path.join(absPathNoExt, `index${ext}`);
-    if (await Bun.file(filePath).exists()) return filePath;
-  }
-  return null;
-}
-
 function resolveSourceWithBun(id: string, fromBase: string): string | null {
   try {
     const resolved = Bun.resolveSync(id, fromBase);

package/frontendBuild/frontendBuild.test.ts

@@ -417,6 +417,9 @@ describe("CssCompiler", () => {
 
     const compiler = new CssCompiler({
       workspace: { workspaceRoot: root },
+      // The candidate cache lands under `<cwdPath>/.akan/cache`, so point it at this test's temp root
+      // rather than wherever the suite happens to run from.
+      cwdPath: root,
       getTsConfig: async () => ({ compilerOptions: { paths: {} } }),
     } as never);
     const css = await compiler.compileCss([cssPath], []);

package/frontendBuild/hmrWatcher.ts

@@ -264,10 +264,16 @@ export class HmrWatcher {
    * Terminates rather than looping: a scan that finds nothing schedules nothing, and the build writes its
    * artifacts under `.akan/` — which the classifier ignores — while codegen writes are content-guarded,
    * so a rebuild does not move a tracked mtime.
+   *
+   * The one case that does schedule another is a directory the index could not date reliably (Linux stamps
+   * directory mtimes on a 1ms clock, see `SourceMtimeIndex`). That still terminates: the next scan is
+   * `verifyDelayMs` later, by which point the timestamp has settled unless something is writing to that
+   * directory right now — in which case looking again is the right answer anyway.
    */
   async #verify(): Promise<void> {
     if (this.#stopped || this.#flushing) return;
     await this.#mergeDetectedChanges();
     if (this.#pending.size > 0) await this.#drain();
+    else if (this.#index.hasUnsettledDirs) this.#scheduleVerify();
   }
 }

package/frontendBuild/sourceMtimeIndex.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { chmod, mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import { chmod, mkdir, mkdtemp, readdir, rm, stat, utimes, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { SourceMtimeIndex } from "./sourceMtimeIndex";
@@ -100,6 +100,51 @@ describe("SourceMtimeIndex", () => {
     expect(await index.collectChanges()).toEqual([]);
   });
 
+  /**
+   * Linux stamps directory mtimes from a coarse clock, so a mutation landing in the same tick as the
+   * value the index recorded leaves that value byte-identical: measured under Docker, 319 of 400
+   * back-to-back `mkdir`s never moved the parent's mtime on overlayfs and 324 of 400 on ext4, while APFS
+   * missed none. `utimes` reproduces that here rather than leaving it to the host's clock resolution —
+   * otherwise this passes on macOS for the wrong reason and is flaky on the Linux fleet.
+   *
+   * `dirSettleMs` is pinned wide so the assertion is about the mechanism, not about how many milliseconds
+   * the lines above happened to take.
+   */
+  test("finds a created directory even when the clock never moves the parent's mtime", async () => {
+    const root = await makeRoot();
+    await seed(root, "lib/a.ts");
+    const dir = path.join(root, "lib");
+    // Pinned before priming too: `utimes` keeps whole milliseconds but drops APFS's sub-millisecond part,
+    // so stamping both sides is what makes "the mtime did not move" exact rather than 0.5ms apart.
+    const frozen = new Date();
+    await utimes(dir, frozen, frozen);
+    const index = new SourceMtimeIndex({ roots: [root], dirSettleMs: 60_000 });
+    await index.prime();
+
+    const created = await seed(root, "lib/user/user.constant.ts");
+    await utimes(dir, frozen, frozen);
+    expect((await stat(dir)).mtimeMs).toBe(frozen.getTime());
+
+    expect(index.hasUnsettledDirs).toBe(true);
+    expect(await index.collectChanges()).toEqual([created]);
+  });
+
+  test("stops re-reading a directory once its mtime is old enough to trust", async () => {
+    const root = await makeRoot();
+    await seed(root, "lib/a.ts");
+    const index = new SourceMtimeIndex({ roots: [root], dirSettleMs: 60_000 });
+    await index.prime();
+    expect(index.hasUnsettledDirs).toBe(true);
+
+    // The retry compensates for a timestamp that is too fresh to trust; it must not become a standing
+    // full walk once the tree settles.
+    const settled = new Date(Date.now() - 120_000);
+    for (const dir of [root, path.join(root, "lib")]) await utimes(dir, settled, settled);
+
+    expect(await index.collectChanges()).toEqual([]);
+    expect(index.hasUnsettledDirs).toBe(false);
+  });
+
   test("reports a deleted file and a deleted directory's files", async () => {
     const root = await makeRoot();
     const kept = await seed(root, "lib/a.ts");
@@ -256,7 +301,11 @@ describe("SourceMtimeIndex", () => {
       // goes unreported.
       expect(await index.collectChanges()).toEqual([]);
       expect(index.trackedFileCount).toBe(1);
-      expect(index.coverageGaps.map((gap) => gap.code)).toEqual(["EACCES"]);
+      // The locked directory joins the list too whenever this scan happened to re-read it — which depends
+      // on how fresh its mtime still was (see `dirSettleMs`) — so assert what the gap is about rather than
+      // how many entries happen to describe it.
+      expect(index.coverageGaps.map((gap) => gap.path)).toContain(abs);
+      expect(index.coverageGaps.every((gap) => gap.code === "EACCES")).toBe(true);
 
       await chmod(locked, 0o755);
       await rewrite(abs, "1234");