@drkmttr/adhere 0.3.1 → 0.4.0

package/README.md

@@ -1,9 +1,9 @@
 # adhere
 
-A linter for rules a normal linter cannot check. A rule is a piece of correct
-reference code plus a one-sentence description. For each source file, adhere
-asks [Jev](https://typesafe.ai) (TypeSafe AI's System One model) whether the
-file diverges from each rule's reference, gets a calibrated probability per
+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
+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
 report uses the same frame as `vp lint`.
 
@@ -54,7 +54,8 @@ Found 1 error.
 ```
 
 The header is the rule id, Jev's probability, and the rule's description. The
-hint is the rule's reference. The exit code is 0 when nothing is reported and 1
+hint is the rule's reference; a rule with only code to avoid shows that code,
+labeled `avoid:`, instead. The exit code is 0 when nothing is reported and 1
 when something is. It is also 1 when the run refuses, for example on an invalid
 config or rule file, a missing `TYPESAFE_API_KEY`, or an unknown command or
 flag; a refusal prints its reason.
@@ -128,6 +129,7 @@ export default {
 const UserId = Schema.String.pipe(Schema.brand("UserId"))
 type UserId = typeof UserId.Type
 `,
+      avoid: "type UserId = string", // optional: what a violation looks like
       threshold: 0.8, // optional per-rule override
     },
   },
@@ -154,7 +156,8 @@ directory exists, it is read without any config.
 
 A file is front matter, then a body. The first fenced code block in the body
 is the reference; prose around it renders on GitHub and is ignored. Without a
-fence, the whole body is the reference.
+fence, the whole body is the reference. A fence tagged `avoid` after its
+language holds code to avoid instead: what a violation looks like.
 
 ````md
 ---
@@ -170,11 +173,25 @@ const Port = Schema.Int.pipe(
   Schema.brand("Port"),
 );
 ```
+
+Not this:
+
+```ts avoid
+const port: number = Number(process.env.PORT);
+```
 ````
 
-`description` is required. `threshold` is optional. A file that fails
-validation refuses the run with its path in the message. `loadRules(directory)`
-from the package root does the same load for your own tooling.
+`description` is required, with a reference, code to avoid, or both.
+`threshold` is optional. A file that fails validation refuses the run with its
+path in the message. `loadRules(directory)` from the package root does the same
+load for your own tooling.
+
+With a reference, Jev is asked whether the file diverges from it, and code to
+avoid, when there is some, is its example of diverging. With only code to
+avoid, Jev is asked whether the file contains it. That suits a rule with no
+single correct form to show, such as a hand-rolled retry loop or an error
+caught and dropped. Neither goes in the other's place: code to avoid in the
+reference reads to Jev as the pattern to follow.
 
 Nested `.adhere/` directories are also discovered, except under
 `node_modules/`, `dist/`, and the other skipped directories (above). A rule in
@@ -221,8 +238,10 @@ beats all of the above for that rule.
 ## How a file is judged
 
 1. One Jev request per file, with the file's numbered lines and every rule as
-   the state, and one `noul` (yes/no probability) question per rule. Every
-   question shares the state cost of the request.
+   the state, and one `noul` (yes/no probability) question per rule: whether
+   the file diverges from the reference or, for a rule with only code to
+   avoid, whether it contains that code. 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

package/package.json

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

package/skills/adhere/SKILL.md

@@ -61,15 +61,22 @@ Optional prose for readers on GitHub. adhere ignores it.
 ```ts
 // Correct code lifted from this repo, trimmed to the pattern.
 ```
+
+```ts avoid
+// Optional: the incorrect form this rule catches, as it appeared in the repo.
+```
 ````
 
 Rules for the rule:
 
 - `description` is one sentence, positive, specific. Jev reads it with the
   reference; vague words ("properly", "correctly") give it nothing to judge.
-- The reference is real code from the repo, not invented. Never include
-  incorrect code; Jev compares files to the reference, so a "bad" example
-  teaches the wrong thing.
+- The reference is real code from the repo, not invented, and only correct
+  code: Jev compares files to it, so incorrect code there teaches the wrong
+  thing. Incorrect code goes in a fence tagged `avoid`, which Jev reads as what
+  a violation looks like. Add one when violations have a recognizable shape,
+  ideally one found in the repo's history. A rule with no single correct form
+  can be only an `avoid` block.
 - One pattern per file. Two patterns in one reference blur the probability.
 - `threshold` is optional. Start without it; set it in step 5 if needed.
 

package/src/config.ts

@@ -6,9 +6,18 @@ export type RuleId = string;
 
 export const Rule = Schema.Struct({
   description: Schema.String,
-  reference: Schema.String,
+  /** Correct code: the pattern a file should follow. */
+  reference: Schema.optionalKey(Schema.String),
+  /** Incorrect code: what a violation looks like. */
+  avoid: Schema.optionalKey(Schema.String),
   threshold: Schema.optionalKey(Schema.Finite),
-});
+}).check(
+  Schema.makeFilter((rule) =>
+    rule.reference !== undefined || rule.avoid !== undefined
+      ? undefined
+      : "a rule needs a reference, code to avoid, or both",
+  ),
+);
 export interface Rule extends Schema.Schema.Type<typeof Rule> {}
 
 export type Rules = Readonly<Record<RuleId, Rule>>;

package/src/init.ts

@@ -43,6 +43,16 @@ export const loadCustomerProfile = (customerId: CustomerId) =>
     return yield* CustomerStore.find(customerId);
   });
 \`\`\`
+
+A fence tagged \`avoid\` shows what a violation looks like. It is optional, and
+a rule can have one without the block above.
+
+\`\`\`ts avoid
+export const handle = (id: string) =>
+  Effect.gen(function* () {
+    return yield* CustomerStore.find(id);
+  });
+\`\`\`
 `;
 
 const CONFIG_PATH = CONFIG_FILES[0];

package/src/markdown.ts

@@ -14,8 +14,13 @@ import { Effect, Schema } from "effect";
  *     const reference = "the correct code"
  *     ```
  *
- * The reference is the first fenced code block. Without a fence, it is the
- * whole body. `threshold` is optional.
+ *     ```ts avoid
+ *     const avoided = "what a violation looks like"
+ *     ```
+ *
+ * The reference is the first fenced code block; `avoid` in a fence's info
+ * string marks the code to avoid instead. A rule has either or both. Without a
+ * fence, the whole body is the reference. `threshold` is optional.
  */
 const FrontMatter = Schema.Struct({
   description: Schema.String,
@@ -23,7 +28,8 @@ const FrontMatter = Schema.Struct({
 });
 
 const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
-const FENCE = /^ {0,3}(`{3,}|~{3,})[^\n]*\n([\s\S]*?)\n {0,3}\1[ \t]*$/m;
+const FENCE = /^ {0,3}(`{3,}|~{3,})([^\n]*)\n([\s\S]*?)\n {0,3}\1[ \t]*$/gm;
+const AVOID = "avoid";
 
 const unquote = (value: string): string => {
   const trimmed = value.trim();
@@ -44,9 +50,35 @@ const parseFrontMatter = (block: string): Record<string, string> => {
   return fields;
 };
 
-const referenceOf = (body: string): string => {
-  const fence = FENCE.exec(body);
-  return (fence?.[2] ?? body).trim();
+interface Fence {
+  readonly avoid: boolean;
+  readonly code: string;
+}
+
+const fencesOf = (body: string): ReadonlyArray<Fence> =>
+  Array.from(body.matchAll(FENCE), (match) => ({
+    avoid: (match[2] ?? "")
+      .trim()
+      .split(/\s+/)
+      .some((word) => word.toLowerCase() === AVOID),
+    code: (match[3] ?? "").trim(),
+  }));
+
+/** An empty block counts as no block. */
+const nonEmpty = (code: string | undefined): string | undefined =>
+  code === undefined || code.length === 0 ? undefined : code;
+
+/** The reference and the code to avoid, each left out when the body has none. */
+const codeOf = (body: string): Pick<Rule, "reference" | "avoid"> => {
+  const fences = fencesOf(body);
+  const reference = nonEmpty(
+    fences.length === 0 ? body.trim() : fences.find((fence) => !fence.avoid)?.code,
+  );
+  const avoid = nonEmpty(fences.find((fence) => fence.avoid)?.code);
+  return {
+    ...(reference === undefined ? {} : { reference }),
+    ...(avoid === undefined ? {} : { avoid }),
+  };
 };
 
 export const parseRuleMarkdown = (
@@ -65,11 +97,11 @@ export const parseRuleMarkdown = (
         ConfigUnavailable.make({ message: `${file}: ${problem.message}` }),
       ),
     );
-    const reference = referenceOf(match[2]);
-    if (reference.length === 0) {
+    const code = codeOf(match[2]);
+    if (code.reference === undefined && code.avoid === undefined) {
       return yield* ConfigUnavailable.make({
-        message: `${file}: the body is the reference code and cannot be empty`,
+        message: `${file}: the body needs reference code, a fence tagged avoid, or both`,
       });
     }
-    return { ...front, reference };
+    return { ...front, ...code };
   });

package/src/services/Jev.ts

@@ -1,4 +1,4 @@
-import type { RuleId, Rules } from "#config.ts";
+import type { Rule, RuleId, Rules } from "#config.ts";
 import { Context, type Effect, Record, Schema } from "effect";
 
 export type { Rules };
@@ -36,12 +36,36 @@ export const needsBlocks = (lines: Lines): boolean =>
 
 const stateOf = (lines: Lines, rules: Rules) => ({
   code: lines.map((line, index) => `${index + 1} | ${line}`).join("\n"),
-  rules: Record.map(rules, ({ description, reference }) => ({
+  rules: Record.map(rules, ({ description, reference, avoid }) => ({
     description,
-    reference,
+    ...(reference === undefined ? {} : { reference }),
+    ...(avoid === undefined ? {} : { avoid }),
   })),
 });
 
+const field = (id: RuleId, key: "avoid" | "description" | "reference") =>
+  `state.rules["${id}"].${key}`;
+
+/**
+ * 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.
+ */
+const judgeInstructions = (id: RuleId, rule: Rule): string =>
+  rule.reference === undefined
+    ? `Does state.code contain the pattern shown in ${field(id, "avoid")}, which ${field(id, "description")} rules out? Answer no if nothing in this file resembles it.`
+    : `Does state.code diverge from the pattern shown in ${field(id, "reference")}${
+        rule.avoid === undefined ? "" : `, for example by doing what ${field(id, "avoid")} shows`
+      }, as described by ${field(id, "description")}? Answer no if the pattern does not apply to this file.`;
+
+/** What the offending line does, for the line and block questions. */
+const offense = (id: RuleId, rule: Rule): string =>
+  rule.reference === undefined
+    ? `shows the pattern in ${field(id, "avoid")}`
+    : rule.avoid === undefined
+      ? `diverges from ${field(id, "reference")}`
+      : `diverges from ${field(id, "reference")} or resembles ${field(id, "avoid")}`;
+
 const lineCriteria = (lines: Lines, from: number, to: number): Record<string, string> => {
   const criteria: Record<string, string> = {};
   for (let n = from; n <= Math.min(to, lines.length); n++) {
@@ -54,9 +78,9 @@ const lineCriteria = (lines: Lines, from: number, to: number): Record<string, st
 export const judgeBody = (model: string, lines: Lines, rules: Rules) => ({
   model,
   state: stateOf(lines, rules),
-  questions: Record.map(rules, (_, id) => ({
+  questions: Record.map(rules, (rule, id) => ({
     type: "noul" as const,
-    instructions: `Does state.code diverge from the pattern shown in state.rules["${id}"].reference, as described by state.rules["${id}"].description? Answer no if the pattern does not apply to this file.`,
+    instructions: judgeInstructions(id, rule),
   })),
 });
 
@@ -68,11 +92,11 @@ export const locateBody = (
 ) => ({
   model,
   state: stateOf(lines, rules),
-  questions: Record.map(rules, (_, id) => {
+  questions: Record.map(rules, (rule, id) => {
     const block = blocks?.[id];
     return {
       type: "choice" as const,
-      instructions: `Which line of state.code most clearly diverges from state.rules["${id}"].reference?`,
+      instructions: `Which line of state.code most clearly ${offense(id, rule)}?`,
       criteria:
         block === undefined
           ? lineCriteria(lines, 1, lines.length)
@@ -92,9 +116,9 @@ export const blockBody = (model: string, lines: Lines, rules: Rules) => {
   return {
     model,
     state: stateOf(lines, rules),
-    questions: Record.map(rules, (_, id) => ({
+    questions: Record.map(rules, (rule, id) => ({
       type: "choice" as const,
-      instructions: `Which block of state.code contains the line that most clearly diverges from state.rules["${id}"].reference?`,
+      instructions: `Which block of state.code contains the line that most clearly ${offense(id, rule)}?`,
       criteria,
     })),
   };

package/src/workflows/audit.ts

@@ -10,7 +10,8 @@ import { type Crypto, Effect, Record } from "effect";
 export interface Finding {
   readonly rule: RuleId;
   readonly description: string;
-  readonly reference: string;
+  readonly reference?: string;
+  readonly avoid?: string;
   readonly file: string;
   readonly line: number;
   readonly snippet: string;
@@ -43,6 +44,19 @@ const fileResult = (
 
 const isEmpty = Record.isEmptyReadonlyRecord;
 
+/**
+ * What a judgment depends on besides the file. A rule without code to avoid
+ * hashes what every rule hashed before `avoid` existed, so its cached
+ * judgments survive the upgrade.
+ */
+const fingerprintOf = (model: string, rule: Rule) =>
+  sha256(
+    model +
+      rule.description +
+      (rule.reference ?? "") +
+      (rule.avoid === undefined ? "" : `\u0000avoid\u0000${rule.avoid}`),
+  );
+
 export const runAudit: Effect.Effect<
   AuditResult,
   WalkUnavailable | JevUnavailable,
@@ -66,7 +80,7 @@ export const runAudit: Effect.Effect<
       Object.entries(configuredRules(file.path)),
       ([id, rule]) =>
         Effect.map(
-          sha256(config.model + rule.description + rule.reference),
+          fingerprintOf(config.model, rule),
           (fingerprint) =>
             [
               id,
@@ -116,6 +130,7 @@ export const runAudit: Effect.Effect<
                 rule: id,
                 description: k.rule.description,
                 reference: k.rule.reference,
+                avoid: k.rule.avoid,
                 file: file.path,
                 line: judgment.line,
                 snippet: judgment.snippet ?? "",

package/src/workflows/format.ts

@@ -24,8 +24,8 @@ export interface RenderOptions {
 
 const isBlank = (line: string): boolean => line.trim().length === 0;
 
-const referenceLines = (reference: string): ReadonlyArray<string> => {
-  const lines = reference.split("\n");
+const codeLines = (code: string): ReadonlyArray<string> => {
+  const lines = code.split("\n");
   const first = lines.findIndex((line) => !isBlank(line));
   if (first < 0) return [];
   let last = lines.length - 1;
@@ -36,12 +36,16 @@ const referenceLines = (reference: string): ReadonlyArray<string> => {
 /**
  * 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.
+ * A rule without a reference shows its code to avoid instead, labeled so.
  */
 const frame = (finding: Finding, options: RenderOptions): ReadonlyArray<string> => {
   const color = options.color === true;
   const digits = String(finding.line);
   const gutter = " ".repeat(digits.length + 2);
-  const [hint = "", ...rest] = referenceLines(finding.reference);
+  const [label, code] =
+    finding.reference === undefined ? ["avoid", finding.avoid ?? ""] : ["hint", finding.reference];
+  const prefix = `  ${label}: `;
+  const [hint = "", ...rest] = codeLines(code);
   const header = `${finding.rule} (${finding.probability.toFixed(2)})`;
   return [
     `  ${red("×", color)} ${red(header, color)}: ${red(finding.description, color)}`,
@@ -49,8 +53,8 @@ const frame = (finding: Finding, options: RenderOptions): ReadonlyArray<string>
     ` ${dim(digits, color)} │ ${finding.snippet}`,
     `${gutter}· ${pink("─".repeat(Math.max(1, finding.snippet.trim().length)), color)}`,
     `${gutter}╰────`,
-    `${helpTint("  hint: ", color)}${hint}`,
-    ...rest.map((line) => (isBlank(line) ? "" : `        ${line}`)),
+    `${helpTint(prefix, color)}${hint}`,
+    ...rest.map((line) => (isBlank(line) ? "" : `${" ".repeat(prefix.length)}${line}`)),
   ];
 };