@drkmttr/adhere 0.18.1 → 0.23.0

package/src/install.ts

@@ -1,15 +1,17 @@
 import { spawn } from "node:child_process";
-import { access, cp, mkdir, mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { access, cp, mkdir, mkdtemp, readdir, readFile, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join, sep } from "node:path";
-import { RULES_DIRECTORY, type RuleId } from "#config.ts";
-import { parseRuleMarkdown } from "#markdown.ts";
+import { INSTRUCTIONS_DIRECTORY, RULES_DIRECTORY, type RuleId } from "#config.ts";
+import { parseRuleMarkdown, ruleBodyOf } from "#markdown.ts";
 import { Effect } from "effect";
 
 /**
- * A GitHub repo whose `.adhere/rules/` another repo copies: `org/repo`, then
- * optionally a topic or a rule's id, then optionally `#` and a branch or tag,
- * as in `darkmatter/standards/data/brand-ports#v3`.
+ * A GitHub repo whose `.adhere/rules/` and `.adhere/instructions/` another
+ * repo copies: `org/repo`, then optionally a topic or a rule's id, then
+ * optionally `#` and a branch or tag, as in
+ * `darkmatter/standards/data/brand-ports#v3`. A `.` or `..` segment is not a
+ * repo, topic, or rule: copied under `.adhere/`, it would land outside.
  */
 export interface Source {
   readonly repo: string;
@@ -20,8 +22,16 @@ export interface Source {
 
 export const parseSource = (spec: string): Source | undefined => {
   const [path = "", ref] = spec.split("#");
-  const [org, repo, ...rule] = path.split("/").filter((segment) => segment.length > 0);
-  if (org === undefined || repo === undefined || ref === "") return undefined;
+  const segments = path.split("/").filter((segment) => segment.length > 0);
+  const [org, repo, ...rule] = segments;
+  if (
+    org === undefined ||
+    repo === undefined ||
+    ref === "" ||
+    segments.some((segment) => segment === "." || segment === "..")
+  ) {
+    return undefined;
+  }
   return { repo: `${org}/${repo}`, rule: rule.join("/"), ...(ref === undefined ? {} : { ref }) };
 };
 
@@ -34,7 +44,7 @@ const failed = (what: string) => (cause: unknown) =>
  * credentials git already has, and `url.<base>.insteadOf` can point
  * github.com elsewhere, such as at SSH.
  */
-const cloned = (source: Source) =>
+export const cloned = (source: Source) =>
   Effect.acquireRelease(
     Effect.tryPromise({
       try: () => mkdtemp(join(tmpdir(), "adhere-install-")),
@@ -47,21 +57,20 @@ const cloned = (source: Source) =>
         try: async () => {
           const branch = source.ref === undefined ? [] : ["--branch", source.ref];
           const url = `https://github.com/${source.repo}.git`;
-          await new Promise<void>((resolve, reject) => {
-            let stderr = "";
-            spawn("git", ["clone", "--quiet", "--depth", "1", ...branch, url, directory], {
-              stdio: ["inherit", "ignore", "pipe"],
+          const { promise, resolve, reject } = Promise.withResolvers<void>();
+          let stderr = "";
+          spawn("git", ["clone", "--quiet", "--depth", "1", ...branch, url, directory], {
+            stdio: ["inherit", "ignore", "pipe"],
+          })
+            .on("error", reject)
+            .on("exit", (code) => {
+              if (code === 0) resolve();
+              else reject(new Error(stderr.trim() || `git exited with ${code}`));
             })
-              .on("error", reject)
-              .on("exit", (code) =>
-                code === 0
-                  ? resolve()
-                  : reject(new Error(stderr.trim() || `git exited with ${code}`)),
-              )
-              .stderr?.on("data", (chunk) => {
-                stderr += chunk;
-              });
-          });
+            .stderr?.on("data", (chunk) => {
+              stderr += chunk;
+            });
+          await promise;
         },
         catch: failed(`Could not clone ${source.repo}`),
       }),
@@ -69,96 +78,289 @@ const cloned = (source: Source) =>
   );
 
 /**
- * The repo's rules in its root `.adhere/rules/`, as lint reads them there:
- * each directory that holds a RULE.md or a RULE.ts, by its path, with that file.
+ * Every Markdown file under the clone's `.adhere/instructions/`, by its path
+ * from there, so a shared repo's `security/hardening.md` is
+ * `security/hardening.md`. A directory whose name ends in `.md` is not a file.
  */
-const rulesIn = (source: Source, clone: string) =>
+const instructionsIn = (clone: string) =>
   Effect.tryPromise({
     try: async () => {
-      const directory = join(clone, RULES_DIRECTORY);
-      const entries = await readdir(directory, { recursive: true }).catch(() => []);
-      const rules = entries
-        .flatMap((entry) => {
-          const [, id, name] = /^(.+)\/(RULE\.(?:md|ts))$/.exec(entry.split(sep).join("/")) ?? [];
-          return id === undefined || name === undefined ? [] : [{ id: id as RuleId, name }];
-        })
-        .filter(
-          ({ id }) => source.rule === "" || id === source.rule || id.startsWith(`${source.rule}/`),
-        )
-        .sort((a, b) => a.id.localeCompare(b.id));
-      if (rules.length === 0) {
-        throw new Error(
-          source.rule === ""
-            ? `it has no rules in ${RULES_DIRECTORY}/`
-            : `it has no rule or topic ${source.rule} in ${RULES_DIRECTORY}/`,
-        );
+      const directory = join(clone, INSTRUCTIONS_DIRECTORY);
+      const entries = await readdir(directory, { recursive: true }).catch((cause: unknown) => {
+        if (
+          typeof cause === "object" &&
+          cause !== null &&
+          "code" in cause &&
+          cause.code === "ENOENT"
+        ) {
+          return [];
+        }
+        throw cause;
+      });
+      const files: Array<string> = [];
+      for (const entry of entries
+        .map((one) => one.split(sep).join("/"))
+        .filter((one) => one.endsWith(".md"))
+        .sort()) {
+        if ((await stat(join(directory, entry))).isFile()) files.push(entry);
       }
-      return rules.map(({ id, name }) => ({ id, name, directory: join(directory, id) }));
+      return files;
     },
-    catch: failed(`Nothing to copy from ${source.repo}`),
+    catch: failed(`Could not read ${INSTRUCTIONS_DIRECTORY}/`),
   });
 
 /**
- * Each rule a source names, with its description. A rule written in
- * TypeScript is listed without one: reading it would run the repo's code.
+ * The clone's rules in its root `.adhere/rules/`, as lint reads them there:
+ * each directory that holds a RULE.md or a RULE.ts, by its path, with that
+ * file. A directory with both refuses, as it does for lint.
  */
-export const listRules = (source: Source) =>
-  Effect.scoped(
-    Effect.gen(function* () {
-      const rules = yield* rulesIn(source, yield* cloned(source));
-      return yield* Effect.forEach(rules, ({ id, name, directory }) =>
-        Effect.gen(function* () {
-          if (name === "RULE.ts")
-            return { id, description: "(TypeScript, which list does not run)" };
-          const text = yield* Effect.tryPromise({
-            try: () => readFile(join(directory, name), "utf8"),
-            catch: failed(`Could not read ${id}`),
-          });
-          const rule = yield* parseRuleMarkdown(text, `${source.repo}/${id}/${name}`);
-          return { id, description: rule.description };
-        }),
+const rulesIn = (clone: string) =>
+  Effect.tryPromise({
+    try: async () => {
+      const entries = await readdir(join(clone, RULES_DIRECTORY), { recursive: true }).catch(
+        (cause: unknown) => {
+          if (
+            typeof cause === "object" &&
+            cause !== null &&
+            "code" in cause &&
+            cause.code === "ENOENT"
+          ) {
+            return [];
+          }
+          throw cause;
+        },
       );
-    }),
+      const byId = new Map<RuleId, "RULE.md" | "RULE.ts">();
+      for (const entry of entries.map((one) => one.split(sep).join("/")).sort()) {
+        const [, id, extension] = /^(.+)\/RULE\.(md|ts)$/.exec(entry) ?? [];
+        if (id === undefined || extension === undefined) continue;
+        const name = extension === "md" ? "RULE.md" : "RULE.ts";
+        const previous = byId.get(id);
+        if (previous !== undefined && previous !== name) {
+          throw new Error(
+            `${RULES_DIRECTORY}/${id} has both RULE.md and RULE.ts, and a rule is one`,
+          );
+        }
+        byId.set(id, name);
+      }
+      return [...byId].map(([id, name]) => ({ id, name })).sort((a, b) => a.id.localeCompare(b.id));
+    },
+    catch: failed(`Could not read ${RULES_DIRECTORY}/`),
+  });
+
+/** A rule a source offers: its id, and the file that defines it. */
+interface CatalogRule {
+  readonly id: RuleId;
+  readonly name: "RULE.md" | "RULE.ts";
+}
+
+/** What a source offers: its instruction files and its rules. */
+interface Catalog {
+  /** Markdown files under `.adhere/instructions/`, by their path from there, sorted. */
+  readonly instructions: ReadonlyArray<string>;
+  readonly rules: ReadonlyArray<CatalogRule>;
+}
+
+/**
+ * Everything a clone of `source` offers, without reading a rule: a malformed
+ * RULE.md elsewhere must not stop a rule from being copied. `describeRules`
+ * reads the descriptions `list` and the picker show.
+ */
+export const catalogOf = (source: Source, clone: string) =>
+  Effect.gen(function* () {
+    const instructions = yield* instructionsIn(clone);
+    const rules = yield* rulesIn(clone);
+    if (instructions.length === 0 && rules.length === 0) {
+      return yield* Effect.fail(
+        new Error(
+          `Nothing to copy from ${source.repo}: it has no instruction files in ${INSTRUCTIONS_DIRECTORY}/ and no rules in ${RULES_DIRECTORY}/`,
+        ),
+      );
+    }
+    return { instructions, rules };
+  });
+
+const TYPESCRIPT_ONLY = "(TypeScript, which list does not run)";
+
+/**
+ * A rule's description and, for a RULE.md, its body: what `adhere list` shows,
+ * and the Markdown a README embeds as written. A RULE.ts is named, never run.
+ */
+const described = (source: Source, clone: string, { id, name }: CatalogRule) =>
+  Effect.gen(function* () {
+    if (name === "RULE.ts") {
+      return { id, name, description: TYPESCRIPT_ONLY };
+    }
+    const text = yield* Effect.tryPromise({
+      try: () => readFile(join(clone, RULES_DIRECTORY, id, name), "utf8"),
+      catch: failed(`Could not read ${id}`),
+    });
+    const rule = yield* parseRuleMarkdown(text, `${source.repo}/${id}/${name}`);
+    return { id, name, description: rule.description, body: ruleBodyOf(text) };
+  });
+
+/**
+ * The description each rule shows: its Markdown's `description`, or a note
+ * for a RULE.ts, which reading would run.
+ */
+export const describeRules = (source: Source, clone: string, rules: ReadonlyArray<CatalogRule>) =>
+  Effect.forEach(rules, (rule) =>
+    Effect.map(described(source, clone, rule), ({ id, name, description }) => ({
+      id,
+      name,
+      description,
+    })),
+  );
+
+/**
+ * Every rule under `root`'s `.adhere/rules/`, with what a README shows: the
+ * description `adhere list` shows and, for a RULE.md, its body. Reads a
+ * RULE.md only; a RULE.ts is named, never run.
+ */
+export const describeRulesAt = (root: string) =>
+  Effect.gen(function* () {
+    const rules = yield* rulesIn(root);
+    return yield* Effect.forEach(rules, (rule) =>
+      described({ repo: "this repo", rule: "" }, root, rule),
+    );
+  });
+
+/** The rules a source's topic or id names, in catalog order. */
+const rulesNamed = (source: Source, catalog: Catalog): ReadonlyArray<CatalogRule> =>
+  source.rule === ""
+    ? catalog.rules
+    : catalog.rules.filter(({ id }) => id === source.rule || id.startsWith(`${source.rule}/`));
+
+const nothingNamed = (source: Source): Error =>
+  new Error(
+    source.rule === ""
+      ? `Nothing to copy from ${source.repo}: it has no rules in ${RULES_DIRECTORY}/`
+      : `Nothing to copy from ${source.repo}: it has no rule or topic ${source.rule} in ${RULES_DIRECTORY}/`,
   );
 
-export interface InstallResult {
+/**
+ * What a source names: one rule to copy as it is, or the files to choose
+ * from. Only an exact rule id, with no rule deeper under it, is copied
+ * without asking. A bare repo chooses from its instruction files and every
+ * rule; a topic chooses from the rules under it, never from instructions,
+ * even when a topic is named `instructions`.
+ */
+export type CatalogMatch =
+  | { readonly kind: "direct"; readonly rule: CatalogRule }
+  | {
+      readonly kind: "choose";
+      readonly instructions: ReadonlyArray<string>;
+      readonly rules: ReadonlyArray<CatalogRule>;
+    };
+
+export const matchOf = (source: Source, catalog: Catalog) =>
+  Effect.gen(function* () {
+    const rules = rulesNamed(source, catalog);
+    const exact = source.rule === "" ? undefined : rules.find(({ id }) => id === source.rule);
+    const topic = source.rule !== "" && rules.some(({ id }) => id.startsWith(`${source.rule}/`));
+    if (exact !== undefined && !topic) return { kind: "direct", rule: exact } as const;
+    if (rules.length === 0 && source.rule !== "") return yield* Effect.fail(nothingNamed(source));
+    return {
+      kind: "choose",
+      instructions: source.rule === "" ? catalog.instructions : [],
+      rules,
+    } as const;
+  });
+
+interface InstallResult {
   readonly created: ReadonlyArray<string>;
   readonly skipped: ReadonlyArray<string>;
 }
 
+/** The catalog entries a run copies: instruction paths, and rule ids. */
+export interface InstallPicks {
+  readonly instructions: ReadonlyArray<string>;
+  readonly rules: ReadonlyArray<RuleId>;
+}
+
+/** Where one instruction file lands in the repo that copies it. */
+export const instructionPath = (source: Source, instruction: string): string =>
+  `${INSTRUCTIONS_DIRECTORY}/${source.repo}/${instruction}`;
+
+/** Where one rule's directory lands in the repo that copies it, with its trailing slash. */
+export const rulePath = (source: Source, rule: RuleId): string =>
+  `${RULES_DIRECTORY}/${source.repo}/${rule}/`;
+
+const copyInto = (
+  from: string,
+  target: string,
+  path: string,
+  options: { readonly force: boolean; readonly recursive: boolean },
+) =>
+  Effect.tryPromise({
+    try: async () => {
+      const exists = await access(target).then(
+        () => true,
+        () => false,
+      );
+      if (exists && !options.force) return false;
+      if (exists) await rm(target, { recursive: true, force: true });
+      await mkdir(dirname(target), { recursive: true });
+      await cp(from, target, { recursive: options.recursive });
+      return true;
+    },
+    catch: failed(`Could not write ${path}`),
+  });
+
 /**
- * Copies the rules a source names, each its whole directory, helpers and all,
- * into `root`'s `.adhere/rules/` under the source's org and repo, so
- * `data/ports` from acme/rules is the rule `acme/rules/data/ports`, and two
- * sources' rules never collide. They are the project's own rules from then
- * on, and a copied RULE.ts runs whenever lint does. As with init, a rule
- * already there is skipped, unless `force` replaces its directory.
+ * Copies the picks from the clone into `root`: each instruction file to
+ * `.adhere/instructions/<org>/<repo>/<path>`, and each rule's whole
+ * directory, helpers and all, to `.adhere/rules/<org>/<repo>/<id>/`. Two
+ * sources' files never collide, and they are the project's own from then on,
+ * so a copied RULE.ts runs whenever lint does. Something already there is
+ * skipped, unless `force` replaces it. Nothing picked is ever deleted.
  */
-export const installRules = (root: string, source: Source, options: { readonly force?: boolean }) =>
+export const installSelected = (
+  root: string,
+  source: Source,
+  clone: string,
+  picks: InstallPicks,
+  options: { readonly force?: boolean },
+) =>
+  Effect.gen(function* () {
+    const created: Array<string> = [];
+    const skipped: Array<string> = [];
+    const force = options.force === true;
+    for (const instruction of picks.instructions) {
+      const path = instructionPath(source, instruction);
+      const wrote = yield* copyInto(
+        join(clone, INSTRUCTIONS_DIRECTORY, instruction),
+        join(root, path),
+        path,
+        { force, recursive: false },
+      );
+      (wrote ? created : skipped).push(path);
+    }
+    for (const rule of picks.rules) {
+      const path = rulePath(source, rule);
+      const wrote = yield* copyInto(join(clone, RULES_DIRECTORY, rule), join(root, path), path, {
+        force,
+        recursive: true,
+      });
+      (wrote ? created : skipped).push(path);
+    }
+    return { created, skipped } satisfies InstallResult;
+  });
+
+/**
+ * Each rule a source names, with its description. A rule written in
+ * TypeScript is listed without one: reading it would run the repo's code.
+ */
+export const listRules = (source: Source) =>
   Effect.scoped(
     Effect.gen(function* () {
-      const rules = yield* rulesIn(source, yield* cloned(source));
-      const created: Array<string> = [];
-      const skipped: Array<string> = [];
-      for (const { id, directory } of rules) {
-        const path = `${RULES_DIRECTORY}/${source.repo}/${id}/`;
-        const target = join(root, path);
-        const copied = yield* Effect.tryPromise({
-          try: async () => {
-            const exists = await access(target).then(
-              () => true,
-              () => false,
-            );
-            if (exists && options.force !== true) return false;
-            await rm(target, { recursive: true, force: true });
-            await mkdir(dirname(target), { recursive: true });
-            await cp(directory, target, { recursive: true });
-            return true;
-          },
-          catch: failed(`Could not write ${path}`),
-        });
-        (copied ? created : skipped).push(path);
-      }
-      return { created, skipped } satisfies InstallResult;
+      const clone = yield* cloned(source);
+      const catalog = yield* catalogOf(source, clone);
+      const rules = rulesNamed(source, catalog);
+      if (rules.length === 0) return yield* Effect.fail(nothingNamed(source));
+      return (yield* describeRules(source, clone, rules)).map(({ id, description }) => ({
+        id,
+        description,
+      }));
     }),
   );

package/src/instructions.ts

@@ -0,0 +1,98 @@
+import { INSTRUCTIONS_DIRECTORY } from "#config.ts";
+import { findConfigFile, loadConfigFile } from "#services/AdhereConfig.ts";
+import { Effect, FileSystem, Path, Schema } from "effect";
+
+const START = "<!-- adhere:instructions:start -->";
+const END = "<!-- adhere:instructions:end -->";
+
+class InstructionsUnavailable extends Schema.TaggedError<InstructionsUnavailable>()(
+  "InstructionsUnavailable",
+  { message: Schema.String },
+) {}
+
+/**
+ * The order instruction files render in: a file more than one directory deep,
+ * as a repo copied from another repo installs them under
+ * `.adhere/instructions/<org>/<repo>/`, comes first; then a file chosen
+ * locally, directly in the instructions directory; then any other locally
+ * nested file. Depth is the only test, so a local file nested two levels deep
+ * is ordered with copied repos too. Each group sorts by path, so a run writes
+ * the same block every time.
+ */
+const groupOf = (relative: string): number => {
+  const depth = relative.split("/").length;
+  if (depth >= 3) return 0;
+  return depth === 1 ? 1 : 2;
+};
+
+/** Update only adhere's marked block; leave all other AGENTS.md content untouched. */
+export const renderInstructions = Effect.fn("renderInstructions")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const configFile = yield* findConfigFile(root);
+  const config =
+    configFile === undefined ? undefined : yield* loadConfigFile(path.join(root, configFile));
+  const candidates =
+    config?.instructions === undefined
+      ? [path.join(root, INSTRUCTIONS_DIRECTORY), path.join(root, ".agents/instructions")]
+      : [path.resolve(root, path.dirname(configFile ?? ""), config.instructions)];
+  let directory: string | undefined;
+  for (const candidate of candidates) {
+    if (yield* fs.exists(candidate)) {
+      directory = candidate;
+      break;
+    }
+  }
+  if (directory === undefined) {
+    return `Skipped AGENTS.md: no instructions directory (${candidates.map((candidate) => path.relative(root, candidate)).join(", ")}).`;
+  }
+
+  const entries = yield* fs.readDirectory(directory, { recursive: true });
+  const files: Array<string> = [];
+  for (const entry of entries) {
+    const relative = entry.split(path.sep).join("/");
+    if (!relative.endsWith(".md")) continue;
+    if ((yield* fs.stat(path.join(directory, entry))).type === "File") files.push(relative);
+  }
+  files.sort((a, b) => groupOf(a) - groupOf(b) || a.localeCompare(b));
+
+  const contents: string[] = [];
+  for (const relative of files) {
+    const file = path.join(directory, relative);
+    const text = (yield* fs.readFileString(file)).trim();
+    if (text.includes(START) || text.includes(END)) {
+      return yield* InstructionsUnavailable.make({
+        message: `${file} contains reserved adhere instruction markers.`,
+      });
+    }
+    if (text !== "") contents.push(text);
+  }
+  const target = path.join(root, "AGENTS.md");
+  const previous = yield* fs
+    .readFileString(target)
+    .pipe(
+      Effect.catchTag("PlatformError", (error) =>
+        error.reason._tag === "NotFound" ? Effect.succeed("") : Effect.fail(error),
+      ),
+    );
+  const start = previous.indexOf(START);
+  const end = previous.indexOf(END);
+  if (
+    (start === -1) !== (end === -1) ||
+    (start !== -1 &&
+      (end < start ||
+        previous.indexOf(START, start + START.length) !== -1 ||
+        previous.indexOf(END, end + END.length) !== -1))
+  ) {
+    return yield* InstructionsUnavailable.make({
+      message: `${target} has malformed or duplicate adhere instruction markers. Fix them before running postinstall.`,
+    });
+  }
+  const block = [START, ...contents, END].join("\n\n");
+  const next =
+    start === -1
+      ? `${previous}${previous === "" ? "" : previous.endsWith("\n\n") ? "" : previous.endsWith("\n") ? "\n" : "\n\n"}${block}\n`
+      : `${previous.slice(0, start)}${block}${previous.slice(end + END.length)}`;
+  if (next !== previous) yield* fs.writeFileString(target, next);
+  return `${next === previous ? "Unchanged" : "Updated"} AGENTS.md: ${contents.length} instruction ${contents.length === 1 ? "file" : "files"} from ${path.relative(root, directory) || "."}.`;
+});

package/src/markdown.ts

@@ -1,4 +1,4 @@
-import { ConfigUnavailable, type Example, type Rule } from "#config.ts";
+import { ConfigUnavailable, type Example, Reads, type Rule } from "#config.ts";
 import { Effect, Schema } from "effect";
 
 /**
@@ -28,13 +28,14 @@ import { Effect, Schema } from "effect";
  * fence's own word wins over its heading's. The first fence under each word is
  * that example, and a rule has either or both. An untagged fence outside those
  * sections is the code to write, and without a fence the whole body is.
- * `avoid`, the word before 0.7, means `never`. `threshold` is optional, and
+ * `threshold` is optional, and
  * so is `tests`: `only` for a rule about test files, which rules otherwise
  * skip, and `include` for a rule that judges them too. So is `level`:
  * `warning` reports the rule's findings as warnings, which do not fail a run.
  * `appliesTo` and `excludeIf`, the rule's scope, are JSON arrays of strings on
  * one line, as in `excludeIf: ["a type that mirrors a third-party format"]`.
-
+ * `reads` is a JSON array of the same names, as in `reads: ["dependents"]`:
+ * it declares what the rule needs, while the config still decides what runs.
  */
 const Matchers = Schema.fromJsonString(Schema.Array(Schema.String));
 
@@ -45,9 +46,18 @@ const FrontMatter = Schema.Struct({
   level: Schema.optionalKey(Schema.Literals(["error", "warning"])),
   appliesTo: Schema.optionalKey(Matchers),
   excludeIf: Schema.optionalKey(Matchers),
+  reads: Schema.optionalKey(Schema.fromJsonString(Reads)),
 });
 
 const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+/**
+ * A rule file's Markdown after its front matter, as written: a README embeds
+ * it whole, examples and prose alike. Without front matter there is nothing to
+ * strip, so the text is its own body; `parseRuleMarkdown` refuses that anyway.
+ */
+export const ruleBodyOf = (text: string): string => FRONT_MATTER.exec(text)?.[2] ?? text;
+
 const FENCE = /^ {0,3}(`{3,}|~{3,})([^\n]*)\n([\s\S]*?)\n {0,3}\1[ \t]*$/gm;
 /** An ATX heading: its level as `#`s, then its text, without a closing run of `#`s. */
 const HEADING = /^ {0,3}(#{1,6})(?:[ \t]+(.*?))?(?:[ \t]+#+)?[ \t]*$/gm;
@@ -85,11 +95,11 @@ interface Heading {
   readonly word: Word | undefined;
 }
 
-/** `must not`, like `never` and the older `avoid`, names code never to write. */
+/** `must not`, like `never`, names code never to write. */
 const wordOf = (info: string): Word | undefined => {
   const words = info.trim().toLowerCase().split(/\s+/);
   const not = words.includes("not");
-  if (words.includes("never") || words.includes("avoid")) return "never";
+  if (words.includes("never")) return "never";
   if (words.includes("should")) return not ? "should not" : "should";
   if (words.includes("must")) return not ? "never" : "must";
   return undefined;
@@ -99,7 +109,6 @@ const HEADING_WORDS: ReadonlySet<string> = new Set([
   "must",
   "must not",
   "never",
-  "avoid",
   "should",
   "should not",
 ]);
@@ -208,11 +217,6 @@ export const parseRuleMarkdown = (
       });
     }
     const fields = parseFrontMatter(match[1]);
-    if (Object.hasOwn(fields, "reads")) {
-      return yield* ConfigUnavailable.make({
-        message: `${file}: move reads from the rule's front matter to the top level of defineConfig({...}) in your config file.`,
-      });
-    }
     const front = yield* Schema.decodeUnknownEffect(FrontMatter)(fields).pipe(
       Effect.mapError((problem) =>
         ConfigUnavailable.make({ message: `${file}: ${problem.message}` }),