@drkmttr/adhere 0.23.0 → 0.24.1

package/package.json

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

package/skills/adhere/SKILL.md

@@ -121,6 +121,18 @@ Front matter besides `description`, all optional:
 - `tests: only` for a rule about tests, `tests: include` for one that holds in
   tests too. Otherwise rules skip `.test` and `.spec` files and files under
   `test/`, `tests/`, `__tests__/`, and `fixtures/`.
+- `include: {"paths":["src/**"],"content":["from\\s+[\"']effect[\"']"]}`
+  and `exclude: {"paths":["**/generated/**"],"content":["@generated"]}`,
+  JSON objects on one line, filter files locally before requests or cached
+  findings. TypeScript rules use ordinary objects with the same fields.
+  Paths are repository-root-relative globs, even for nested rules. Content
+  patterns are JavaScript regex source strings without delimiters or flags,
+  matched against original text including comments. Invalid regex refuses
+  loading. Entries within each list are alternatives; every nonempty include
+  list must match, and any exclude match vetoes the file. Empty lists impose
+  no restriction. Existing scope, test settings, and ignores still apply.
+  An import regex is not import resolution: check comments, alternative import
+  forms, and re-exports before narrowing a rule and silently missing violations.
 - `appliesTo: ["a declared union type or schema"]` and
   `excludeIf: ["a type that mirrors a third-party format"]`, JSON arrays on
   one line, scope a rule without widening its description: a finding stands
@@ -354,14 +366,18 @@ A convention a linter can decide exactly does not belong in a `RULE.md`.
 Whichever route it takes, the draft is trialled on real files before anything
 is written: the first 100 applicable files by default, the entire repo, or a
 number the user types, with the plan's known cost shown first. The authoring
-agent reads the saved report in `.adhere/trial/` and the source it names, then
-the user accepts the findings, reviews each as correct, a false positive, or
-unsure, or asks for a revision. Findings and examples take optional notes for
-the agent; a revision is re-approved and reruns the same files, so the new
-evidence is comparable. Skipping is allowed, but the write prompt then says
-`(not trialled)` and the closing line says `Not trialled: …`; nothing is called
-validated on a skipped, partial, or stale run. The trial runs for native
-settings and approved plugins too.
+agent reads the saved report in `.adhere/trial/` and the source it names. After
+the first completed adhere trial, it is explicitly asked whether path/content
+filters would help: recommend exact entries or explain why none are needed,
+including the risk of hiding real violations. The user accepts the draft,
+reviews findings, or asks for a revision. Findings and examples take optional
+notes; revisions receive those notes and the filter recommendation, are
+re-approved, and rerun the same sample. Newly filtered files are reported as
+skipped, not replaced. The initial cap counts files that pass filters.
+Skipping is allowed, but the write prompt then says `(not trialled)` and the
+closing line says `Not trialled: …`; nothing is called validated on a skipped,
+partial, or stale run. Native settings and approved plugins are trialled too,
+without adhere-only filter recommendations.
 
 A project plugin and its checked-in test go to
 `.adhere/oxlint/<plugin>.mjs` and `.adhere/oxlint/<plugin>.test.mjs`; the
@@ -395,10 +411,12 @@ Oxlint. `adhere validate` reports rules left over that a linter could check.
 An organization keeps its instructions, rules, and lint settings in one repo,
 scaffolded by `adhere init --shared org/repo`. Its `README.md` carries a
 managed guide between `<!-- adhere:rules:start -->` and
-`<!-- adhere:rules:end -->`: a contents list nesting every rule under its
-topic, the rules grouped by topic with each bold statement and rule id opening
-that rule's `RULE.md` verbatim: examples and explanation, then a source link
-under a stable permalink, every enabled native setting in `oxlint/rules.json`
+`<!-- adhere:rules:end -->`: a contents list linking the rules, lint settings,
+and custom plugin sections. Under a level-two Rules heading, rules sort by
+topic and id without visible topic headings. Each rule id opens an expandable
+entry containing its description, its `RULE.md` examples and explanation,
+and a source link under a stable permalink. The guide also lists every enabled
+native setting in `oxlint/rules.json`
 with its severity, and each custom plugin's enabled rules, linked to
 `oxlint/plugins/<name>.js` when that is a local file. A `RULE.ts` is linked as
 TypeScript source only: the guide never reads or runs it, and plugin code is
@@ -586,6 +604,10 @@ Per rule, read its findings and decide:
 - Many hits at 0.80 to 0.90, mostly not violations: the description is too
   broad. Narrow it, or scope it with `appliesTo` or `excludeIf`, before
   raising its `threshold`: a threshold hides, a sentence explains.
+- Hits in irrelevant files: consider local `include`/`exclude` path or content
+  filters before paying to judge them. Verify the boundary against real
+  violations and unflagged files; an absent import does not prove the library
+  is unused when the project uses wrappers or re-exports.
 - Hits on code that follows the pattern through another API: the `must`
   block is too specific. Use the repo's most general correct example.
 - Right less than half the time and not fixable by wording: `level: warning`,

package/src/config.ts

@@ -71,6 +71,44 @@ export const Reads = Schema.Array(
   Schema.Literals(["workspacePackages", "dependents", "symbols", "references"]),
 );
 
+/**
+ * A JavaScript regular expression's source, checked here so a rule with a bad
+ * pattern fails to load rather than at the first file it would filter.
+ */
+const isValidRegexSource = (source: string): string | undefined => {
+  try {
+    new RegExp(source);
+    return undefined;
+  } catch (problem) {
+    return `is not a valid JavaScript regular expression: ${
+      problem instanceof Error ? problem.message : String(problem)
+    }`;
+  }
+};
+
+const RegexSource = Schema.String.check(
+  Schema.makeFilter(isValidRegexSource, {
+    toCode: () => ({ runtime: "Schema.makeFilter(isValidRegexSource)" }),
+  }),
+);
+
+/**
+ * One side of a rule's file filter: repository-relative globs for paths, and
+ * regular expression sources for the file's text as written. A rule's
+ * `include` and `exclude` each take this shape.
+ */
+export const RuleFilter = Schema.Struct({
+  paths: Schema.optionalKey(Schema.Array(Schema.String)).annotate({
+    description:
+      "Repository-root-relative glob patterns, `/`-separated, as in `src/**` or `**/*.test.ts`.",
+  }),
+  content: Schema.optionalKey(Schema.Array(RegexSource)).annotate({
+    description:
+      "JavaScript regular expression sources, without `/` delimiters or flags, matched against the file's text as written, comments included.",
+  }),
+}).annotate({ identifier: "RuleFilter" });
+export interface RuleFilter extends Schema.Schema.Type<typeof RuleFilter> {}
+
 /**
  * A rule's examples, named in RFC 2119's words, which Jev reads as written. A
  * requirement shows code that `must` be written and code that must `never`
@@ -109,6 +147,14 @@ export const Rule = Schema.Struct({
     description:
       "How a finding under the rule is reported: an `error`, the default, which fails the run, or a `warning`, for a nit or a rule that errs toward false findings, which does not.",
   }),
+  include: Schema.optionalKey(RuleFilter).annotate({
+    description:
+      "Where the rule applies, beside its scope and `tests`: a file must match every configured category, and within `paths` or `content` any entry is enough. An omitted or empty list puts no condition on that category.",
+  }),
+  exclude: Schema.optionalKey(RuleFilter).annotate({
+    description:
+      "Where the rule does not apply: the same shape as `include`. Any matching path or content entry drops the file before it is judged, so no cached finding for it is read or reported.",
+  }),
   appliesTo: Schema.optionalKey(Schema.Array(Schema.String)).annotate({
     description:
       "Where the rule applies, each a description of code that breaks it: Jev is asked of each whether any code that breaks the rule is as it describes, and a finding stands only when it says yes to every one.",

package/src/create/ask.ts

@@ -155,6 +155,17 @@ const readsInstruction = (shape: Shape) => {
   return `Declare the context Jev needs beside the code as \`reads: [${reads.map((read) => `"${read}"`).join(", ")}]\` ${shape.format === "typescript" ? "in `defineRule({...})`" : "in its front matter"}. A rule's \`reads\` is a declaration, not an enablement: the project's config still decides what Jev reads, and lint warns that the rule may be less accurate until a declared read is enabled.`;
 };
 
+/**
+ * What a rule may do to narrow the files it judges at all: a mechanical
+ * filter, taught when a rule is written or revised, never to an oxlint rule.
+ */
+const filtersInstruction = (shape: Shape) =>
+  `A rule may also narrow the files it judges before Jev sees them, with optional \`include\` and \`exclude\` objects. Each holds \`paths\`, globs relative to the repository root with forward slashes, matched as \`--filter\` matches them, and \`content\`, JavaScript regular expression sources without / delimiters or flags, tested against each file's original text, comments included. Any entry in a list suffices; \`include\` applies only when every list it sets matches, while a match in either \`exclude\` list drops the file. An absent object or an empty list restricts nothing. A filter is silent: a file it drops is never judged, so a wrong one is a false negative. Use \`paths\` for where the rule applies and \`content\` for what a file says; a filter is not a substitute for \`appliesTo\` or \`excludeIf\`, which ask Jev about the code. \`content\` can match a named package's import specifier, such as from "effect", or a directive, but a regular expression cannot resolve aliases or re-exports, know whether a name is a type or a value, or reliably tell code from comments and other strings; use \`paths\`, \`appliesTo\`, or a TypeScript rule for that. Because \`content\` entries are strings, escape a regex's backslashes: a regex ^\\s*import is written "^\\\\s*import" in both front matter JSON and a RULE.ts string. ${
+    shape.format === "typescript"
+      ? 'Set them in defineRule({...}) as object literals, such as include: { paths: ["src/**"] }.'
+      : 'Set them in the front matter as one-line JSON objects, such as include: {"paths": ["src/**"]}.'
+  }`;
+
 const typescriptFormat = (shape: Shape) =>
   `Write it as a RULE.ts, because ${shape.formatReason} It imports defineRule from "@drkmttr/adhere" and default-exports defineRule({ description, details, must, never, reads, appendState }). appendState(state, file, Bun) runs before each request for the rule: file is { path, contents }, its path absolute, and Bun is Bun's API, as in Bun.file(path).text() or new Bun.Glob(pattern). What it returns is spread over the request's state; name each key it adds in the description, in backticks. Helpers go in the same file.`;
 
@@ -183,6 +194,8 @@ Rule id: ${id}
 What it enforces: ${idea}
 What Jev reads beside the rule: ${contextOf(shape)}
 ${readsInstruction(shape)}
+${filtersInstruction(shape)}
+Leave them out unless the idea itself names a kind of file, such as API routes or React components; the trial will settle whether they are needed.
 ${shape.format === "typescript" ? typescriptFormat(shape) : "Write it as a RULE.md."}
 
 ${reviewedOf(reviewed)}
@@ -255,6 +268,21 @@ export const inspectionPrompt = (report: string, id: string) =>
 - Concrete changes to the rule's wording or examples, if any.
 Do not edit files. Keep it short.`;
 
+/**
+ * The first trial of an adhere rule asks the authoring agent, explicitly,
+ * whether the rule should narrow which files it judges. A filter is a silent
+ * false negative, so the agent names exact entries or says why none fit.
+ */
+export const filterAdvicePrompt = (report: string, id: string) =>
+  `adhere trialled the adhere rule ${id} on real files without installing it. The full report is at ${report}, and it holds the rule's source. Read the report, the rule, and the files it names, then answer in plain text:
+- Whether the rule should carry \`include\` or \`exclude\` filters at all.
+- If it should, the exact entries, as the rule's file writes them: in a RULE.md's front matter, one-line JSON objects such as include: {"paths": ["src/**"]}; in a RULE.ts, object literals such as include: { paths: ["src/**"] }. Say which list each entry belongs to and what it leaves out or keeps.
+- If it should not, one sentence saying why the rule is better judging every file Jev reads.
+
+Filters are mechanical and silent: a file one leaves out is never judged, so a wrong filter hides real violations. \`paths\` are repository-root-relative globs with forward slashes, matched as \`--filter\` matches them. \`content\` entries are JavaScript regex source strings without / delimiters or flags, tested against original text including comments. Content filters may match a named package's import specifier, for example from "effect". They cannot resolve aliases or re-exports, and matching text in comments or strings does not prove the file imports the package. Escape regex backslashes in JSON and TypeScript strings: the regex ^\\s*import is written "^\\\\s*import". Within each list, any entry may match; all nonempty inclusion lists must match, and a match in either exclusion list vetoes the file. Empty lists impose no restriction. Recommend a filter only when the evidence supports that boundary.
+
+Do not suggest filters for an oxlint rule: those have no such fields. Do not edit files. Keep it short.`;
+
 /** Asks for the adhere rule again, with what the trial found and what the user made of it. */
 export const adhereRevisionPrompt = (
   idea: string,
@@ -269,6 +297,8 @@ export const adhereRevisionPrompt = (
 Revise the adhere rule ${id}. It enforces: ${idea}
 What Jev reads beside the rule: ${contextOf(shape)}
 ${readsInstruction(shape)}
+${filtersInstruction(shape)}
+Apply, change, or remove \`include\` and \`exclude\` as the trial, the recommendation, and the user's verdicts support; keep a filter only while the evidence supports it.
 ${shape.format === "typescript" ? typescriptFormat(shape) : "Write it as a RULE.md."}
 
 A trial judged real files against the current rule. What it found, and what the user made of it:
@@ -279,7 +309,7 @@ The current file:
 
 ${draft}
 
-Keep what the evidence supports and change what it contradicts. Reply with only the corrected file, starting with its ${shape.format === "typescript" ? "imports" : "front matter"}.`;
+Keep what the evidence supports and change what it contradicts, including its filter recommendation. Reply with only the corrected file, starting with its ${shape.format === "typescript" ? "imports" : "front matter"}.`;
 
 /** Asks for the oxlint plugin again, with what the trial found and what the user made of it. */
 export const pluginRevisionPrompt = (

package/src/create/look.ts

@@ -4,7 +4,6 @@
  * rail, and a spinner, as `gum spin` draws one, while an agent works.
  */
 import { highlightedLines } from "#workflows/format.ts";
-import { ruleBodyOf } from "#markdown.ts";
 import { Status, clearingStatus } from "#services/Status.ts";
 import { Console, Duration, Effect, Fiber } from "effect";
 import { Prompt } from "effect/cli";
@@ -61,23 +60,16 @@ const columns = () => process.stderr.columns ?? 80;
 export const indented = (text: string) =>
   Bun.wrapAnsi(text, Math.max(columns() - 5, 20)).replaceAll("\n", "\n    ");
 
-/**
- * Renders the body of a rule for preview, preserving its YAML frontmatter.
- * The frontmatter is shown as-is so its metadata stays visible; the body is
- * rendered with Bun's native Markdown-to-ANSI renderer.
- */
+/** Renders Markdown for preview with Bun's native Markdown-to-ANSI renderer. */
 export const renderMarkdown = (text: string) =>
   Effect.gen(function* () {
     const theme = yield* Prompt.Theme;
-    const body = ruleBodyOf(text);
-    const prefix = text.slice(0, text.length - body.length);
-    const rendered = Bun.markdown
-      .ansi(body, {
+    return Bun.markdown
+      .ansi(text, {
         colors: theme.colors,
         columns: Math.max(columns() - 4, 20),
       })
       .trimEnd();
-    return prefix + rendered;
   });
 
 type Color = (theme: Prompt.Theme) => string;

package/src/create/trial-review.ts

@@ -8,8 +8,8 @@
  * explicitly untested; it never counts as validation.
  */
 import { type Agent } from "#create/agents.ts";
-import { RuleNotCreated, asking, inspectionPrompt } from "#create/ask.ts";
-import { line, note, said, spinning, warn } from "#create/look.ts";
+import { RuleNotCreated, asking, filterAdvicePrompt, inspectionPrompt } from "#create/ask.ts";
+import { line, note, renderMarkdown, said, spinning, warn } from "#create/look.ts";
 import {
   type TrialDraft,
   type TrialFinding,
@@ -128,7 +128,11 @@ const showPreview = (scope: TrialScope, preview: TrialPreview) =>
     if (preview.deferred > 0) {
       yield* note(`${filesWord(preview.deferred)} wait for a later run.`);
     }
-    if (preview.skipped > 0) yield* note(`${filesWord(preview.skipped)} skipped as too long.`);
+    if (preview.skipped > 0) {
+      yield* note(
+        `${filesWord(preview.skipped)} skipped (too long, or left out by the rule's filters).`,
+      );
+    }
     if (preview.requests === 0) {
       yield* note("Nothing to send: the selected files have no pending requests.");
     }
@@ -265,7 +269,7 @@ const showRun = (run: TrialRun) =>
     );
     yield* note(`${run.findings.length} finding${run.findings.length === 1 ? "" : "s"}.`);
     if (run.judged === 0 && run.files > 0) {
-      yield* note("Every selected file was cached; no request was sent.");
+      yield* note("No request was sent: every selected file was cached or skipped.");
     }
     yield* note(`Report: ${run.reportPath}`);
     for (const limitation of run.notes) yield* note(limitation);
@@ -286,6 +290,36 @@ const inspect = <D, R>(subject: TrialSubject<D, R>, run: TrialRun) =>
     Effect.catch((cause) => Effect.succeed({ _tag: "Failed", message: messageOf(cause) } as const)),
   );
 
+type Advice =
+  | { readonly _tag: "Text"; readonly text: string }
+  | { readonly _tag: "Failed"; readonly message: string }
+  | { readonly _tag: "None" };
+
+/**
+ * The first adhere trial asks the authoring agent whether the rule should
+ * filter files. An oxlint rule has no filter fields, and a rerun already has
+ * the answer.
+ */
+const filterAdvice = <D, R>(subject: TrialSubject<D, R>, run: TrialRun, first: boolean) =>
+  first && run.draft.kind === "adhere"
+    ? spinning(
+        `Asking ${subject.agent} whether the rule needs filters`,
+        asking(
+          subject.agent,
+          "to recommend filters",
+          subject.root,
+          filterAdvicePrompt(run.reportPath, subject.id),
+        ),
+      ).pipe(
+        Effect.map((text): Advice =>
+          text.trim() === "" ? { _tag: "None" } : { _tag: "Text", text: text.trim() },
+        ),
+        Effect.catch((cause): Effect.Effect<Advice> =>
+          Effect.succeed({ _tag: "Failed", message: messageOf(cause) }),
+        ),
+      )
+    : Effect.succeed<Advice>({ _tag: "None" });
+
 const MAX_SHOWN = 40;
 
 const showFindings = (run: TrialRun) =>
@@ -421,14 +455,27 @@ const reviewFindings = (run: TrialRun) =>
       : ({ _tag: "Cancel" } as const);
   });
 
-/** What the agent reads when revising: the report, the counts, and the user's verdicts. */
-export const trialEvidence = (run: TrialRun, reviews: ReadonlyArray<FindingReview>) => {
+/**
+ * What the agent reads when revising: the report, the counts, the filter
+ * recommendation the first trial asked for, and the user's verdicts.
+ */
+export const trialEvidence = (
+  run: TrialRun,
+  reviews: ReadonlyArray<FindingReview>,
+  advice?: string,
+) => {
   const lines = [
     `Trial report: ${run.reportPath}`,
     `Scope: ${run.scope.kind === "all" ? "the entire repo" : `the first ${run.scope.limit} files`}; ${filesWord(run.selectedFiles.length)} selected.`,
     `Counts: ${run.files} files, ${run.judged} judged, ${run.cached} cached, ${run.skipped} skipped, ${run.waiting} waiting.`,
     `Findings: ${run.findings.length}.`,
   ];
+  if (advice !== undefined) {
+    lines.push(
+      "The agent's filter recommendation from the first trial. It is historical: the latest trial report and the user's verdicts decide, and a filter the evidence contradicts should be removed.",
+    );
+    lines.push(advice);
+  }
   if (reviews.length > 0) {
     lines.push("The user's verdicts:");
     for (const review of reviews) {
@@ -497,6 +544,8 @@ export const trialAndReview = <D, R>(subject: TrialSubject<D, R>) =>
     yield* showPreview(scope, preview.preview);
 
     let pinned: ReadonlyArray<string> | undefined;
+    let firstRun = true;
+    let advice: string | undefined;
     for (;;) {
       const result = yield* runOnce(subject, draft, scope, pinned);
       if (result._tag === "Failed") {
@@ -510,10 +559,24 @@ export const trialAndReview = <D, R>(subject: TrialSubject<D, R>) =>
       yield* showRun(run);
       const inspection = yield* inspect(subject, run);
       if (inspection._tag === "Text") {
-        if (inspection.text.trim() !== "") yield* line(inspection.text.trim());
+        if (inspection.text.trim() !== "") {
+          yield* line(yield* renderMarkdown(inspection.text.trim()));
+        }
       } else {
         yield* warn(`The agent could not read the report: ${inspection.message}`);
       }
+      const filters = yield* filterAdvice(subject, run, firstRun);
+      firstRun = false;
+      if (filters._tag === "Text") {
+        advice = filters.text;
+        yield* note("The agent's filter recommendation:");
+        yield* line(filters.text);
+        yield* note(
+          "Accept the draft as it is, or ask the agent to revise it with this recommendation.",
+        );
+      } else if (filters._tag === "Failed") {
+        yield* warn(`The agent could not recommend filters: ${filters.message}`);
+      }
       const decision = yield* reviewFindings(run);
       if (decision._tag === "Accept") {
         return { _tag: "Accepted", draft, run, reviews: decision.reviews } as const;
@@ -521,7 +584,7 @@ export const trialAndReview = <D, R>(subject: TrialSubject<D, R>) =>
       if (decision._tag === "Cancel") {
         return { _tag: "Cancelled", draft, reason: "The trial was cancelled." } as const;
       }
-      const revised = yield* subject.revise(draft, trialEvidence(run, decision.reviews));
+      const revised = yield* subject.revise(draft, trialEvidence(run, decision.reviews, advice));
       yield* subject.show(revised);
       const again = yield* approved(subject, revised);
       if (again._tag === "Declined") {

package/src/create/trial.ts

@@ -29,7 +29,9 @@ import {
   type TrialRun,
   type TrialScope,
 } from "#create/oxlint-trial.ts";
+import { filtersNeedText, hasFilters, ruleAppliesTo } from "#filters.ts";
 import { parseRuleMarkdown } from "#markdown.ts";
+import { WalkUnavailable } from "#models/Audit.ts";
 import { importRule, judgesFile } from "#rules.ts";
 import {
   AdhereConfig,
@@ -176,27 +178,70 @@ const eligibleFiles = (root: string, config: ResolvedConfig) =>
   });
 
 interface Selection {
+  /** The files planning may judge: the selected sample, less those filters leave out. */
   readonly files: ReadonlyArray<SourceFile>;
   /** Sorted repo-relative paths, exactly as run and as the report names them. */
   readonly paths: ReadonlyArray<string>;
   /** Applicable files before the cap. */
   readonly eligible: number;
+  /** Pinned paths the draft's filters now leave out: kept in the sample, never planned. */
+  readonly excluded: ReadonlyArray<string>;
 }
 
-/** The cap is on files, cached ones included; a pinned rerun keeps its exact set. */
+/**
+ * Which candidate files the draft's own include/exclude filters allow. Only a
+ * content filter reads the file; a path-only filter is decided from its path,
+ * and an unfiltered rule allows every file.
+ */
+const allowedFiles = (
+  rule: Rule,
+  walker: SourceWalker["Service"],
+  candidates: ReadonlyArray<SourceFile>,
+  root: string,
+): Effect.Effect<ReadonlyMap<SourceFile, boolean>, WalkUnavailable> => {
+  if (!hasFilters(rule)) return Effect.succeed(new Map());
+  if (!filtersNeedText(rule)) {
+    return Effect.succeed(
+      new Map(
+        candidates.map(
+          (file) => [file, ruleAppliesTo(rule, display(root, file.path), "")] as const,
+        ),
+      ),
+    );
+  }
+  return Effect.forEach(
+    candidates,
+    (file) =>
+      Effect.map(walker.read(file), ({ lines }) => {
+        const allowed = ruleAppliesTo(rule, display(root, file.path), lines.join("\n"));
+        return [file, allowed] as const;
+      }),
+    { concurrency: 8 },
+  ).pipe(Effect.map((verdicts) => new Map(verdicts)));
+};
+
+/**
+ * The cap is on files, cached ones included, and filters apply before it on a
+ * first run. A pinned rerun keeps its exact set: files the draft's filters now
+ * leave out stay in the sample but are not planned, so before and after remain
+ * comparable. A file that is missing, or ineligible for any other reason, is
+ * still an error rather than a skip.
+ */
 const selectionOf = (
   root: string,
   eligible: ReadonlyArray<SourceFile>,
   applies: (file: SourceFile) => boolean,
   scope: TrialScope,
   pinned: ReadonlyArray<string> | undefined,
+  allowed: ReadonlyMap<SourceFile, boolean> = new Map(),
 ): Effect.Effect<Selection, TrialUnavailable> =>
   Effect.gen(function* () {
-    const sorted = [...eligible].filter(applies).sort((a, b) => a.path.localeCompare(b.path));
-    const paths = sorted.map((file) => display(root, file.path));
+    const candidates = [...eligible].filter(applies).sort((a, b) => a.path.localeCompare(b.path));
+    const allowedByPath = (file: SourceFile) => allowed.get(file) !== false;
+    const sorted = candidates.filter(allowedByPath);
     if (pinned !== undefined) {
       const wanted = [...new Set(pinned.map(normalized))];
-      const known = new Map(sorted.map((file, index) => [paths[index]!, file]));
+      const known = new Map(candidates.map((file) => [display(root, file.path), file] as const));
       const missing = wanted.filter((file) => !known.has(file));
       if (missing.length > 0) {
         return yield* trialError(
@@ -204,10 +249,13 @@ const selectionOf = (
           `The pinned trial files are no longer eligible: ${missing.join(", ")}. Run the trial again without pinned files.`,
         );
       }
+      const files = wanted.map((file) => known.get(file)!);
+      const excluded = files.filter((file) => !allowedByPath(file));
       return {
-        files: wanted.map((file) => known.get(file)!),
+        files: files.filter(allowedByPath),
         paths: wanted,
         eligible: sorted.length,
+        excluded: excluded.map((file) => display(root, file.path)),
       };
     }
     const limit = scope.kind === "files" ? scope.limit : undefined;
@@ -222,6 +270,7 @@ const selectionOf = (
       files: chosen,
       paths: chosen.map((file) => display(root, file.path)),
       eligible: sorted.length,
+      excluded: [],
     };
   });
 
@@ -245,7 +294,12 @@ const planTrial = (
 
 const requestsOf = (plan: AuditPlan): number => plan.requests + (plan.cachedLocateRequests ?? 0);
 
-const previewOf = (plan: AuditPlan, eligible: number, selected: number): TrialPreview => ({
+const previewOf = (
+  plan: AuditPlan,
+  eligible: number,
+  selected: number,
+  filteredOut = 0,
+): TrialPreview => ({
   eligible,
   selected,
   requests: requestsOf(plan),
@@ -253,7 +307,7 @@ const previewOf = (plan: AuditPlan, eligible: number, selected: number): TrialPr
   ...(plan.price === undefined ? {} : { price: plan.price }),
   cached: plan.cached,
   deferred: plan.deferred,
-  skipped: plan.skipped,
+  skipped: plan.skipped + filteredOut,
   model: plan.model,
   ...(plan.provider === undefined ? {} : { provider: plan.provider }),
 });
@@ -346,19 +400,15 @@ export const previewTrial = (draft: TrialDraft, scope: TrialScope, options: Tria
       const rule = yield* draftRule(draft);
       const config = yield* draftConfig(root, raw, draft.id, rule);
       const { walker, files } = yield* eligibleFiles(root, config);
-      const selected = yield* selectionOf(
-        root,
-        files,
-        (file) => judgesFile(rule, file.test === true),
-        scope,
-        options.files,
-      );
+      const applies = (file: SourceFile) => judgesFile(rule, file.test === true);
+      const allowed = yield* allowedFiles(rule, walker, files.filter(applies), root);
+      const selected = yield* selectionOf(root, files, applies, scope, options.files, allowed);
       const cache = options.services?.cache ?? AuditCacheAt(root);
       const context = yield* Layer.build(
         Layer.mergeAll(Layer.succeed(AdhereConfig, config), cache),
       );
       const plan = yield* planTrial(selected, walker, context, root);
-      return previewOf(plan, selected.eligible, selected.paths.length);
+      return previewOf(plan, selected.eligible, selected.paths.length, selected.excluded.length);
     }),
   ).pipe(
     Effect.catchTag("ConfigUnavailable", (problem) =>
@@ -454,13 +504,9 @@ export const runTrial = (draft: TrialDraft, scope: TrialScope, options: TrialRun
       const rule = yield* draftRule(draft);
       const config = yield* draftConfig(root, raw, draft.id, rule);
       const { walker, files } = yield* eligibleFiles(root, config);
-      const selected = yield* selectionOf(
-        root,
-        files,
-        (file) => judgesFile(rule, file.test === true),
-        scope,
-        options.files,
-      );
+      const applies = (file: SourceFile) => judgesFile(rule, file.test === true);
+      const allowed = yield* allowedFiles(rule, walker, files.filter(applies), root);
+      const selected = yield* selectionOf(root, files, applies, scope, options.files, allowed);
       const cache = options.services?.cache ?? AuditCacheAt(root);
       const jev =
         options.services?.jev ??
@@ -523,6 +569,11 @@ export const runTrial = (draft: TrialDraft, scope: TrialScope, options: TrialRun
               `${result.skipped} selected files were too long to judge with this rule and its context.`,
             ]
           : []),
+        ...(selected.excluded.length > 0
+          ? [
+              `${selected.excluded.length} pinned files are no longer in the draft's include/exclude filters and were skipped: ${selected.excluded.join(", ")}.`,
+            ]
+          : []),
         ...(config.typeAware
           ? [
               "Type-aware reads were requested; symbols and references came from the installed TypeScript compiler.",
@@ -540,6 +591,7 @@ export const runTrial = (draft: TrialDraft, scope: TrialScope, options: TrialRun
           scope,
           eligible: selected.eligible,
           selectedFiles: selected.paths,
+          ...(selected.excluded.length === 0 ? {} : { excludedFiles: selected.excluded }),
           plan: {
             model: plan.model,
             ...(plan.provider === undefined ? {} : { provider: plan.provider }),
@@ -570,10 +622,10 @@ export const runTrial = (draft: TrialDraft, scope: TrialScope, options: TrialRun
         scope,
         revision,
         selectedFiles: selected.paths,
-        files: result.files,
+        files: result.files + selected.excluded.length,
         judged: result.judged,
         cached: result.cached,
-        skipped: result.skipped,
+        skipped: result.skipped + selected.excluded.length,
         waiting: result.waiting,
         findings: result.findings.map((finding) => trialFinding(root, finding)),
         reportPath,

package/src/create/wizard.ts

@@ -37,7 +37,7 @@ import {
   warn,
 } from "#create/look.ts";
 import { cloned } from "#install.ts";
-import { parseRuleMarkdown } from "#markdown.ts";
+import { parseRuleMarkdown, ruleBodyOf } from "#markdown.ts";
 import { isSharedRepo, refreshIndexIfShared, refreshReadme, validateReadme } from "#readme.ts";
 import { importRule } from "#rules.ts";
 import { findConfigFile, loadConfigFile } from "#services/AdhereConfig.ts";
@@ -141,8 +141,10 @@ const problemsOf = (text: string, file: string, format: Shape["format"]) =>
  */
 const showDraft = (text: string, format: Shape["format"]) =>
   Effect.gen(function* () {
-    const shown = format === "markdown" ? yield* renderMarkdown(text) : text;
-    yield* line(`\n${shown}\n`);
+    if (format !== "markdown") return yield* line(`\n${text}\n`);
+    const body = ruleBodyOf(text);
+    const frontmatter = text.slice(0, text.length - body.length);
+    yield* line(`\n${frontmatter}${yield* renderMarkdown(body)}\n`);
   });
 
 /** A RULE.ts that imported, with its wording strays, or one that did not import. */

package/src/filters.ts

@@ -0,0 +1,86 @@
+import type { Rule, RuleFilter } from "#config.ts";
+import { matchesGlob } from "node:path";
+
+/** A repository path as every matcher here reads it: `/`-separated, without a leading `./`. */
+export const normalizedPath = (path: string): string =>
+  path.replaceAll("\\", "/").replace(/^\.\//, "");
+
+interface CompiledSide {
+  readonly paths: ReadonlyArray<string>;
+  readonly content: ReadonlyArray<RegExp>;
+}
+
+interface CompiledFilters {
+  readonly include: CompiledSide;
+  readonly exclude: CompiledSide;
+}
+
+const compiled = new WeakMap<Pick<Rule, "include" | "exclude">, CompiledFilters>();
+
+const compileSide = (filter: RuleFilter | undefined): CompiledSide => ({
+  paths: (filter?.paths ?? []).map(normalizedPath),
+  // Validated when the rule was decoded, so this cannot throw here.
+  content: (filter?.content ?? []).map((source) => new RegExp(source)),
+});
+
+/**
+ * A rule's filters, compiled once per rule: its globs with `/` separators, and
+ * its content patterns as regular expressions. Both sides are kept, since
+ * `include` and `exclude` differ only in what a match means.
+ */
+export const compiledFiltersOf = (rule: Pick<Rule, "include" | "exclude">): CompiledFilters => {
+  const held = compiled.get(rule);
+  if (held !== undefined) return held;
+  const filters = { include: compileSide(rule.include), exclude: compileSide(rule.exclude) };
+  compiled.set(rule, filters);
+  return filters;
+};
+
+/** Whether a rule has either filter, so a run can leave unfiltered rules untouched. */
+export const hasFilters = (rule: Pick<Rule, "include" | "exclude">): boolean =>
+  rule.include !== undefined || rule.exclude !== undefined;
+
+/** Whether a rule's content patterns, if any, need the file's text to decide. */
+export const filtersNeedText = (rule: Pick<Rule, "include" | "exclude">): boolean => {
+  const { include, exclude } = compiledFiltersOf(rule);
+  return include.content.length > 0 || exclude.content.length > 0;
+};
+
+const matchesAnyPath = (path: string, patterns: ReadonlyArray<string>): boolean =>
+  patterns.some((pattern) => matchesGlob(path, pattern));
+
+/**
+ * Whether a repository-relative path passes a rule's path filters alone: an
+ * `include.paths` list must match when it has entries, and any
+ * `exclude.paths` match drops the file even when it matched.
+ */
+export const pathsPass = (rule: Rule, relativePath: string): boolean => {
+  const { include, exclude } = compiledFiltersOf(rule);
+  const path = normalizedPath(relativePath);
+  return (
+    (include.paths.length === 0 || matchesAnyPath(path, include.paths)) &&
+    !(exclude.paths.length > 0 && matchesAnyPath(path, exclude.paths))
+  );
+};
+
+/**
+ * Whether a rule's content filters allow `text`, the file as written: any
+ * `include` entry matches, and no `exclude` entry does. A path fix for one
+ * file cannot change between planning and execution, so reloading a file
+ * rechecks only this half.
+ */
+export const contentPasses = (rule: Rule, text: string): boolean => {
+  const { include, exclude } = compiledFiltersOf(rule);
+  return (
+    (include.content.length === 0 || include.content.some((pattern) => pattern.test(text))) &&
+    !(exclude.content.length > 0 && exclude.content.some((pattern) => pattern.test(text)))
+  );
+};
+
+/**
+ * Whether a rule applies to a file at a repository-relative path whose text
+ * is `text`: `pathsPass` and `contentPasses`. An `include` category that is
+ * set must match, while a match in any `exclude` category drops the file.
+ */
+export const ruleAppliesTo = (rule: Rule, relativePath: string, text: string): boolean =>
+  pathsPass(rule, relativePath) && contentPasses(rule, text);

package/src/markdown.ts

@@ -1,4 +1,4 @@
-import { ConfigUnavailable, type Example, Reads, type Rule } from "#config.ts";
+import { ConfigUnavailable, type Example, Reads, type Rule, RuleFilter } from "#config.ts";
 import { Effect, Schema } from "effect";
 
 /**
@@ -34,16 +34,25 @@ import { Effect, Schema } from "effect";
  * `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"]`.
+ * `include` and `exclude`, its file filters, are JSON objects on one line, as
+ * in `include: {"paths": ["src/**"], "content": ["^import"]}`: a file
+ * must match every `include` category, any match in a category is enough, and
+ * any `exclude` match drops it. `content` takes regular expression sources
+ * matched against the file as written, comments included.
  * `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));
+/** A filter object on one line, as in `include: {"paths": ["src/**"]}`. */
+const Filters = Schema.fromJsonString(RuleFilter);
 
 const FrontMatter = Schema.Struct({
   description: Schema.String,
   threshold: Schema.optionalKey(Schema.FiniteFromString),
   tests: Schema.optionalKey(Schema.Literals(["only", "include"])),
   level: Schema.optionalKey(Schema.Literals(["error", "warning"])),
+  include: Schema.optionalKey(Filters),
+  exclude: Schema.optionalKey(Filters),
   appliesTo: Schema.optionalKey(Matchers),
   excludeIf: Schema.optionalKey(Matchers),
   reads: Schema.optionalKey(Schema.fromJsonString(Reads)),

package/src/readme-guide.ts

@@ -356,15 +356,15 @@ const ruleEntry = (rule: ReadmeRule, anchor: string, used: Set<string>): Readonl
     `<a id="${anchor}"></a>`,
     "",
     "<details>",
-    rule.name === "RULE.ts"
-      ? `<summary><strong>TypeScript rule</strong> ${label}</summary>`
-      : `<summary><strong>${statement}</strong> ${label}</summary>`,
+    `<summary><h3>${label}</h3></summary>`,
     "",
     ...(rule.name === "RULE.ts"
       ? [
           `This rule is TypeScript, so the guide does not read or run it: [\`${rule.id}\`](${source}).`,
         ]
       : [
+          statement,
+          "",
           ...(body === "" ? [] : [embedBody(source, anchor, body, used), ""]),
           `Source: [\`${rule.id}\`](${source}).`,
         ]),
@@ -374,32 +374,25 @@ const ruleEntry = (rule: ReadmeRule, anchor: string, used: Set<string>): Readonl
 };
 
 /**
- * The managed block's body: a contents list naming every rule, each topic's
- * rules as expandable entries, then the lint settings and plugins. Rules sort
- * by id and topics by name, so the same checkout always writes the same text.
+ * The managed block's body: section links, rules as expandable entries, then
+ * the lint settings and plugins. Rules sort by id and topics by name, so the
+ * same checkout always writes the same text.
  */
 export const renderReadmeIndex = (rules: ReadonlyArray<ReadmeRule>, config: LintConfig): string => {
   const entries = lintEntries(config);
   const { topics, used } = topicsOf(rules);
   const contents = [
     `- [Rules](#${RULES_ANCHOR})`,
-    ...topics.flatMap(({ name, anchor, rules: group }) => [
-      `  - [\`${name}\`](#${anchor})`,
-      ...group.map(({ rule, anchor: at }) => `    - [\`${rule.id}\`](#${at})`),
-    ]),
     `- [Lint settings](#${LINT_SETTINGS_ANCHOR})`,
     `- [Custom lint plugins](#${PLUGINS_ANCHOR})`,
   ];
   const body =
     topics.length === 0
       ? ["- None.", ""]
-      : topics.flatMap(({ name, anchor, rules: group }) => [
+      : topics.flatMap(({ anchor, rules: group }) => [
           `<a id="${anchor}"></a>`,
           "",
-          `#### ${name}`,
-          "",
           ...group.flatMap(({ rule, anchor: at }) => [...ruleEntry(rule, at, used), ""]),
-          backToContents,
           "",
         ]);
   return [
@@ -411,7 +404,7 @@ export const renderReadmeIndex = (rules: ReadonlyArray<ReadmeRule>, config: Lint
     "",
     `<a id="${RULES_ANCHOR}"></a>`,
     "",
-    "### Rules",
+    "## Rules",
     "",
     ...body,
     `<a id="${LINT_SETTINGS_ANCHOR}"></a>`,

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;
 });
 
@@ -455,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.
@@ -501,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