@drkmttr/adhere 0.4.1 → 0.5.0

package/README.md

@@ -30,9 +30,9 @@ with a TypeSafe AI API key: the one `adhere login` saved, or
 
 ```sh
 adhere init                          # .adhere/config.ts and two example rules
-adhere validate                      # check the config and rules, without Jev
 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 lint                          # audit the working directory
 ```
 
@@ -68,7 +68,7 @@ refusal prints its reason.
 adhere lint                    # audit the working directory
 adhere lint --preset effect    # add a built-in rule set; the config becomes optional
 adhere lint --threshold 0.8    # replace the config's threshold; per-rule thresholds still apply
-adhere validate                # load the config and rules without Jev, check for contradictions
+adhere validate                # load the config and rules, ask Jev whether any contradict
 adhere init [--force]          # scaffold .adhere/config.ts and two example rules
 adhere login                   # save a TypeSafe AI API key for later runs
 adhere logout                  # delete the saved key
@@ -99,20 +99,24 @@ kept, and no second one is added, even with `--force`.
 ### Validate
 
 `adhere validate` loads the config, rule files, and presets the way `lint`
-does, without calling Jev, so a file that fails to decode refuses here too, and
-it prints how many rules it loaded. `--preset` adds a built-in rule set, as for
-`lint`. It then checks the rules for local textual contradictions: it exits 1
-and prints the conflicting rule files when overlapping rule scopes contain
-opposite textual directives for the same topic, such as "Use service classes
-for IO" and "Do not use service classes for IO". Same-id nested rules are
-treated as intentional shadowing rather than contradictions.
+does, so a file that fails to decode refuses here too, and it prints how many
+rules it loaded. `--preset` adds a built-in rule set, as for `lint`. It then
+asks Jev whether any two rules that apply to the same files contradict, so that
+no code can follow both: one request names, per rule, the rule it conflicts
+with, if any, and each named pair then gets a probability from a request of
+its own, holding only those two rules, since other rules beside them dilute
+the judgment. A pair above
+the threshold is printed with both rule files, and the exit code is 1. Two
+rules with the same id are not compared: a nested rule that shares an id
+shadows the other on purpose. When no two rules share files nothing is sent;
+otherwise `validate` needs the API key, as `lint` does.
 
 ### Login
 
 `adhere login` prompts for a TypeSafe AI API key, masking what you type, and
 saves it to `~/.config/adhere/credentials.json`, or under `$XDG_CONFIG_HOME`
 when that is set, readable only by you. Piped input is read instead of a
-prompt: `adhere login < key.txt`. `lint` uses the saved key, but
+prompt: `adhere login < key.txt`. `lint` and `validate` use the saved key, but
 `TYPESAFE_API_KEY`, when set, takes precedence, so CI can pass a key without a
 login. `adhere logout` deletes the saved key.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "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.4.1",
-    "@drkmttr/adhere-darwin-x64": "0.4.1",
-    "@drkmttr/adhere-linux-arm64": "0.4.1",
-    "@drkmttr/adhere-linux-x64": "0.4.1",
-    "@drkmttr/adhere-win32-x64": "0.4.1"
+    "@drkmttr/adhere-darwin-arm64": "0.5.0",
+    "@drkmttr/adhere-darwin-x64": "0.5.0",
+    "@drkmttr/adhere-linux-arm64": "0.5.0",
+    "@drkmttr/adhere-linux-x64": "0.5.0",
+    "@drkmttr/adhere-win32-x64": "0.5.0"
   }
 }

package/skills/adhere/SKILL.md

@@ -103,7 +103,7 @@ precedence; in this org it comes from SOPS via `just shell`.
 ## 5. Run and calibrate
 
 ```sh
-adhere validate              # decodes the config and rules, checks contradictions
+adhere validate              # decodes the config and rules, asks Jev about contradictions
 adhere lint                  # or: adhere lint --preset effect
 adhere lint --threshold 0.9  # re-reads the cache, sends nothing
 ```

package/src/cli.ts

@@ -94,16 +94,24 @@ export const lintCommand = Command.make("lint", { preset, threshold }, () =>
   ),
 );
 
+/** Jev, with the key `lint` uses, and the config it reads the model and threshold from. */
+export const validateLayer = (overrides: Overrides) =>
+  JevLive.pipe(
+    Layer.provide([FetchHttpClient.layer, CredentialsLive]),
+    Layer.provideMerge(AdhereConfigLive(overrides)),
+  );
+
 /**
- * `adhere validate`: everything `lint` loads, without Jev. A config, rule file,
- * or preset that does not decode refuses here the way it would refuse `lint`.
+ * `adhere validate`: everything `lint` loads, then Jev on whether any two rules
+ * that apply to the same files contradict. A config, rule file, or preset that
+ * does not decode refuses here the way it would refuse `lint`.
  */
 export const validateCommand = Command.make("validate", { preset }, () =>
   Effect.gen(function* () {
     const config = yield* AdhereConfig;
     const path = yield* Path.Path;
     const entries = config.scopedRules ?? globalRuleSet(config.rules, path.resolve());
-    const contradictions = findContradictions(entries);
+    const contradictions = yield* findContradictions(entries, config.threshold);
     const loaded = `${entries.length} ${entries.length === 1 ? "rule" : "rules"} loaded.`;
     yield* Console.log([loaded, formatContradictions(contradictions)].join("\n"));
     if (contradictions.length > 0) {
@@ -112,9 +120,9 @@ export const validateCommand = Command.make("validate", { preset }, () =>
   }),
 ).pipe(
   Command.withDescription(
-    "Load the config, rule files, and presets the way lint does, without calling Jev, and check the rules for contradictions.",
+    "Load the config, rule files, and presets the way lint does, then ask Jev whether any two rules that apply to the same files contradict each other.",
   ),
-  Command.provide((input) => AdhereConfigLive({ presets: chosenPresets(input.preset) })),
+  Command.provide((input) => validateLayer({ presets: chosenPresets(input.preset) })),
 );
 
 /** `adhere init`: the scaffold. */

package/src/contradictions.ts

@@ -1,19 +1,14 @@
 import type { RuleEntry } from "#rules.ts";
+import { Jev, type Pair } from "#services/Jev.ts";
+import { Effect } from "effect";
 
 export interface Contradiction {
   readonly first: RuleEntry;
   readonly second: RuleEntry;
-  readonly reason: string;
+  /** Jev's probability that no code can follow both rules. */
+  readonly probability: number;
 }
 
-type Polarity = "positive" | "negative";
-
-const NEGATIVE = /\b(?:avoid|do not|don't|must not|never|no|should not)\b/gi;
-const POSITIVE = /\b(?:always|must|prefer|require|requires|required|should|use)\b/gi;
-const NEGATIVE_WORD = /\b(?:avoid|do not|don't|must not|never|no|should not)\b/i;
-const POSITIVE_WORD = /\b(?:always|must|prefer|require|requires|required|should|use)\b/i;
-const FILLER = /\b(?:a|an|the|for|to|with|by|in|of)\b/gi;
-
 const normalized = (path: string): string => path.replaceAll("\\", "/");
 
 const scopesOverlap = (a: string, b: string): boolean => {
@@ -22,58 +17,57 @@ const scopesOverlap = (a: string, b: string): boolean => {
   return first === second || first.startsWith(`${second}/`) || second.startsWith(`${first}/`);
 };
 
-const polarityOf = (text: string): Polarity | undefined => {
-  if (NEGATIVE_WORD.test(text)) return "negative";
-  if (POSITIVE_WORD.test(text)) return "positive";
-  return undefined;
-};
-
-const topicOf = (text: string): string =>
-  text
-    .toLowerCase()
-    .replaceAll(NEGATIVE, " ")
-    .replaceAll(POSITIVE, " ")
-    .replaceAll(FILLER, " ")
-    .replace(/[^a-z0-9]+/g, " ")
-    .trim()
-    .replace(/\s+/g, " ");
+/**
+ * Per rule, the rules that apply to some of the same files. A rule with the
+ * same id is left out: a nested rule that shares an id shadows the other on
+ * purpose.
+ */
+const partnersOf = (entries: ReadonlyArray<RuleEntry>): ReadonlyArray<ReadonlyArray<number>> =>
+  entries.map((first, index) =>
+    entries.flatMap((second, other) =>
+      other !== index && first.id !== second.id && scopesOverlap(first.scope, second.scope)
+        ? [other]
+        : [],
+    ),
+  );
 
-const contradicts = (first: RuleEntry, second: RuleEntry): boolean => {
-  if (first.id === second.id) return false;
-  if (!scopesOverlap(first.scope, second.scope)) return false;
-  const firstPolarity = polarityOf(first.rule.description);
-  const secondPolarity = polarityOf(second.rule.description);
-  if (
-    firstPolarity === undefined ||
-    secondPolarity === undefined ||
-    firstPolarity === secondPolarity
-  ) {
-    return false;
+/** Each pair Jev named once, lower index first. */
+const distinctPairs = (named: ReadonlyArray<Pair>): ReadonlyArray<Pair> => {
+  const pairs = new Map<string, Pair>();
+  for (const [rule, partner] of named) {
+    const pair: Pair = rule < partner ? [rule, partner] : [partner, rule];
+    pairs.set(`${pair[0]}-${pair[1]}`, pair);
   }
-  const firstTopic = topicOf(first.rule.description);
-  const secondTopic = topicOf(second.rule.description);
-  return firstTopic.length > 0 && firstTopic === secondTopic;
+  return [...pairs.values()].sort((a, b) => a[0] - b[0] || a[1] - b[1]);
 };
 
-export const findContradictions = (
+/**
+ * Pairs of rules that apply to the same files and that Jev judges no code can
+ * follow both of, above `threshold`. Jev first names, per rule, which rule
+ * sharing its files it conflicts with, then gives each named pair a
+ * probability. Nothing is sent when no two rules share files, so such a run
+ * needs no API key.
+ */
+export const findContradictions = Effect.fn("findContradictions")(function* (
   entries: ReadonlyArray<RuleEntry>,
-): ReadonlyArray<Contradiction> => {
-  const contradictions: Array<Contradiction> = [];
-  for (let i = 0; i < entries.length; i++) {
-    const first = entries[i];
-    if (first === undefined) continue;
-    for (let j = i + 1; j < entries.length; j++) {
-      const second = entries[j];
-      if (second === undefined || !contradicts(first, second)) continue;
-      contradictions.push({
-        first,
-        second,
-        reason: "overlapping scopes contain opposite textual directives for the same topic",
-      });
-    }
-  }
-  return contradictions;
-};
+  threshold: number,
+) {
+  const none: ReadonlyArray<Contradiction> = [];
+  const partners = partnersOf(entries);
+  if (partners.every((some) => some.length === 0)) return none;
+  const jev = yield* Jev;
+  const pairs = distinctPairs(yield* jev.conflicts(entries, partners));
+  if (pairs.length === 0) return none;
+  const probabilities = yield* jev.contradicts(entries, pairs);
+  return pairs.flatMap(([first, second], index): ReadonlyArray<Contradiction> => {
+    const one = entries[first];
+    const other = entries[second];
+    const probability = probabilities[index] ?? 0;
+    return one !== undefined && other !== undefined && probability > threshold
+      ? [{ first: one, second: other, probability }]
+      : [];
+  });
+});
 
 const locationOf = (entry: RuleEntry): string => `${entry.id} (${entry.file ?? entry.scope})`;
 
@@ -87,7 +81,7 @@ export const formatContradictions = (contradictions: ReadonlyArray<Contradiction
     } among configured rules:`,
     "",
     ...contradictions.flatMap((contradiction, index) => [
-      `${index + 1}. ${contradiction.reason}`,
+      `${index + 1}. No code can follow both (${contradiction.probability.toFixed(2)}):`,
       `   - ${locationOf(contradiction.first)}`,
       `     ${contradiction.first.rule.description}`,
       `   - ${locationOf(contradiction.second)}`,

package/src/services/Jev.http.ts

@@ -2,12 +2,18 @@ import { AdhereConfig } from "#services/AdhereConfig.ts";
 import { Credentials } from "#services/Credentials.ts";
 import {
   blockBody,
+  type ComparedRule,
+  conflictBody,
+  contradictBody,
   Jev,
   JevUnavailable,
   judgeBody,
   type Lines,
   locateBody,
+  namedPairs,
   needsBlocks,
+  type Pair,
+  pairProbability,
   type Rules,
 } from "#services/Jev.ts";
 import { Effect, Layer, Record, Schedule, Schema } from "effect";
@@ -76,6 +82,28 @@ export const JevLive = Layer.effect(Jev)(
       return chosen(answers);
     });
 
-    return Jev.of({ judge, locate });
+    const conflicts = Effect.fn("Jev.conflicts")(function* (
+      rules: ReadonlyArray<ComparedRule>,
+      partners: ReadonlyArray<ReadonlyArray<number>>,
+    ) {
+      const { answers } = yield* ask(conflictBody(config.model, rules, partners), ChoiceAnswers);
+      return namedPairs(answers, partners);
+    });
+
+    const contradicts = Effect.fn("Jev.contradicts")(function* (
+      rules: ReadonlyArray<ComparedRule>,
+      pairs: ReadonlyArray<Pair>,
+    ) {
+      return yield* Effect.forEach(
+        pairs,
+        (pair) =>
+          Effect.map(ask(contradictBody(config.model, rules, pair), NoulAnswers), ({ answers }) =>
+            pairProbability(answers, pair),
+          ),
+        { concurrency: 8 },
+      );
+    });
+
+    return Jev.of({ judge, locate, conflicts, contradicts });
   }),
 );

package/src/services/Jev.ts

@@ -19,9 +19,35 @@ export class Jev extends Context.Service<
       lines: Lines,
       rules: Rules,
     ) => Effect.Effect<Record<RuleId, number>, JevUnavailable>;
+    /**
+     * 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
+     * left out.
+     */
+    readonly conflicts: (
+      rules: ReadonlyArray<ComparedRule>,
+      partners: ReadonlyArray<ReadonlyArray<number>>,
+    ) => Effect.Effect<ReadonlyArray<Pair>, JevUnavailable>;
+    /**
+     * Per pair, in order, Jev's probability that no code can follow both rules,
+     * each pair asked on its own.
+     */
+    readonly contradicts: (
+      rules: ReadonlyArray<ComparedRule>,
+      pairs: ReadonlyArray<Pair>,
+    ) => Effect.Effect<ReadonlyArray<number>, JevUnavailable>;
   }
 >()("@drkmttr/adhere/services/Jev") {}
 
+/** A rule compared with other rules rather than with a file. */
+export interface ComparedRule {
+  readonly id: RuleId;
+  readonly rule: Rule;
+}
+
+/** Two rules, as indexes into the rules being compared. */
+export type Pair = readonly [number, number];
+
 /** A `choice` question accepts at most this many criteria. */
 const CHOICE_LIMIT = 255;
 const LINES_PER_BLOCK = 20;
@@ -34,15 +60,33 @@ const isBlank = (line: string): boolean => line.trim().length === 0;
 export const needsBlocks = (lines: Lines): boolean =>
   lines.filter((line) => !isBlank(line)).length > CHOICE_LIMIT;
 
+/** A rule's text as Jev 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 }),
+});
+
 const stateOf = (lines: Lines, rules: Rules) => ({
   code: lines.map((line, index) => `${index + 1} | ${line}`).join("\n"),
-  rules: Record.map(rules, ({ description, reference, avoid }) => ({
-    description,
-    ...(reference === undefined ? {} : { reference }),
-    ...(avoid === undefined ? {} : { avoid }),
-  })),
+  rules: Record.map(rules, (rule) => ruleState(rule)),
 });
 
+/**
+ * The compared rules a question mentions, keyed by index: ids alone would
+ * collide, since a nested rule can share its id with the rule it shadows.
+ */
+const comparedState = (rules: ReadonlyArray<ComparedRule>, mentioned: Iterable<number>) => {
+  const state: Record<string, { readonly id: RuleId } & ReturnType<typeof ruleState>> = {};
+  for (const index of [...new Set(mentioned)].sort((a, b) => a - b)) {
+    const compared = rules[index];
+    if (compared !== undefined) {
+      state[String(index)] = { id: compared.id, ...ruleState(compared.rule) };
+    }
+  }
+  return { rules: state };
+};
+
 const field = (id: RuleId, key: "avoid" | "description" | "reference") =>
   `state.rules["${id}"].${key}`;
 
@@ -123,3 +167,83 @@ export const blockBody = (model: string, lines: Lines, rules: Rules) => {
     })),
   };
 };
+
+/** A choice keeps one criterion for "none", which leaves this many for partners. */
+const PARTNERS_PER_QUESTION = CHOICE_LIMIT - 1;
+
+interface ChoiceQuestion {
+  readonly type: "choice";
+  readonly instructions: string;
+  readonly criteria: Record<string, string>;
+}
+
+/**
+ * Per rule, one `choice` among the rules that apply to the same files: which
+ * of them cannot be followed in the same code, or none. The questions grow
+ * with the rules, not with every pair of them. A rule with more partners than
+ * a choice holds gets one question per chunk, keyed `rule:chunk`.
+ */
+export const conflictBody = (
+  model: string,
+  rules: ReadonlyArray<ComparedRule>,
+  partners: ReadonlyArray<ReadonlyArray<number>>,
+) => {
+  const questions: Record<string, ChoiceQuestion> = {};
+  const mentioned: Array<number> = [];
+  partners.forEach((some, index) => {
+    for (let chunk = 0; chunk * PARTNERS_PER_QUESTION < some.length; chunk++) {
+      const from = chunk * PARTNERS_PER_QUESTION;
+      const offered = some.slice(from, from + PARTNERS_PER_QUESTION);
+      const criteria: Record<string, string> = { none: "None of them" };
+      for (const partner of offered) {
+        criteria[String(partner)] = rules[partner]?.rule.description ?? "";
+      }
+      mentioned.push(index, ...offered);
+      questions[`${index}:${chunk}`] = {
+        type: "choice",
+        instructions: `Each choice other than none is the rule in state.rules under its key. Which of them demands the opposite of what state.rules["${index}"] demands of the same code, so that following one breaks the other? Choose none if code can follow each of them alongside it.`,
+        criteria,
+      };
+    }
+  });
+  return { model, state: comparedState(rules, mentioned), questions };
+};
+
+const pairKey = ([first, second]: Pair): string => `${first}-${second}`;
+
+/**
+ * A `noul` for one pair Jev named: do the two rules demand opposite things of
+ * the same code? One pair per request, with only its two rules in the state.
+ * Other rules beside them dilute the judgment: over the effect preset, a real
+ * contradiction scored 0.89 alone and 0.59 among the other named pairs.
+ */
+export const contradictBody = (model: string, rules: ReadonlyArray<ComparedRule>, pair: Pair) => ({
+  model,
+  state: comparedState(rules, pair),
+  questions: {
+    [pairKey(pair)]: {
+      type: "noul" as const,
+      instructions: `Do state.rules["${pair[0]}"] and state.rules["${pair[1]}"] demand opposite things of the same code, so that following one breaks the other? Answer no if code can follow both, or if they are about different things.`,
+    },
+  },
+});
+
+/**
+ * The pairs a conflict answer names: per question, the partner Jev chose, when
+ * it was one the question offered. "none", or a stray answer, names no pair.
+ */
+export const namedPairs = (
+  answers: Readonly<Record<string, { readonly choice: string }>>,
+  partners: ReadonlyArray<ReadonlyArray<number>>,
+): ReadonlyArray<Pair> =>
+  Object.entries(answers).flatMap(([key, { choice }]): ReadonlyArray<Pair> => {
+    const rule = Number(key.split(":")[0]);
+    const partner = Number(choice);
+    return partners[rule]?.includes(partner) === true ? [[rule, partner]] : [];
+  });
+
+/** The probability a contradiction answer gives its pair; 0 when it gives none. */
+export const pairProbability = (
+  answers: Readonly<Record<string, { readonly noul: number }>>,
+  pair: Pair,
+): number => answers[pairKey(pair)]?.noul ?? 0;