@drkmttr/adhere 0.21.2 → 0.24.0

package/src/services/AuditCache.ts

@@ -155,180 +155,187 @@ const OLD_NAME = /^[0-9a-f]{64}$/;
 /**
  * `.adhere/cache/`, which is meant to be committed. `files/` holds answers by
  * the content they are about, and `tallies/` the linter check's tallies, with
- * paths from the working directory. A file is written once and never
- * rewritten: it is named for its group, a content hash or a tally key, and for
- * the hash of its own text. Two branches that add to a group add different
- * files, or the same one, so git merges them without a conflict. Reading a
- * group takes the union of its files, and pruning folds them back into one.
+ * paths from the checkout root (`base`, the working directory by default). A
+ * file is written once and never rewritten: it is named for its group, a
+ * content hash or a tally key, and for the hash of its own text. Two branches
+ * that add to a group add different files, or the same one, so git merges them
+ * without a conflict. Reading a group takes the union of its files, and pruning
+ * folds them back into one.
  *
  * A cache must never fail a run: whatever cannot be read counts as missing,
  * and whatever cannot be written is left unwritten.
  */
-export const AuditCacheLive = Layer.effect(AuditCache)(
-  Effect.gen(function* () {
-    const fs = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const crypto = yield* Crypto.Crypto;
-    const root = path.resolve();
-    const directory = path.join(root, CACHE_DIRECTORY);
-    const hash = (text: string) => sha256(text).pipe(Effect.provideService(Crypto.Crypto, crypto));
-
-    /** Each group's file names in one folder, listed once and kept current as files come and go. */
-    const indexOf = (folder: string) =>
-      Effect.cached(
-        fs.readDirectory(path.join(directory, folder)).pipe(
-          Effect.orElseSucceed((): ReadonlyArray<string> => []),
-          Effect.map((names) => {
-            const groups = new Map<string, Set<string>>();
-            for (const name of names) {
-              const group = NAME.exec(name)?.[1];
-              if (group !== undefined)
-                groups.set(group, (groups.get(group) ?? new Set()).add(name));
-            }
-            return groups;
-          }),
-        ),
-      );
-    const indexes = { files: yield* indexOf("files"), tallies: yield* indexOf("tallies") };
-    type Folder = keyof typeof indexes;
-
-    const read = <A>(decode: (text: string) => Option.Option<A>, file: string) =>
-      fs.readFileString(file).pipe(
-        Effect.map((text) => Option.getOrUndefined(decode(text))),
-        Effect.orElseSucceed(() => undefined),
-      );
-
-    /** A group's files that decode, in name order. */
-    const readGroup = Effect.fn("AuditCache.readGroup")(function* <A>(
-      folder: Folder,
-      group: string,
-      decode: (text: string) => Option.Option<A>,
-    ) {
-      const names = [...((yield* indexes[folder]).get(group) ?? [])].sort();
-      const decoded = yield* Effect.forEach(names, (name) =>
-        read(decode, path.join(directory, folder, name)),
-      );
-      return decoded.filter((value): value is A => value !== undefined);
-    });
-
-    const nameOf = (group: string, text: string) =>
-      Effect.map(hash(text), (digest) => `${group}.${digest.slice(0, 16)}.json`);
-
-    /** Adds `value` to a group as a new file, unless the group has that file already. */
-    const add = Effect.fn("AuditCache.add")(function* (
-      folder: Folder,
-      group: string,
-      value: unknown,
-    ) {
-      const text = textOf(value);
-      const name = yield* nameOf(group, text);
-      const index = yield* indexes[folder];
-      const names = index.get(group) ?? new Set<string>();
-      if (names.has(name)) return;
-      const written = yield* fs
-        .makeDirectory(path.join(directory, folder), { recursive: true })
-        .pipe(
-          Effect.andThen(fs.writeFileString(path.join(directory, folder, name), text)),
-          Effect.as(true),
-          Effect.orElseSucceed(() => false),
+export const AuditCacheAt = (base?: string) =>
+  Layer.effect(AuditCache)(
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const crypto = yield* Crypto.Crypto;
+      const root = path.resolve(base ?? ".");
+      const directory = path.join(root, CACHE_DIRECTORY);
+      const hash = (text: string) =>
+        sha256(text).pipe(Effect.provideService(Crypto.Crypto, crypto));
+
+      /** Each group's file names in one folder, listed once and kept current as files come and go. */
+      const indexOf = (folder: string) =>
+        Effect.cached(
+          fs.readDirectory(path.join(directory, folder)).pipe(
+            Effect.orElseSucceed((): ReadonlyArray<string> => []),
+            Effect.map((names) => {
+              const groups = new Map<string, Set<string>>();
+              for (const name of names) {
+                const group = NAME.exec(name)?.[1];
+                if (group !== undefined)
+                  groups.set(group, (groups.get(group) ?? new Set()).add(name));
+              }
+              return groups;
+            }),
+          ),
         );
-      if (written) index.set(group, names.add(name));
-    });
-
-    const remove = (file: string) =>
-      fs.remove(file).pipe(
-        Effect.as(1),
-        Effect.orElseSucceed(() => 0),
-      );
-
-    /** Replaces a group's files with one holding `value`, or with none. Succeeds with the files deleted. */
-    const fold = Effect.fn("AuditCache.fold")(function* (
-      folder: Folder,
-      group: string,
-      value: unknown,
-    ) {
-      const index = yield* indexes[folder];
-      const names = [...(index.get(group) ?? [])];
-      const keep = value === undefined ? undefined : yield* nameOf(group, textOf(value));
-      if (value !== undefined) yield* add(folder, group, value);
-      let deleted = 0;
-      for (const name of names) {
-        if (name !== keep) deleted += yield* remove(path.join(directory, folder, name));
-      }
-      if (keep === undefined) index.delete(group);
-      else index.set(group, new Set([keep]));
-      return deleted;
-    });
-
-    const relativeOf = (tally: Tally): Tally => ({
-      files: sorted(
-        Record.mapKeys(tally.files, (file) =>
-          path.isAbsolute(file) ? path.relative(root, file) : file,
-        ),
-      ),
-    });
-
-    const get = Effect.fn("AuditCache.get")(function* (contentHash: string, filePath: string) {
-      const entries = yield* readGroup("files", contentHash, decodeEntry);
-      if (entries.length > 0) return unionOf(entries.map((entry) => entry.answers));
-      // Before content keys, a file's entry sat under the hash of its absolute path.
-      const old = yield* read(decodeOldEntry, path.join(directory, yield* hash(filePath)));
-      if (old === undefined || old.hash !== contentHash) return {};
-      const answers = answersOf(old.judgments);
-      yield* add("files", contentHash, { answers: sorted(answers) });
-      return answers;
-    });
-
-    const tally = Effect.fn("AuditCache.tally")(function* (key: string) {
-      const tallies = yield* readGroup("tallies", key, decodeTally);
-      if (tallies.length > 0) {
-        const { files } = tallyUnionOf(tallies);
-        return { files: Record.mapKeys(files, (file) => path.resolve(root, file)) };
-      }
-      // Before, a tally sat under the hash of its key, with absolute paths.
-      const old = yield* read(
-        decodeTally,
-        path.join(directory, yield* hash(`\u0000tally\u0000${key}`)),
-      );
-      if (old !== undefined) yield* add("tallies", key, relativeOf(old));
-      return old;
-    });
-
-    const prune = Effect.fn("AuditCache.prune")(function* (live: Live) {
-      // Tallies still in the layout before content keys move first, so deleting what is left of it loses nothing.
-      yield* Effect.forEach(live.tallies, tally, { discard: true });
-      let deleted = 0;
-      // 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 = unionOf(entries.map((entry) => entry.answers));
-        deleted += yield* fold(
-          "files",
-          group,
-          Object.keys(answers).length === 0 ? undefined : { answers: sorted(answers) },
+      const indexes = { files: yield* indexOf("files"), tallies: yield* indexOf("tallies") };
+      type Folder = keyof typeof indexes;
+
+      const read = <A>(decode: (text: string) => Option.Option<A>, file: string) =>
+        fs.readFileString(file).pipe(
+          Effect.map((text) => Option.getOrUndefined(decode(text))),
+          Effect.orElseSucceed(() => undefined),
         );
-      }
-      for (const key of (yield* indexes.tallies).keys()) {
+
+      /** A group's files that decode, in name order. */
+      const readGroup = Effect.fn("AuditCache.readGroup")(function* <A>(
+        folder: Folder,
+        group: string,
+        decode: (text: string) => Option.Option<A>,
+      ) {
+        const names = [...((yield* indexes[folder]).get(group) ?? [])].sort();
+        const decoded = yield* Effect.forEach(names, (name) =>
+          read(decode, path.join(directory, folder, name)),
+        );
+        return decoded.filter((value): value is A => value !== undefined);
+      });
+
+      const nameOf = (group: string, text: string) =>
+        Effect.map(hash(text), (digest) => `${group}.${digest.slice(0, 16)}.json`);
+
+      /** Adds `value` to a group as a new file, unless the group has that file already. */
+      const add = Effect.fn("AuditCache.add")(function* (
+        folder: Folder,
+        group: string,
+        value: unknown,
+      ) {
+        const text = textOf(value);
+        const name = yield* nameOf(group, text);
+        const index = yield* indexes[folder];
+        const names = index.get(group) ?? new Set<string>();
+        if (names.has(name)) return;
+        const written = yield* fs
+          .makeDirectory(path.join(directory, folder), { recursive: true })
+          .pipe(
+            Effect.andThen(fs.writeFileString(path.join(directory, folder, name), text)),
+            Effect.as(true),
+            Effect.orElseSucceed(() => false),
+          );
+        if (written) index.set(group, names.add(name));
+      });
+
+      const remove = (file: string) =>
+        fs.remove(file).pipe(
+          Effect.as(1),
+          Effect.orElseSucceed(() => 0),
+        );
+
+      /** Replaces a group's files with one holding `value`, or with none. Succeeds with the files deleted. */
+      const fold = Effect.fn("AuditCache.fold")(function* (
+        folder: Folder,
+        group: string,
+        value: unknown,
+      ) {
+        const index = yield* indexes[folder];
+        const names = [...(index.get(group) ?? [])];
+        const keep = value === undefined ? undefined : yield* nameOf(group, textOf(value));
+        if (value !== undefined) yield* add(folder, group, value);
+        let deleted = 0;
+        for (const name of names) {
+          if (name !== keep) deleted += yield* remove(path.join(directory, folder, name));
+        }
+        if (keep === undefined) index.delete(group);
+        else index.set(group, new Set([keep]));
+        return deleted;
+      });
+
+      const relativeOf = (tally: Tally): Tally => ({
+        files: sorted(
+          Record.mapKeys(tally.files, (file) =>
+            path.isAbsolute(file) ? path.relative(root, file) : file,
+          ),
+        ),
+      });
+
+      const get = Effect.fn("AuditCache.get")(function* (contentHash: string, filePath: string) {
+        const entries = yield* readGroup("files", contentHash, decodeEntry);
+        if (entries.length > 0) return unionOf(entries.map((entry) => entry.answers));
+        // Before content keys, a file's entry sat under the hash of its absolute path.
+        const old = yield* read(decodeOldEntry, path.join(directory, yield* hash(filePath)));
+        if (old === undefined || old.hash !== contentHash) return {};
+        const answers = answersOf(old.judgments);
+        yield* add("files", contentHash, { answers: sorted(answers) });
+        return answers;
+      });
+
+      const tally = Effect.fn("AuditCache.tally")(function* (key: string) {
         const tallies = yield* readGroup("tallies", key, decodeTally);
-        deleted += yield* fold(
-          "tallies",
-          key,
-          tallies.length === 0 ? undefined : relativeOf(tallyUnionOf(tallies)),
+        if (tallies.length > 0) {
+          const { files } = tallyUnionOf(tallies);
+          return { files: Record.mapKeys(files, (file) => path.resolve(root, file)) };
+        }
+        // Before, a tally sat under the hash of its key, with absolute paths.
+        const old = yield* read(
+          decodeTally,
+          path.join(directory, yield* hash(`\u0000tally\u0000${key}`)),
         );
-      }
-      const old = yield* fs.readDirectory(directory).pipe(Effect.orElseSucceed(() => []));
-      for (const name of old) {
-        if (OLD_NAME.test(name)) deleted += yield* remove(path.join(directory, name));
-      }
-      return deleted;
-    });
-
-    return AuditCache.of({
-      get,
-      put: (contentHash, answers) => add("files", contentHash, { answers: sorted(answers) }),
-      tally,
-      putTally: (key, value) => add("tallies", key, relativeOf(value)),
-      prune,
-    });
-  }),
-);
+        if (old !== undefined) yield* add("tallies", key, relativeOf(old));
+        return old;
+      });
+
+      const prune = Effect.fn("AuditCache.prune")(function* (live: Live) {
+        // Tallies still in the layout before content keys move first, so deleting what is left of it loses nothing.
+        yield* Effect.forEach(live.tallies, tally, { discard: true });
+        let deleted = 0;
+        // 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 = unionOf(entries.map((entry) => entry.answers));
+          deleted += yield* fold(
+            "files",
+            group,
+            Object.keys(answers).length === 0 ? undefined : { answers: sorted(answers) },
+          );
+        }
+        for (const key of (yield* indexes.tallies).keys()) {
+          const tallies = yield* readGroup("tallies", key, decodeTally);
+          deleted += yield* fold(
+            "tallies",
+            key,
+            tallies.length === 0 ? undefined : relativeOf(tallyUnionOf(tallies)),
+          );
+        }
+        const old = yield* fs.readDirectory(directory).pipe(Effect.orElseSucceed(() => []));
+        for (const name of old) {
+          if (OLD_NAME.test(name)) deleted += yield* remove(path.join(directory, name));
+        }
+        return deleted;
+      });
+
+      return AuditCache.of({
+        get,
+        put: (contentHash, answers) => add("files", contentHash, { answers: sorted(answers) }),
+        tally,
+        putTally: (key, value) => add("tallies", key, relativeOf(value)),
+        prune,
+      });
+    }),
+  );
+
+export const AuditCacheLive = AuditCacheAt();

package/src/services/SourceWalker.ts

@@ -172,20 +172,27 @@ const scanDirs = Effect.fn("SourceWalker.scanDirs")(function* (
  * Tests are listed even when no rule judges them, so a prune keeps what other runs
  * know of them. Tests substitute their own tree.
  * The scan root is the current working directory, so the audit reads the
- * repository it is run in.
+ * repository it is run in. `roots` overrides the workspace trees read: `["."]`
+ * reads the whole working directory, for a trial that must not miss a file
+ * outside `agents/`, `apps/`, and `packages/`. `base` roots the walk
+ * elsewhere, for a trial of a checkout that is not the working directory.
  */
-export const SourceWalkerLive = (filter: ReadonlyArray<string> = []) =>
+export const SourceWalkerLive = (
+  filter: ReadonlyArray<string> = [],
+  roots?: ReadonlyArray<string>,
+  base?: string,
+) =>
   Layer.effect(SourceWalker)(
     Effect.gen(function* () {
       const fs = yield* FileSystem.FileSystem;
       const path = yield* Path.Path;
       const config = yield* AdhereConfig;
-      // No segments: Path resolves against the working directory.
-      const root = path.resolve();
+      const root = base === undefined ? path.resolve() : path.resolve(base);
       const self = yield* path.fromFileUrl(new URL("../../", import.meta.url)).pipe(Effect.orDie);
       const patterns = [...filter, ...(config.exclude ?? []).map((glob) => `!${glob}`)];
       const walk = Effect.fn("SourceWalker.files")(function* () {
-        const dirs = yield* scanDirs(fs, root).pipe(Effect.mapError(refused));
+        const dirs =
+          roots === undefined ? yield* scanDirs(fs, root).pipe(Effect.mapError(refused)) : roots;
         const trees = yield* clearingStatus(
           Effect.forEach(dirs, (dir) =>
             listRoot(

package/src/wording.ts

@@ -4,7 +4,7 @@ import { type RuleEntry, shownId } from "#rules.ts";
 type Word = Example["word"];
 
 /**
- * A way a rule's wording differs from the README's rule writing tips, which
+ * A way a rule's wording differs from the docs' rule writing tips, which
  * the eval measured: the rule shows code of both kinds, and its description
  * says the words its code is under.
  */
@@ -22,7 +22,7 @@ export interface Stray {
   readonly straying: ReadonlyArray<Straying>;
 }
 
-export const TIPS_URL = "https://github.com/darkmatter/adhere#rule-writing-tips";
+export const TIPS_URL = "https://dm.sh/adhere/writing-good-rules/#rule-writing-tips";
 
 /** Whether a description says a word, whole and in any case: "Must" does, "mustard" does not. */
 const says = (description: string, word: Word): boolean =>
@@ -30,7 +30,7 @@ const says = (description: string, word: Word): boolean =>
 
 /**
  * How one rule strays from the tips. A rule with only code that breaks it
- * lacks no example: the README keeps that for a rule with no single correct
+ * lacks no example: the docs keep that for a rule with no single correct
  * form to show.
  */
 export const strayingOf = (rule: Rule): ReadonlyArray<Straying> => {

package/src/workflows/audit.ts

@@ -9,6 +9,7 @@ import {
   type Rules,
 } from "#config.ts";
 import { type Excerpt, type Range } from "#excerpt.ts";
+import { contentPasses, filtersNeedText, hasFilters, ruleAppliesTo } from "#filters.ts";
 import { type ScannedFile, WalkUnavailable } from "#models/Audit.ts";
 import { AdhereConfig } from "#services/AdhereConfig.ts";
 import { AuditCache, answersOf, type Judgment, sha256, type Tally } from "#services/AuditCache.ts";
@@ -147,6 +148,8 @@ const fingerprintOf = (model: string, reads: string, rule: Rule) => {
   const hook = rule.appendState === undefined ? "" : `\u0000${rule.appendState.toString()}`;
   const options =
     rule.optionValues === undefined ? "" : `\u0000${JSON.stringify(rule.optionValues)}`;
+  // Filters decide which files a rule may judge, not what Jev answers, so they
+  // do not change the fingerprint: applicability is checked before the cache.
   return sha256(
     `${model}\u0000${LAYOUT}${reads}\u0000${JSON.stringify(judgeQuestion(rule))}${scope}${hook}${options}`,
   );
@@ -352,7 +355,12 @@ const sameSuppressions = (left: Suppressions, right: Suppressions): boolean => {
   );
 };
 
-/** Validate code and ignore policy before sending a request or showing a cached excerpt. */
+/**
+ * Validate code, ignore policy, and text-dependent filters before sending a
+ * request or showing a cached excerpt. A comment-only edit keeps the code hash
+ * but can change what a content filter sees, so those filters are rechecked
+ * against the new text; path filters cannot change for the same file.
+ */
 const reloadFile = Effect.fn("audit.reload")(function* (plan: FilePlan, includeComments: boolean) {
   const original = yield* (yield* SourceWalker).read(plan.file);
   const { lines, suppressions } = normalized(original.lines, includeComments);
@@ -364,6 +372,17 @@ const reloadFile = Effect.fn("audit.reload")(function* (plan: FilePlan, includeC
       message: `${plan.file.path}: source changed since planning. Rerun adhere lint to create a fresh plan; changed contents were not sent or cached under the old content key. Files already completed remain cached.`,
     });
   }
+  let written: string | undefined;
+  const dropped = Object.entries(plan.prepared).flatMap(([id, { rule }]) =>
+    filtersNeedText(rule) && !contentPasses(rule, (written ??= original.lines.join("\n")))
+      ? [id]
+      : [],
+  );
+  if (dropped.length > 0) {
+    return yield* WalkUnavailable.make({
+      message: `${plan.file.path}: source changed since planning, and content filters no longer apply to ${dropped.join(", ")}. Rerun adhere lint to create a fresh plan; changed contents were not sent or cached under the old content key. Files already completed remain cached.`,
+    });
+  }
   return { file: { ...plan.file, lines }, original: original.lines } satisfies LoadedFile;
 });
 
@@ -385,6 +404,8 @@ const MAX_DEPENDENT_FILES = 50;
 export interface PlanOptions {
   /** Select at most this many files needing judge or cached-locate requests; zero plans only. */
   readonly limit?: number | undefined;
+  /** The checkout Jev's paths are relative to. Defaults to the working directory. */
+  readonly root?: string | undefined;
 }
 
 export const planAudit = (
@@ -410,9 +431,10 @@ export const planAudit = (
     };
     const walker = yield* SourceWalker;
     const files = yield* walker.files;
-    // Each file's path from the working directory, `/`-separated, as Jev reads it.
+    // Each file's path from the checkout, `/`-separated, as Jev reads it.
+    const root = options.root ?? process.cwd();
     const fromRoot = new Map(
-      files.map((file) => [file.path, relative(process.cwd(), file.path).split(sep).join("/")]),
+      files.map((file) => [file.path, relative(root, file.path).split(sep).join("/")]),
     );
     // Only the specifiers stay in memory: each file is read again when it is planned.
     const dependentFiles = config.reads.includes("dependents")
@@ -452,15 +474,17 @@ export const planAudit = (
     );
 
     // The rules that judge a file: those scoped to it, of which only the rules that say `tests`
-    // judge a test, and none that an adhere-ignore-file comment names.
-    const configuredRules = (file: SourceFile, suppressions: Suppressions) =>
+    // judge a test, none that an adhere-ignore-file comment names, and none whose own
+    // include/exclude filters leave this file out.
+    const configuredRules = (file: SourceFile, suppressions: Suppressions, text: () => string) =>
       Record.filter(
         config.scopedRules === undefined
           ? config.rules
           : applicableRules(file.path, config.scopedRules),
         (rule, id) =>
           judgesFile(rule, file.test === true) &&
-          !suppressions.file.has(shownId({ id, preset: presetOfRule.get(rule) })),
+          !suppressions.file.has(shownId({ id, preset: presetOfRule.get(rule) })) &&
+          (!hasFilters(rule) || ruleAppliesTo(rule, fromRoot.get(file.path)!, text())),
       );
 
     // Model, thresholds, and presets are fixed per plan; share immutable descriptors by Rule identity.
@@ -498,7 +522,16 @@ export const planAudit = (
     const planFile = Effect.fn("audit.plan")(function* (file: SourceFile) {
       const original = yield* walker.read(file);
       const { lines, suppressions } = normalized(original.lines, config.includeComments === true);
-      const rules = configuredRules(file, suppressions);
+      // A rule's content filters read the file as written, comments and all, even
+      // when Jev is sent code without them. The decision is kept in `prepared`;
+      // reloading rechecks only those filters, in case a comment-only edit changed
+      // their answer without changing the code hash.
+      let written: string | undefined;
+      const rules = configuredRules(
+        file,
+        suppressions,
+        () => (written ??= original.lines.join("\n")),
+      );
       const code = lines.join("\n");
       const readState: ReadState = {
         ...(workspacePackages === undefined

package/src/workflows/format.ts

@@ -214,7 +214,7 @@ const excerpt = (finding: Finding, root: string | undefined): ReadonlyArray<Line
 /**
  * The warning on a finding whose file may not show enough to check its rule,
  * which its context score in the header says how far, and help: how to add
- * what the code relies on as a note Jev reads, in the form the README asks for.
+ * what the code relies on as a note Jev reads, in the form the docs ask for.
  */
 const insufficient = (finding: Finding, sufficiencyThreshold: number): ReadonlyArray<Line> =>
   !lacksContext(finding, sufficiencyThreshold)