@drkmttr/adhere 0.7.1 → 0.7.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Darkmatter Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -107,6 +107,13 @@ the report goes to stdout. A request Jev refuses stops the run with the file,
 the HTTP status, and Jev's reason. Files finished before it are cached, so
 running again continues from there.
 
+The firewall in front of Jev's API can refuse a request whose code reads to
+it as an attack, with a 403 and an HTML page rather than Jev's JSON. It refuses
+the same request every run, so that file is skipped, the run goes on, and the
+report lists each such file with Cloudflare's Ray ID, which TypeSafe AI can
+look the block up by. When only the question that finds the line is refused,
+the file's judgments are kept, and a rerun sends that question alone.
+
 ### Limiting a run
 
 Three flags bound what a run does. `--limit <checks>` judges at most that many
@@ -431,3 +438,7 @@ runs. The publish workflow can be run manually for an already-created release
 tag if a publish needs to be retried; it skips every package whose version is
 already on npm. The main package's `files` list keeps it to `bin/`, `src/`,
 `presets/`, and `skills/`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "private": false,
   "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/darkmatter/adhere.git"
@@ -67,10 +68,10 @@
     }
   },
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.7.1",
-    "@drkmttr/adhere-darwin-x64": "0.7.1",
-    "@drkmttr/adhere-linux-arm64": "0.7.1",
-    "@drkmttr/adhere-linux-x64": "0.7.1",
-    "@drkmttr/adhere-win32-x64": "0.7.1"
+    "@drkmttr/adhere-darwin-arm64": "0.7.3",
+    "@drkmttr/adhere-darwin-x64": "0.7.3",
+    "@drkmttr/adhere-linux-arm64": "0.7.3",
+    "@drkmttr/adhere-linux-x64": "0.7.3",
+    "@drkmttr/adhere-win32-x64": "0.7.3"
   }
 }

package/src/services/Jev.http.ts

@@ -7,6 +7,7 @@ import {
   conflictBody,
   contradictBody,
   Jev,
+  JevBlocked,
   JevOverflow,
   JevUnavailable,
   judgeBody,
@@ -48,6 +49,11 @@ const Overflowed = Schema.fromJsonString(
 const isOverflow = (body: string): boolean =>
   Option.isSome(Schema.decodeUnknownOption(Overflowed)(body));
 
+/** A firewall's block page: HTML where Jev answers JSON, even for its own errors. */
+const isBlockPage = (response: HttpClientResponse.HttpClientResponse, body: string): boolean =>
+  (response.headers["content-type"] ?? "").includes("text/html") ||
+  body.trimStart().startsWith("<");
+
 /**
  * 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
@@ -63,19 +69,33 @@ const failed = (
   const { response } = problem.reason;
   return Effect.flatMap(
     Effect.orElseSucceed(response.text, () => ""),
-    (body): Effect.Effect<never, JevOverflow | JevUnavailable> =>
+    (body): Effect.Effect<never, JevOverflow | JevBlocked | JevUnavailable> =>
       response.status === 400 && isOverflow(body)
         ? Effect.fail(JevOverflow.make())
-        : Effect.fail(refused(`Jev answered HTTP ${response.status}${detailOf(body)}`)),
+        : response.status === 403 && isBlockPage(response, body)
+          ? Effect.fail(JevBlocked.make({ ray: response.headers["cf-ray"] ?? "none given" }))
+          : 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. */
+/**
+ * Comparing rules has no file to skip, so a request over Jev's context, or one
+ * the firewall blocks, refuses instead.
+ */
 const refuseOverflow = <A>(
-  self: Effect.Effect<A, JevOverflow | JevUnavailable>,
+  self: Effect.Effect<A, JevOverflow | JevBlocked | JevUnavailable>,
 ): Effect.Effect<A, JevUnavailable> =>
-  Effect.catchTag(self, "JevOverflow", () =>
-    Effect.fail(refused("Comparing the rules took a request over Jev's context")),
+  self.pipe(
+    Effect.catchTag("JevOverflow", () =>
+      Effect.fail(refused("Comparing the rules took a request over Jev's context")),
+    ),
+    Effect.catchTag("JevBlocked", ({ ray }) =>
+      Effect.fail(
+        refused(
+          `The firewall in front of Jev's API blocked comparing the rules (Cloudflare Ray ID ${ray})`,
+        ),
+      ),
+    ),
   );
 
 export const JevLive = Layer.effect(Jev)(

package/src/services/Jev.ts

@@ -14,17 +14,27 @@ export class JevUnavailable extends Schema.TaggedError<JevUnavailable>()("JevUna
  */
 export class JevOverflow extends Schema.TaggedError<JevOverflow>()("JevOverflow", {}) {}
 
+/**
+ * A request the firewall in front of Jev's API refused: a 403 with an HTML
+ * block page where Jev answers JSON. It reads some code as an attack, so the
+ * same request is refused every time while the rest of a run goes through.
+ * `ray` is Cloudflare's Ray ID, which TypeSafe AI can look the block up by.
+ */
+export class JevBlocked extends Schema.TaggedError<JevBlocked>()("JevBlocked", {
+  ray: Schema.String,
+}) {}
+
 export class Jev extends Context.Service<
   Jev,
   {
     readonly judge: (
       lines: Lines,
       rules: Rules,
-    ) => Effect.Effect<Record<RuleId, number>, JevUnavailable | JevOverflow>;
+    ) => Effect.Effect<Record<RuleId, number>, JevUnavailable | JevOverflow | JevBlocked>;
     readonly locate: (
       lines: Lines,
       rules: Rules,
-    ) => Effect.Effect<Record<RuleId, number>, JevUnavailable | JevOverflow>;
+    ) => Effect.Effect<Record<RuleId, number>, 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

package/src/workflows/audit.ts

@@ -32,12 +32,21 @@ export interface AuditResult {
   readonly skipped: number;
   /** Files whose checks `--limit` left for a later run, none judged in this one. */
   readonly waiting: number;
+  /** Files the firewall in front of Jev's API refused, with the ID to report each by. */
+  readonly blocked: ReadonlyArray<Blocked>;
   readonly findings: ReadonlyArray<Finding>;
 }
 
+/** A file whose request the firewall refused, and Cloudflare's Ray ID for the refusal. */
+export interface Blocked {
+  readonly file: string;
+  readonly ray: string;
+}
+
 interface FileResult {
-  readonly status: "judged" | "cached" | "skipped" | "waiting";
+  readonly status: "judged" | "cached" | "skipped" | "waiting" | "blocked";
   readonly findings: ReadonlyArray<Finding>;
+  readonly blocked?: Blocked;
 }
 
 interface PreparedRule {
@@ -257,9 +266,22 @@ export const executeAudit = (
           judgment.line === undefined
         );
       });
-      const lines = isEmpty(flagged)
-        ? {}
-        : yield* jev.locate(file.lines, rulesOf(flagged)).pipe(inFile(file));
+      // A blocked line question still leaves the judgments worth caching: a rerun
+      // asks only for the lines again, not for every rule.
+      const {
+        lines,
+        blocked,
+      }: { readonly lines: Readonly<Record<RuleId, number>>; readonly blocked?: Blocked } = isEmpty(
+        flagged,
+      )
+        ? { lines: {}, blocked: undefined }
+        : yield* jev.locate(file.lines, rulesOf(flagged)).pipe(
+            Effect.map((lines) => ({ lines, blocked: undefined })),
+            Effect.catchTag("JevBlocked", ({ ray }) =>
+              Effect.succeed({ lines: {}, blocked: { file: file.path, ray } }),
+            ),
+            inFile(file),
+          );
       const located = Record.map(judged, (judgment, id) => {
         const line = lines[id];
         return line === undefined
@@ -291,7 +313,10 @@ export const executeAudit = (
         })
         .sort((a, b) => a.line - b.line);
       return {
-        result: fileResult(cached ? (deferred > 0 ? "waiting" : "cached") : "judged", findings),
+        result:
+          blocked === undefined
+            ? fileResult(cached ? (deferred > 0 ? "waiting" : "cached") : "judged", findings)
+            : { status: "blocked", findings, blocked },
         requests:
           (isEmpty(pending) ? 0 : judgeRequests(file.lines, rulesOf(pending))) +
           (isEmpty(flagged) ? 0 : locateRequests(file.lines, rulesOf(flagged))),
@@ -309,6 +334,17 @@ export const executeAudit = (
                 requests: judgeRequests(plan.file.lines, rulesOf(plan.pending)),
               }),
             ),
+            // The firewall refuses this file's code every time; the rest of the run goes on.
+            Effect.catchTag("JevBlocked", ({ ray }) =>
+              Effect.succeed({
+                result: {
+                  status: "blocked",
+                  findings: [],
+                  blocked: { file: plan.file.path, ray },
+                } satisfies FileResult,
+                requests: judgeRequests(plan.file.lines, rulesOf(plan.pending)),
+              }),
+            ),
           );
       yield* progress({ requests, findings: result.findings.length });
       return result;
@@ -323,6 +359,7 @@ export const executeAudit = (
       cached: count("cached"),
       skipped: count("skipped"),
       waiting: count("waiting"),
+      blocked: results.flatMap((result) => (result.blocked === undefined ? [] : [result.blocked])),
       findings: results.flatMap((result) => result.findings),
     };
   });

package/src/workflows/format.ts

@@ -6,7 +6,15 @@ import type { AuditPlan, AuditResult, FileDone, Finding } from "#workflows/audit
  * token of code, named by its role. Layout measures text; only `serialize`
  * turns a role into color, so no width or blank line ever sees an escape code.
  */
-type Role = "error" | "path" | "lineNumber" | "underline" | "label" | Kind;
+type Role =
+  | "error"
+  | "probability"
+  | "description"
+  | "path"
+  | "lineNumber"
+  | "underline"
+  | "label"
+  | Kind;
 
 interface Span {
   readonly text: string;
@@ -16,17 +24,22 @@ interface Span {
 type Line = ReadonlyArray<Span>;
 
 /**
- * SGR parameters per role. The frame's match `vp lint`: truecolor
- * (`38;2;R;G;B`), bold with a trailing `;1`, and a dim line number. The code's
- * are the terminal's own colors (`3N`), so the user's theme picks shades that
- * read on its background; none is magenta, which would run into the label.
+ * SGR parameters per role. The frame's are set colors, from the 256-color
+ * palette (`38;5;N`) or truecolor (`38;2;R;G;B`), bold with a trailing `;1`,
+ * and a dim line number. Of the header, only the `×` and the rule are red,
+ * since a whole line of red is hard to read: the probability is an accent, and
+ * the description a soft white. The code's are the terminal's own colors
+ * (`3N`), so the user's theme picks shades that read on its background; none
+ * is magenta, which would run into the label.
  */
 const THEME: Readonly<Record<Role, string>> = {
-  error: "38;2;219;91;81;1",
+  error: "38;5;197;1",
+  probability: "38;2;250;179;135",
+  description: "38;2;242;205;205",
   path: "38;2;5;125;160;1",
   lineNumber: "2",
   underline: "38;2;255;0;175",
-  label: "38;2;180;105;245",
+  label: "38;5;212",
   comment: "2",
   string: "32",
   constant: "33",
@@ -77,9 +90,11 @@ const header = (finding: Finding): Line => [
   span("  "),
   span("×", "error"),
   span(" "),
-  span(`${finding.rule} (${finding.probability.toFixed(2)})`, "error"),
-  span(": "),
-  span(finding.description, "error"),
+  span(finding.rule, "error"),
+  span(" ("),
+  span(finding.probability.toFixed(2), "probability"),
+  span("): "),
+  span(finding.description, "description"),
 ];
 
 /** The path, the offending line numbered in the gutter, and an underline as long as the line. */
@@ -109,8 +124,9 @@ const hint = (finding: Finding): ReadonlyArray<Line> => {
 };
 
 /**
- * One diagnostic, in the frame `vp lint` prints on a terminal: a red header,
- * the offending line, a pink underline, and the code to write as the hint.
+ * One diagnostic, in the frame `vp lint` prints on a terminal: a header with
+ * the rule in red, 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),
@@ -125,6 +141,7 @@ const summary = (result: AuditResult): ReadonlyArray<Line> => {
     `${result.cached} cached`,
     ...(result.skipped > 0 ? [`${result.skipped} skipped`] : []),
     ...(result.waiting > 0 ? [`${result.waiting} waiting`] : []),
+    ...(result.blocked.length > 0 ? [`${result.blocked.length} blocked`] : []),
   ];
   return [
     [span(`Found ${counted(result.findings.length, "error", "errors")}.`)],
@@ -132,6 +149,27 @@ const summary = (result: AuditResult): ReadonlyArray<Line> => {
   ];
 };
 
+/**
+ * The files the firewall in front of Jev's API refused, each with the Ray ID
+ * TypeSafe AI can look the block up by, so a gap in the audit says where it is.
+ */
+const blockedFiles = (result: AuditResult, root: string | undefined): ReadonlyArray<Line> =>
+  result.blocked.length === 0
+    ? []
+    : [
+        [],
+        [
+          span(
+            `The firewall in front of Jev's API blocked ${counted(result.blocked.length, "file", "files")}, so ${result.blocked.length === 1 ? "it is" : "they are"} not judged in full. TypeSafe AI can look each block up by its Ray ID:`,
+          ),
+        ],
+        ...result.blocked.map(({ file, ray }) => [
+          span("  "),
+          span(displayPath(file, root), "path"),
+          span(` (Ray ID ${ray})`),
+        ]),
+      ];
+
 export interface RenderOptions {
   /** Color the frame the way `vp lint` does on a terminal, and highlight the code. */
   readonly color?: boolean;
@@ -147,6 +185,7 @@ export const render = (result: AuditResult, options: RenderOptions = {}): Readon
   [
     ...result.findings.flatMap((finding) => [...frame(finding, options.root), []]),
     ...summary(result),
+    ...blockedFiles(result, options.root),
   ].map((line) => serialize(line, options.color === true));
 
 /**