@drkmttr/adhere 0.12.0 → 0.13.1

package/src/init.ts

@@ -28,9 +28,13 @@ export interface InitOptions {
    * install`, rather than one that lints itself.
    */
   readonly shared?: string;
+  /** Who can see the shared repo alchemy creates. Defaults to public. */
+  readonly visibility?: Visibility;
 }
 
-// adhere-ignore-file rules/import-written-files -- src/index.ts exports initProject, so a Bun text import here breaks loading the package on Node and in Vitest (checked 2026-09-26), and the compiled executable has no files beside it to read.
+export type Visibility = "public" | "private";
+
+// adhere-ignore-file import-written-files -- src/index.ts exports initProject, so a Bun text import here breaks loading the package on Node and in Vitest (checked 2026-09-26), and the compiled executable has no files beside it to read.
 const CONFIG = `import { defineConfig } from "@drkmttr/adhere";
 
 export default defineConfig({
@@ -39,10 +43,11 @@ export default defineConfig({
 `;
 
 /**
- * A project for the config alone. A tsconfig's globs skip dot directories, so
- * without it the editor opens `.adhere/config.ts` outside any project, where
- * it cannot resolve `@drkmttr/adhere`, whose types only `bundler`, `node16`,
- * and `nodenext` resolution reach.
+ * A project for the config and any rules written in TypeScript. A tsconfig's
+ * globs skip dot directories, so without it the editor opens
+ * `.adhere/config.ts` outside any project, where it cannot resolve
+ * `@drkmttr/adhere`, whose types only `bundler`, `node16`, and `nodenext`
+ * resolution reach.
  */
 const TSCONFIG = `{
   "compilerOptions": {
@@ -54,7 +59,7 @@ const TSCONFIG = `{
     "skipLibCheck": true,
     "allowImportingTsExtensions": true
   },
-  "include": ["config.ts"]
+  "include": ["**/*.ts"]
 }
 `;
 
@@ -113,8 +118,9 @@ export const handle = (id: string) =>
 const sharedReadme = (org: string, repo: string) => `# ${repo}
 
 Shared [adhere](https://github.com/darkmatter/adhere) rules for ${org}'s
-repositories. Each rule is a Markdown file in \`.adhere/\`, and a repo that
-copies it in has Jev judge its files against it when it runs \`adhere lint\`.
+repositories. Each rule is a directory in \`.adhere/rules/\` that holds a
+\`RULE.md\`, or a \`RULE.ts\`, and a repo that copies it in has Jev judge its
+files against it when it runs \`adhere lint\`.
 
 ## Use these rules
 
@@ -127,13 +133,14 @@ adhere install ${org}/${repo}/style
 adhere install ${org}/${repo}/style/prefer-small-files
 \`\`\`
 
-The copies land in \`.adhere/${org}/${repo}/\` and are that repo's own from then
+The copies land in \`.adhere/rules/${org}/${repo}/\` and are that repo's own from then
 on, to edit or to start other rules from. To take a later version of a rule,
 install it again with \`--force\`, which overwrites local edits.
 
 ## Add a rule
 
-Add a Markdown file under \`.adhere/<topic>/\`; its path is its id. See
+Add a directory under \`.adhere/rules/<topic>/\` with the rule in a \`RULE.md\`;
+its path is the rule's id. See
 [Rules as Markdown files](https://github.com/darkmatter/adhere#rules-as-markdown-files)
 and the [rule writing tips](https://github.com/darkmatter/adhere#rule-writing-tips).
 \`adhere validate\` checks each rule's wording and asks Jev whether any two
@@ -172,7 +179,11 @@ jobs:
           TYPESAFE_API_KEY: \${{ secrets.TYPESAFE_API_KEY }}
 `;
 
-const sharedStack = (org: string, repo: string) => `import * as Alchemy from "alchemy";
+const sharedStack = (
+  org: string,
+  repo: string,
+  visibility: Visibility,
+) => `import * as Alchemy from "alchemy";
 import * as GitHub from "alchemy/GitHub";
 import * as Output from "alchemy/Output";
 import * as Config from "effect/Config";
@@ -188,7 +199,7 @@ export default Alchemy.Stack(
       owner,
       name: "${repo}",
       description: "Shared adhere rules",
-      visibility: "private",
+      visibility: "${visibility}",
     });
     // CI's adhere validate asks Jev whether any two rules contradict. Naming
     // the repository by its output makes alchemy create it before the secret.
@@ -232,19 +243,22 @@ const SHARED_GITIGNORE = `node_modules/
 
 const CONFIG_PATH = CONFIG_FILES[0];
 
-/** The config's own project, which only a config at `.adhere/config.ts` needs. */
+/** The project of the config at `.adhere/config.ts`, and of the rules written in TypeScript beside it. */
 const CONFIG_PROJECT = ".adhere/tsconfig.json";
 
 const EXAMPLES = [
-  [".adhere/style/prefer-small-files.md", SMALL_FILES],
-  [".adhere/style/name-domain-actions.md", NAME_EFFECTS],
+  [".adhere/rules/style/prefer-small-files/RULE.md", SMALL_FILES],
+  [".adhere/rules/style/name-domain-actions/RULE.md", NAME_EFFECTS],
 ] as const;
 
 /**
- * A shared repo has no config: \`adhere install\` copies only rule files, and
- * \`validate\` reads \`.adhere/\` without one.
+ * A shared repo has no config: \`adhere install\` copies only rules, and
+ * \`validate\` reads \`.adhere/rules/\` without one.
  */
-const filesFor = (shared: string | undefined): ReadonlyArray<readonly [string, string]> => {
+const filesFor = (
+  shared: string | undefined,
+  visibility: Visibility,
+): ReadonlyArray<readonly [string, string]> => {
   if (shared === undefined) {
     return [[CONFIG_PATH, CONFIG], [CONFIG_PROJECT, TSCONFIG], ...EXAMPLES];
   }
@@ -252,7 +266,7 @@ const filesFor = (shared: string | undefined): ReadonlyArray<readonly [string, s
   return [
     ["README.md", sharedReadme(org, repo)],
     [".github/workflows/adhere.yaml", SHARED_WORKFLOW],
-    ["alchemy.run.ts", sharedStack(org, repo)],
+    ["alchemy.run.ts", sharedStack(org, repo, visibility)],
     ["package.json", sharedPackage(repo)],
     [".gitignore", SHARED_GITIGNORE],
     ...EXAMPLES,
@@ -312,14 +326,11 @@ const packageManagerAt = async (root: string): Promise<PackageManager> => {
 
 /**
  * pnpm refuses to add to a workspace root without a flag. `-w` fails outside a
- * workspace, so the first one, which works in both, stands in for it. pnpm 11
- * also fails on msgpackr-extract's unapproved build script. It comes with
- * effect, and adhere never calls msgpackr, so the second flag lets pnpm skip
- * the build with a warning.
+ * workspace, so this one, which works in both, stands in for it.
  */
 const addFlags: Record<PackageManager, ReadonlyArray<string>> = {
   bun: [],
-  pnpm: ["--ignore-workspace-root-check", "--config.strict-dep-builds=false"],
+  pnpm: ["--ignore-workspace-root-check"],
   yarn: [],
   npm: [],
 };
@@ -369,7 +380,7 @@ export const initProject = (
     const created: Array<string> = [];
     const skipped: Array<string> = [];
     const existing = options.shared === undefined ? yield* otherConfig(root) : undefined;
-    for (const [path, contents] of filesFor(options.shared)) {
+    for (const [path, contents] of filesFor(options.shared, options.visibility ?? "public")) {
       if (path === CONFIG_PATH && existing !== undefined) {
         skipped.push(existing);
         continue;

package/src/install.ts

@@ -1,13 +1,13 @@
 import { spawn } from "node:child_process";
-import { access, copyFile, mkdir, mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { access, cp, mkdir, mkdtemp, readdir, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join, sep } from "node:path";
-import { ADHERE_DIRECTORY, type RuleId } from "#config.ts";
+import { RULES_DIRECTORY, type RuleId } from "#config.ts";
 import { parseRuleMarkdown } from "#markdown.ts";
 import { Effect } from "effect";
 
 /**
- * A GitHub repo whose `.adhere/` rules another repo copies: `org/repo`, then
+ * 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`.
  */
@@ -63,43 +63,52 @@ const cloned = (source: Source) =>
     (directory) => Effect.promise(() => rm(directory, { recursive: true, force: true })),
   );
 
-/** The repo's root `.adhere/` rule files by id, as lint reads them there: every `*.md` outside `cache/`. */
+/**
+ * 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.
+ */
 const rulesIn = (source: Source, clone: string) =>
   Effect.tryPromise({
     try: async () => {
-      const directory = join(clone, ADHERE_DIRECTORY);
+      const directory = join(clone, RULES_DIRECTORY);
       const entries = await readdir(directory, { recursive: true }).catch(() => []);
-      const ids = entries
-        .filter((entry) => entry.endsWith(".md") && !entry.startsWith(`cache${sep}`))
-        .map((entry): RuleId => entry.slice(0, -".md".length).split(sep).join("/"))
+      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}/`),
+          ({ id }) => source.rule === "" || id === source.rule || id.startsWith(`${source.rule}/`),
         )
-        .sort();
-      if (ids.length === 0) {
+        .sort((a, b) => a.id.localeCompare(b.id));
+      if (rules.length === 0) {
         throw new Error(
           source.rule === ""
-            ? `it has no rules in ${ADHERE_DIRECTORY}/`
-            : `it has no rule or topic ${source.rule} in ${ADHERE_DIRECTORY}/`,
+            ? `it has no rules in ${RULES_DIRECTORY}/`
+            : `it has no rule or topic ${source.rule} in ${RULES_DIRECTORY}/`,
         );
       }
-      return ids.map((id) => ({ id, file: join(directory, `${id}.md`) }));
+      return rules.map(({ id, name }) => ({ id, name, directory: join(directory, id) }));
     },
     catch: failed(`Nothing to copy from ${source.repo}`),
   });
 
-/** Each rule a source names, with its description. */
+/**
+ * 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));
-      return yield* Effect.forEach(rules, ({ id, file }) =>
+      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(file, "utf8"),
+            try: () => readFile(join(directory, name), "utf8"),
             catch: failed(`Could not read ${id}`),
           });
-          const rule = yield* parseRuleMarkdown(text, `${source.repo}/${id}.md`);
+          const rule = yield* parseRuleMarkdown(text, `${source.repo}/${id}/${name}`);
           return { id, description: rule.description };
         }),
       );
@@ -112,11 +121,12 @@ export interface InstallResult {
 }
 
 /**
- * Copies the rules a source names into `root`'s `.adhere/` 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. As with init, a file already there is
- * skipped unless `force`.
+ * 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.
  */
 export const installRules = (root: string, source: Source, options: { readonly force?: boolean }) =>
   Effect.scoped(
@@ -124,8 +134,8 @@ export const installRules = (root: string, source: Source, options: { readonly f
       const rules = yield* rulesIn(source, yield* cloned(source));
       const created: Array<string> = [];
       const skipped: Array<string> = [];
-      for (const { id, file } of rules) {
-        const path = `${ADHERE_DIRECTORY}/${source.repo}/${id}.md`;
+      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 () => {
@@ -134,8 +144,9 @@ export const installRules = (root: string, source: Source, options: { readonly f
               () => false,
             );
             if (exists && options.force !== true) return false;
+            await rm(target, { recursive: true, force: true });
             await mkdir(dirname(target), { recursive: true });
-            await copyFile(file, target);
+            await cp(directory, target, { recursive: true });
             return true;
           },
           catch: failed(`Could not write ${path}`),

package/src/main.ts

@@ -5,7 +5,7 @@ import { version } from "#version.ts";
 import { BunRuntime, BunServices } from "@effect/platform-bun";
 import { plugin } from "bun";
 import { Cause, Effect, Layer, Logger, References, Runtime } from "effect";
-import { Command } from "effect/unstable/cli";
+import { Command } from "effect/cli";
 
 // A config file may import `@drkmttr/adhere`, for `defineConfig`. The compiled
 // executable resolves no packages from disk, so it answers that import with

package/src/markdown.ts

@@ -44,6 +44,7 @@ const FrontMatter = Schema.Struct({
   level: Schema.optionalKey(Schema.Literals(["error", "warning"])),
   appliesTo: Schema.optionalKey(Matchers),
   excludeIf: Schema.optionalKey(Matchers),
+  includeWorkspacePackages: Schema.optionalKey(Schema.Literals(["true", "false"])),
 });
 
 const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
@@ -206,5 +207,12 @@ export const parseRuleMarkdown = (
         message: `${file}: the body needs code, in a fence under a Must, Never, Should, or Should not heading, or untagged`,
       });
     }
-    return { ...front, ...code };
+    const { includeWorkspacePackages, ...fields } = front;
+    return {
+      ...fields,
+      ...(includeWorkspacePackages === undefined
+        ? {}
+        : { includeWorkspacePackages: includeWorkspacePackages === "true" }),
+      ...code,
+    };
   });

package/src/rules.ts

@@ -1,7 +1,7 @@
 import {
   ConfigUnavailable,
   type Override,
-  type Rule,
+  Rule,
   type RuleId,
   type RuleSource,
   SKIPPED_DIRECTORIES,
@@ -9,7 +9,7 @@ import {
 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";
+import { Effect, FileSystem, Path, Record, Schema } from "effect";
 
 const refused = (directory: string) => (problem: { readonly message: string }) =>
   ConfigUnavailable.make({
@@ -40,6 +40,10 @@ export type RuleSet = ReadonlyArray<RuleEntry>;
 
 const ADHERE_SEGMENT = ".adhere";
 const CACHE_SEGMENT = "cache";
+/** Where in a `.adhere/` its rules sit, one to a directory. */
+const RULES_PREFIX = "rules/";
+/** The file in a rule's directory that is the rule: Markdown, or TypeScript that default-exports `defineRule({...})`. */
+const RULE_FILES: ReadonlySet<string> = new Set(["RULE.md", "RULE.ts"]);
 
 const normalized = (path: string): string => path.replaceAll("\\", "/");
 
@@ -48,12 +52,69 @@ const segmentsOf = (relative: string): ReadonlyArray<string> =>
     .split("/")
     .filter((segment) => segment.length > 0);
 
-const isMarkdown = (path: string): boolean => path.endsWith(".md");
+/** A rule file, and its path in the directory it was read from. */
+interface RuleFile {
+  readonly id: RuleId;
+  readonly leaf: string;
+}
+
+/**
+ * The rules among `leaves`, the paths in `directory`, whose rules sit under
+ * `prefix` one to a directory: `<id>/RULE.md` or `<id>/RULE.ts`. Anything else
+ * in a rule's directory, such as a helper its RULE.ts imports, is not a rule.
+ * A directory with both files refuses, and so does a Markdown file outside
+ * every rule's directory, but a README.md: before rule directories, it was a
+ * rule, and the refusal says where it goes now to keep its id.
+ */
+const ruleFilesIn = (
+  directory: string,
+  leaves: ReadonlyArray<string>,
+  prefix: string,
+): Effect.Effect<ReadonlyArray<RuleFile>, ConfigUnavailable> => {
+  const files = leaves.flatMap((leaf): ReadonlyArray<RuleFile> => {
+    const segments = segmentsOf(leaf.slice(prefix.length));
+    return leaf.startsWith(prefix) && segments.length > 1 && RULE_FILES.has(segments.at(-1) ?? "")
+      ? [{ id: segments.slice(0, -1).join("/"), leaf }]
+      : [];
+  });
+  const both = files.find((file, index) => files.findIndex(({ id }) => id === file.id) < index);
+  if (both !== undefined) {
+    return Effect.fail(
+      ConfigUnavailable.make({
+        message: `${directory}/${prefix}${both.id}: a rule is a RULE.md or a RULE.ts, not both`,
+      }),
+    );
+  }
+  const homes = files.map(({ leaf }) => leaf.slice(0, leaf.lastIndexOf("/") + 1));
+  const flat = leaves.filter((leaf) => {
+    const name = segmentsOf(leaf).at(-1) ?? "";
+    return (
+      leaf.endsWith(".md") &&
+      !RULE_FILES.has(name) &&
+      name !== "README.md" &&
+      !homes.some((home) => leaf.startsWith(home))
+    );
+  });
+  if (flat.length > 0) {
+    return Effect.fail(
+      ConfigUnavailable.make({
+        message: [
+          `Rules now live one to a directory, as ${directory}/${prefix}<id>/RULE.md or RULE.ts. Move each of these to keep its id:`,
+          ...flat.map(
+            (leaf) =>
+              `  ${directory}/${leaf} → ${directory}/${prefix}${leaf.slice(0, -".md".length)}/RULE.md`,
+          ),
+        ].join("\n"),
+      }),
+    );
+  }
+  return Effect.succeed(files);
+};
 
 /**
  * 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.
+ * directory there such as `.adhere/rules/e2e/` is a rule topic.
  */
 const entersForRules = (relative: string): boolean => {
   const segments = segmentsOf(relative);
@@ -65,45 +126,30 @@ const entersForRules = (relative: string): boolean => {
   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);
-  return (
-    adhere >= 0 &&
-    segments[adhere + 1] !== CACHE_SEGMENT &&
-    isMarkdown(relative) &&
-    // Only the path to the `.adhere/`: `.adhere/e2e/` is a rule topic, not a skip.
-    !segments.slice(0, adhere).some((segment) => SKIPPED_DIRECTORIES.has(segment))
-  );
-};
-
-const rulePathOf = (segments: ReadonlyArray<string>): ReadonlyArray<string> => {
-  const adhere = segments.lastIndexOf(ADHERE_SEGMENT);
-  return adhere < 0 ? [] : segments.slice(adhere + 1);
-};
-
-const scopePathOf = (segments: ReadonlyArray<string>): ReadonlyArray<string> => {
-  const adhere = segments.lastIndexOf(ADHERE_SEGMENT);
-  return adhere < 0 ? [] : segments.slice(0, adhere);
-};
-
-const ruleIdOf = (relative: string): RuleId => {
-  const rulePath = rulePathOf(segmentsOf(relative));
-  const leaf = rulePath.join("/");
-  return leaf.slice(0, -".md".length);
+/**
+ * Each `.adhere/` the walk found, by its path from the root, with the paths
+ * of the files in it. Only the path to a `.adhere/` counts against skipped
+ * trees: `.adhere/rules/e2e/` is a rule topic, not a skip.
+ */
+const adhereDirectoriesOf = (
+  relatives: ReadonlyArray<string>,
+): ReadonlyMap<string, ReadonlyArray<string>> => {
+  const found = new Map<string, Array<string>>();
+  for (const relative of relatives) {
+    const segments = segmentsOf(relative);
+    const adhere = segments.lastIndexOf(ADHERE_SEGMENT);
+    if (adhere < 0 || segments.slice(0, adhere).some((name) => SKIPPED_DIRECTORIES.has(name))) {
+      continue;
+    }
+    const directory = segments.slice(0, adhere + 1).join("/");
+    found.set(directory, [...(found.get(directory) ?? []), segments.slice(adhere + 1).join("/")]);
+  }
+  return found;
 };
 
 const joinPath = (path: Path.Path, root: string, parts: ReadonlyArray<string>): string =>
   parts.reduce((current, part) => path.join(current, part), root);
 
-const scopedRule = (path: Path.Path, root: string, relative: string, rule: Rule): RuleEntry => {
-  const segments = segmentsOf(relative);
-  const scopeParts = scopePathOf(segments);
-  const scope = scopeParts.length === 0 ? path.resolve(root) : joinPath(path, root, scopeParts);
-  const file = joinPath(path, root, segments);
-  return { id: ruleIdOf(relative), file, scope, rule };
-};
-
 const isInside = (file: string, scope: string): boolean =>
   file === scope || file.startsWith(`${scope}/`);
 
@@ -111,9 +157,40 @@ const moreSpecific = (a: RuleEntry, b: RuleEntry): RuleEntry =>
   normalized(a.scope).length >= normalized(b.scope).length ? a : b;
 
 /**
- * Every `*.md` file under `directory`, validated and keyed by its path
- * relative to the directory without the extension: `basics/gen.md` is the
- * rule `basics/gen`.
+ * A rule written in TypeScript: the file's default export, decoded as a
+ * config's inline rule is, so a hook such as `appendState` comes with it.
+ * Like a config, the file is imported, so its code runs.
+ */
+const importRule = Effect.fn("importRule")(function* (file: string) {
+  const path = yield* Path.Path;
+  const url = yield* path.toFileUrl(file).pipe(Effect.orDie);
+  const loaded = yield* Effect.tryPromise({
+    try: () => import(url.href) as Promise<{ readonly default?: unknown }>,
+    catch: (cause) =>
+      ConfigUnavailable.make({
+        message: `Could not load ${file}: ${cause instanceof Error ? cause.message : String(cause)}`,
+      }),
+  });
+  return yield* Schema.decodeUnknownEffect(Rule)(loaded.default).pipe(
+    Effect.mapError((problem) =>
+      ConfigUnavailable.make({
+        message: `${file}: a rule file must default-export defineRule({...}): ${problem.message}`,
+      }),
+    ),
+  );
+});
+
+/** A rule file's rule. A file that cannot be read refuses with the directory it was read from. */
+const readRule = Effect.fn("readRule")(function* (file: string, directory: string) {
+  if (file.endsWith(".ts")) return yield* importRule(file);
+  const fs = yield* FileSystem.FileSystem;
+  const text = yield* fs.readFileString(file).pipe(Effect.mapError(refused(directory)));
+  return yield* parseRuleMarkdown(text, file);
+});
+
+/**
+ * Every rule under `directory`, validated and keyed by its directory's path
+ * in it: `basics/gen/RULE.md` is the rule `basics/gen`.
  */
 export const loadRules = Effect.fn("loadRules")(function* (directory: string) {
   const fs = yield* FileSystem.FileSystem;
@@ -121,19 +198,18 @@ export const loadRules = Effect.fn("loadRules")(function* (directory: string) {
   const entries = yield* fs
     .readDirectory(directory, { recursive: true })
     .pipe(Effect.mapError(refused(directory)));
-  const files = entries.filter((entry) => entry.endsWith(".md")).sort();
-  const rules = yield* Effect.forEach(files, (relative) =>
-    Effect.gen(function* () {
-      const file = path.join(directory, relative);
-      const text = yield* fs.readFileString(file).pipe(Effect.mapError(refused(directory)));
-      const id: RuleId = relative.slice(0, -".md".length).split(path.sep).join("/");
-      return [id, yield* parseRuleMarkdown(text, file)] as const;
-    }),
+  const files = yield* ruleFilesIn(directory, entries.map(normalized).sort(), "");
+  const rules = yield* Effect.forEach(files, ({ id, leaf }) =>
+    Effect.map(readRule(path.join(directory, leaf), directory), (rule) => [id, rule] as const),
   );
   return Record.fromEntries(rules) as Readonly<Record<RuleId, Rule>>;
 });
 
-/** Every nested `.adhere/` rule under `root`, scoped to its owner directory. */
+/**
+ * Every rule in a `.adhere/rules/` under `root`, scoped to the directory that
+ * holds its `.adhere/`: `packages/api/.adhere/rules/data/ports/RULE.md` is
+ * `data/ports` for the files under `packages/api/`.
+ */
 export const loadAdhereRuleSet = Effect.fn("loadAdhereRuleSet")(function* (root: string) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
@@ -145,14 +221,17 @@ export const loadAdhereRuleSet = Effect.fn("loadAdhereRuleSet")(function* (root:
       ),
     ),
   ).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));
-      const text = yield* fs.readFileString(file).pipe(Effect.mapError(refused(root)));
-      return scopedRule(path, root, relative, yield* parseRuleMarkdown(text, file));
+  const found = yield* Effect.forEach(adhereDirectoriesOf(entries), ([adhere, leaves]) =>
+    Effect.flatMap(ruleFilesIn(adhere, [...leaves].sort(), RULES_PREFIX), (files) => {
+      const owner = segmentsOf(adhere).slice(0, -1);
+      const scope = owner.length === 0 ? path.resolve(root) : joinPath(path, root, owner);
+      return Effect.forEach(files, ({ id, leaf }) => {
+        const file = joinPath(path, root, segmentsOf(`${adhere}/${leaf}`));
+        return Effect.map(readRule(file, root), (rule): RuleEntry => ({ id, file, scope, rule }));
+      });
     }),
   );
+  return found.flat();
 });
 
 /** Rules as given, or loaded from the directory a source names. */

package/src/services/AdhereConfig.ts

@@ -1,5 +1,4 @@
 import {
-  ADHERE_DIRECTORY,
   AdhereConfig as AdhereConfigSchema,
   CONFIG_FILES,
   ConfigUnavailable,
@@ -10,6 +9,7 @@ import {
   presetsOf,
   type ResolvedConfig,
   resolveConfig,
+  RULES_DIRECTORY,
 } from "#config.ts";
 import { type PresetName, presetOf, presets, wholePresetOf } from "#presets.ts";
 import {
@@ -21,6 +21,7 @@ import {
   shownId,
   withOverrides,
 } from "#rules.ts";
+import { workspacePackagesOf } from "#workspaces.ts";
 import { Context, Effect, FileSystem, Layer, Path, Record } from "effect";
 
 export class AdhereConfig extends Context.Service<AdhereConfig, ResolvedConfig>()(
@@ -94,7 +95,7 @@ export const AdhereConfigLive = (flags: Flags) =>
       const hasProjectRules = discoveredEntries.length > 0;
       if (configFile === undefined && !hasProjectRules && !hasPreset) {
         return yield* ConfigUnavailable.make({
-          message: `Nothing to audit against: no config file (${CONFIG_FILES.join(", ")}), no ${ADHERE_DIRECTORY}/ directory of rules, and no --preset. Pass --preset effect to use the built-in rules.`,
+          message: `Nothing to audit against: no config file (${CONFIG_FILES.join(", ")}), no rules in ${RULES_DIRECTORY}/, and no --preset. Pass --preset effect to use the built-in rules.`,
         });
       }
       const projectEntries: RuleSet =
@@ -129,6 +130,17 @@ export const AdhereConfigLive = (flags: Flags) =>
           });
         }
       }
-      return AdhereConfig.of({ ...resolved, scopedRules: withOverrides(entries, overrides) });
+      const scopedRules = withOverrides(entries, overrides);
+      // The manifests are read on every run, so a changed workspace is seen, and only when a rule reads them.
+      const workspacePackages = scopedRules.some(
+        (entry) => entry.rule.includeWorkspacePackages === true,
+      )
+        ? yield* workspacePackagesOf(cwd)
+        : undefined;
+      return AdhereConfig.of({
+        ...resolved,
+        scopedRules,
+        ...(workspacePackages === undefined ? {} : { workspacePackages }),
+      });
     }),
   );

package/src/services/Credentials.ts

@@ -46,10 +46,10 @@ export const CredentialsLive = Layer.effect(Credentials)(
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
 
-    const file = Config.nonEmptyString("XDG_CONFIG_HOME").pipe(
+    const file = Config.NonEmptyString("XDG_CONFIG_HOME").pipe(
       Config.orElse(() =>
-        Config.nonEmptyString("HOME").pipe(
-          Config.orElse(() => Config.nonEmptyString("USERPROFILE")),
+        Config.NonEmptyString("HOME").pipe(
+          Config.orElse(() => Config.NonEmptyString("USERPROFILE")),
           Config.map((home) => path.join(home, ".config")),
         ),
       ),
@@ -78,7 +78,7 @@ export const CredentialsLive = Layer.effect(Credentials)(
 
     // Read when a request needs the key, not before: a cached run needs none.
     const apiKey = Effect.fn("Credentials.apiKey")(function* () {
-      const fromEnvironment = yield* Config.option(Config.redacted("TYPESAFE_API_KEY")).pipe(
+      const fromEnvironment = yield* Config.option(Config.Redacted("TYPESAFE_API_KEY")).pipe(
         Effect.mapError((problem) => refused(`Cannot read TYPESAFE_API_KEY: ${problem.message}`)),
       );
       if (Option.isSome(fromEnvironment)) return fromEnvironment.value;