@drkmttr/adhere 0.6.0 → 0.6.1

package/README.md

@@ -1,7 +1,8 @@
 # adhere
 
 A linter for rules a normal linter cannot check. A rule is a one-sentence
-description plus correct reference code, code to avoid, or both. For each
+description like "business logic should live in services", plus correct 
+reference code / code to avoid / or both. For each
 source file, adhere asks [Jev](https://typesafe.ai) (TypeSafe AI's System One
 model) whether the file breaks each rule, gets a calibrated probability per
 rule, and reports the ones above a threshold with the line Jev points at. The
@@ -9,18 +10,23 @@ report uses the same frame as `vp lint`.
 
 Deterministic rules (substring matches, type checks) belong in a normal linter.
 
+A preset for effect is included which can be run without setup: 
+
+```sh
+TYPESAFE_API_KEY=xxx npx @drkmttr/adhere lint --preset effect
+```
+
 ## Install
 
 ```sh
-npm install --global @drkmttr/adhere   # or: bun add --global @drkmttr/adhere
+bun add --global @drkmttr/adhere   # or: npm install --global @drkmttr/adhere
 ```
 
 To pin the version in a repo, for CI or scripts, add it as a dev dependency
-and run `npx adhere`. To try it without installing, run
-`npx @drkmttr/adhere` or `bunx @drkmttr/adhere`.
+and run `npx adhere`.
 
 `adhere` is a prebuilt executable for macOS and Linux on arm64 and x64 and for
-Windows on x64. It needs Node to start, and no Bun.
+Windows on x64. .
 
 adhere sends each file it judges to Jev at `api.typesafe.ai`, authenticated
 with a TypeSafe AI API key: the one `adhere login` saved, or
@@ -32,7 +38,7 @@ with a TypeSafe AI API key: the one `adhere login` saved, or
 adhere init                          # .adhere/config.ts and two example rules
 echo ".adhere/cache/" >> .gitignore
 adhere login                         # save your TypeSafe AI API key, once
-adhere validate                      # check the rules, and ask Jev whether any contradict
+adhere validate                      # Checks your rules for contradictions using Jev
 adhere lint                          # audit the working directory
 ```
 
@@ -275,13 +281,13 @@ beats all of the above for that rule.
 
 1. One Jev request per file. The state is the file's numbered lines and
    nothing else. Each rule is one `noul` (yes/no probability) question that
-   carries the rule: whether the file breaks the rule's description, with
-   criteria for each answer. Yes means part of the file breaks the rule, and
-   the code to avoid is an example of it. No means the file follows the rule
-   or has nothing the rule covers, and the reference is an example of it.
-   Since no rule sits in the shared state, a rule's probability depends only
-   on the file and that rule, not on which other rules share the request.
-   Every question shares the state cost of the request.
+   carries the rule's description, reference, and code to avoid: whether the
+   file diverges from the reference or, for a rule with only code to avoid,
+   whether it contains that code. Criteria for each answer draw the line at
+   the rule's scope, so a file with no code the rule is about is a no. Since
+   no rule sits in the shared state, a rule's probability depends only on the
+   file and that rule, not on which other rules share the request. Every
+   question shares the state cost of the request.
 2. A second request only when at least one rule's probability is above its
    threshold: one `choice` question per flagged rule over the file's non-blank
    lines, which yields the line to report. A file with more than 255 non-blank
@@ -291,7 +297,9 @@ beats all of the above for that rule.
    about three bytes a token. When a file's questions would not fit in one
    request, they are split across several. A file whose code and longest
    question would not fit together, or that has more than 5100 lines, is
-   skipped and counted in the summary, and the rest of the run goes on.
+   skipped and counted in the summary, and the rest of the run goes on. So is
+   a file Jev itself counts as over its context, which text denser than the
+   estimate, such as CJK, can cause.
 
 ## Cache
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "private": false,
   "description": "Lints a repository against reference code in .adhere/, judged by Jev.",
   "repository": {
@@ -67,10 +67,10 @@
     }
   },
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.6.0",
-    "@drkmttr/adhere-darwin-x64": "0.6.0",
-    "@drkmttr/adhere-linux-arm64": "0.6.0",
-    "@drkmttr/adhere-linux-x64": "0.6.0",
-    "@drkmttr/adhere-win32-x64": "0.6.0"
+    "@drkmttr/adhere-darwin-arm64": "0.6.1",
+    "@drkmttr/adhere-darwin-x64": "0.6.1",
+    "@drkmttr/adhere-linux-arm64": "0.6.1",
+    "@drkmttr/adhere-linux-x64": "0.6.1",
+    "@drkmttr/adhere-win32-x64": "0.6.1"
   }
 }

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

@@ -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,9 +91,12 @@ 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 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 }),
+});
 
 /** 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) => ({
@@ -112,28 +122,43 @@ 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. 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.
  */
-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 example = rule.avoid === undefined ? "" : ", for example by doing what `avoid` shows";
+  const [question, yes, no] =
+    rule.reference === 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\` 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}`,
+          "`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 =>
+  rule.reference === undefined
+    ? "shows the pattern in `avoid`"
+    : rule.avoid === undefined
+      ? "diverges from `reference`"
+      : "diverges from `reference` or resembles `avoid`";
 
 const lineCriteria = (lines: Lines, from: number, to: number): Record<string, string> => {
   const criteria: Record<string, string> = {};
@@ -163,7 +188,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 +213,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

@@ -98,12 +98,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 +185,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));
@@ -244,13 +244,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 });