@drkmttr/adhere 0.9.0 → 0.9.4

package/README.md

@@ -101,8 +101,12 @@ prints a completion script.
 
 ### Before and during a run
 
-Before it sends anything, `lint` says on stderr what it found and what judging
-takes:
+Until it knows what judging takes, a status line on stderr says what `lint` is
+doing: looking for `.adhere/` rules, listing and reading the files, then
+planning, each with a count, such as `Planning: 5,120 of 10,333 files`. The
+line is drawn only on a terminal, and not at `--log-level debug` or below,
+whose log lines would land in it. Then `lint` says on stderr what it found and
+what judging takes:
 
 ```text
 200 files and 14 rules: 2800 checks, 1400 cached.
@@ -370,8 +374,10 @@ each rule worded otherwise.
 ### Presets
 
 A preset has the shape of a config without `presets`: `rules`, and optionally
-`model` and `threshold`. Name one in the config, or on the command line with
-`--preset`, in which case the config file is optional. There are two:
+`model` and `threshold`. Name presets in the config's `presets`, or on the
+command line with `--preset`, repeated or separated by commas, as in
+`--preset effect,alchemy`, in which case the config file is optional. Presets
+named in both places apply together. There are two:
 
 - `effect`: Markdown rules in [`presets/effect/`](./presets/effect/), lifted
   from the [effect-solutions](https://github.com/kitlangton/effect-solutions)
@@ -489,8 +495,11 @@ A cache file is written once and never changed: it is also named for the hash
 of its own text. Two branches that judge the same code add files rather than
 edit them, so git merges the cache without a conflict. After a run that reads
 every file, adhere prunes the cache: it deletes answers about content no file
-has and answers to rule texts no rule asks, and folds what is left into one
-file per content. A run narrowed by `--filter` does not prune. To keep the
+has, and folds what is left into one file per content. Answers to rules the
+run left out stay, so a run with other presets or rules, or with one topic,
+loses nothing another run still asks; answers to a rule's old texts stay too,
+until the content they are about is gone. A run narrowed by `--filter` does not
+prune. To keep the
 cache out of diffs, mark it as generated in `.gitattributes`:
 
 ```text

package/bin/adhere.js

@@ -8,6 +8,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
+import { constants } from "node:os";
 import { fileURLToPath } from "node:url";
 
 const platform = `${process.platform}-${process.arch}`;
@@ -26,6 +27,14 @@ const resolveExecutable = () => {
 const run = (command, commandArgs) => {
   const result = spawnSync(command, commandArgs, { stdio: "inherit" });
   if (result.error) throw result.error;
+  if (result.signal) {
+    // A killed process says nothing itself, so say what killed it.
+    const memory =
+      result.signal === "SIGKILL" ? ", usually the system ending it for running out of memory" : "";
+    console.error(`adhere: the executable was killed by ${result.signal}${memory}.`);
+    process.exitCode = 128 + (constants.signals[result.signal] ?? 0);
+    return;
+  }
   process.exitCode = result.status ?? 1;
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.9.0",
+  "version": "0.9.4",
   "private": false,
   "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
   "license": "MIT",
@@ -68,10 +68,10 @@
     }
   },
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.9.0",
-    "@drkmttr/adhere-darwin-x64": "0.9.0",
-    "@drkmttr/adhere-linux-arm64": "0.9.0",
-    "@drkmttr/adhere-linux-x64": "0.9.0",
-    "@drkmttr/adhere-win32-x64": "0.9.0"
+    "@drkmttr/adhere-darwin-arm64": "0.9.4",
+    "@drkmttr/adhere-darwin-x64": "0.9.4",
+    "@drkmttr/adhere-linux-arm64": "0.9.4",
+    "@drkmttr/adhere-linux-x64": "0.9.4",
+    "@drkmttr/adhere-win32-x64": "0.9.4"
   }
 }

package/src/cli.ts

@@ -3,6 +3,7 @@ import { AuditCacheLive } from "#services/AuditCache.ts";
 import { Credentials, CredentialsLive, CredentialsUnavailable } from "#services/Credentials.ts";
 import { JevLive } from "#services/Jev.http.ts";
 import { SourceWalkerLive } from "#services/SourceWalker.ts";
+import { Status } from "#services/Status.ts";
 import {
   type AuditPlan,
   executeAudit,
@@ -61,10 +62,31 @@ class ContradictionsReported extends Schema.TaggedError<ContradictionsReported>(
   readonly [Runtime.errorReported] = false;
 }
 
-const preset = Flag.choice("preset", presetNames).pipe(
-  Flag.optional,
+/** The names each `--preset` gives, split at commas: `--preset effect,alchemy` gives two. */
+const presetsIn = (values: ReadonlyArray<string>): ReadonlyArray<string> =>
+  values
+    .flatMap((value) => value.split(","))
+    .map((name) => name.trim())
+    .filter((name) => name.length > 0);
+
+const isPresetName = (name: string): name is PresetName =>
+  (presetNames as ReadonlyArray<string>).includes(name);
+
+const preset = Flag.string("preset").pipe(
+  Flag.atLeast(0),
+  Flag.filterMap(
+    (values): Option.Option<ReadonlyArray<PresetName>> => {
+      const names = presetsIn(values);
+      return names.every(isPresetName) ? Option.some([...new Set(names)]) : Option.none();
+    },
+    // The CLI puts this after "Expected:".
+    (values) => {
+      const unknown = presetsIn(values).filter((name) => !isPresetName(name));
+      return `one of ${presetNames.join(", ")}, or several separated by commas (not ${unknown.join(", ")})`;
+    },
+  ),
   Flag.withDescription(
-    "Add a built-in rule set, or one of its topics, such as effect/basics. With a preset, .adhere/config.ts is optional.",
+    `Add built-in rule sets, or their topics, such as effect/basics. Repeat the flag or separate names with commas, as in --preset effect,alchemy. With a preset, .adhere/config.ts is optional. (choices: ${presetNames.join(", ")})`,
   ),
 );
 
@@ -141,20 +163,51 @@ const counterFor = (plan: AuditPlan, logging: LogLevel.LogLevel) => {
   };
 };
 
+/**
+ * The status line for what a run does before its plan: walking the checkout,
+ * reading files, planning. On a terminal it is one line of stderr, redrawn at
+ * most every 100 ms and cut to the terminal's width; anywhere else, and at
+ * debug or below, whose log lines would land in it, it shows nothing.
+ */
+const statusLayer = Layer.effect(Status)(
+  Effect.gen(function* () {
+    const logging = yield* References.MinimumLogLevel;
+    if (process.stderr.isTTY !== true || !LogLevel.isGreaterThan(logging, "Debug")) {
+      return Status.defaultValue();
+    }
+    let drawn = 0;
+    let shown = false;
+    return {
+      show: (text: string) =>
+        Effect.sync(() => {
+          const now = Date.now();
+          if (now - drawn < 100) return;
+          drawn = now;
+          shown = true;
+          // A terminal that reports no width, as some report 0, gets 80 columns.
+          const width = (process.stderr.columns || 80) - 1;
+          process.stderr.write(`\r\u001b[2K${text.slice(0, width)}`);
+        }),
+      clear: Effect.sync(() => {
+        if (shown) process.stderr.write("\r\u001b[2K");
+        shown = false;
+        drawn = 0;
+      }),
+    };
+  }),
+);
+
 const force = Flag.boolean("force").pipe(
   Flag.withDefault(false),
   Flag.withDescription("Overwrite existing scaffold files."),
 );
 
-const chosenPresets = (flag: Option.Option<PresetName>): ReadonlyArray<PresetName> =>
-  Option.isSome(flag) ? [flag.value] : [];
-
 export const auditLayer = (overrides: Overrides, filter: ReadonlyArray<string> = []) =>
   Layer.mergeAll(
     SourceWalkerLive(filter),
     AuditCacheLive,
     JevLive.pipe(Layer.provide([FetchHttpClient.layer, CredentialsLive])),
-  ).pipe(Layer.provideMerge(AdhereConfigLive(overrides)));
+  ).pipe(Layer.provideMerge(AdhereConfigLive(overrides)), Layer.provideMerge(statusLayer));
 
 /** `adhere lint`: the audit. */
 export const lintCommand = Command.make(
@@ -200,7 +253,7 @@ export const lintCommand = Command.make(
   Command.provide((input) =>
     auditLayer(
       {
-        presets: chosenPresets(input.preset),
+        presets: input.preset,
         threshold: Option.getOrUndefined(input.threshold),
         rpm: Option.getOrUndefined(input.rpm),
       },
@@ -214,7 +267,7 @@ export const validateLayer = (overrides: Overrides) =>
   Layer.merge(
     JevLive.pipe(Layer.provide([FetchHttpClient.layer, CredentialsLive])),
     AuditCacheLive,
-  ).pipe(Layer.provideMerge(AdhereConfigLive(overrides)));
+  ).pipe(Layer.provideMerge(AdhereConfigLive(overrides)), Layer.provideMerge(statusLayer));
 
 /**
  * `adhere validate`: everything `lint` loads, then how each rule's wording
@@ -250,7 +303,7 @@ export const validateCommand = Command.make("validate", { preset }, () =>
   Command.withDescription(
     "Load the config, rule files, and presets the way lint does, check each rule's wording against the README's rule writing tips, report the rules lint's linter check flags, then ask Jev whether any two rules that apply to the same files contradict each other.",
   ),
-  Command.provide((input) => validateLayer({ presets: chosenPresets(input.preset) })),
+  Command.provide((input) => validateLayer({ presets: input.preset })),
 );
 
 /** `adhere init`: the scaffold. */

package/src/rules.ts

@@ -6,6 +6,8 @@ import {
   SKIPPED_DIRECTORIES,
 } from "#config.ts";
 import { parseRuleMarkdown } from "#markdown.ts";
+import { walkFiles } from "#walk.ts";
+import { clearingStatus, countOf, Status } from "#services/Status.ts";
 import { Effect, FileSystem, Path, Record } from "effect";
 
 const refused = (directory: string) => (problem: { readonly message: string }) =>
@@ -36,6 +38,21 @@ const segmentsOf = (relative: string): ReadonlyArray<string> =>
 
 const isMarkdown = (path: string): boolean => path.endsWith(".md");
 
+/**
+ * Whether the rule walk reads into a directory: on the way to a `.adhere/`,
+ * not a skipped tree or `.git`; inside one, anything but its cache, since a
+ * directory there such as `.adhere/e2e/` is a rule topic.
+ */
+const entersForRules = (relative: string): boolean => {
+  const segments = segmentsOf(relative);
+  const name = segments.at(-1) ?? "";
+  const adhere = segments.lastIndexOf(ADHERE_SEGMENT);
+  if (adhere >= 0 && adhere < segments.length - 1) {
+    return !(adhere === segments.length - 2 && name === CACHE_SEGMENT);
+  }
+  return name === ADHERE_SEGMENT || !(SKIPPED_DIRECTORIES.has(name) || name === ".git");
+};
+
 const isNestedRuleFile = (relative: string): boolean => {
   const segments = segmentsOf(relative);
   const adhere = segments.lastIndexOf(ADHERE_SEGMENT);
@@ -108,10 +125,15 @@ export const loadRules = Effect.fn("loadRules")(function* (directory: string) {
 export const loadAdhereRuleSet = Effect.fn("loadAdhereRuleSet")(function* (root: string) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
-  const entries = yield* fs
-    .readDirectory(root, { recursive: true })
-    .pipe(Effect.mapError(refused(root)));
-  const files = entries.filter(isNestedRuleFile).sort();
+  const status = yield* Status;
+  const entries = yield* clearingStatus(
+    walkFiles(fs, path, root, entersForRules, (directories) =>
+      status.show(
+        `Looking for .adhere/ rules: ${countOf(directories, "directory", "directories")} read`,
+      ),
+    ),
+  ).pipe(Effect.mapError(refused(root)));
+  const files = entries.filter(isNestedRuleFile);
   return yield* Effect.forEach(files, (relative) =>
     Effect.gen(function* () {
       const file = joinPath(path, root, segmentsOf(relative));

package/src/services/AuditCache.ts

@@ -45,13 +45,11 @@ export const Tally = Schema.Struct({
 export interface Tally extends Schema.Schema.Type<typeof Tally> {}
 const decodeTally = Schema.decodeUnknownOption(Schema.fromJsonString(Tally));
 
-/** What a run that read every file still needs from the cache. */
+/** What a run that read every file tells the cache. */
 export interface Live {
-  /** The hash of each file's content. */
+  /** The hash of each file's content, too long to judge or not. */
   readonly hashes: ReadonlySet<string>;
-  /** The fingerprint of each rule text asked about a file. */
-  readonly fingerprints: ReadonlySet<string>;
-  /** The key of each rule's tally. */
+  /** The key of each of the run's rules' tallies, to carry over from the layout before content keys. */
   readonly tallies: ReadonlySet<string>;
 }
 
@@ -84,9 +82,11 @@ export class AuditCache extends Context.Service<
     readonly tally: (key: string) => Effect.Effect<Tally | undefined>;
     readonly putTally: (key: string, tally: Tally) => Effect.Effect<void>;
     /**
-     * Deletes what `live` does not need, and folds the rest into one file per
-     * content and per tally. Only after a run that read every file: it cannot
-     * tell what the files it did not read need. Succeeds with the files deleted.
+     * Deletes the answers about content no file has, and folds the rest into
+     * one file per content and per tally. Answers to rules the run left out
+     * stay, as do their tallies: a run with other presets or rules asks them.
+     * Only after a run that read every file: it cannot tell what content the
+     * files it did not read have. Succeeds with the files deleted.
      */
     readonly prune: (live: Live) => Effect.Effect<number>;
   }
@@ -275,10 +275,7 @@ export const AuditCacheLive = Layer.effect(AuditCache)(
       // Folding replaces or removes the group being visited, which a Map's iteration allows.
       for (const group of (yield* indexes.files).keys()) {
         const entries = live.hashes.has(group) ? yield* readGroup("files", group, decodeEntry) : [];
-        const answers = Record.filter(
-          unionOf(entries.map((entry) => entry.answers)),
-          (_, fingerprint) => live.fingerprints.has(fingerprint),
-        );
+        const answers = unionOf(entries.map((entry) => entry.answers));
         deleted += yield* fold(
           "files",
           group,
@@ -286,7 +283,7 @@ export const AuditCacheLive = Layer.effect(AuditCache)(
         );
       }
       for (const key of (yield* indexes.tallies).keys()) {
-        const tallies = live.tallies.has(key) ? yield* readGroup("tallies", key, decodeTally) : [];
+        const tallies = yield* readGroup("tallies", key, decodeTally);
         deleted += yield* fold(
           "tallies",
           key,

package/src/services/SourceWalker.ts

@@ -3,6 +3,8 @@ import { Context, Effect, FileSystem, Layer, Path } from "effect";
 import { ADHERE_DIRECTORY, SKIPPED_DIRECTORIES } from "#config.ts";
 import type { ScannedFile } from "#models/Audit.ts";
 import { WalkUnavailable } from "#models/Audit.ts";
+import { walkFiles } from "#walk.ts";
+import { clearingStatus, counted, countOf, Status } from "#services/Status.ts";
 
 /** Walks the repository's TypeScript source, skipping what is not ours to read. */
 export class SourceWalker extends Context.Service<
@@ -63,9 +65,15 @@ const isScannable = (file: string, self: string): boolean =>
 const refused = (problem: { readonly message: string }): WalkUnavailable =>
   WalkUnavailable.make({ message: problem.message });
 
-/** `readdir(recursive)` yields paths relative to the root it read: root them. */
+/** The walk yields paths relative to the root it read: root them. */
 const rooted = (root: string, paths: ReadonlyArray<string>) => paths.map((rel) => `${root}/${rel}`);
 
+/** Whether the walk reads into a directory: never a skipped tree, `.adhere/`, or `.git`. */
+const entersForSource = (relative: string): boolean => {
+  const name = relative.split("/").at(-1) ?? "";
+  return !(SKIPPED_DIRECTORIES.has(name) || name === ADHERE_DIRECTORY || name === ".git");
+};
+
 /** A test on a path relative to the root being read: whether the run wants it. */
 type Keep = (relative: string) => boolean;
 
@@ -76,20 +84,27 @@ const scannable = (root: string, paths: ReadonlyArray<string>, self: string, kee
     paths.filter((relative) => !isInSkippedTree(relative) && keep(relative)),
   ).filter((file) => isScannable(file, self));
 
-/** One root's paths, filtered to what the audit reads. */
-const listRoot = Effect.fn("SourceWalker.listRoot")(
-  (fs: FileSystem.FileSystem, root: string, self: string, keep: Keep) =>
-    Effect.flatMap(fs.readDirectory(root, { recursive: true }), (paths) => {
-      const files = scannable(root, paths, self, keep);
-      // The paths listed against the files kept: node_modules shows as the difference.
-      return Effect.as(
-        Effect.logDebug(
-          `listed ${root}: ${paths.length} paths, ${files.length} source files to read`,
-        ),
-        files,
-      );
-    }),
-);
+/** One root's files, filtered to what the audit reads. `label` names the root on the status line. */
+const listRoot = Effect.fn("SourceWalker.listRoot")(function* (
+  fs: FileSystem.FileSystem,
+  path: Path.Path,
+  root: string,
+  label: string,
+  self: string,
+  keep: Keep,
+) {
+  const status = yield* Status;
+  const paths = yield* walkFiles(fs, path, root, entersForSource, (directories, found) =>
+    status.show(
+      `Listing ${label}: ${countOf(directories, "directory", "directories")}, ${countOf(found, "file", "files")}`,
+    ),
+  );
+  const files = scannable(root, paths, self, keep);
+  yield* Effect.logDebug(
+    `listed ${root}: ${paths.length} files, ${files.length} source files to read`,
+  );
+  return files;
+});
 
 /** One scannable path, read into lines. */
 const readFile = Effect.fn("SourceWalker.readFile")((fs: FileSystem.FileSystem, path: string) =>
@@ -99,14 +114,42 @@ const readFile = Effect.fn("SourceWalker.readFile")((fs: FileSystem.FileSystem,
   })).pipe(Effect.tap((file) => Effect.logTrace(`read ${path}: ${file.lines.length} lines`))),
 );
 
-/** Read a batch of paths; the inner loop hoisted out of `forEach`. */
-const readEach = (fs: FileSystem.FileSystem, paths: ReadonlyArray<string>) =>
-  Effect.forEach(paths, (path: string) => readFile(fs, path));
+/** Reads a root's paths, several at a time, keeping their order, and counts them on the status line. */
+const readEach = Effect.fn("SourceWalker.readEach")(function* (
+  fs: FileSystem.FileSystem,
+  label: string,
+  paths: ReadonlyArray<string>,
+) {
+  const status = yield* Status;
+  let read = 0;
+  return yield* Effect.forEach(
+    paths,
+    (path: string) =>
+      readFile(fs, path).pipe(
+        Effect.tap(() => {
+          read += 1;
+          return status.show(
+            `Reading ${label}: ${counted(read)} of ${countOf(paths.length, "file", "files")}`,
+          );
+        }),
+      ),
+    { concurrency: 16 },
+  );
+});
 
-/** One root's files, in directory order: read every scannable path. */
+/** One root's files, in path order: read every scannable path. */
 const readRoot = Effect.fn("SourceWalker.readRoot")(
-  (fs: FileSystem.FileSystem, root: string, self: string, keep: Keep) =>
-    Effect.flatMap(listRoot(fs, root, self, keep), (paths) => readEach(fs, paths)),
+  (
+    fs: FileSystem.FileSystem,
+    path: Path.Path,
+    root: string,
+    label: string,
+    self: string,
+    keep: Keep,
+  ) =>
+    Effect.flatMap(listRoot(fs, path, root, label, self, keep), (paths) =>
+      readEach(fs, label, paths),
+    ),
 );
 
 /**
@@ -125,8 +168,9 @@ const scanDirs = Effect.fn("SourceWalker.scanDirs")(function* (
 });
 
 /**
- * The real walker: `FileSystem.readDirectory` recursively over the roots,
- * each file read and split into lines. Tests substitute their own tree.
+ * The real walker: the roots walked a directory at a time, skipped trees
+ * left unread, each file read and split into lines. Tests substitute their
+ * own tree.
  * The scan root is the current working directory, so the audit reads the
  * repository it is run in.
  */
@@ -140,11 +184,19 @@ export const SourceWalkerLive = (filter: ReadonlyArray<string> = []) =>
       const self = yield* path.fromFileUrl(new URL("../../", import.meta.url)).pipe(Effect.orDie);
       const walk = Effect.fn("SourceWalker.files")(function* () {
         const dirs = yield* scanDirs(fs, root).pipe(Effect.mapError(refused));
-        const trees = yield* Effect.forEach(dirs, (dir) =>
-          readRoot(fs, path.join(root, dir), self, (relative) =>
-            // Filter patterns are relative to the working directory, not the tree read.
-            passesFilter(dir === "." ? relative : `${dir}/${relative}`, filter),
-          ).pipe(Effect.mapError(refused)),
+        const trees = yield* clearingStatus(
+          Effect.forEach(dirs, (dir) =>
+            readRoot(
+              fs,
+              path,
+              path.join(root, dir),
+              dir === "." ? "the working directory" : `${dir}/`,
+              self,
+              (relative) =>
+                // Filter patterns are relative to the working directory, not the tree read.
+                passesFilter(dir === "." ? relative : `${dir}/${relative}`, filter),
+            ).pipe(Effect.mapError(refused)),
+          ),
         );
         return trees.flat();
       });

package/src/services/Status.ts

@@ -0,0 +1,31 @@
+import { Context, Effect } from "effect";
+
+export interface StatusLine {
+  /** Shows what the run is doing now, in place of what was shown before. */
+  readonly show: (text: string) => Effect.Effect<void>;
+  /** Takes the line away, before anything else is written. */
+  readonly clear: Effect.Effect<void>;
+}
+
+/**
+ * What a run is doing before it has anything to report: walking the
+ * checkout, reading files, planning. The CLI draws it as one line on
+ * stderr; wherever nothing provides it, as in tests, it shows nothing.
+ */
+export const Status = Context.Reference<StatusLine>("@drkmttr/adhere/services/Status", {
+  defaultValue: () => ({ show: () => Effect.void, clear: Effect.void }),
+});
+
+/** `effect`, with the status line cleared when it ends, however it ends. */
+export const clearingStatus = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+  Effect.gen(function* () {
+    const status = yield* Status;
+    return yield* Effect.ensuring(effect, status.clear);
+  });
+
+/** A count as the status line shows it: 10,333. */
+export const counted = (n: number): string => n.toLocaleString("en-US");
+
+/** A count and its noun: 1 directory, 2,679 directories. */
+export const countOf = (n: number, one: string, many: string): string =>
+  `${counted(n)} ${n === 1 ? one : many}`;

package/src/walk.ts

@@ -0,0 +1,85 @@
+import { Effect, type FileSystem, type Path, type PlatformError } from "effect";
+
+/** A directory entry, as the walk sorts it: a file to list, a directory to read, or neither. */
+type Entry =
+  | { readonly kind: "file"; readonly relative: string }
+  | { readonly kind: "directory"; readonly relative: string }
+  | { readonly kind: "skipped" };
+
+const skipped: Entry = { kind: "skipped" };
+
+/**
+ * Every file under `root`, each as a path relative to it with `/` between
+ * segments, sorted. `enter` says, of each directory below the root by its
+ * relative path, whether to read into it, so a walk never lists what it would
+ * throw away.
+ *
+ * A directory reached through a symbolic link is never entered: pnpm's
+ * `node_modules` links packages into one another, and following the links
+ * lists every path through the dependency graph. A recursive `readdir` does
+ * follow them; on alchemy's checkout it passed 160 GB before the kernel
+ * killed it. A symbolic link to a file is listed like the file, and a link
+ * to nothing is left out.
+ *
+ * `progress` hears, as each directory is read, how many have been and how
+ * many files they held.
+ */
+export const walkFiles = Effect.fn("walkFiles")(function* (
+  fs: FileSystem.FileSystem,
+  path: Path.Path,
+  root: string,
+  enter: (relative: string) => boolean,
+  progress: (directories: number, files: number) => Effect.Effect<void> = () => Effect.void,
+) {
+  const entryOf = (relative: string): Effect.Effect<Entry, PlatformError.PlatformError> => {
+    const full = path.join(root, relative);
+    return fs.stat(full).pipe(
+      Effect.flatMap((info): Effect.Effect<Entry> => {
+        if (info.type !== "Directory") return Effect.succeed({ kind: "file", relative });
+        if (!enter(relative)) return Effect.succeed(skipped);
+        // Only a link can be read as one, so a failed read is a real directory.
+        return fs.readLink(full).pipe(
+          Effect.match({
+            onFailure: (): Entry => ({ kind: "directory", relative }),
+            onSuccess: (): Entry => skipped,
+          }),
+        );
+      }),
+      Effect.catchIf(
+        (problem) => problem.reason._tag === "NotFound",
+        () => Effect.succeed(skipped),
+      ),
+    );
+  };
+
+  const files: Array<string> = [];
+  let directories = 0;
+  let level: ReadonlyArray<string> = [""];
+  while (level.length > 0) {
+    const next: Array<string> = [];
+    yield* Effect.forEach(
+      level,
+      (directory) =>
+        fs.readDirectory(directory === "" ? root : path.join(root, directory)).pipe(
+          Effect.flatMap((names) =>
+            Effect.forEach(
+              names,
+              (name) => entryOf(directory === "" ? name : `${directory}/${name}`),
+              { concurrency: 16 },
+            ),
+          ),
+          Effect.flatMap((entries) => {
+            for (const entry of entries) {
+              if (entry.kind === "file") files.push(entry.relative);
+              else if (entry.kind === "directory") next.push(entry.relative);
+            }
+            directories += 1;
+            return progress(directories, files.length);
+          }),
+        ),
+      { concurrency: 8, discard: true },
+    );
+    level = next;
+  }
+  return files.sort();
+});

package/src/workflows/audit.ts

@@ -16,6 +16,7 @@ import {
   tokensOf,
 } from "#services/Jev.ts";
 import { SourceWalker } from "#services/SourceWalker.ts";
+import { clearingStatus, counted, countOf, Status } from "#services/Status.ts";
 import { SAMPLE, tallyKeyOf } from "#mechanical.ts";
 import { applicableRules } from "#rules.ts";
 import { type Crypto, Duration, Effect, Record, Result, Semaphore } from "effect";
@@ -174,13 +175,15 @@ export const planAudit = (
 
     const planFile = Effect.fn("audit.plan")(function* (file: ScannedFile) {
       const rules = configuredRules(file.path);
+      // Hashed even when skipped, so a prune keeps what other runs know of its content.
+      const hash = yield* sha256(file.lines.join("\n"));
       // Too long for Jev's context: skipped and counted, rather than refused mid-run.
       if (!fits(file.lines, rules)) {
         yield* Effect.logTrace(`plan ${file.path}: too long for Jev's context, skipped`);
         return {
           file,
           skipped: true,
-          hash: "",
+          hash,
           prepared: {},
           kept: {},
           pending: {},
@@ -197,7 +200,6 @@ export const planAudit = (
               [id, { rule, fingerprint, threshold: rule.threshold ?? config.threshold }] as const,
           ),
       ).pipe(Effect.map(Record.fromEntries));
-      const hash = yield* sha256(file.lines.join("\n"));
       const answers = yield* cache.get(hash, file.path);
       const kept: Record<RuleId, Judgment> = Record.filterMap(prepared, ({ fingerprint }) => {
         const answer = answers[fingerprint];
@@ -281,9 +283,23 @@ export const planAudit = (
     });
 
     const sorted = [...files].sort((a, b) => a.path.localeCompare(b.path));
-    const everything: ReadonlyArray<FilePlan> = yield* Effect.forEach(sorted, planFile, {
-      concurrency: 8,
-    });
+    const status = yield* Status;
+    let done = 0;
+    const everything: ReadonlyArray<FilePlan> = yield* clearingStatus(
+      Effect.forEach(
+        sorted,
+        (file) =>
+          planFile(file).pipe(
+            Effect.tap(() => {
+              done += 1;
+              return status.show(
+                `Planning: ${counted(done)} of ${countOf(sorted.length, "file", "files")}`,
+              );
+            }),
+          ),
+        { concurrency: 8 },
+      ),
+    );
     const limited =
       options.limit === undefined ? everything : withinLimit(everything, options.limit);
     const planned = yield* withSamples(limited);
@@ -486,22 +502,21 @@ export const executeAudit = (
   });
 
 /**
- * Deletes from the cache what the files and rules of a run no longer need:
- * answers about content no file has, answers to rule texts no rule asks, and
- * tallies of rules gone. Only after a run that read every file; a run narrowed
- * by `--filter` cannot tell what the files it left out need.
+ * Deletes from the cache the answers about content no file has anymore.
+ * Answers to rules the run left out stay, since a run with other presets or
+ * rules asks them. Only after a run that read every file; a run narrowed by
+ * `--filter` cannot tell what content the files it left out have.
  */
 export const pruneCache = Effect.fn("audit.prune")(function* (plan: AuditPlan) {
   const config = yield* AdhereConfig;
   const cache = yield* AuditCache;
-  const read = plan.files.filter((file) => !file.skipped);
-  const prepared = read.flatMap((file) => Object.values(file.prepared));
+  const prepared = plan.files.flatMap((file) => Object.values(file.prepared));
   const tallies = yield* Effect.forEach(new Set(prepared.map(({ rule }) => rule)), (rule) =>
     tallyKeyOf(config.model, rule),
   );
   const deleted = yield* cache.prune({
-    hashes: new Set(read.map((file) => file.hash)),
-    fingerprints: new Set(prepared.map(({ fingerprint }) => fingerprint)),
+    // A file too long to judge counts: a run with shorter questions judges it.
+    hashes: new Set(plan.files.map((file) => file.hash)),
     tallies: new Set(tallies),
   });
   yield* Effect.logDebug(`cache pruned: ${deleted} ${deleted === 1 ? "file" : "files"} deleted`);