@drkmttr/adhere 0.6.0 → 0.7.0

package/src/services/Jev.http.ts

@@ -7,6 +7,7 @@ import {
   conflictBody,
   contradictBody,
   Jev,
+  JevOverflow,
   JevUnavailable,
   judgeBody,
   type Lines,
@@ -18,7 +19,7 @@ import {
   requestsOf,
   type Rules,
 } from "#services/Jev.ts";
-import { type Cause, Effect, Layer, Record, Schedule, Schema } from "effect";
+import { type Cause, Effect, Layer, Option, Record, Schedule, Schema } from "effect";
 import { HttpClient, HttpClientError, HttpClientResponse } from "effect/unstable/http";
 import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
 
@@ -39,21 +40,41 @@ const detailOf = (body: string): string => {
   return text.length === 0 ? "" : `: ${text.slice(0, 300)}`;
 };
 
+/** What Jev answers, with a 400, to a request over its context. */
+const Overflowed = Schema.fromJsonString(
+  Schema.Struct({ detail: Schema.Struct({ error_type: Schema.Literal("max_tokens_exceeded") }) }),
+);
+const isOverflow = (body: string): boolean =>
+  Option.isSome(Schema.decodeUnknownOption(Overflowed)(body));
+
 /**
- * A failed request as a refusal: for an answer outside 2xx, its status and
- * what Jev said, since the status alone does not say why; otherwise the cause.
+ * A request that failed. A 400 saying the request is over Jev's context is a
+ * `JevOverflow`, which skips the file. Any other answer outside 2xx refuses
+ * 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 refusalOf = (problem: HttpClientError.HttpClientError | Cause.TimeoutError) => {
+const failed = (problem: HttpClientError.HttpClientError | Cause.TimeoutError) => {
   if (!HttpClientError.isHttpClientError(problem) || problem.reason._tag !== "StatusCodeError") {
-    return Effect.succeed(refused(`System One request failed: ${problem.message}`));
+    return Effect.fail(refused(`System One request failed: ${problem.message}`));
   }
   const { response } = problem.reason;
-  return Effect.map(
+  return Effect.flatMap(
     Effect.orElseSucceed(response.text, () => ""),
-    (body) => refused(`Jev answered HTTP ${response.status}${detailOf(body)}`),
+    (body): Effect.Effect<never, JevOverflow | JevUnavailable> =>
+      response.status === 400 && isOverflow(body)
+        ? Effect.fail(JevOverflow.make())
+        : Effect.fail(refused(`Jev answered HTTP ${response.status}${detailOf(body)}`)),
   );
 };
 
+/** Comparing rules has no file to skip, so a request over Jev's context refuses instead. */
+const refuseOverflow = <A>(
+  self: Effect.Effect<A, JevOverflow | JevUnavailable>,
+): Effect.Effect<A, JevUnavailable> =>
+  Effect.catchTag(self, "JevOverflow", () =>
+    Effect.fail(refused("Comparing the rules took a request over Jev's context")),
+  );
+
 export const JevLive = Layer.effect(Jev)(
   Effect.gen(function* () {
     const config = yield* AdhereConfig;
@@ -79,7 +100,7 @@ export const JevLive = Layer.effect(Jev)(
         ).pipe(Effect.orDie);
         const response = yield* client
           .execute(HttpClientRequest.bearerToken(request, apiKey))
-          .pipe(Effect.catch((problem) => Effect.flatMap(refusalOf(problem), Effect.fail)));
+          .pipe(Effect.catch(failed));
         return yield* HttpClientResponse.schemaBodyJson(Answers)(response).pipe(
           Effect.mapError((problem) =>
             refused(`System One response did not decode: ${problem.message}`),
@@ -127,7 +148,10 @@ export const JevLive = Layer.effect(Jev)(
       rules: ReadonlyArray<ComparedRule>,
       partners: ReadonlyArray<ReadonlyArray<number>>,
     ) {
-      const answers = yield* answersTo(conflictBody(config.model, rules, partners), ChoiceAnswers);
+      const answers = yield* answersTo(
+        conflictBody(config.model, rules, partners),
+        ChoiceAnswers,
+      ).pipe(refuseOverflow);
       return namedPairs(answers, partners);
     });
 
@@ -138,8 +162,9 @@ export const JevLive = Layer.effect(Jev)(
       return yield* Effect.forEach(
         pairs,
         (pair) =>
-          Effect.map(ask(contradictBody(config.model, rules, pair), NoulAnswers), ({ answers }) =>
-            pairProbability(answers, pair),
+          Effect.map(
+            ask(contradictBody(config.model, rules, pair), NoulAnswers).pipe(refuseOverflow),
+            ({ answers }) => pairProbability(answers, pair),
           ),
         { concurrency: 8 },
       );

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 };
@@ -8,17 +8,23 @@ export class JevUnavailable extends Schema.TaggedError<JevUnavailable>()("JevUna
   message: Schema.String,
 }) {}
 
+/**
+ * Jev's refusal of a request over its context. `fits` keeps such files from
+ * being sent, but by an estimate; this is Jev's own count disagreeing.
+ */
+export class JevOverflow extends Schema.TaggedError<JevOverflow>()("JevOverflow", {}) {}
+
 export class Jev extends Context.Service<
   Jev,
   {
     readonly judge: (
       lines: Lines,
       rules: Rules,
-    ) => Effect.Effect<Record<RuleId, number>, JevUnavailable>;
+    ) => Effect.Effect<Record<RuleId, number>, JevUnavailable | JevOverflow>;
     readonly locate: (
       lines: Lines,
       rules: Rules,
-    ) => Effect.Effect<Record<RuleId, number>, JevUnavailable>;
+    ) => Effect.Effect<Record<RuleId, number>, JevUnavailable | JevOverflow>;
     /**
      * 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
@@ -66,8 +72,9 @@ const encoder = new TextEncoder();
 
 /**
  * An estimate, meant to run high, of the tokens Jev reads for a value: one
- * per three bytes of its JSON. Code runs a little over three bytes a token,
- * prose about four.
+ * per three bytes of its JSON. Jev 1.13 reads numbered TypeScript at 3.2
+ * bytes a token, and this ran 12 to 16 percent high on the eval's requests.
+ * Text that packs more tokens into its bytes, such as CJK, can outrun it.
  */
 export const tokensOf = (value: unknown): number =>
   Math.ceil(encoder.encode(JSON.stringify(value)).length / 3);
@@ -84,16 +91,23 @@ const stateOf = (lines: Lines) => ({
   code: lines.map((line, index) => `${index + 1} | ${line}`).join("\n"),
 });
 
-/** One side of a noul: what it means, with the rule's code for that side as an example. */
-const sideOf = (what: string, example: string | undefined) =>
-  example === undefined ? { what } : { what, examples: [example] };
+/** 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
@@ -112,28 +126,53 @@ 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. The criteria draw
- * the line: code to avoid is a yes, and the reference is a no, as is a file
- * with nothing the rule covers.
+ * 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) => ({
-  type: "noul" as const,
-  instructions: { question: "Does `code` break `rule`?", rule: rule.description },
-  criteria: {
-    true: sideOf("Part of `code` breaks `rule`", rule.avoid),
-    false: sideOf(
-      "Every part of `code` that `rule` covers follows it, or `rule` covers no part of `code`",
-      rule.reference,
-    ),
-  },
-});
+export const judgeQuestion = (rule: Rule) => {
+  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] =
+    good === undefined
+      ? [
+          `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 \`${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 {
+    type: "noul" as const,
+    instructions: { question, ...ruleFields(rule) },
+    criteria: {
+      true: `${yes}, in code that \`rule\` is about`,
+      false: `${no}, or has no code that \`rule\` is about`,
+    },
+  };
+};
 
-/** The rule as a line question carries it: the description, and its code on either side. */
-const ruleFields = (rule: Rule) => ({
-  rule: rule.description,
-  ...(rule.reference === undefined ? {} : { follows_rule: rule.reference }),
-  ...(rule.avoid === undefined ? {} : { breaks_rule: rule.avoid }),
-});
+/** What the offending line does, for the line and block questions. */
+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> = {};
@@ -163,7 +202,7 @@ export const locateBody = (
     return {
       type: "choice" as const,
       instructions: {
-        question: "Which line of `code` most clearly breaks `rule`?",
+        question: `Which line of \`code\` most clearly ${offense(rule)}?`,
         ...ruleFields(rule),
       },
       criteria:
@@ -188,7 +227,7 @@ export const blockBody = (model: string, lines: Lines, rules: Rules) => {
     questions: Record.map(rules, (rule) => ({
       type: "choice" as const,
       instructions: {
-        question: "Which block of `code` contains the line that most clearly breaks `rule`?",
+        question: `Which block of \`code\` contains the line that most clearly ${offense(rule)}?`,
         ...ruleFields(rule),
       },
       criteria,

package/src/workflows/audit.ts

@@ -1,4 +1,4 @@
-import type { Rule, RuleId } from "#config.ts";
+import { type Examples, examplesOf, type Rule, type RuleId } from "#config.ts";
 import type { ScannedFile, WalkUnavailable } from "#models/Audit.ts";
 import { AdhereConfig } from "#services/AdhereConfig.ts";
 import { AuditCache, type Judgment, sha256 } from "#services/AuditCache.ts";
@@ -18,8 +18,7 @@ import { type Crypto, Effect, Record } from "effect";
 export interface Finding {
   readonly rule: RuleId;
   readonly description: string;
-  readonly reference?: string;
-  readonly avoid?: string;
+  readonly examples: Examples;
   readonly file: string;
   readonly line: number;
   readonly snippet: string;
@@ -98,12 +97,16 @@ const rulesOf = (some: Readonly<Record<RuleId, PreparedRule>>) => Record.map(som
 const sizeOf = (some: Readonly<Record<string, unknown>>): number => Object.keys(some).length;
 
 /** A refusal that names the file it stopped at. Files finished before it are already cached. */
-const inFile = (file: ScannedFile) =>
-  Effect.mapError((problem: JevUnavailable) =>
-    JevUnavailable.make({
-      message: `${file.path}: ${problem.message}. Files judged before it are cached, so a rerun continues from there.`,
-    }),
-  );
+const inFile =
+  (file: ScannedFile) =>
+  <A, E, R>(self: Effect.Effect<A, E, R>) =>
+    Effect.mapError(self, (problem) =>
+      problem instanceof JevUnavailable
+        ? JevUnavailable.make({
+            message: `${file.path}: ${problem.message}. Files judged before it are cached, so a rerun continues from there.`,
+          })
+        : problem,
+    );
 
 export const planAudit: Effect.Effect<
   AuditPlan,
@@ -181,18 +184,14 @@ export const executeAudit = (
     const jev = yield* Jev;
     const cache = yield* AuditCache;
 
-    const auditFile = Effect.fn("audit.file")(function* ({
+    /** Judges and locates one file the plan left pending, with the requests that took. */
+    const judgeFile = Effect.fn("audit.judgeFile")(function* ({
       file,
-      skipped,
       hash,
       prepared,
       kept,
       pending,
     }: FilePlan) {
-      if (skipped) {
-        yield* progress({ requests: 0, findings: 0 });
-        return fileResult("skipped", []);
-      }
       const probabilities = isEmpty(pending)
         ? {}
         : yield* jev.judge(file.lines, rulesOf(pending)).pipe(inFile(file));
@@ -233,8 +232,7 @@ export const executeAudit = (
                 {
                   rule: id,
                   description: k.rule.description,
-                  reference: k.rule.reference,
-                  avoid: k.rule.avoid,
+                  examples: examplesOf(k.rule),
                   file: file.path,
                   line: judgment.line,
                   snippet: judgment.snippet ?? "",
@@ -244,13 +242,28 @@ export const executeAudit = (
             : [];
         })
         .sort((a, b) => a.line - b.line);
-      yield* progress({
+      return {
+        result: fileResult(cached ? "cached" : "judged", findings),
         requests:
           (isEmpty(pending) ? 0 : judgeRequests(file.lines, rulesOf(pending))) +
           (isEmpty(flagged) ? 0 : locateRequests(file.lines, rulesOf(flagged))),
-        findings: findings.length,
-      });
-      return fileResult(cached ? "cached" : "judged", findings);
+      };
+    });
+
+    const auditFile = Effect.fn("audit.file")(function* (plan: FilePlan) {
+      const { result, requests } = plan.skipped
+        ? { result: fileResult("skipped", []), requests: 0 }
+        : yield* judgeFile(plan).pipe(
+            // Jev counted more than `fits` estimated. Its count decides: skipped the same way.
+            Effect.catchTag("JevOverflow", () =>
+              Effect.succeed({
+                result: fileResult("skipped", []),
+                requests: judgeRequests(plan.file.lines, rulesOf(plan.pending)),
+              }),
+            ),
+          );
+      yield* progress({ requests, findings: result.findings.length });
+      return result;
     });
 
     const results = yield* Effect.forEach(plan.files, auditFile, { concurrency: 8 });

package/src/workflows/format.ts

@@ -97,16 +97,20 @@ const excerpt = (finding: Finding, root: string | undefined): ReadonlyArray<Line
   ];
 };
 
-/** The reference as the hint. A rule without one shows its code to avoid instead, labeled so. */
+/**
+ * The code to write as the hint. A rule with only code not to write shows
+ * that instead, labeled with its word: `never`, or `should not`.
+ */
 const hint = (finding: Finding): ReadonlyArray<Line> => {
+  const { good, bad } = finding.examples;
   const [label, code] =
-    finding.reference === undefined ? ["avoid", finding.avoid ?? ""] : ["hint", finding.reference];
+    good === undefined ? [bad?.word ?? "hint", bad?.code ?? ""] : ["hint", good.code];
   return hanging(span(`  ${label}: `, "label"), codeLines(code));
 };
 
 /**
  * One diagnostic, in the frame `vp lint` prints on a terminal: a red header,
- * the offending line, a pink underline, and the reference code as the hint.
+ * the offending line, a pink underline, and the code to write as the hint.
  */
 const frame = (finding: Finding, root: string | undefined): ReadonlyArray<Line> => [
   header(finding),