@drkmttr/adhere 0.9.4 → 0.9.5

package/README.md

@@ -66,7 +66,10 @@ Found 1 error.
 42 files, 3 judged, 39 cached.
 ```
 
-The header is the rule id, Jev's probability, and the rule's description.
+The header is the rule id, Jev's probability, and the rule's description. A
+preset's rule has the preset's name first, as in
+`effect/basics/external-calls-are-resilient`, so a report that mixes presets
+with a repo's own rules says where each came from.
 Under it is the line Jev points at, underlined, with the code around it: the
 largest statement around the line that is 30 lines or fewer, usually the whole
 function, and up to 3 lines of whole statements on either side. The
@@ -111,9 +114,17 @@ what judging takes:
 ```text
 200 files and 14 rules: 2800 checks, 1400 cached.
 Judging the other 1400 takes 200 requests to Jev, plus 1 or more for each file with a finding.
-? Send 200 requests to Jev? › (Y/n)
+Those carry about 1.9 million input tokens: about $0.08 at $0.042 per million, and more for locating findings.
+? Send 200 requests to Jev, about $0.08? › (Y/n)
 ```
 
+The cost is adhere's estimate of the input tokens times the model's price.
+Jev charges only for input tokens: $0.042 a million for `jev-latest`, per
+[TypeSafe AI's models page](https://docs.typesafe.ai/models) in September 2026.
+The estimate runs about a tenth high, and locating findings, which depends on
+what judging finds, comes on top. For a model adhere has no price for, the plan
+gives the tokens alone.
+
 It asks only with a terminal on stdin and stdout, and never when the cache
 answers every check; `--yes` sends without asking. While it runs, a counter on
 stderr shows the files done, the requests sent, and the findings so far, and
@@ -377,7 +388,8 @@ A preset has the shape of a config without `presets`: `rules`, and optionally
 `model` and `threshold`. Name presets in the config's `presets`, or on the
 command line with `--preset`, repeated or separated by commas, as in
 `--preset effect,alchemy`, in which case the config file is optional. Presets
-named in both places apply together. There are two:
+named in both places apply together. Reports name a preset's rule with the
+preset first, as in `alchemy/secrets/…`. There are two:
 
 - `effect`: Markdown rules in [`presets/effect/`](./presets/effect/), lifted
   from the [effect-solutions](https://github.com/kitlangton/effect-solutions)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "private": false,
   "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
   "license": "MIT",
@@ -68,10 +68,10 @@
     }
   },
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.9.4",
-    "@drkmttr/adhere-darwin-x64": "0.9.4",
-    "@drkmttr/adhere-linux-arm64": "0.9.4",
-    "@drkmttr/adhere-linux-x64": "0.9.4",
-    "@drkmttr/adhere-win32-x64": "0.9.4"
+    "@drkmttr/adhere-darwin-arm64": "0.9.5",
+    "@drkmttr/adhere-darwin-x64": "0.9.5",
+    "@drkmttr/adhere-linux-arm64": "0.9.5",
+    "@drkmttr/adhere-linux-x64": "0.9.5",
+    "@drkmttr/adhere-win32-x64": "0.9.5"
   }
 }

package/src/contradictions.ts

@@ -1,4 +1,4 @@
-import type { RuleEntry } from "#rules.ts";
+import { type RuleEntry, shownId } from "#rules.ts";
 import { Jev, type Pair } from "#services/Jev.ts";
 import { Effect } from "effect";
 
@@ -69,7 +69,9 @@ export const findContradictions = Effect.fn("findContradictions")(function* (
   });
 });
 
-const locationOf = (entry: RuleEntry): string => `${entry.id} (${entry.file ?? entry.scope})`;
+/** Where a rule lives: a preset's names the preset in its id; the project's own rule names its file. */
+const locationOf = (entry: RuleEntry): string =>
+  entry.preset === undefined ? `${entry.id} (${entry.file ?? entry.scope})` : shownId(entry);
 
 export const formatContradictions = (contradictions: ReadonlyArray<Contradiction>): string => {
   if (contradictions.length === 0) {

package/src/mechanical.ts

@@ -1,5 +1,5 @@
 import type { Rule } from "#config.ts";
-import type { RuleEntry } from "#rules.ts";
+import { type RuleEntry, shownId } from "#rules.ts";
 import { AuditCache, sha256, type Tally } from "#services/AuditCache.ts";
 import { linterQuestion } from "#services/Jev.ts";
 import { Effect } from "effect";
@@ -76,7 +76,7 @@ export const formatLinterCheck = (
       : [
           `${flagged.length} ${flagged.length === 1 ? "rule" : "rules"} flagged by the linter check:`,
           ...flagged.flatMap((one) => [
-            `  ${one.entry.id}${one.entry.file === undefined ? "" : ` (${displayPath(one.entry.file, root)})`}`,
+            `  ${shownId(one.entry)}${one.entry.file === undefined ? "" : ` (${displayPath(one.entry.file, root)})`}`,
             `    ${adviceOf(one)}`,
           ]),
         ]),

package/src/presets.ts

@@ -57,4 +57,7 @@ export const presets: Readonly<Record<WholePreset, BuiltInPreset>> = {
 };
 
 /** The directory each whole preset reads, for checking `topics` against it. */
+/** The whole preset a name belongs to: effect, for effect and for effect/basics alike. */
+export const wholePresetOf = (name: PresetName): string => name.split("/")[0] ?? name;
+
 export const topicsOf = (preset: WholePreset): ReadonlyArray<string> => topics[preset];

package/src/pricing.ts

@@ -0,0 +1,14 @@
+/**
+ * Jev's price for input tokens, in dollars per million, by the name a config
+ * sends as its model. Output tokens are free. From TypeSafe AI's models page,
+ * https://docs.typesafe.ai/models, on 2026-09-25, when jev-latest and
+ * jev-preview both pointed to jev-1.13.0.
+ */
+const DOLLARS_PER_MILLION: Readonly<Record<string, number>> = {
+  "jev-1.13.0": 0.042,
+  "jev-latest": 0.042,
+  "jev-preview": 0.042,
+};
+
+/** The model's price per million input tokens, when adhere knows it. */
+export const priceOf = (model: string): number | undefined => DOLLARS_PER_MILLION[model];

package/src/rules.ts

@@ -20,10 +20,19 @@ export interface RuleEntry {
   readonly rule: Rule;
   readonly scope: string;
   readonly file?: string;
-  /** The built-in rule set the rule came from, when it is not the project's own. */
+  /** The built-in preset the rule came from, by its whole name (effect for effect/basics), when it is not the project's own. */
   readonly preset?: string;
 }
 
+/**
+ * A rule's id as output shows it: a preset's rule with the preset's name
+ * first, as in effect/basics/external-calls-are-resilient, so a report that
+ * mixes presets with the project's own rules says where each came from. The
+ * project's own rules show their `.adhere/` ids as they are.
+ */
+export const shownId = (entry: { readonly id: RuleId; readonly preset?: string }): string =>
+  entry.preset === undefined ? entry.id : `${entry.preset}/${entry.id}`;
+
 export type RuleSet = ReadonlyArray<RuleEntry>;
 
 const ADHERE_SEGMENT = ".adhere";

package/src/services/AdhereConfig.ts

@@ -11,7 +11,7 @@ import {
   type ResolvedConfig,
   resolveConfig,
 } from "#config.ts";
-import { type PresetName, presetOf } from "#presets.ts";
+import { type PresetName, presetOf, wholePresetOf } from "#presets.ts";
 import {
   applicableRules,
   globalRuleSet,
@@ -95,7 +95,10 @@ export const AdhereConfigLive = (overrides: Overrides) =>
       ).pipe(Effect.map(Record.fromEntries));
       const resolved = resolveConfig({ ...config, rules }, overrides, registry);
       const presetEntries = Object.entries(registry).flatMap(([name, preset]) =>
-        globalRuleSet(preset.rules, cwd).map((entry) => ({ ...entry, preset: name })),
+        globalRuleSet(preset.rules, cwd).map((entry) => ({
+          ...entry,
+          preset: wholePresetOf(name as PresetName),
+        })),
       );
       yield* Effect.logDebug(
         `config: ${configFile ?? "no config file"}; presets ${Object.keys(registry).join(", ") || "none"}; ${presetEntries.length} preset and ${projectEntries.length} project rules; model ${resolved.model}, threshold ${resolved.threshold}${resolved.rpm === undefined ? "" : `, at most ${resolved.rpm} requests a minute`}`,

package/src/services/Jev.ts

@@ -344,6 +344,23 @@ export const requestsOf = (body: Body): ReadonlyArray<Body> => {
   return requests.map(({ questions }) => ({ ...body, questions }));
 };
 
+/**
+ * The requests judging `rules` over a file takes, and about how many input
+ * tokens they carry, by `tokensOf`: the judge body, split to fit, as `judge`
+ * sends it, each request with the file again.
+ */
+export const judgeLoad = (
+  lines: Lines,
+  rules: Rules,
+  sampled: ReadonlyArray<RuleId> = [],
+): { readonly requests: number; readonly tokens: number } => {
+  const requests = requestsOf(judgeBody("", lines, rules, sampled));
+  return {
+    requests: requests.length,
+    tokens: requests.reduce((sum, request) => sum + tokensOf(request), 0),
+  };
+};
+
 /** The requests judging `rules` over a file takes: the judge body, split to fit, as `judge` sends it. */
 export const judgeRequests = (
   lines: Lines,

package/src/wording.ts

@@ -1,5 +1,5 @@
 import { type Example, examplesOf, type Rule } from "#config.ts";
-import type { RuleEntry } from "#rules.ts";
+import { type RuleEntry, shownId } from "#rules.ts";
 
 type Word = Example["word"];
 
@@ -83,7 +83,7 @@ export const formatStrays = (strays: ReadonlyArray<Stray>, root: string): Readon
     : [
         `${strays.length} ${strays.length === 1 ? "rule is" : "rules are"} not worded as the rule writing tips recommend:`,
         ...strays.flatMap(({ entry, straying }) => [
-          `  ${entry.id}${entry.file === undefined ? "" : ` (${displayPath(entry.file, root)})`}`,
+          `  ${shownId(entry)}${entry.file === undefined ? "" : ` (${displayPath(entry.file, root)})`}`,
           ...straying.map((one) => `    ${sentenceOf(one)}`),
         ]),
         `Rule writing tips: ${TIPS_URL}`,

package/src/workflows/audit.ts

@@ -9,6 +9,7 @@ import {
   JevUnavailable,
   type Judged,
   judgeQuestion,
+  judgeLoad,
   judgeRequests,
   linterQuestion,
   locateRequests,
@@ -18,11 +19,14 @@ import {
 import { SourceWalker } from "#services/SourceWalker.ts";
 import { clearingStatus, counted, countOf, Status } from "#services/Status.ts";
 import { SAMPLE, tallyKeyOf } from "#mechanical.ts";
+import { priceOf } from "#pricing.ts";
 import { applicableRules } from "#rules.ts";
 import { type Crypto, Duration, Effect, Record, Result, Semaphore } from "effect";
 
 export interface Finding {
   readonly rule: RuleId;
+  /** The preset the rule came from, when it is not the project's own. */
+  readonly preset?: string;
   readonly description: string;
   readonly examples: Examples;
   readonly file: string;
@@ -60,6 +64,8 @@ interface PreparedRule {
   readonly rule: Rule;
   readonly fingerprint: string;
   readonly threshold: number;
+  /** The preset the rule came from, when it is not the project's own. */
+  readonly preset?: string;
 }
 
 const fileResult = (
@@ -108,6 +114,10 @@ export interface AuditPlan {
   readonly deferred: number;
   /** Requests to Jev that judging the other checks takes. Locating findings adds 1 or more per file. */
   readonly requests: number;
+  /** About how many input tokens those requests carry, which Jev charges for. */
+  readonly tokens: number;
+  /** The model's price per million input tokens, in dollars, when adhere knows it. */
+  readonly price?: number;
 }
 
 /** A file finished, for a progress counter: the requests it took and the findings it has. */
@@ -194,11 +204,18 @@ export const planAudit = (
       const prepared: Record<RuleId, PreparedRule> = yield* Effect.forEach(
         Object.entries(rules),
         ([id, rule]) =>
-          Effect.map(
-            fingerprintOf(config.model, rule),
-            (fingerprint) =>
-              [id, { rule, fingerprint, threshold: rule.threshold ?? config.threshold }] as const,
-          ),
+          Effect.map(fingerprintOf(config.model, rule), (fingerprint) => {
+            const preset = presetOfRule.get(rule);
+            return [
+              id,
+              {
+                rule,
+                fingerprint,
+                threshold: rule.threshold ?? config.threshold,
+                ...(preset === undefined ? {} : { preset }),
+              },
+            ] as const;
+          }),
       ).pipe(Effect.map(Record.fromEntries));
       const answers = yield* cache.get(hash, file.path);
       const kept: Record<RuleId, Judgment> = Record.filterMap(prepared, ({ fingerprint }) => {
@@ -221,6 +238,12 @@ export const planAudit = (
       } satisfies FilePlan;
     });
 
+    // Each preset's rule, with the preset it came from, for its findings to name.
+    const presetOfRule = new Map(
+      (config.scopedRules ?? []).flatMap((entry) =>
+        entry.preset === undefined ? [] : [[entry.rule, entry.preset] as const],
+      ),
+    );
     // Preset rules are not the project's to change, so the linter check leaves them out.
     const presetRules = new Set(
       (config.scopedRules ?? []).flatMap((entry) =>
@@ -304,6 +327,12 @@ export const planAudit = (
       options.limit === undefined ? everything : withinLimit(everything, options.limit);
     const planned = yield* withSamples(limited);
     const judged = planned.filter((plan) => !plan.skipped);
+    const loads = judged.map((plan) =>
+      isEmpty(plan.pending)
+        ? { requests: 0, tokens: 0 }
+        : judgeLoad(plan.file.lines, rulesOf(plan.pending), Object.keys(plan.sampled)),
+    );
+    const price = priceOf(config.model);
     const total = (count: (plan: FilePlan) => number) =>
       judged.reduce((sum, plan) => sum + count(plan), 0);
     return {
@@ -313,11 +342,9 @@ export const planAudit = (
       cached: total((plan) => sizeOf(plan.kept)),
       skipped: planned.length - judged.length,
       deferred: total((plan) => plan.deferred),
-      requests: total((plan) =>
-        isEmpty(plan.pending)
-          ? 0
-          : judgeRequests(plan.file.lines, rulesOf(plan.pending), Object.keys(plan.sampled)),
-      ),
+      requests: loads.reduce((sum, load) => sum + load.requests, 0),
+      tokens: loads.reduce((sum, load) => sum + load.tokens, 0),
+      ...(price === undefined ? {} : { price }),
     };
   });
 
@@ -417,6 +444,7 @@ export const executeAudit = (
             ? [
                 {
                   rule: id,
+                  ...(k.preset === undefined ? {} : { preset: k.preset }),
                   description: k.rule.description,
                   examples: examplesOf(k.rule),
                   file: file.path,

package/src/workflows/format.ts

@@ -1,4 +1,5 @@
 import { type Kind, tokenize } from "#highlight.ts";
+import { shownId } from "#rules.ts";
 import type { AuditPlan, AuditResult, FileDone, Finding } from "#workflows/audit.ts";
 
 /**
@@ -91,7 +92,7 @@ const header = (finding: Finding): Line => [
   span("  "),
   span("×", "error"),
   span(" "),
-  span(finding.rule, "error"),
+  span(shownId({ id: finding.rule, preset: finding.preset }), "error"),
   span(" ("),
   span(finding.probability.toFixed(2), "probability"),
   span("): "),
@@ -224,6 +225,41 @@ const durationAt = (requests: number, rpm: number): string => {
     : counted(Math.round(seconds / 60), "minute", "minutes");
 };
 
+/** A number to one decimal place, without a trailing .0: 3.2, 43. */
+const tenths = (n: number): string => Number(n.toFixed(1)).toLocaleString("en-US");
+
+/** A token count as the plan says it: 612, 41,000, 3.2 million, 43 million, 1.1 billion. */
+const tokensSaid = (tokens: number): string =>
+  tokens >= 1e9
+    ? `${tenths(tokens / 1e9)} billion`
+    : tokens >= 1e6
+      ? `${tenths(tokens / 1e6)} million`
+      : tokens >= 1e3
+        ? (Math.round(tokens / 1e3) * 1e3).toLocaleString("en-US")
+        : tokens.toLocaleString("en-US");
+
+/** An estimated cost as the plan says it: under $0.01, about $0.14, about $1,234. */
+const dollars = (amount: number): string =>
+  amount < 0.01
+    ? "under $0.01"
+    : amount < 100
+      ? `about $${amount.toFixed(2)}`
+      : `about $${Math.round(amount).toLocaleString("en-US")}`;
+
+/** What judging the plan costs at the model's price, when adhere knows it. */
+const costOf = (plan: AuditPlan): number | undefined =>
+  plan.price === undefined ? undefined : (plan.tokens / 1e6) * plan.price;
+
+/** The plan's input tokens and their cost; locating findings comes on top, since it depends on the findings. */
+const costLine = (plan: AuditPlan): string => {
+  const cost = costOf(plan);
+  const priced =
+    cost === undefined || plan.price === undefined
+      ? ""
+      : `: ${dollars(cost)} at $${plan.price} per million`;
+  return `Those carry about ${tokensSaid(plan.tokens)} input tokens${priced}, and more for locating findings.`;
+};
+
 export const describePlan = (plan: AuditPlan, limits: RunLimits = {}): ReadonlyArray<string> => {
   const cached = plan.cached > 0 ? `, ${plan.cached} cached` : "";
   const skipped =
@@ -260,12 +296,16 @@ export const describePlan = (plan: AuditPlan, limits: RunLimits = {}): ReadonlyA
   return [
     found,
     `Judging ${rest} takes ${counted(plan.requests, "request", "requests")} to Jev, plus 1 or more for each file with a finding.${pace}${waiting}`,
+    ...(plan.tokens > 0 ? [costLine(plan)] : []),
   ];
 };
 
 /** The question before a run sends anything. */
-export const sendQuestion = (plan: AuditPlan): string =>
-  `Send ${counted(plan.requests, "request", "requests")} to Jev?`;
+export const sendQuestion = (plan: AuditPlan): string => {
+  const cost = costOf(plan);
+  const priced = cost === undefined || plan.tokens === 0 ? "" : `, ${dollars(cost)}`;
+  return `Send ${counted(plan.requests, "request", "requests")} to Jev${priced}?`;
+};
 
 /** A run's progress so far: every file it finished, with the requests and findings they added up to. */
 export interface Progress {