@drkmttr/adhere 0.9.5 → 0.11.0

package/src/services/Jev.ts

@@ -1,4 +1,5 @@
 import { type Example, examplesOf, type Rule, type RuleId, type Rules } from "#config.ts";
+import { type Range, sectionsOf } from "#excerpt.ts";
 import { Context, type Effect, Record, Schema } from "effect";
 
 export type { Rules };
@@ -24,12 +25,20 @@ export class JevBlocked extends Schema.TaggedError<JevBlocked>()("JevBlocked", {
   ray: Schema.String,
 }) {}
 
+/** Jev's probability for each of a rule's matchers, in the order the rule lists them. */
+export interface MatcherScores {
+  readonly appliesTo: ReadonlyArray<number>;
+  readonly excludeIf: ReadonlyArray<number>;
+}
+
 /** What judging a file answers: per rule, whether it breaks it, and the linter check's answers. */
 export interface Judged {
   /** Per rule, Jev's probability that the file breaks it. */
   readonly probabilities: Readonly<Record<RuleId, number>>;
   /** Per sampled rule, Jev's probability that a regular linter could have decided the file against it. */
   readonly linter: Readonly<Record<RuleId, number>>;
+  /** Per rule with `appliesTo` or `excludeIf`, the scores of its matchers. */
+  readonly matchers?: Readonly<Record<RuleId, MatcherScores>>;
 }
 
 export class Jev extends Context.Service<
@@ -45,10 +54,15 @@ export class Jev extends Context.Service<
       rules: Rules,
       sampled?: ReadonlyArray<RuleId>,
     ) => Effect.Effect<Judged, JevUnavailable | JevOverflow | JevBlocked>;
+    /**
+     * Per rule, the section of the file that most clearly breaks it, and
+     * whether the file shows enough to decide. A rule Jev answers either
+     * question for with nothing it offered is left out.
+     */
     readonly locate: (
       lines: Lines,
       rules: Rules,
-    ) => Effect.Effect<Record<RuleId, number>, JevUnavailable | JevOverflow | JevBlocked>;
+    ) => Effect.Effect<Record<RuleId, Located>, JevUnavailable | JevOverflow | JevBlocked>;
     /**
      * Per rule, the partner Jev names as impossible to follow in the same code,
      * as `[rule, partner]` indexes into `rules`. A rule Jev names none for is
@@ -69,6 +83,15 @@ export class Jev extends Context.Service<
   }
 >()("@drkmttr/adhere/services/Jev") {}
 
+/** Where a finding is, and how sure Jev is that the file shows enough to decide it. */
+export interface Located {
+  readonly section: Range;
+  /** Jev's probability that everything judging the rule turns on is in the file. */
+  readonly sufficiency: number;
+  /** The lines in the section the code that breaks the rule starts and ends on, when Jev named them. */
+  readonly lines?: Range;
+}
+
 /** A rule compared with other rules rather than with a file. */
 export interface ComparedRule {
   readonly id: RuleId;
@@ -78,10 +101,8 @@ export interface ComparedRule {
 /** Two rules, as indexes into the rules being compared. */
 export type Pair = readonly [number, number];
 
-/** A `choice` question accepts at most this many criteria. */
+/** A `choice` question accepts at most this many criteria, so a file has at most this many sections. */
 const CHOICE_LIMIT = 255;
-const LINES_PER_BLOCK = 20;
-const MAX_LINES = CHOICE_LIMIT * LINES_PER_BLOCK;
 
 /**
  * Jev 1.13's context, from its model card: the state with its longest
@@ -103,16 +124,19 @@ const encoder = new TextEncoder();
 export const tokensOf = (value: unknown): number =>
   Math.ceil(encoder.encode(JSON.stringify(value)).length / 3);
 
-const snippetOf = (line: string): string => line.trim().slice(0, 120);
-
-const isBlank = (line: string): boolean => line.trim().length === 0;
-
-export const needsBlocks = (lines: Lines): boolean =>
-  lines.filter((line) => !isBlank(line)).length > CHOICE_LIMIT;
-
-/** The file, numbered so a line question can name a line. The only thing the questions share. */
+/**
+ * The file as Jev reads it: its sections, by `sectionsOf`, under their
+ * numbers from 1, so the locate question can name one. The only thing the
+ * questions share. On the eval it judged as well as the file with every line
+ * numbered, and located as well as a choice among the lines.
+ */
 const stateOf = (lines: Lines) => ({
-  code: lines.map((line, index) => `${index + 1} | ${line}`).join("\n"),
+  code: Object.fromEntries(
+    sectionsOf(lines).map((section, index) => [
+      String(index + 1),
+      lines.slice(section.first - 1, section.last).join("\n"),
+    ]),
+  ),
 });
 
 /** The field an example goes under in a question: its word, with `should not` as `should_not`. */
@@ -187,7 +211,7 @@ export const judgeQuestion = (rule: Rule) => {
   };
 };
 
-/** What the offending line does, for the line and block questions. */
+/** What the offending section does, for the locate question. */
 const offense = (rule: Rule): string => {
   const { good, bad } = examplesOf(rule);
   const avoided = `\`${fieldOf(bad ?? { word: "never", code: "" })}\``;
@@ -198,15 +222,6 @@ const offense = (rule: Rule): string => {
       : `diverges from \`${fieldOf(good)}\` or resembles ${avoided}`;
 };
 
-const lineCriteria = (lines: Lines, from: number, to: number): Record<string, string> => {
-  const criteria: Record<string, string> = {};
-  for (let n = from; n <= Math.min(to, lines.length); n++) {
-    const text = lines[n - 1] ?? "";
-    if (!isBlank(text)) criteria[String(n)] = snippetOf(text);
-  }
-  return criteria;
-};
-
 /**
  * The linter check's question: whether a regular linter could have decided
  * `code` against the rule. It carries the judge question's fields, so Jev
@@ -232,11 +247,56 @@ export const linterQuestion = (rule: Rule) => {
 /** The key a rule's linter question rides under, beside its judge question. */
 export const linterKey = (id: RuleId): string => `linter:${id}`;
 
+type MatcherKind = keyof MatcherScores;
+
+/**
+ * A matcher's question: whether the code that breaks the rule is as the
+ * matcher describes. It asks about that code rather than the file, so a file
+ * with a real violation beside code a matcher excludes keeps its finding: for
+ * `appliesTo`, whether any of that code is as described, and for `excludeIf`,
+ * whether all of it is. It carries the rule as the judge question does.
+ */
+export const matcherQuestion = (rule: Rule, kind: MatcherKind, matcher: string) => {
+  const { instructions } = judgeQuestion(rule);
+  const [quantity, yes, no] =
+    kind === "appliesTo" ? ["any", "Some", "None"] : ["all", "All", "Not all"];
+  return {
+    type: "noul" as const,
+    instructions: {
+      ...instructions,
+      question: `Is ${quantity} of the code in \`code\` that breaks \`rule\` as \`matcher\` describes? Answer no if no code in \`code\` breaks \`rule\`.`,
+      matcher,
+    },
+    criteria: {
+      true: `${yes} of the code in \`code\` that breaks \`rule\` is as \`matcher\` describes`,
+      false: `${no} of the code in \`code\` that breaks \`rule\` is as \`matcher\` describes, or no code in \`code\` breaks \`rule\``,
+    },
+  };
+};
+
+/** The key a rule's matcher question rides under, beside its judge question. */
+export const matcherKey = (kind: MatcherKind, id: RuleId, index: number): string =>
+  `${kind}:${id}:${index}`;
+
+const MATCHER_KINDS: ReadonlyArray<MatcherKind> = ["appliesTo", "excludeIf"];
+
+/** A rule's matcher questions under their keys, `appliesTo` first, each in the rule's order. */
+export const matcherQuestions = (id: RuleId, rule: Rule) =>
+  MATCHER_KINDS.flatMap((kind) =>
+    (rule[kind] ?? []).map(
+      (matcher, index) =>
+        [matcherKey(kind, id, index), matcherQuestion(rule, kind, matcher)] as const,
+    ),
+  );
+
 /** The tokens a file's code leaves in Jev's context for any one question beside it, as `fits` counts them. */
 export const questionRoom = (lines: Lines): number =>
   QUESTION_CONTEXT - WRAPPER - tokensOf(stateOf(lines));
 
-/** One question per rule, and the linter question beside each rule in `sampled`. */
+/**
+ * One question per rule, one per matcher of each rule, and the linter
+ * question beside each rule in `sampled`.
+ */
 export const judgeBody = (
   model: string,
   lines: Lines,
@@ -247,6 +307,9 @@ export const judgeBody = (
   state: stateOf(lines),
   questions: {
     ...Record.map(rules, (rule): ReturnType<typeof judgeQuestion> => judgeQuestion(rule)),
+    ...Object.fromEntries(
+      Object.entries(rules).flatMap(([id, rule]) => matcherQuestions(id, rule)),
+    ),
     ...Object.fromEntries(
       sampled.flatMap((id) => {
         const rule = rules[id];
@@ -256,62 +319,123 @@ export const judgeBody = (
   },
 });
 
-export const locateBody = (
-  model: string,
+/**
+ * Whether the file shows enough to decide the rule at all: a finding that
+ * turns on another file, a library, or a service is a coin flip, and the
+ * report says so. It asks the condition itself, beside the rule: on the
+ * eval, asking whether `code` held enough to answer the judge question, put
+ * in a field, ranked real findings worse, and read no easier. Of findings
+ * it scored below 0.6, 62% were false, where 22% of all were.
+ */
+export const sufficiencyQuestion = (rule: Rule) => ({
+  type: "noul" as const,
+  instructions: {
+    question:
+      "Can you tell whether `code` breaks `rule` from `code` alone, without knowing what other files, libraries, services, or configuration do?",
+    ...ruleFields(rule),
+  },
+  criteria: {
+    true: "`code` shows everything needed to tell whether it breaks `rule`",
+    false:
+      "Whether `code` breaks `rule` depends on something `code` does not show, such as another file, a library, a service, or configuration",
+  },
+});
+
+/** The key a rule's sufficiency question rides under, beside its locate question. */
+export const sufficiencyKey = (id: RuleId): string => `sufficient:${id}`;
+
+/** The key of the question where in section `section` (from 1) the code that breaks a rule starts or ends. */
+export const edgeKey = (edge: "start" | "end", id: RuleId, section: number): string =>
+  `${edge}:${id}:${section}`;
+
+/**
+ * Which line of one section the code that breaks the rule starts or ends
+ * on: a choice among the section's lines that hold code, each option the
+ * line's text, since the state carries no line numbers.
+ */
+const edgeQuestion = (
+  rule: Rule,
+  edge: "start" | "end",
+  key: string,
   lines: Lines,
-  rules: Rules,
-  blocks?: Readonly<Record<RuleId, number>>,
+  numbers: ReadonlyArray<number>,
 ) => ({
-  model,
-  state: stateOf(lines),
-  questions: Record.map(rules, (rule, id) => {
-    const block = blocks?.[id];
-    return {
-      type: "choice" as const,
-      instructions: {
-        question: `Which line of \`code\` most clearly ${offense(rule)}?`,
-        ...ruleFields(rule),
-      },
-      criteria:
-        block === undefined
-          ? lineCriteria(lines, 1, lines.length)
-          : lineCriteria(lines, block * LINES_PER_BLOCK + 1, (block + 1) * LINES_PER_BLOCK),
-    };
-  }),
+  type: "choice" as const,
+  instructions: {
+    question: `Which line of \`code["${key}"]\` does the code that breaks \`rule\` ${edge} on?`,
+    ...ruleFields(rule),
+  },
+  criteria: Object.fromEntries(
+    numbers.map((line) => [String(line), (lines[line - 1] ?? "").trim().slice(0, 120)]),
+  ),
 });
 
-export const blockBody = (model: string, lines: Lines, rules: Rules) => {
-  const criteria: Record<string, string> = {};
-  for (let block = 0; block * LINES_PER_BLOCK < lines.length; block++) {
-    const first = lines
-      .slice(block * LINES_PER_BLOCK, (block + 1) * LINES_PER_BLOCK)
-      .find((line) => !isBlank(line));
-    if (first !== undefined) criteria[String(block)] = `${snippetOf(first)}...`;
-  }
+/**
+ * Per rule, which section of `code` breaks it, one choice among the
+ * sections' numbers; for every section, the lines in it the code that breaks
+ * the rule starts and ends on, of which the chosen section's are kept; and
+ * the sufficiency question. The section options carry no text: each is a
+ * key of the state, and describing a section by its first line or by what
+ * it declares located no better on the eval. A file of one section has no
+ * section to choose. On the eval, asked together, the start and end lines
+ * held a violation for 94% of real findings, and 98% where the section was
+ * right, and were most often one line.
+ */
+export const locateBody = (model: string, lines: Lines, rules: Rules) => {
+  const state = stateOf(lines);
+  const criteria = Record.map(state.code, () => null);
+  const choosing = Object.keys(criteria).length > 1;
+  const withCode = sectionsOf(lines).map(({ first, last }) =>
+    Array.from({ length: last - first + 1 }, (_, index) => first + index).filter(
+      (line) => (lines[line - 1] ?? "").trim() !== "",
+    ),
+  );
   return {
     model,
-    state: stateOf(lines),
-    questions: Record.map(rules, (rule) => ({
-      type: "choice" as const,
-      instructions: {
-        question: `Which block of \`code\` contains the line that most clearly ${offense(rule)}?`,
-        ...ruleFields(rule),
-      },
-      criteria,
-    })),
+    state,
+    questions: Object.fromEntries(
+      Object.entries(rules).flatMap(([id, rule]) => [
+        ...(choosing
+          ? [
+              [
+                id,
+                {
+                  type: "choice" as const,
+                  instructions: {
+                    question: `Which entry of \`code\` most clearly ${offense(rule)}?`,
+                    ...ruleFields(rule),
+                  },
+                  criteria,
+                },
+              ] as const,
+            ]
+          : []),
+        ...withCode.flatMap((numbers, index) =>
+          numbers.length === 0
+            ? []
+            : (["start", "end"] as const).map(
+                (edge) =>
+                  [
+                    edgeKey(edge, id, index + 1),
+                    edgeQuestion(rule, edge, String(index + 1), lines, numbers),
+                  ] as const,
+              ),
+        ),
+        [sufficiencyKey(id), sufficiencyQuestion(rule)] as const,
+      ]),
+    ),
   };
 };
 
 /**
- * Whether Jev can take every request a file may need: its lines within two
- * line choices, and its code beside the longest question any rule asks.
+ * Whether Jev can take every request a file may need: its sections within
+ * one choice, and its code beside the longest question any rule asks.
  */
 export const fits = (lines: Lines, rules: Rules): boolean => {
-  if (lines.length > MAX_LINES) return false;
-  const located = needsBlocks(lines) ? blockBody("", lines, rules) : locateBody("", lines, rules);
+  if (sectionsOf(lines).length > CHOICE_LIMIT) return false;
   const questions = [
     ...Object.values(judgeBody("", lines, rules).questions),
-    ...Object.values(located.questions),
+    ...Object.values(locateBody("", lines, rules).questions),
   ];
   const longest = Math.max(0, ...questions.map(tokensOf));
   return tokensOf(stateOf(lines)) + longest <= QUESTION_CONTEXT - WRAPPER;
@@ -368,14 +492,8 @@ export const judgeRequests = (
   sampled: ReadonlyArray<RuleId> = [],
 ): number => requestsOf(judgeBody("", lines, rules, sampled)).length;
 
-/**
- * The requests locating `rules` in a file takes, split to fit as `locate`
- * sends them: a block choice first for a long file, then a line choice. For a
- * long file the line choice is counted before a block is chosen, so it can
- * run high.
- */
+/** The requests locating `rules` in a file takes, split to fit as `locate` sends them. */
 export const locateRequests = (lines: Lines, rules: Rules): number =>
-  (needsBlocks(lines) ? requestsOf(blockBody("", lines, rules)).length : 0) +
   requestsOf(locateBody("", lines, rules)).length;
 
 /** A choice keeps one criterion for "none", which leaves this many for partners. */

package/src/services/SourceWalker.ts

@@ -1,9 +1,10 @@
 import { matchesGlob } from "node:path";
 import { Context, Effect, FileSystem, Layer, Path } from "effect";
-import { ADHERE_DIRECTORY, SKIPPED_DIRECTORIES } from "#config.ts";
+import { ADHERE_DIRECTORY, SKIPPED_DIRECTORIES, TEST_DIRECTORIES } from "#config.ts";
 import type { ScannedFile } from "#models/Audit.ts";
 import { WalkUnavailable } from "#models/Audit.ts";
 import { walkFiles } from "#walk.ts";
+import { AdhereConfig } from "#services/AdhereConfig.ts";
 import { clearingStatus, counted, countOf, Status } from "#services/Status.ts";
 
 /** Walks the repository's TypeScript source, skipping what is not ours to read. */
@@ -11,9 +12,9 @@ export class SourceWalker extends Context.Service<
   SourceWalker,
   {
     /**
-     * Every TypeScript file under the audit's roots, in directory order. A
-     * file that cannot be read refuses the walk: a silent gap would report
-     * a clean audit that was never complete.
+     * Every TypeScript file under the audit's roots, in directory order, test
+     * files marked. A file that cannot be read refuses the walk: a silent gap
+     * would report a clean audit that was never complete.
      */
     readonly files: Effect.Effect<ReadonlyArray<ScannedFile>, WalkUnavailable>;
   }
@@ -50,13 +51,42 @@ export const passesFilter = (relative: string, patterns: ReadonlyArray<string>):
   return (include.length === 0 || include.some(matches)) && !exclude.some(matches);
 };
 
+/**
+ * A fixture or test helper named as one: `fixtures.ts`, `GitHubHttpFixtures.ts`,
+ * `ledger-copy.fixture.ts`, `linear-test-helpers.ts`, `GitHubHttpTestUtils.ts`.
+ * "test" starts a word, so `latest-utils.ts` is not one.
+ */
+const TEST_SUPPORT_NAME =
+  /(?:[fF]ixtures?|(?:(?:^|[-_.])[tT]est[-_]?|[a-z]Test)(?:[hH]elpers?|[uU]tils?))\.[cm]?tsx?$/;
+
+/** A TypeScript source file: `.ts`, `.tsx`, `.mts`, or `.cts`. */
+const SOURCE = /\.(?:tsx?|mts|cts)$/;
+/** A declaration file: `.d.ts`, `.d.mts`, or `.d.cts`. */
+const DECLARATION = /\.d\.[cm]?ts$/;
+/** A test by its name: `a.test.ts`, `Button.spec.tsx`. */
+const TEST_NAME = /\.(?:test|spec)\.[cm]?tsx?$/;
+
+/**
+ * Whether a path, relative to the working directory, is a test: a `.test` or
+ * `.spec` file, such as `a.test.ts` or `Button.spec.tsx`, a fixture or test
+ * helper named as one, or any file under a test directory such as `test/`.
+ */
+export const isTestFile = (relative: string): boolean => {
+  const segments = relative.split(/[\\/]/);
+  const name = segments.at(-1) ?? "";
+  return (
+    TEST_NAME.test(name) ||
+    TEST_SUPPORT_NAME.test(name) ||
+    segments.slice(0, -1).some((segment) => TEST_DIRECTORIES.has(segment))
+  );
+};
+
 const isInside = (file: string, root: string): boolean =>
   file === root || file.startsWith(`${root}/`);
 
-const isScannable = (file: string, self: string): boolean =>
-  file.endsWith(".ts") &&
-  !file.endsWith(".d.ts") &&
-  !file.endsWith(".test.ts") &&
+export const isScannable = (file: string, self: string): boolean =>
+  SOURCE.test(file) &&
+  !DECLARATION.test(file) &&
   !file.endsWith("/adhere.config.ts") &&
   !file.endsWith("/.adhere.config.ts") &&
   // The audit's own detector patterns are data, not violations of themselves.
@@ -169,8 +199,10 @@ const scanDirs = Effect.fn("SourceWalker.scanDirs")(function* (
 
 /**
  * The real walker: the roots walked a directory at a time, skipped trees
- * left unread, each file read and split into lines. Tests substitute their
- * own tree.
+ * left unread, each file read and split into lines. The run's filter and the
+ * config's `exclude` leave out what they match. Test files are read, and
+ * marked, even when no rule judges them, so a prune keeps what other runs
+ * know of them. Tests substitute their own tree.
  * The scan root is the current working directory, so the audit reads the
  * repository it is run in.
  */
@@ -179,9 +211,11 @@ export const SourceWalkerLive = (filter: ReadonlyArray<string> = []) =>
     Effect.gen(function* () {
       const fs = yield* FileSystem.FileSystem;
       const path = yield* Path.Path;
+      const config = yield* AdhereConfig;
       // No segments: Path resolves against the working directory.
       const root = path.resolve();
       const self = yield* path.fromFileUrl(new URL("../../", import.meta.url)).pipe(Effect.orDie);
+      const patterns = [...filter, ...(config.exclude ?? []).map((glob) => `!${glob}`)];
       const walk = Effect.fn("SourceWalker.files")(function* () {
         const dirs = yield* scanDirs(fs, root).pipe(Effect.mapError(refused));
         const trees = yield* clearingStatus(
@@ -193,12 +227,16 @@ export const SourceWalkerLive = (filter: ReadonlyArray<string> = []) =>
               dir === "." ? "the working directory" : `${dir}/`,
               self,
               (relative) =>
-                // Filter patterns are relative to the working directory, not the tree read.
-                passesFilter(dir === "." ? relative : `${dir}/${relative}`, filter),
+                // Patterns are relative to the working directory, not the tree read.
+                passesFilter(dir === "." ? relative : `${dir}/${relative}`, patterns),
             ).pipe(Effect.mapError(refused)),
           ),
         );
-        return trees.flat();
+        return trees
+          .flat()
+          .map((file) =>
+            isTestFile(path.relative(root, file.path)) ? { ...file, test: true } : file,
+          );
       });
       return SourceWalker.of({ files: walk() });
     }),

package/src/suppress.ts

@@ -0,0 +1,119 @@
+import { type Range, statementFrom } from "#excerpt.ts";
+import { scan } from "#highlight.ts";
+
+/**
+ * What a file's `adhere-ignore` comments suppress. `// adhere-ignore <rules>
+ * -- <reason>` on a line of its own suppresses the rules it names in the
+ * statement that starts on the next line of code, wherever in it Jev points;
+ * at the end of a line of code, in the statement that starts on that line,
+ * or the line alone.
+ * `// adhere-ignore-file <rules> -- <reason>` suppresses them in the whole
+ * file, which they then do not judge. Rules are named as a report names
+ * them, separated by commas.
+ */
+export interface Suppressions {
+  /** Rules suppressed in the whole file. */
+  readonly file: ReadonlySet<string>;
+  /** Rules suppressed over the lines of one statement. */
+  readonly statements: ReadonlyArray<Range & { readonly rules: ReadonlySet<string> }>;
+}
+
+export const NO_SUPPRESSIONS: Suppressions = { file: new Set(), statements: [] };
+
+/** A directive's comment: whether it covers the file, then what follows, up to a block comment's end. */
+const DIRECTIVE = /^(?:\/\/|\/\*)\s*adhere-ignore(-file)?\s+(.*?)\s*(?:\*\/)?$/s;
+
+/** An `adhere-ignore` comment: where it is, and the rules it names. */
+interface Directive {
+  readonly line: number;
+  /** At the end of a line of code, rather than on a line of its own. */
+  readonly trailing: boolean;
+  /** `adhere-ignore-file`, for the whole file. */
+  readonly file: boolean;
+  readonly rules: ReadonlySet<string>;
+}
+
+/** The rules a directive names, before any ` -- ` and its reason. None if it is not a directive. */
+const directiveOf = (comment: string): Pick<Directive, "file" | "rules"> | undefined => {
+  const match = DIRECTIVE.exec(comment);
+  const named = (match?.[2] ?? "").split(/(?:^|\s)--(?:\s|$)/)[0] ?? "";
+  const rules = named.split(/[\s,]+/).filter((rule) => rule.length > 0);
+  return match === null || rules.length === 0
+    ? undefined
+    : { file: match[1] !== undefined, rules: new Set(rules) };
+};
+
+/** Whether a line holds nothing a statement could start with: blank, or a comment. */
+const isQuiet = (line: string): boolean => {
+  const text = line.trim();
+  return (
+    text.length === 0 || text.startsWith("//") || text.startsWith("/*") || text.startsWith("*")
+  );
+};
+
+/** The statement that starts on the first line of code after `line`, or that line alone. */
+const statementAfter = (lines: ReadonlyArray<string>, line: number): Range | undefined => {
+  for (let next = line + 1; next <= lines.length; next++) {
+    if (isQuiet(lines[next - 1] ?? "")) continue;
+    return statementFrom(lines, next) ?? { first: next, last: next };
+  }
+  return undefined;
+};
+
+/**
+ * A file's lines with its `adhere-ignore` comments blanked, each line keeping
+ * its number, so Jev never reads them, and what they suppress.
+ */
+export const suppressionsOf = (
+  lines: ReadonlyArray<string>,
+): { readonly lines: ReadonlyArray<string>; readonly suppressions: Suppressions } => {
+  const code = lines.join("\n");
+  if (!code.includes("adhere-ignore")) return { lines, suppressions: NO_SUPPRESSIONS };
+  const tokens = scan(code);
+  const found: Array<Directive> = [];
+  const kept: Array<string> = [];
+  let line = 1;
+  // Whether code comes before the current token on its line.
+  let afterCode = false;
+  for (const token of tokens) {
+    const directive = token.kind === "comment" ? directiveOf(token.text) : undefined;
+    if (directive !== undefined) found.push({ line, trailing: afterCode, ...directive });
+    kept.push(directive === undefined ? token.text : token.text.replace(/[^\n]/g, ""));
+    const breaks = token.text.split("\n").length - 1;
+    const tail = token.text.slice(token.text.lastIndexOf("\n") + 1);
+    if (breaks > 0) afterCode = false;
+    if (token.kind !== "comment" && tail.trim().length > 0) afterCode = true;
+    line += breaks;
+  }
+  // What the highlighter could not read, if anything, stays as it was.
+  const read = tokens.reduce((length, token) => length + token.text.length, 0);
+  const cleaned = (kept.join("") + code.slice(read))
+    .split("\n")
+    .map((text, index) => (text === lines[index] ? text : text.trimEnd()));
+  const statements = found.flatMap(({ line: at, trailing, file, rules }) => {
+    if (file) return [];
+    const range = trailing
+      ? (statementFrom(cleaned, at) ?? { first: at, last: at })
+      : statementAfter(cleaned, at);
+    return range === undefined ? [] : [{ ...range, rules }];
+  });
+  return {
+    lines: cleaned,
+    suppressions: {
+      file: new Set(found.filter(({ file }) => file).flatMap(({ rules }) => [...rules])),
+      statements,
+    },
+  };
+};
+
+/**
+ * Whether a file's comments suppress `rule`, named as a report names it, at
+ * `place`, the lines Jev points at or, without them, their section: in the
+ * whole file, or in a statement that overlaps it.
+ */
+export const suppresses = (suppressions: Suppressions, rule: string, place: Range): boolean =>
+  suppressions.file.has(rule) ||
+  suppressions.statements.some(
+    (statement) =>
+      statement.rules.has(rule) && statement.first <= place.last && place.first <= statement.last,
+  );

package/src/version.ts

@@ -1,3 +1,27 @@
 import packageJson from "../package.json";
 
-export const version = packageJson.version;
+/**
+ * `git describe --tags --dirty --always` where `bun run build` compiled
+ * this, which it defines: the release it follows, the commits since, and
+ * whether the tree had changes, or the commit alone in a clone without tags.
+ * A release build defines nothing.
+ */
+declare const ADHERE_BUILD: string;
+
+/** Read off `globalThis`, as in `presets.ts`, for Vitest on Node and for Bun's types left out. */
+const isStandaloneExecutable =
+  (globalThis as { readonly Bun?: { readonly isStandaloneExecutable?: boolean } }).Bun
+    ?.isStandaloneExecutable === true;
+
+/**
+ * What `--version` prints after `adhere v`: a local build's `git describe`,
+ * such as `0.10.0-16-g9a41328`, so it is not taken for the release it
+ * follows; a release build's version; and from source, the version the
+ * checkout says, marked as such.
+ */
+export const version =
+  typeof ADHERE_BUILD === "string" && ADHERE_BUILD !== ""
+    ? ADHERE_BUILD.replace(/^v/, "")
+    : isStandaloneExecutable
+      ? packageJson.version
+      : `${packageJson.version} (source)`;