@drkmttr/adhere 0.10.0 → 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

@@ -52,15 +52,31 @@ export const passesFilter = (relative: string, patterns: ReadonlyArray<string>):
 };
 
 /**
- * Whether a path, relative to the working directory, is a test: a `.test.ts`
- * or `.spec.ts` file, or any file under a test directory such as `test/`.
+ * 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 (
-    name.endsWith(".test.ts") ||
-    name.endsWith(".spec.ts") ||
+    TEST_NAME.test(name) ||
+    TEST_SUPPORT_NAME.test(name) ||
     segments.slice(0, -1).some((segment) => TEST_DIRECTORIES.has(segment))
   );
 };
@@ -68,9 +84,9 @@ export const isTestFile = (relative: string): boolean => {
 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") &&
+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.

package/src/suppress.ts

@@ -5,10 +5,11 @@ 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.
+ * 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. */
@@ -105,9 +106,14 @@ export const suppressionsOf = (
   };
 };
 
-/** Whether a file's comments suppress `rule`, named as a report names it, at `line`. */
-export const suppresses = (suppressions: Suppressions, rule: string, line: number): boolean =>
+/**
+ * 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 <= line && line <= statement.last,
+    (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)`;