@drkmttr/adhere 0.9.5 → 0.11.0

package/src/main.ts

@@ -49,7 +49,6 @@ const report = (cause: Cause.Cause<unknown>): Effect.Effect<void> => {
 
 Command.run(cli, { version }).pipe(
   Effect.tapCause(report),
-  // oxlint-disable-next-line effecttsgo/strict-effect-provide -- this executable entrypoint supplies Bun's process services and the logger.
   Effect.provide(Layer.merge(BunServices.layer, logger)),
   (program) => BunRuntime.runMain(program, { disableErrorReporting: true }),
 );

package/src/markdown.ts

@@ -10,27 +10,46 @@ import { Effect, Schema } from "effect";
  *     ---
  *     Any prose, rendered on GitHub and ignored by adhere.
  *
- *     ```ts must
+ *     ## Must
+ *
+ *     ```ts
  *     const written = "code that must be written this way"
  *     ```
  *
- *     ```ts never
+ *     ## Never
+ *
+ *     ```ts
  *     const avoided = "code that must never be written this way"
  *     ```
  *
- * A fence's info string names its code with RFC 2119's words: `must` and
- * `never` for a requirement, `should` and `should not` for a guideline. The
- * first fence under each word is that example, and a rule has either or both.
- * An untagged fence is the code to write, and without a fence the whole body
- * is. `avoid`, the word before 0.7, means `never`. `threshold` is optional.
+ * A heading names the code in its section with RFC 2119's words: `must` and
+ * `never` for a requirement, `should` and `should not` for a guideline. So
+ * does a fence's info string, as in `ts never`, which GitHub does not show; a
+ * fence's own word wins over its heading's. The first fence under each word is
+ * that example, and a rule has either or both. An untagged fence outside those
+ * sections is the code to write, and without a fence the whole body is.
+ * `avoid`, the word before 0.7, means `never`. `threshold` is optional, and
+ * so is `tests`: `only` for a rule about test files, which rules otherwise
+ * skip, and `include` for a rule that judges them too. So is `level`:
+ * `warning` reports the rule's findings as warnings, which do not fail a run.
+ * `appliesTo` and `excludeIf`, the rule's scope, are JSON arrays of strings on
+ * one line, as in `excludeIf: ["a type that mirrors a third-party format"]`.
  */
+const Matchers = Schema.fromJsonString(Schema.Array(Schema.String));
+
 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"])),
+  appliesTo: Schema.optionalKey(Matchers),
+  excludeIf: Schema.optionalKey(Matchers),
 });
 
 const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
 const FENCE = /^ {0,3}(`{3,}|~{3,})([^\n]*)\n([\s\S]*?)\n {0,3}\1[ \t]*$/gm;
+/** An ATX heading: its level as `#`s, then its text, without a closing run of `#`s. */
+const HEADING = /^ {0,3}(#{1,6})(?:[ \t]+(.*?))?(?:[ \t]+#+)?[ \t]*$/gm;
 
 const unquote = (value: string): string => {
   const trimmed = value.trim();
@@ -54,11 +73,17 @@ const parseFrontMatter = (block: string): Record<string, string> => {
 type Word = Example["word"];
 
 interface Fence {
-  /** The word the info string names the code with; none for an untagged fence. */
+  /** The word its info string, or else its heading, names the code with; none for untagged code. */
   readonly word: Word | undefined;
   readonly code: string;
 }
 
+interface Heading {
+  readonly level: number;
+  /** The word the heading names its section's code with; none for any other heading. */
+  readonly word: Word | undefined;
+}
+
 /** `must not`, like `never` and the older `avoid`, names code never to write. */
 const wordOf = (info: string): Word | undefined => {
   const words = info.trim().toLowerCase().split(/\s+/);
@@ -69,11 +94,55 @@ const wordOf = (info: string): Word | undefined => {
   return undefined;
 };
 
-const fencesOf = (body: string): ReadonlyArray<Fence> =>
-  Array.from(body.matchAll(FENCE), (match) => ({
-    word: wordOf(match[2] ?? ""),
-    code: (match[3] ?? "").trim(),
-  }));
+const HEADING_WORDS: ReadonlySet<string> = new Set([
+  "must",
+  "must not",
+  "never",
+  "avoid",
+  "should",
+  "should not",
+]);
+
+/**
+ * A heading names a word only when it is the word alone, in any case and with
+ * or without a colon: `## Never` does, `## Why never` does not.
+ */
+const headingWordOf = (text: string): Word | undefined => {
+  const phrase = text.trim().replace(/:$/, "").trim().toLowerCase().split(/\s+/).join(" ");
+  return HEADING_WORDS.has(phrase) ? wordOf(phrase) : undefined;
+};
+
+/**
+ * The headings open after `text`, outermost first, given those open before
+ * it. A heading closes the sections at its level and deeper, so a deeper
+ * heading stays inside the section above it.
+ */
+const openAfter = (open: ReadonlyArray<Heading>, text: string): ReadonlyArray<Heading> =>
+  Array.from(text.matchAll(HEADING)).reduce<ReadonlyArray<Heading>>((headings, match) => {
+    const level = (match[1] ?? "#").length;
+    return [
+      ...headings.filter((heading) => heading.level < level),
+      { level, word: headingWordOf(match[2] ?? "") },
+    ];
+  }, open);
+
+/**
+ * Each fence, under the word its info string names or, without one, the word
+ * of the innermost heading over it that names one.
+ */
+const fencesOf = (body: string): ReadonlyArray<Fence> => {
+  const fences: Array<Fence> = [];
+  let open: ReadonlyArray<Heading> = [];
+  let read = 0;
+  for (const match of body.matchAll(FENCE)) {
+    // Only headings between fences count: a `#` line inside one is code.
+    open = openAfter(open, body.slice(read, match.index));
+    read = match.index + match[0].length;
+    const section = open.findLast((heading) => heading.word !== undefined)?.word;
+    fences.push({ word: wordOf(match[2] ?? "") ?? section, code: (match[3] ?? "").trim() });
+  }
+  return fences;
+};
 
 /** An empty block counts as no block. */
 const nonEmpty = (code: string | undefined): string | undefined =>
@@ -134,7 +203,7 @@ export const parseRuleMarkdown = (
     }
     if (!requirement && !guideline) {
       return yield* ConfigUnavailable.make({
-        message: `${file}: the body needs code, in a fence tagged must, never, should, or should not, or untagged`,
+        message: `${file}: the body needs code, in a fence under a Must, Never, Should, or Should not heading, or untagged`,
       });
     }
     return { ...front, ...code };

package/src/models/Audit.ts

@@ -3,6 +3,8 @@ import { Schema } from "effect";
 export interface ScannedFile {
   readonly path: string;
   readonly lines: ReadonlyArray<string>;
+  /** A test file, which only the rules that say `tests` judge. */
+  readonly test?: boolean;
 }
 
 /** A source walker's refusal: the tree it was asked to read is not readable. */

package/src/presets.ts

@@ -4,10 +4,13 @@ import type { Preset } from "#config.ts";
  * `presets/` sits next to `src/` in a checkout. In a compiled executable
  * (`bun build --compile --asset ./presets`) Bun embeds it under the bundle's
  * own directory instead, hence the fork on `Bun.isStandaloneExecutable`, which
- * is the check Bun's docs give for this. Measured on Bun 1.4. The `typeof`
- * guard is for Vitest, which imports this module on Node.
+ * is the check Bun's docs give for this. Measured on Bun 1.4. It is read off
+ * `globalThis` for Vitest, which imports this module on Node, and for a
+ * project that type-checks this package's source without Bun's types.
  */
-const isStandaloneExecutable = typeof Bun !== "undefined" && Bun.isStandaloneExecutable;
+const isStandaloneExecutable =
+  (globalThis as { readonly Bun?: { readonly isStandaloneExecutable?: boolean } }).Bun
+    ?.isStandaloneExecutable === true;
 
 const presetsRoot = isStandaloneExecutable
   ? new URL("./presets/", import.meta.url)
@@ -20,6 +23,9 @@ const presetsRoot = isStandaloneExecutable
 const topics = {
   effect: ["basics", "config", "data", "errors", "services", "testing"],
   alchemy: ["apis", "data", "durable", "providers", "resources", "runtime", "secrets", "security"],
+  typescript: ["async", "design", "errors", "testing", "types"],
+  react: ["effects", "server", "state"],
+  security: [],
 } as const;
 
 type Topics = typeof topics;
@@ -54,6 +60,9 @@ export const presetOf = (name: PresetName): BuiltInPreset => {
 export const presets: Readonly<Record<WholePreset, BuiltInPreset>> = {
   effect: presetOf("effect"),
   alchemy: presetOf("alchemy"),
+  typescript: presetOf("typescript"),
+  react: presetOf("react"),
+  security: presetOf("security"),
 };
 
 /** The directory each whole preset reads, for checking `topics` against it. */

package/src/rules.ts

@@ -1,5 +1,6 @@
 import {
   ConfigUnavailable,
+  type Override,
   type Rule,
   type RuleId,
   type RuleSource,
@@ -26,12 +27,14 @@ export interface RuleEntry {
 
 /**
  * A rule's id as output shows it: a preset's rule with the preset's name
- * first, as in effect/basics/external-calls-are-resilient, so a report that
+ * first, as in effect/basics/gen-for-sequencing, so a report that
  * mixes presets with the project's own rules says where each came from. The
  * project's own rules show their `.adhere/` ids as they are.
  */
-export const shownId = (entry: { readonly id: RuleId; readonly preset?: string }): string =>
-  entry.preset === undefined ? entry.id : `${entry.preset}/${entry.id}`;
+export const shownId = (entry: {
+  readonly id: RuleId;
+  readonly preset?: string | undefined;
+}): string => (entry.preset === undefined ? entry.id : `${entry.preset}/${entry.id}`);
 
 export type RuleSet = ReadonlyArray<RuleEntry>;
 
@@ -170,6 +173,36 @@ export const materializeRules = Effect.fn("materializeRules")(function* (
 export const globalRuleSet = (rules: Readonly<Record<RuleId, Rule>>, root: string) =>
   Object.entries(rules).map(([id, rule]): RuleEntry => ({ id, rule, scope: root }));
 
+/**
+ * The rules as a config's overrides leave them, each found by the id a report
+ * names it with: a rule set `off` gone, and any other with the level and
+ * threshold its override gives, over its own.
+ */
+export const withOverrides = (
+  entries: RuleSet,
+  overrides: Readonly<Record<string, Override>>,
+): RuleSet =>
+  entries.flatMap((entry) => {
+    const override = overrides[shownId(entry)];
+    if (override === undefined) return [entry];
+    const { level, threshold }: Exclude<Override, string> =
+      typeof override === "string" ? { level: override } : override;
+    if (level === "off") return [];
+    const rule: Rule = {
+      ...entry.rule,
+      ...(level === undefined ? {} : { level }),
+      ...(threshold === undefined ? {} : { threshold }),
+    };
+    return [{ ...entry, rule }];
+  });
+
+/**
+ * Whether a rule judges a file: a test file only when the rule says `tests`,
+ * and any other file unless it says `tests: only`.
+ */
+export const judgesFile = (rule: Rule, test: boolean): boolean =>
+  test ? rule.tests !== undefined : rule.tests !== "only";
+
 /**
  * The flat rule map for one source file. Root rules apply everywhere. When a
  * nested `.adhere/` defines the same id, the deepest matching scope wins.

package/src/services/AdhereConfig.ts

@@ -1,23 +1,25 @@
 import {
   ADHERE_DIRECTORY,
-  type AdhereConfig as Decoded,
+  AdhereConfig as AdhereConfigSchema,
   CONFIG_FILES,
   ConfigUnavailable,
   decodeConfig,
   type Loaded,
-  type Overrides,
+  type Flags,
   type Preset,
   presetsOf,
   type ResolvedConfig,
   resolveConfig,
 } from "#config.ts";
-import { type PresetName, presetOf, wholePresetOf } from "#presets.ts";
+import { type PresetName, presetOf, presets, wholePresetOf } from "#presets.ts";
 import {
   applicableRules,
   globalRuleSet,
   loadAdhereRuleSet,
   materializeRules,
   type RuleSet,
+  shownId,
+  withOverrides,
 } from "#rules.ts";
 import { Context, Effect, FileSystem, Layer, Path, Record } from "effect";
 
@@ -50,13 +52,23 @@ const loadPreset = Effect.fn("AdhereConfig.loadPreset")(function* (name: PresetN
   return [name, { ...preset, rules } satisfies Loaded<Preset>] as const;
 });
 
+/** Every rule of every built-in preset, by the id a report names it with. */
+const everyPresetRule = Effect.fn("AdhereConfig.everyPresetRule")(function* (base: string) {
+  const loaded = yield* Effect.forEach(Object.entries(presets), ([name, preset]) =>
+    Effect.map(materializeRules(preset.rules, base), (rules) =>
+      Object.keys(rules).map((id) => `${name}/${id}`),
+    ),
+  );
+  return new Set(loaded.flat());
+});
+
 /**
  * The config file in the working directory (one of `CONFIG_FILES`) with the
- * command-line overrides applied. The file is optional when `.adhere/` holds
+ * command-line flags applied. The file is optional when `.adhere/` holds
  * rules or a preset is named. Rule directories resolve against the working
  * directory.
  */
-export const AdhereConfigLive = (overrides: Overrides) =>
+export const AdhereConfigLive = (flags: Flags) =>
   Layer.effect(AdhereConfig)(
     Effect.gen(function* () {
       const path = yield* Path.Path;
@@ -73,8 +85,8 @@ export const AdhereConfigLive = (overrides: Overrides) =>
         });
       }
       const configFile = found[0];
-      const hasPreset = overrides.presets !== undefined && overrides.presets.length > 0;
-      const config: Decoded =
+      const hasPreset = flags.presets !== undefined && flags.presets.length > 0;
+      const config: typeof AdhereConfigSchema.Type =
         configFile === undefined
           ? yield* decodeConfig({})
           : yield* loadConfigFile(path.join(cwd, configFile));
@@ -90,10 +102,10 @@ export const AdhereConfigLive = (overrides: Overrides) =>
           ? discoveredEntries
           : globalRuleSet(yield* materializeRules(config.rules ?? {}, cwd), cwd);
       const rules = applicableRules(cwd, projectEntries);
-      const registry = yield* Effect.forEach(presetsOf(config, overrides), (name) =>
+      const registry = yield* Effect.forEach(presetsOf(config, flags), (name) =>
         loadPreset(name, cwd),
       ).pipe(Effect.map(Record.fromEntries));
-      const resolved = resolveConfig({ ...config, rules }, overrides, registry);
+      const resolved = resolveConfig({ ...config, rules }, flags, registry);
       const presetEntries = Object.entries(registry).flatMap(([name, preset]) =>
         globalRuleSet(preset.rules, cwd).map((entry) => ({
           ...entry,
@@ -103,9 +115,20 @@ export const AdhereConfigLive = (overrides: Overrides) =>
       yield* Effect.logDebug(
         `config: ${configFile ?? "no config file"}; presets ${Object.keys(registry).join(", ") || "none"}; ${presetEntries.length} preset and ${projectEntries.length} project rules; model ${resolved.model}, threshold ${resolved.threshold}${resolved.rpm === undefined ? "" : `, at most ${resolved.rpm} requests a minute`}`,
       );
-      return AdhereConfig.of({
-        ...resolved,
-        scopedRules: [...presetEntries, ...projectEntries],
-      });
+      const entries = [...presetEntries, ...projectEntries];
+      const overrides = config.overrides ?? {};
+      const loaded = new Set(entries.map(shownId));
+      const elsewhere = Object.keys(overrides).filter((id) => !loaded.has(id));
+      if (elsewhere.length > 0) {
+        // A rule of a preset this run leaves out may be overridden; one no rule has is a typo.
+        const every = yield* everyPresetRule(cwd);
+        const unknown = elsewhere.filter((id) => !every.has(id));
+        if (unknown.length > 0) {
+          return yield* ConfigUnavailable.make({
+            message: `overrides names ${unknown.join(", ")}, which is no preset or project rule. A preset's rule is named with its preset first, as in alchemy/providers/idempotent-delete.`,
+          });
+        }
+      }
+      return AdhereConfig.of({ ...resolved, scopedRules: withOverrides(entries, overrides) });
     }),
   );

package/src/services/AuditCache.ts

@@ -1,11 +1,30 @@
 import { CACHE_DIRECTORY } from "#config.ts";
 import { Context, Crypto, Effect, FileSystem, Layer, Option, Path, Record, Schema } from "effect";
 
+/** Jev's probability for each of a rule's `appliesTo` and `excludeIf` matchers, when it has them. */
+const MatcherFields = {
+  appliesTo: Schema.optionalKey(Schema.Array(Schema.Finite)),
+  excludeIf: Schema.optionalKey(Schema.Array(Schema.Finite)),
+};
+
+/** Lines of a file, first to last. */
+const Lines = Schema.Struct({ first: Schema.Finite, last: Schema.Finite });
+/** The lines of the section a finding is in, once located. */
+const Section = Schema.optionalKey(Lines);
+/** The lines in its section the code that breaks the rule starts and ends on, when Jev named them. */
+const Located = Schema.optionalKey(Lines);
+
+/** Jev's probability, asked with the section, that the file shows enough to decide the rule. */
+const Sufficiency = Schema.optionalKey(Schema.Finite);
+
 /** A rule's judgment as a run holds it: Jev's answer, with the fingerprint of the rule's text. */
 export const Judgment = Schema.Struct({
   fingerprint: Schema.String,
   probability: Schema.Finite,
-  line: Schema.optionalKey(Schema.Finite),
+  section: Section,
+  lines: Located,
+  sufficiency: Sufficiency,
+  ...MatcherFields,
 });
 export interface Judgment extends Schema.Schema.Type<typeof Judgment> {}
 
@@ -21,10 +40,17 @@ export const CacheEntry = Schema.Struct({
 });
 export interface CacheEntry extends Schema.Schema.Type<typeof CacheEntry> {}
 
-/** Jev's answer about some code for one rule text: the probability, and the line once located. */
+/**
+ * Jev's answer about some code for one rule text: the probability, the
+ * section, lines, and sufficiency once located, and its matchers' scores. An answer from before
+ * sections held a line instead, under a fingerprint no rule has now.
+ */
 export const Answer = Schema.Struct({
   probability: Schema.Finite,
-  line: Schema.optionalKey(Schema.Finite),
+  section: Section,
+  lines: Located,
+  sufficiency: Sufficiency,
+  ...MatcherFields,
 });
 export interface Answer extends Schema.Schema.Type<typeof Answer> {}
 
@@ -98,13 +124,13 @@ const sorted = <A>(record: Readonly<Record<string, A>>): Record<string, A> =>
 
 const textOf = (value: unknown): string => `${JSON.stringify(value, null, 2)}\n`;
 
-/** One answer per rule text: one that has its line over one that has not, otherwise the first. */
+/** One answer per rule text: one that has its section over one that has not, otherwise the first. */
 const unionOf = (entries: ReadonlyArray<Answers>): Answers => {
   const union: Record<string, Answer> = {};
   for (const answers of entries) {
     for (const [fingerprint, answer] of Object.entries(answers)) {
       const held = union[fingerprint];
-      if (held === undefined || (held.line === undefined && answer.line !== undefined)) {
+      if (held === undefined || (held.section === undefined && answer.section !== undefined)) {
         union[fingerprint] = answer;
       }
     }

package/src/services/Jev.http.ts

@@ -1,10 +1,11 @@
 import type { RuleId } from "#config.ts";
+import { sectionsOf } from "#excerpt.ts";
 import { AdhereConfig } from "#services/AdhereConfig.ts";
 import { Credentials } from "#services/Credentials.ts";
 import {
-  blockBody,
   type Body,
   type ComparedRule,
+  edgeKey,
   conflictBody,
   contradictBody,
   Jev,
@@ -16,15 +17,27 @@ import {
   type Lines,
   linterKey,
   locateBody,
+  matcherKey,
+  type MatcherScores,
   namedPairs,
-  needsBlocks,
   type Pair,
   pairProbability,
   requestsOf,
   type Rules,
+  sufficiencyKey,
   tokensOf,
 } from "#services/Jev.ts";
-import { type Cause, Duration, Effect, Layer, Option, Record, Schedule, Schema } from "effect";
+import {
+  type Cause,
+  Duration,
+  Effect,
+  Layer,
+  Option,
+  Record,
+  Result,
+  Schedule,
+  Schema,
+} from "effect";
 import { HttpClient, HttpClientError, HttpClientResponse } from "effect/unstable/http";
 import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
 import { RateLimiter } from "effect/unstable/persistence";
@@ -37,6 +50,16 @@ const NoulAnswers = Schema.Struct({
 const ChoiceAnswers = Schema.Struct({
   answers: Schema.Record(Schema.String, Schema.Struct({ choice: Schema.String })),
 });
+/** A locate request's answers: a choice per rule, and a noul per sufficiency question. */
+const LocateAnswers = Schema.Struct({
+  answers: Schema.Record(
+    Schema.String,
+    Schema.Struct({
+      choice: Schema.optionalKey(Schema.String),
+      noul: Schema.optionalKey(Schema.Finite),
+    }),
+  ),
+});
 
 const refused = (message: string) => JevUnavailable.make({ message });
 
@@ -219,22 +242,64 @@ export const JevLive = Layer.effect(Jev)(
             return answer === undefined ? [] : [[id, answer.noul] as const];
           }),
         );
+      // A matcher Jev left unanswered counts as a no.
+      const scored = (
+        kind: keyof MatcherScores,
+        id: RuleId,
+        matchers: ReadonlyArray<string> = [],
+      ) => matchers.map((_, index) => answers[matcherKey(kind, id, index)]?.noul ?? 0);
+      const matchers: Record<RuleId, MatcherScores> = Record.fromEntries(
+        Object.entries(rules).flatMap(([id, rule]) =>
+          rule.appliesTo === undefined && rule.excludeIf === undefined
+            ? []
+            : [
+                [
+                  id,
+                  {
+                    appliesTo: scored("appliesTo", id, rule.appliesTo),
+                    excludeIf: scored("excludeIf", id, rule.excludeIf),
+                  },
+                ] as const,
+              ],
+        ),
+      );
       return {
         probabilities: answered(Object.keys(rules), (id) => id),
         linter: answered(sampled, linterKey),
+        ...(Record.isEmptyRecord(matchers) ? {} : { matchers }),
       } satisfies Judged;
     });
 
-    const chosen = (answers: Readonly<Record<string, { choice: string }>>) =>
-      Record.map(answers, (answer) => Number(answer.choice));
-
     const locate = Effect.fn("Jev.locate")(function* (lines: Lines, rules: Rules) {
-      const blocks = needsBlocks(lines)
-        ? chosen(yield* answersTo("blocks", blockBody(config.model, lines, rules), ChoiceAnswers))
-        : undefined;
-      return chosen(
-        yield* answersTo("locate", locateBody(config.model, lines, rules, blocks), ChoiceAnswers),
+      const sections = sectionsOf(lines);
+      const answers = yield* answersTo(
+        "locate",
+        locateBody(config.model, lines, rules),
+        LocateAnswers,
       );
+      // A file of one section has every finding in it. An answer that names no section,
+      // or none at all, which Jev should not give, leaves the rule unlocated; lines outside
+      // the section leave it without lines.
+      return Record.filterMap(rules, (_, id) => {
+        const chosen = sections.length === 1 ? 1 : Number(answers[id]?.choice);
+        const section = sections[chosen - 1];
+        const sufficiency = answers[sufficiencyKey(id)]?.noul;
+        if (section === undefined || sufficiency === undefined) return Result.failVoid;
+        const [start, end] = (["start", "end"] as const).map((edge) =>
+          Number(answers[edgeKey(edge, id, chosen)]?.choice),
+        );
+        const within = (line: number | undefined): line is number =>
+          line !== undefined && section.first <= line && line <= section.last;
+        return Result.succeed(
+          within(start) && within(end)
+            ? {
+                section,
+                sufficiency,
+                lines: { first: Math.min(start, end), last: Math.max(start, end) },
+              }
+            : { section, sufficiency },
+        );
+      });
     });
 
     const conflicts = Effect.fn("Jev.conflicts")(function* (