@drkmttr/adhere 0.18.1 → 0.23.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/Credentials.ts

@@ -66,6 +66,18 @@ export class Credentials extends Context.Service<
 
 const refused = (message: string) => CredentialsUnavailable.make({ message });
 
+/** `$XDG_CONFIG_HOME/adhere`, or `~/.config/adhere` without it, on every platform: where adhere keeps a user's own files. */
+export const adhereConfigDirectory = (path: Path.Path) =>
+  Config.NonEmptyString("XDG_CONFIG_HOME").pipe(
+    Config.orElse(() =>
+      Config.NonEmptyString("HOME").pipe(
+        Config.orElse(() => Config.NonEmptyString("USERPROFILE")),
+        Config.map((home) => path.join(home, ".config")),
+      ),
+    ),
+    Config.map((configHome) => path.join(configHome, "adhere")),
+  );
+
 /**
  * The keys live in `$XDG_CONFIG_HOME/adhere/credentials.json`, or under
  * `~/.config` without it, on every platform. The file is written whole to a
@@ -77,14 +89,8 @@ export const CredentialsLive = Layer.effect(Credentials)(
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
 
-    const file = Config.NonEmptyString("XDG_CONFIG_HOME").pipe(
-      Config.orElse(() =>
-        Config.NonEmptyString("HOME").pipe(
-          Config.orElse(() => Config.NonEmptyString("USERPROFILE")),
-          Config.map((home) => path.join(home, ".config")),
-        ),
-      ),
-      Config.map((configHome) => path.join(configHome, "adhere", "credentials.json")),
+    const file = adhereConfigDirectory(path).pipe(
+      Config.map((directory) => path.join(directory, "credentials.json")),
       Effect.mapError(() =>
         refused("No home directory to keep the API key in: set HOME or XDG_CONFIG_HOME."),
       ),

package/src/services/Jev.reads.test.ts

@@ -194,6 +194,28 @@ describe("prepared shared Jev reads", () => {
     expect(locateRequests(lines, rules, readState)).toBe(3);
   });
 
+  it("sends a rule's options in requests of its own, under `options`", () => {
+    const optioned = { ...plain, optionValues: { edgePaths: ["src/edge"] } };
+    const rules = { plain, optioned, alsoPlain: plain };
+    const readState: ReadState = { workspacePackages: { orders: "packages/orders" } };
+    const groups = requestGroups(rules);
+    expect(groups.map((group) => Object.keys(group))).toEqual([
+      ["plain", "alsoPlain"],
+      ["optioned"],
+    ]);
+    const [shared, own] = groups.map((group) => locateBody("", lines, group, readState).state);
+    expect(shared?.options).toBeUndefined();
+    expect(own?.options).toEqual({
+      edgePaths: ["src/edge"],
+      __comment: expect.stringMatching(/options\./),
+    });
+    expect(judgeBody("", lines, { optioned }, [], readState).state).toEqual(own);
+    expect(own?.workspacePackages).toEqual(shared?.workspacePackages);
+    const huge = { ...plain, optionValues: { edgePaths: ["p".repeat(120_000)] } };
+    expect(fits(lines, { plain, optioned }, readState)).toBe(true);
+    expect(fits(lines, { plain, huge }, readState)).toBe(false);
+  });
+
   it("preserves caller comments and raw context through judge, locate, and appended maps", async () => {
     const readState = {
       __comment: "User context: only target code is audited.",

package/src/services/Jev.ts

@@ -146,6 +146,10 @@ const READ_COMMENTS: Readonly<Record<string, string>> = {
     "Declarations of symbols used in `code`. Each key is `symbol:pathname`: the symbol name as used in `code` followed by its repository-relative declaration path. Each value is a complete declaration excerpt.",
   workspacePackages:
     "Workspace packages imported by `code`; keys are package names and values are repository-relative package directories. Only packages imported by this file are listed.",
+  dependents:
+    "What depends on the file `code` holds. `packages` maps workspace packages whose package.json depends on this file's package to their repository-relative directories. `files` lists repository-relative paths of files that import this file by a relative path; `omittedFiles`, when present, counts more that are not listed. Package-name imports of this file are not in `files`.",
+  options:
+    "Settings this project gives the rule the questions ask about, which the rule names as `options.<key>`.",
 };
 
 /** Explain the known context maps while preserving caller-provided descriptions and target code. */
@@ -347,11 +351,21 @@ export const matcherQuestions = (id: RuleId, rule: Rule) =>
         [matcherKey(kind, id, index), matcherQuestion(rule, kind, matcher)] as const,
     ),
   );
-
-/** The room for one question beside the file and its shared prepared context. Hooks are not predicted. */
+/** The room for one question beside the file and the prepared context of its request. Hooks are not predicted. */
 export const questionRoom = (lines: Lines, readState: ReadState = {}): number =>
   QUESTION_CONTEXT - WRAPPER - tokensOf(stateOf(lines, readState));
 
+/**
+ * The shared context, with the options of the rule in `rules` that has them
+ * under `options`: `requestGroups` gives such a rule a body of its own.
+ */
+const withOptions = (rules: Rules, readState: ReadState): ReadState => {
+  const options = Object.values(rules).find(
+    (rule) => rule.optionValues !== undefined,
+  )?.optionValues;
+  return options === undefined ? readState : { ...readState, options };
+};
+
 /**
  * One question per rule, one per matcher of each rule, and the linter
  * question beside each rule in `sampled`.
@@ -364,7 +378,7 @@ export const judgeBody = (
   readState: ReadState = {},
 ) => ({
   model,
-  state: stateOf(lines, readState),
+  state: stateOf(lines, withOptions(rules, readState)),
   questions: {
     ...Record.map(rules, (rule): ReturnType<typeof judgeQuestion> => judgeQuestion(rule)),
     ...Object.fromEntries(
@@ -482,7 +496,7 @@ export const locateBody = (
   readState: ReadState = {},
 ) => {
   const sections = sectionsOf(lines);
-  const state = stateOf(lines, readState, sections);
+  const state = stateOf(lines, withOptions(rules, readState), sections);
   const criteria = Record.map(state.code, () => null);
   const choosing = sections.length > 1;
   const withCode = sections.map((section) => lineCriteria(lines, section));
@@ -513,10 +527,16 @@ export const locateBody = (
 };
 
 /**
- * Whether Jev can take every request a file may need: its sections within
- * one choice, and the shared state beside its longest question. Hooks are not predicted.
+ * Whether Jev can take every request a file may need: each request group's
+ * sections within one choice, and its state, options and all, beside its
+ * longest question. Hooks are not predicted.
  */
-export const fits = (lines: Lines, rules: Rules, readState: ReadState = {}): boolean => {
+export const fits = (lines: Lines, rules: Rules, readState: ReadState = {}): boolean =>
+  Record.isEmptyRecord(rules)
+    ? groupFits(lines, rules, readState)
+    : requestGroups(rules).every((group) => groupFits(lines, group, withOptions(group, readState)));
+
+const groupFits = (lines: Lines, rules: Rules, readState: ReadState): boolean => {
   const sections = sectionsOf(lines);
   if (sections.length > CHOICE_LIMIT) return false;
   const state = stateOf(lines, readState, sections);
@@ -633,16 +653,18 @@ export const requestsOf = <Q>(body: Body<Q>): ReadonlyArray<Body<Q>> => {
 };
 
 /**
- * All rules share one body except those with `appendState`, each in a body
- * of its own so only its questions read what its hook adds to the shared state.
+ * All rules share one body except those with `appendState` or options, each
+ * in a body of its own so only its questions read what it adds to the shared state.
  */
 export const requestGroups = (rules: Rules): ReadonlyArray<Rules> => {
-  const shared = Record.filter(rules, (rule) => rule.appendState === undefined);
+  const alone = Record.filter(
+    rules,
+    (rule) => rule.appendState !== undefined || rule.optionValues !== undefined,
+  );
+  const shared = Record.filter(rules, (_, id) => !(id in alone));
   return [
     ...(Record.isEmptyRecord(shared) ? [] : [shared]),
-    ...Object.entries(rules).flatMap(([id, rule]) =>
-      rule.appendState === undefined ? [] : [{ [id]: rule }],
-    ),
+    ...Object.entries(alone).map(([id, rule]) => ({ [id]: rule })),
   ];
 };
 

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> => {
@@ -60,7 +60,7 @@ export const straysAmong = (entries: ReadonlyArray<RuleEntry>): ReadonlyArray<St
   });
 
 /** One way a rule strays, as a sentence. */
-const sentenceOf = (straying: Straying): string => {
+export const sentenceOf = (straying: Straying): string => {
   switch (straying._tag) {
     case "Unsaid":
       return `The description does not say "${straying.word}", though the rule has a ${straying.word} example.`;