@drkmttr/adhere 0.6.1 → 0.7.1

package/src/markdown.ts

@@ -1,26 +1,28 @@
-import { ConfigUnavailable, type Rule } from "#config.ts";
+import { ConfigUnavailable, type Example, type Rule } from "#config.ts";
 import { Effect, Schema } from "effect";
 
 /**
  * A rule as a Markdown file:
  *
  *     ---
- *     description: One sentence naming the pattern.
+ *     description: One sentence saying what code must be, or never be.
  *     threshold: 0.8
  *     ---
  *     Any prose, rendered on GitHub and ignored by adhere.
  *
- *     ```ts
- *     const reference = "the correct code"
+ *     ```ts must
+ *     const written = "code that must be written this way"
  *     ```
  *
- *     ```ts avoid
- *     const avoided = "what a violation looks like"
+ *     ```ts never
+ *     const avoided = "code that must never be written this way"
  *     ```
  *
- * The reference is the first fenced code block; `avoid` in a fence's info
- * string marks the code to avoid instead. A rule has either or both. Without a
- * fence, the whole body is the reference. `threshold` is optional.
+ * 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.
  */
 const FrontMatter = Schema.Struct({
   description: Schema.String,
@@ -29,7 +31,6 @@ const FrontMatter = Schema.Struct({
 
 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;
-const AVOID = "avoid";
 
 const unquote = (value: string): string => {
   const trimmed = value.trim();
@@ -50,17 +51,27 @@ const parseFrontMatter = (block: string): Record<string, string> => {
   return fields;
 };
 
+type Word = Example["word"];
+
 interface Fence {
-  readonly avoid: boolean;
+  /** The word the info string names the code with; none for an untagged fence. */
+  readonly word: Word | undefined;
   readonly code: string;
 }
 
+/** `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+/);
+  const not = words.includes("not");
+  if (words.includes("never") || words.includes("avoid")) return "never";
+  if (words.includes("should")) return not ? "should not" : "should";
+  if (words.includes("must")) return not ? "never" : "must";
+  return undefined;
+};
+
 const fencesOf = (body: string): ReadonlyArray<Fence> =>
   Array.from(body.matchAll(FENCE), (match) => ({
-    avoid: (match[2] ?? "")
-      .trim()
-      .split(/\s+/)
-      .some((word) => word.toLowerCase() === AVOID),
+    word: wordOf(match[2] ?? ""),
     code: (match[3] ?? "").trim(),
   }));
 
@@ -68,16 +79,32 @@ const fencesOf = (body: string): ReadonlyArray<Fence> =>
 const nonEmpty = (code: string | undefined): string | undefined =>
   code === undefined || code.length === 0 ? undefined : code;
 
-/** The reference and the code to avoid, each left out when the body has none. */
-const codeOf = (body: string): Pick<Rule, "reference" | "avoid"> => {
+type Code = Pick<Rule, "must" | "never" | "should" | "shouldNot">;
+
+/**
+ * Each example the body has, under its word. An untagged fence is the code
+ * to write: `should` in a guideline, which a `should` or `should not` fence
+ * makes the rule, and `must` otherwise.
+ */
+const codeOf = (body: string): Code => {
   const fences = fencesOf(body);
-  const reference = nonEmpty(
-    fences.length === 0 ? body.trim() : fences.find((fence) => !fence.avoid)?.code,
-  );
-  const avoid = nonEmpty(fences.find((fence) => fence.avoid)?.code);
+  if (fences.length === 0) {
+    const must = nonEmpty(body.trim());
+    return must === undefined ? {} : { must };
+  }
+  const first = (word: Word | undefined) =>
+    nonEmpty(fences.find((fence) => fence.word === word)?.code);
+  const guideline = fences.some((fence) => fence.word === "should" || fence.word === "should not");
+  const untagged = first(undefined);
+  const must = first("must") ?? (guideline ? undefined : untagged);
+  const never = first("never");
+  const should = first("should") ?? (guideline ? untagged : undefined);
+  const shouldNot = first("should not");
   return {
-    ...(reference === undefined ? {} : { reference }),
-    ...(avoid === undefined ? {} : { avoid }),
+    ...(must === undefined ? {} : { must }),
+    ...(never === undefined ? {} : { never }),
+    ...(should === undefined ? {} : { should }),
+    ...(shouldNot === undefined ? {} : { shouldNot }),
   };
 };
 
@@ -98,9 +125,16 @@ export const parseRuleMarkdown = (
       ),
     );
     const code = codeOf(match[2]);
-    if (code.reference === undefined && code.avoid === undefined) {
+    const requirement = code.must !== undefined || code.never !== undefined;
+    const guideline = code.should !== undefined || code.shouldNot !== undefined;
+    if (requirement && guideline) {
+      return yield* ConfigUnavailable.make({
+        message: `${file}: a rule is a requirement (must, never) or a guideline (should, should not), not both`,
+      });
+    }
+    if (!requirement && !guideline) {
       return yield* ConfigUnavailable.make({
-        message: `${file}: the body needs reference code, a fence tagged avoid, or both`,
+        message: `${file}: the body needs code, in a fence tagged must, never, should, or should not, or untagged`,
       });
     }
     return { ...front, ...code };

package/src/services/Jev.http.ts

@@ -19,9 +19,10 @@ import {
   requestsOf,
   type Rules,
 } from "#services/Jev.ts";
-import { type Cause, Effect, Layer, Option, Record, Schedule, Schema } from "effect";
+import { type Cause, Duration, Effect, Layer, Option, Record, 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";
 
 const SYSTEM_ONE = "https://api.typesafe.ai/v1/systemone";
 
@@ -53,7 +54,9 @@ const isOverflow = (body: string): boolean =>
  * the run with its status and what Jev said, since the status alone does not
  * say why, and a request that got no answer refuses with the cause.
  */
-const failed = (problem: HttpClientError.HttpClientError | Cause.TimeoutError) => {
+const failed = (
+  problem: HttpClientError.HttpClientError | RateLimiter.RateLimiterError | Cause.TimeoutError,
+) => {
   if (!HttpClientError.isHttpClientError(problem) || problem.reason._tag !== "StatusCodeError") {
     return Effect.fail(refused(`System One request failed: ${problem.message}`));
   }
@@ -79,8 +82,27 @@ export const JevLive = Layer.effect(Jev)(
   Effect.gen(function* () {
     const config = yield* AdhereConfig;
     const credentials = yield* Credentials;
-    const client = (yield* HttpClient.HttpClient).pipe(
-      HttpClient.filterStatusOk,
+    const http = (yield* HttpClient.HttpClient).pipe(HttpClient.filterStatusOk);
+    // `--rpm`: one request per 60/rpm seconds, evenly spaced rather than in a
+    // burst each minute. Before the retries, so a retry waits its turn too.
+    type Failure = HttpClientError.HttpClientError | RateLimiter.RateLimiterError;
+    const paced: HttpClient.HttpClient.With<Failure> =
+      config.rpm === undefined
+        ? // The same client, typed to fail the ways the throttled one can.
+          HttpClient.transformResponse(
+            http,
+            (response): Effect.Effect<HttpClientResponse.HttpClientResponse, Failure> => response,
+          )
+        : http.pipe(
+            HttpClient.withRateLimiter({
+              limiter: yield* RateLimiter.RateLimiter,
+              key: "jev",
+              algorithm: "token-bucket",
+              limit: 1,
+              window: Duration.millis(60_000 / config.rpm),
+            }),
+          );
+    const client = paced.pipe(
       HttpClient.transformResponse(Effect.timeout("30 seconds")),
       HttpClient.retryTransient({
         schedule: Schedule.exponential("500 millis"),
@@ -172,4 +194,4 @@ export const JevLive = Layer.effect(Jev)(
 
     return Jev.of({ judge, locate, conflicts, contradicts });
   }),
-);
+).pipe(Layer.provide(RateLimiter.layer.pipe(Layer.provide(RateLimiter.layerStoreMemory))));

package/src/services/Jev.ts

@@ -1,4 +1,4 @@
-import type { Rule, RuleId, Rules } from "#config.ts";
+import { type Example, examplesOf, type Rule, type RuleId, type Rules } from "#config.ts";
 import { Context, type Effect, Record, Schema } from "effect";
 
 export type { Rules };
@@ -91,19 +91,23 @@ const stateOf = (lines: Lines) => ({
   code: lines.map((line, index) => `${index + 1} | ${line}`).join("\n"),
 });
 
-/** The rule as its questions carry it: the description, and its code on either side. */
-const ruleFields = (rule: Rule) => ({
-  rule: rule.description,
-  ...(rule.reference === undefined ? {} : { reference: rule.reference }),
-  ...(rule.avoid === undefined ? {} : { avoid: rule.avoid }),
-});
+/** The field an example goes under in a question: its word, with `should not` as `should_not`. */
+const fieldOf = (example: Example): string => example.word.replace(" ", "_");
 
-/** A rule's text as a comparison of rules reads it. Code a rule lacks is left out, not sent empty. */
-const ruleState = ({ description, reference, avoid }: Rule) => ({
-  description,
-  ...(reference === undefined ? {} : { reference }),
-  ...(avoid === undefined ? {} : { avoid }),
-});
+/** A rule's examples under their words. Code a rule lacks is left out, not sent empty. */
+const exampleFields = (rule: Rule): Record<string, string> => {
+  const { good, bad } = examplesOf(rule);
+  return {
+    ...(good === undefined ? {} : { [fieldOf(good)]: good.code }),
+    ...(bad === undefined ? {} : { [fieldOf(bad)]: bad.code }),
+  };
+};
+
+/** The rule as its questions carry it: the description, and its examples under their words. */
+const ruleFields = (rule: Rule) => ({ rule: rule.description, ...exampleFields(rule) });
+
+/** A rule's text as a comparison of rules reads it. */
+const ruleState = (rule: Rule) => ({ description: rule.description, ...exampleFields(rule) });
 
 /**
  * The compared rules a question mentions, keyed by index: ids alone would
@@ -122,24 +126,31 @@ const comparedState = (rules: ReadonlyArray<ComparedRule>, mentioned: Iterable<n
 
 /**
  * Whether the file breaks the rule. The rule rides in the question, not the
- * state, so each question reads its own rule and no other. A rule with a
- * reference asks whether the file diverges from it, with the code to avoid
- * as an example when there is some. A rule without one asks whether the file
- * contains the code to avoid. The criteria draw the line at the rule's scope:
- * a file with no code the rule is about is a no.
+ * state, so each question reads its own rule and no other, its code under its
+ * own words: `must` and `never`, or a guideline's `should` and `should_not`.
+ * A rule with code to write asks whether the file diverges from it, with the
+ * code not to write as an example when there is some. A rule without any
+ * asks whether the file contains the code not to write. The criteria draw the
+ * line at the rule's scope: a file with no code the rule is about is a no.
+ *
+ * On the eval, "diverge from the pattern shown in `must`" judged better than
+ * asking whether code "must be written the way `must` shows": the same words,
+ * but a pattern to compare rather than code to match.
  */
 export const judgeQuestion = (rule: Rule) => {
-  const example = rule.avoid === undefined ? "" : ", for example by doing what `avoid` shows";
+  const { good, bad } = examplesOf(rule);
+  const avoided = fieldOf(bad ?? { word: "never", code: "" });
+  const example = bad === undefined ? "" : `, for example by doing what \`${avoided}\` shows`;
   const [question, yes, no] =
-    rule.reference === undefined
+    good === undefined
       ? [
-          "Does `code` contain the pattern shown in `avoid`, which `rule` rules out? Answer no if nothing in this file resembles it.",
-          "`code` contains the pattern shown in `avoid`",
-          "`code` has nothing like `avoid`",
+          `Does \`code\` contain the pattern shown in \`${avoided}\`, which \`rule\` rules out? Answer no if nothing in this file resembles it.`,
+          `\`code\` contains the pattern shown in \`${avoided}\``,
+          `\`code\` has nothing like \`${avoided}\``,
         ]
       : [
-          `Does \`code\` diverge from the pattern shown in \`reference\`${example}, as described by \`rule\`? Answer no if the pattern does not apply to this file.`,
-          `\`code\` diverges from the pattern shown in \`reference\`${example}`,
+          `Does \`code\` diverge from the pattern shown in \`${fieldOf(good)}\`${example}, as described by \`rule\`? Answer no if the pattern does not apply to this file.`,
+          `\`code\` diverges from the pattern shown in \`${fieldOf(good)}\`${example}`,
           "`code` follows the pattern",
         ];
   return {
@@ -153,12 +164,15 @@ export const judgeQuestion = (rule: Rule) => {
 };
 
 /** What the offending line does, for the line and block questions. */
-const offense = (rule: Rule): string =>
-  rule.reference === undefined
-    ? "shows the pattern in `avoid`"
-    : rule.avoid === undefined
-      ? "diverges from `reference`"
-      : "diverges from `reference` or resembles `avoid`";
+const offense = (rule: Rule): string => {
+  const { good, bad } = examplesOf(rule);
+  const avoided = `\`${fieldOf(bad ?? { word: "never", code: "" })}\``;
+  return good === undefined
+    ? `shows the pattern in ${avoided}`
+    : bad === undefined
+      ? `diverges from \`${fieldOf(good)}\``
+      : `diverges from \`${fieldOf(good)}\` or resembles ${avoided}`;
+};
 
 const lineCriteria = (lines: Lines, from: number, to: number): Record<string, string> => {
   const criteria: Record<string, string> = {};

package/src/services/SourceWalker.ts

@@ -1,3 +1,4 @@
+import { matchesGlob } from "node:path";
 import { Context, Effect, FileSystem, Layer, Path } from "effect";
 import { ADHERE_DIRECTORY, SKIPPED_DIRECTORIES } from "#config.ts";
 import type { ScannedFile } from "#models/Audit.ts";
@@ -31,6 +32,22 @@ export const isInSkippedTree = (relative: string): boolean =>
     .split(/[\\/]/)
     .some((segment) => segment === ADHERE_DIRECTORY || SKIPPED_DIRECTORIES.has(segment));
 
+/**
+ * Whether a path, relative to the working directory, passes a run's filter.
+ * A pattern is a glob; one starting with `!` leaves out what it matches. A
+ * path passes when no `!` pattern matches it and either another pattern does
+ * or there are none.
+ */
+export const passesFilter = (relative: string, patterns: ReadonlyArray<string>): boolean => {
+  const path = relative.replaceAll("\\", "/");
+  const matches = (pattern: string) => matchesGlob(path, pattern);
+  const include = patterns.filter((pattern) => !pattern.startsWith("!"));
+  const exclude = patterns
+    .filter((pattern) => pattern.startsWith("!"))
+    .map((pattern) => pattern.slice(1));
+  return (include.length === 0 || include.some(matches)) && !exclude.some(matches);
+};
+
 const isInside = (file: string, root: string): boolean =>
   file === root || file.startsWith(`${root}/`);
 
@@ -49,18 +66,21 @@ const refused = (problem: { readonly message: string }): WalkUnavailable =>
 /** `readdir(recursive)` yields paths relative to the root it read: root them. */
 const rooted = (root: string, paths: ReadonlyArray<string>) => paths.map((rel) => `${root}/${rel}`);
 
+/** A test on a path relative to the root being read: whether the run wants it. */
+type Keep = (relative: string) => boolean;
+
 /** What the root actually contains: only paths the audit reads. */
-const scannable = (root: string, paths: ReadonlyArray<string>, self: string) =>
+const scannable = (root: string, paths: ReadonlyArray<string>, self: string, keep: Keep) =>
   rooted(
     root,
-    paths.filter((relative) => !isInSkippedTree(relative)),
+    paths.filter((relative) => !isInSkippedTree(relative) && keep(relative)),
   ).filter((file) => isScannable(file, self));
 
 /** One root's paths, filtered to what the audit reads. */
 const listRoot = Effect.fn("SourceWalker.listRoot")(
-  (fs: FileSystem.FileSystem, root: string, self: string) =>
+  (fs: FileSystem.FileSystem, root: string, self: string, keep: Keep) =>
     Effect.map(fs.readDirectory(root, { recursive: true }), (paths) =>
-      scannable(root, paths, self),
+      scannable(root, paths, self, keep),
     ),
 );
 
@@ -78,8 +98,8 @@ const readEach = (fs: FileSystem.FileSystem, paths: ReadonlyArray<string>) =>
 
 /** One root's files, in directory order: read every scannable path. */
 const readRoot = Effect.fn("SourceWalker.readRoot")(
-  (fs: FileSystem.FileSystem, root: string, self: string) =>
-    Effect.flatMap(listRoot(fs, root, self), (paths) => readEach(fs, paths)),
+  (fs: FileSystem.FileSystem, root: string, self: string, keep: Keep) =>
+    Effect.flatMap(listRoot(fs, root, self, keep), (paths) => readEach(fs, paths)),
 );
 
 /**
@@ -103,20 +123,24 @@ const scanDirs = Effect.fn("SourceWalker.scanDirs")(function* (
  * The scan root is the current working directory, so the audit reads the
  * repository it is run in.
  */
-export const SourceWalkerLive = Layer.effect(SourceWalker)(
-  Effect.gen(function* () {
-    const fs = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    // 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 walk = Effect.fn("SourceWalker.files")(function* () {
-      const dirs = yield* scanDirs(fs, root).pipe(Effect.mapError(refused));
-      const trees = yield* Effect.forEach(dirs, (dir) =>
-        readRoot(fs, path.join(root, dir), self).pipe(Effect.mapError(refused)),
-      );
-      return trees.flat();
-    });
-    return SourceWalker.of({ files: walk() });
-  }),
-);
+export const SourceWalkerLive = (filter: ReadonlyArray<string> = []) =>
+  Layer.effect(SourceWalker)(
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      // 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 walk = Effect.fn("SourceWalker.files")(function* () {
+        const dirs = yield* scanDirs(fs, root).pipe(Effect.mapError(refused));
+        const trees = yield* Effect.forEach(dirs, (dir) =>
+          readRoot(fs, path.join(root, dir), self, (relative) =>
+            // Filter patterns are relative to the working directory, not the tree read.
+            passesFilter(dir === "." ? relative : `${dir}/${relative}`, filter),
+          ).pipe(Effect.mapError(refused)),
+        );
+        return trees.flat();
+      });
+      return SourceWalker.of({ files: walk() });
+    }),
+  );