@drkmttr/adhere 0.10.0 → 0.11.0

package/src/excerpt.ts

@@ -1,20 +1,12 @@
 import { scan } from "#highlight.ts";
 
-/**
- * The lines a finding shows: the statement its line is in, such as the
- * function around it, and a few lines on either side of the line.
- */
+/** The lines a finding shows: the section of the file it is in. */
 export interface Excerpt {
   /** The number of the first line, counting from 1. */
   readonly start: number;
   readonly lines: ReadonlyArray<string>;
 }
 
-/** How far an excerpt reaches on either side of the finding's line, in whole statements. */
-const AROUND = 3;
-/** The most lines a statement can have and still be shown whole. */
-const WHOLE = 30;
-
 /** Lines of the code, first to last, counting from 1. */
 export interface Range {
   readonly first: number;
@@ -48,19 +40,13 @@ const ROLES: Readonly<Record<string, Piece["role"]>> = {
   ",": "separator",
 };
 
-/**
- * The code as pieces, without whitespace and comments, and the comments and
- * literals that span lines: a line that starts inside one does not read as
- * code on its own.
- */
+/** The code as pieces, without whitespace and comments. */
 const piecesOf = (code: string) => {
   const pieces: Array<Piece> = [];
-  const spans: Array<Range> = [];
   let line = 1;
   let spaced = true;
   for (const { text, kind } of scan(code)) {
     const end = line + text.split("\n").length - 1;
-    if (kind !== undefined && end > line) spans.push({ first: line, last: end });
     if (kind === "comment" || text.trim().length === 0) {
       spaced = true;
     } else if (kind !== undefined || /^[\w$]/.test(text)) {
@@ -75,7 +61,7 @@ const piecesOf = (code: string) => {
     }
     line = end;
   }
-  return { pieces, spans };
+  return { pieces };
 };
 
 /**
@@ -209,6 +195,75 @@ const statementsAround = (
   ];
 };
 
+/** The most lines a section holds, unless one statement with no group to split is longer. */
+const SECTION = 30;
+
+/**
+ * The file in sections, each ending where a statement does: its top-level
+ * statements, such as its imports, constants, and functions, packed in
+ * order into sections of at most `SECTION` lines, a decorator with what it
+ * decorates. A statement longer than that splits into the statements of its
+ * largest group, such as a class's methods or a component's body, the lines
+ * around that group going with the first and last of them. Every line is in
+ * one section: the comments and blank lines above a statement go with it,
+ * and the last section runs to the end.
+ */
+export const sectionsOf = (lines: ReadonlyArray<string>): ReadonlyArray<Range> => {
+  const { pieces } = piecesOf(lines.join("\n"));
+  const closes = closesOf(pieces);
+  const lineOf = (index: number) => pieces[index]?.line ?? 0;
+  /** Statements as ranges of at most `SECTION` lines where they can be split. */
+  const units = (statements: ReadonlyArray<Statement>): ReadonlyArray<Range> =>
+    statements.flatMap((statement): ReadonlyArray<Range> => {
+      if (statement.last - statement.first < SECTION) return [statement];
+      const largest = statement.groups.reduce<readonly [number, number] | undefined>(
+        (best, group) =>
+          best === undefined ||
+          lineOf(group[1]) - lineOf(group[0]) > lineOf(best[1]) - lineOf(best[0])
+            ? group
+            : best,
+        undefined,
+      );
+      const inner =
+        largest === undefined
+          ? []
+          : units(statementsIn(pieces, closes, largest[0] + 1, largest[1]));
+      const [head, tail] = [inner[0], inner.at(-1)];
+      if (head === undefined || tail === undefined || inner.length < 2) return [statement];
+      return [
+        { first: statement.first, last: head.last },
+        ...inner.slice(1, -1),
+        { first: tail.first, last: statement.last },
+      ];
+    });
+  const sections: Array<Range> = [];
+  /** A decorator, such as `@Command({…})`, waiting for the declaration it decorates. */
+  let decorator: Range | undefined;
+  for (const found of units(statementsIn(pieces, closes, 0, pieces.length))) {
+    if ((lines[found.first - 1] ?? "").trimStart().startsWith("@")) {
+      decorator = { first: decorator?.first ?? found.first, last: found.last };
+      continue;
+    }
+    const unit = { first: decorator?.first ?? found.first, last: found.last };
+    decorator = undefined;
+    const previous = sections.at(-1);
+    if (previous !== undefined && unit.last - previous.first < SECTION) {
+      sections[sections.length - 1] = { first: previous.first, last: unit.last };
+    } else {
+      sections.push({ first: unit.first, last: unit.last });
+    }
+  }
+  if (decorator !== undefined) sections.push(decorator);
+  // A file of comments alone, with no statement, is one section.
+  if (sections.length === 0) return lines.length === 0 ? [] : [{ first: 1, last: lines.length }];
+  // Each section starts where the one before it ends, and the last one ends with the file.
+  return sections.flatMap((section, index): ReadonlyArray<Range> => {
+    const first = (sections[index - 1]?.last ?? 0) + 1;
+    const last = index === sections.length - 1 ? lines.length : section.last;
+    return last < first ? [] : [{ first, last }];
+  });
+};
+
 /**
  * The statement that starts on `line`, such as a property, a function, or a
  * call that opens there: the outermost statement around `line` whose first
@@ -218,48 +273,3 @@ export const statementFrom = (lines: ReadonlyArray<string>, line: number): Range
   const { pieces } = piecesOf(lines.join("\n"));
   return statementsAround(pieces, closesOf(pieces), line).find((range) => range.first === line);
 };
-
-/**
- * The excerpt for a finding on `line`: the outermost statement around it
- * with at most `WHOLE` lines, such as the function it is in, and up to
- * `AROUND` lines on either side of `line`. A comment or template literal
- * that spans lines counts as a statement inside the one it is in.
- *
- * Around `line`, the excerpt shows only whole statements, never the end of
- * the one above or the start of the one below, so it cannot start partway
- * through a comment, whose lines do not read as code on their own. What
- * `line` itself is in can show in part: a long function's first line, above
- * the statement of its body. It ends at code, since a comment at the end
- * would be about code the excerpt leaves out.
- */
-export const excerptOf = (lines: ReadonlyArray<string>, line: number): Excerpt => {
-  const { pieces, spans } = piecesOf(lines.join("\n"));
-  const closes = closesOf(pieces);
-  /** What a line is in, outermost first. */
-  const around = (at: number): ReadonlyArray<Range> => [
-    ...statementsAround(pieces, closes, at),
-    ...spans.filter((span) => holds(span, at)),
-  ];
-  const scope = around(line).find((range) => range.last - range.first < WHOLE);
-  const top = Math.max(1, Math.min(scope?.first ?? line, line - AROUND));
-  const bottom = Math.min(lines.length, Math.max(scope?.last ?? line, line + AROUND));
-  /** What a line is in that `line` is not, which an edge shows whole or not at all. */
-  const beside = (at: number) => around(at).filter((range) => !holds(range, line));
-  let first = Math.max(
-    top,
-    ...beside(top)
-      .filter((range) => range.first < top)
-      .map((range) => range.last + 1),
-  );
-  let last = Math.min(
-    bottom,
-    ...beside(bottom)
-      .filter((range) => range.last > bottom)
-      .map((range) => range.first - 1),
-  );
-  const isBlank = (at: number) => (lines[at - 1] ?? "").trim().length === 0;
-  const hasCode = (at: number) => pieces.some((piece) => piece.line <= at && at <= piece.end);
-  while (first < line && isBlank(first)) first += 1;
-  while (last > line && !hasCode(last)) last -= 1;
-  return { start: first, lines: lines.slice(first - 1, last) };
-};

package/src/highlight.ts

@@ -30,6 +30,8 @@ const CLASSES = ["comment", "string", "constant"] as const;
 /** One group per token class, tried in order at each position. A template literal is read apart. */
 const TOKEN = new RegExp(
   [
+    // A URL outside a string is JSX text, as in `<a>https://example.com</a>`, and its `//` no comment.
+    /(?<url>[a-z][\w+.-]*:\/\/[^\s<>{}"'`]*)/,
     /(?<comment>\/\/[^\n]*|\/\*[\s\S]*?(?:\*\/|$))/,
     /(?<string>"(?:[^"\\\n]|\\.)*"?|'(?:[^'\\\n]|\\.)*'?)/,
     /(?<constant>0[box][\da-f_]+n?|\d[\d_]*(?:\.\d[\d_]*)?(?:e[+-]?\d+)?n?)/,

package/src/markdown.ts

@@ -32,12 +32,18 @@ import { Effect, Schema } from "effect";
  * 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]*)$/;

package/src/presets.ts

@@ -23,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;
@@ -57,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

@@ -27,7 +27,7 @@ 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.
  */

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* (