@drkmttr/adhere 0.9.5 → 0.11.0

package/skills/adhere/SKILL.md

@@ -58,51 +58,77 @@ threshold: 0.8
 
 Optional prose for readers on GitHub. adhere ignores it.
 
-```ts must
+## Must
+
+```ts
 // Correct code lifted from this repo, trimmed to the pattern.
 ```
 
-```ts never
+## Never
+
+```ts
 // Optional: the incorrect form this rule catches, as it appeared in the repo.
 ```
 ````
 
 Rules for the rule:
 
-- `description` is one sentence, specific, in the same words as the fences:
+- `description` is one sentence, specific, in the same words as the headings:
   what code must be, and what it must never be. Jev reads the description
   with the code, and "must" in both is one demand; vague words ("properly",
   "correctly") give it nothing to judge.
+- A heading names the code under it only when it is the word alone: `## Never`,
+  not `## Never do this`. The next heading at its level or higher ends it.
 - The `must` block 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 `never`, which Jev reads as what
-  a violation looks like. Add one whenever violations have a recognizable
+  thing. Incorrect code goes under `## Never`, which Jev reads as what a
+  violation looks like. Add one whenever violations have a recognizable
   shape, ideally one found in the repo's history: over the effect preset, a
   `never` block raised how well Jev told violations from compliant code under
   every wording tried. A rule with no single correct form can be only a
   `never` block.
 - A convention that is a guideline rather than a requirement says "should" in
-  its description and tags its fences `should` and `should not`. A rule is one
-  or the other; it cannot mix the two.
+  its description and puts its code under `## Should` and `## Should not`. A
+  rule is one or the other; it cannot mix the two.
 - One pattern per file. Two patterns in one `must` block blur the probability.
+- Jev reads code without its comments, except comments that say `@adhere`. A
+  rule about comments, such as doc comments on exports, needs
+  `includeComments: true` in the config.
+- Rules skip tests: `.test` and `.spec` files, such as `a.test.ts` and
+  `Button.spec.tsx`, and files under `test/`, `tests/`, `__tests__/`, or
+  `fixtures/`. A rule about tests says `tests: only` in its front matter, and
+  one that holds in tests as well `tests: include`.
+- A nit, or a rule that tends to flag code wrongly, says `level: warning` in
+  its front matter: its findings show in amber and do not fail CI.
 - `threshold` is optional. Start without it; set it in step 5 if needed.
 
 ## 4. Configure
 
 Put the config at `.adhere/config.ts`. `adhere.config.ts` and
 `.adhere.config.ts` also load; keep one. A config is optional when `.adhere/`
-exists or a preset is passed on the command line. Use a type-only import so
-the file also loads under the native binary:
+exists or a preset is passed on the command line. `adhere init` scaffolds it
+with `defineConfig`, adds `@drkmttr/adhere` as a dev dependency, and writes
+`.adhere/tsconfig.json` so the editor resolves its types; the native binary
+supplies the import either way:
 
 ```ts
-import type { Config } from "@drkmttr/adhere";
+import { defineConfig } from "@drkmttr/adhere";
 
-export default {
+export default defineConfig({
   presets: ["effect"],
   threshold: 0.75,
-} satisfies Config;
+  exclude: ["**/generated/**"],
+});
 ```
 
+To quiet a preset rule that does not suit the repo, override it rather than
+copy it: `overrides: { "alchemy/providers/idempotent-delete": "warning" }`, or
+`"off"`, or `{ threshold: 0.9 }`. The id is the one the report shows.
+
+`exclude` lists globs, from the working directory, of files no rule judges.
+Exclude generated and vendored code the skipped directories do not already
+cover, since findings there are noise no one will fix.
+
 Commit `.adhere/cache/` with the code, so the team and CI reuse its judgments
 instead of paying for them again. Uncached files need a TypeSafe AI API
 key: one saved by `adhere login`, or `TYPESAFE_API_KEY`, which takes
@@ -127,6 +153,9 @@ Then, per rule, read the findings and decide:
   rule fires, remove the file. A rule that cannot fire is not a rule.
 - Hits at 0.9 and above: read them first. They are usually real.
 
+To verify and fix the findings themselves, one at a time, use the adhere-fix
+skill, which `adhere skill fix` prints.
+
 Threshold changes never re-judge; only edited rules do (per rule) and edited
 files do (per file). Iterate on wording freely, it costs one request per file
 per changed rule.

package/skills/adhere-fix/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: adhere-fix
+description: Verify and fix the findings `adhere lint` reports. Decide whether each finding is a real violation of its rule, fix the real ones, and report the false ones with the evidence, suppressing a finding with an `adhere-ignore` comment only when the user allows it. Use when adhere, or CI running it, reports errors or warnings, or when asked to fix adhere findings.
+---
+
+# Verify and fix adhere findings
+
+adhere is a linter for rules a normal linter cannot check. Jev, TypeSafe AI's
+model, reads each file against each rule and answers with the probability that
+the file breaks it; adhere reports each rule above a threshold, in the section
+of the file Jev points to. A finding is a judgment, not a proof. On one rule adhere's authors
+checked against the live API, only 1 of its 20 findings was a real violation.
+Verify every finding before you change code for it: fix the real ones, and
+report the false ones with the evidence.
+
+## 1. Get the findings
+
+Invoking this skill is the user's permission to run `adhere lint` as many
+times as the work needs, and to pay for every request it sends to Jev. Never
+ask before a run, never wait for a go-ahead, and never stop to report its cost:
+the skill runs unattended, as in CI, where no one is there to answer. Pass
+`--yes`, so adhere does not ask either.
+
+```sh
+adhere lint --yes                        # judges what is not cached, then reports
+adhere lint --yes --filter 'src/**'      # only the files a glob matches
+```
+
+Judgments are cached in `.adhere/cache/`, so a rerun judges only files and
+rules that changed.
+
+Each finding shows:
+
+- the rule id, a preset's with its preset first, as in
+  `alchemy/providers/idempotent-delete`, Jev's probability, and the rule's
+  description;
+- the section of the file Jev points at, a run of whole statements of about 30
+  lines, with the lines it names underlined, or marked with a bar when they
+  are several: usually where the violation starts, which may run on past them;
+- sometimes `warning: this file may not show enough to check this rule`: the
+  rule may turn on another file, a library, or a service. Most of these are
+  false; read what the code relies on before fixing it. Its `help:` suggests
+  an `@adhere` note, which follows the same rule as a suppression (see below);
+- `hint:`, the code the rule wants, or `never:` for a rule that only shows code
+  to avoid.
+
+`×` marks an error, which fails the run; `⚠` a warning, which does not: a nit,
+or a rule that tends to flag code wrongly. Verify warnings the same way; they
+are wrong more often.
+
+## 2. Read the rule
+
+The report gives the rule's description and one example. Read the whole rule:
+the code under `## Must` and `## Never`, and anything it puts out of scope.
+
+- A project rule is `.adhere/<id>.md`, or under the directory the config's
+  `rules` names.
+- A preset rule is `presets/<preset>/<id>.md` in the adhere package, in
+  `node_modules/@drkmttr/adhere/presets/`, or at
+  https://github.com/darkmatter/adhere/tree/main/presets.
+
+## 3. Verify each finding
+
+Read the code as a reviewer would, not only the excerpt:
+
+- **The whole unit.** Read the function, handler, or class the section holds,
+  and what calls it.
+- **What it calls.** Follow helpers into other files. A helper can already do
+  what the rule asks, such as a delete that looks unguarded calling a client
+  that treats "already gone" as success.
+- **The rule's scope.** Code the rule is not about, such as a runtime binding
+  under a rule about providers' delete handlers, is a false finding.
+- **Comments are claims.** A comment saying the code is fine is not evidence.
+  In adhere's study of one rule, 8 of 35 comments saying a delete succeeds on a
+  missing resource were wrong. Check the claim before you rely on it. Jev does
+  not see comments, except those that say `@adhere`, so it judged the code
+  without them.
+- **Behavior outside the file.** When the rule turns on how an API or a library
+  behaves, find out: its source, its tests, its documentation. Typings help but
+  can be wrong. A live check can settle it, such as a call with an identifier
+  no resource has, but only when the user asked for live checks, and never
+  against a real resource. Do not ask for one: without it, the finding is
+  unsure.
+
+Then decide:
+
+- **real**: the code breaks the rule as it is written, in its scope;
+- **false**: it does not, and you can say how you know;
+- **unsure**: you could not tell. Do not guess; leave it for the user.
+
+## 4. Fix a real finding
+
+- Change the code the way the rule's `must` code shows, in the style of the
+  code around it, and only as much as the fix needs.
+- Run the repo's tests and type check.
+- Confirm with `adhere lint --yes --filter '<file>'`, which judges only the
+  changed file again. If the finding stays, reread the rule: the fix may not
+  be what it asks for.
+- Try at most three fixes for one finding. If it stays after the third, undo
+  your changes for it, so no half-done fix is left, and leave it for the user.
+
+## 5. Suppress a finding, only when allowed
+
+By default, never add an `adhere-ignore` comment or an `@adhere` note, and
+never change the ones already there. Leave the finding, and say why in the
+report. Suppressing is allowed only when the user allows it: their request
+says so, or `ADHERE_ALLOW_SUPPRESSIONS=1` is set in your environment, which
+`printenv ADHERE_ALLOW_SUPPRESSIONS` shows.
+
+When it is allowed, suppress:
+
+- a false finding;
+- a real finding that three fixes did not clear, or whose fix would break
+  something, such as behavior, a public API, or loading the code on a
+  platform. The reason names what the fix would break.
+
+Above the statement the finding is in, add a comment naming the rule as the
+report does, then `--` and the evidence:
+
+```ts
+// adhere-ignore alchemy/providers/idempotent-delete -- DeleteActivity succeeds on a missing activity; probed 2026-09-25
+delete: Effect.fn(function* ({ output }) {
+  yield* sfn.deleteActivity({ activityArn: output.activityArn });
+}),
+```
+
+- The comment covers the whole statement that starts on the next line of code,
+  wherever in it Jev points. At the end of a line of code, it covers the
+  statement that starts on that line.
+- `// adhere-ignore-file <rule> -- <reason>` covers a whole file. Use it only
+  when the rule is wrong for all of the file, such as generated code.
+- Name several rules with commas: `// adhere-ignore <rule>, <rule> -- <reason>`.
+- The reason says what you checked and what you found, so whoever reads it can
+  check it again. "False positive" is not a reason.
+- Never suppress a finding you are unsure of, or a real one you have not
+  tried to fix.
+- Jev never reads these comments: adhere removes them before it sends a file.
+
+When suppressing is allowed and the finding was false because of a fact the
+file does not show, such as how an API behaves, also write the fact where Jev
+will see it the next time it judges this code: in a comment that says
+`@adhere`, on the code the fact is about, with how you know.
+
+```ts
+/**
+ * Deletes the activity. @adhere DeleteActivity succeeds on a missing
+ * activity, so no not-found error needs catching; probed 2026-09-25.
+ */
+```
+
+A note informs Jev and suppresses nothing: Jev still judges the code, so a
+real violation added later is still found. Write one only for a fact you
+checked. A wrong note hides real violations the way wrong comments did.
+
+## 6. When a rule is wrong more often than right
+
+If most of one rule's findings are false, suppressing them one by one hides
+the problem. Stop suppressing that rule's findings, carry on with the other
+rules, and in the report give the user the counts and suggest one of:
+
+- in the config, `overrides: { "<rule id>": "warning" }`, or `"off"`, or
+  `{ threshold: 0.9 }`;
+- for a project rule, rewording it to say what code it is about and what is
+  out of scope, following the rule writing tips:
+  https://github.com/darkmatter/adhere#rule-writing-tips.
+
+## 7. Report
+
+Tell the user, for each finding: the rule, the file and line, the verdict, and
+what you did: fixed it, suppressed it with the reason, or left it for them.
+Give the evidence for each false one. Name the rules that were mostly wrong,
+and every finding you were unsure of.
+
+If you left findings because suppressing was not allowed, end the report with
+this message, filled in:
+
+> Left N findings that suppressing would settle: `<rule>` at `<file>:<line>`,
+> … To let the agent suppress findings it shows are false, or that three fixes
+> did not clear, with the evidence in each comment, set
+> `ADHERE_ALLOW_SUPPRESSIONS=1` in the agent's environment and run it again.

package/src/cli.ts

@@ -7,6 +7,7 @@ import { Status } from "#services/Status.ts";
 import {
   type AuditPlan,
   executeAudit,
+  failing,
   type FileDone,
   planAudit,
   pruneCache,
@@ -19,9 +20,9 @@ import {
   progressLine,
   sendQuestion,
 } from "#workflows/format.ts";
-import type { Overrides } from "#config.ts";
+import type { Flags } from "#config.ts";
 import { findContradictions, formatContradictions } from "#contradictions.ts";
-import { initProject } from "#init.ts";
+import { type Install, initProject } from "#init.ts";
 import { formatLinterCheck, tallyProjectRules } from "#mechanical.ts";
 import { type PresetName, presetNames } from "#presets.ts";
 import { globalRuleSet } from "#rules.ts";
@@ -41,13 +42,14 @@ import {
   Stdio,
   Stream,
 } from "effect";
-import { Command, Flag, Prompt } from "effect/unstable/cli";
+import { Argument, Command, Flag, Prompt } from "effect/unstable/cli";
 import { FetchHttpClient } from "effect/unstable/http";
 // A Bun text import (https://bun.sh/docs/bundler/loaders#text): the file's
 // contents become a string at bundle time, so the compiled binary carries the
 // skill without an --asset flag. `skills/` sits beside `src/`, outside the `#`
 // import map, hence the relative path.
 import skill from "../skills/adhere/SKILL.md" with { type: "text" };
+import fixSkill from "../skills/adhere-fix/SKILL.md" with { type: "text" };
 
 class FindingsReported extends Schema.TaggedError<FindingsReported>()("FindingsReported", {
   count: Schema.Finite,
@@ -97,6 +99,13 @@ const threshold = Flag.float("threshold").pipe(
   ),
 );
 
+const sufficiencyThreshold = Flag.float("sufficiency-threshold").pipe(
+  Flag.optional,
+  Flag.withDescription(
+    "Warn on a finding when Jev's probability that the file shows enough to decide it is below this value, 0 to 1. Replaces the config's sufficiencyThreshold; the default is 0.6.",
+  ),
+);
+
 const limit = Flag.integer("limit").pipe(
   Flag.filter(
     (checks) => checks >= 0,
@@ -124,6 +133,11 @@ const filter = Flag.string("filter").pipe(
   ),
 );
 
+const denyWarnings = Flag.boolean("deny-warnings").pipe(
+  Flag.withDefault(false),
+  Flag.withDescription("Fail the run on warnings as well as errors."),
+);
+
 const yes = Flag.boolean("yes").pipe(
   Flag.withAlias("y"),
   Flag.withDefault(false),
@@ -202,17 +216,17 @@ const force = Flag.boolean("force").pipe(
   Flag.withDescription("Overwrite existing scaffold files."),
 );
 
-export const auditLayer = (overrides: Overrides, filter: ReadonlyArray<string> = []) =>
+export const auditLayer = (flags: Flags, filter: ReadonlyArray<string> = []) =>
   Layer.mergeAll(
     SourceWalkerLive(filter),
     AuditCacheLive,
     JevLive.pipe(Layer.provide([FetchHttpClient.layer, CredentialsLive])),
-  ).pipe(Layer.provideMerge(AdhereConfigLive(overrides)), Layer.provideMerge(statusLayer));
+  ).pipe(Layer.provideMerge(AdhereConfigLive(flags)), Layer.provideMerge(statusLayer));
 
 /** `adhere lint`: the audit. */
 export const lintCommand = Command.make(
   "lint",
-  { preset, threshold, yes, limit, rpm, filter },
+  { preset, threshold, sufficiencyThreshold, yes, limit, rpm, filter, denyWarnings },
   (input) =>
     Effect.gen(function* () {
       const stdio = yield* Stdio.Stdio;
@@ -242,8 +256,10 @@ export const lintCommand = Command.make(
       const path = yield* Path.Path;
       // One write: separate Console.log calls have interleaved out of order here.
       yield* Console.log(render(result, { color, root: path.resolve() }).join("\n"));
-      if (result.findings.length > 0) {
-        yield* FindingsReported.make({ count: result.findings.length });
+      // Only errors fail the run, unless --deny-warnings: a warning is for a nit or a noisy rule.
+      const failed = failing(result.findings, input.denyWarnings);
+      if (failed.length > 0) {
+        yield* FindingsReported.make({ count: failed.length });
       }
     }),
 ).pipe(
@@ -255,6 +271,7 @@ export const lintCommand = Command.make(
       {
         presets: input.preset,
         threshold: Option.getOrUndefined(input.threshold),
+        sufficiencyThreshold: Option.getOrUndefined(input.sufficiencyThreshold),
         rpm: Option.getOrUndefined(input.rpm),
       },
       input.filter,
@@ -263,11 +280,11 @@ export const lintCommand = Command.make(
 );
 
 /** Jev, with the key `lint` uses, and the config it reads the model and threshold from. */
-export const validateLayer = (overrides: Overrides) =>
+export const validateLayer = (flags: Flags) =>
   Layer.merge(
     JevLive.pipe(Layer.provide([FetchHttpClient.layer, CredentialsLive])),
     AuditCacheLive,
-  ).pipe(Layer.provideMerge(AdhereConfigLive(overrides)), Layer.provideMerge(statusLayer));
+  ).pipe(Layer.provideMerge(AdhereConfigLive(flags)), Layer.provideMerge(statusLayer));
 
 /**
  * `adhere validate`: everything `lint` loads, then how each rule's wording
@@ -306,6 +323,17 @@ export const validateCommand = Command.make("validate", { preset }, () =>
   Command.provide((input) => validateLayer({ presets: input.preset })),
 );
 
+const installLine = (install: Install): string => {
+  switch (install.status) {
+    case "installed":
+      return `installed: @drkmttr/adhere with ${install.packageManager}`;
+    case "listed":
+      return "installed: none, @drkmttr/adhere is already in package.json";
+    case "no-package-json":
+      return "installed: none, there is no package.json";
+  }
+};
+
 /** `adhere init`: the scaffold. */
 export const initCommand = Command.make("init", { force }, (input) =>
   Effect.gen(function* () {
@@ -314,10 +342,15 @@ export const initCommand = Command.make("init", { force }, (input) =>
     const lines = [
       result.created.length > 0 ? `created: ${result.created.join(", ")}` : "created: none",
       result.skipped.length > 0 ? `skipped: ${result.skipped.join(", ")}` : "skipped: none",
+      installLine(result.install),
     ];
     yield* Console.log(lines.join("\n"));
   }),
-).pipe(Command.withDescription("Scaffold .adhere/config.ts and example Markdown rules."));
+).pipe(
+  Command.withDescription(
+    "Scaffold .adhere/config.ts and example Markdown rules, and add @drkmttr/adhere to devDependencies with the project's package manager.",
+  ),
+);
 
 /**
  * The key typed at a masked prompt, or piped in: `adhere login < key.txt`.
@@ -376,10 +409,22 @@ export const logoutCommand = Command.make("logout", {}, () =>
   Command.provide(CredentialsLive),
 );
 
-/** `adhere skill`: the agent skill for writing rules, as shipped in the binary. */
-export const skillCommand = Command.make("skill", {}, () => Console.log(skill.trimEnd())).pipe(
+/** The agent skills the binary carries, by the name `adhere skill` takes. */
+const skills = { rules: skill, fix: fixSkill } as const;
+
+const skillName = Argument.choice("skill", ["rules", "fix"] as const).pipe(
+  Argument.withDefault("rules" as const),
+  Argument.withDescription(
+    "rules, the default, to gather a repo's conventions into rules and configure adhere; fix, to verify and fix the findings lint reports.",
+  ),
+);
+
+/** `adhere skill [rules|fix]`: an agent skill, as shipped in the binary. */
+export const skillCommand = Command.make("skill", { name: skillName }, ({ name }) =>
+  Console.log(skills[name].trimEnd()),
+).pipe(
   Command.withDescription(
-    "Print the agent skill that gathers a repo's conventions into rules and configures adhere. Pipe it into .agents/skills/adhere/SKILL.md or hand it to an agent.",
+    "Print an agent skill: by default the one that gathers a repo's conventions into rules and configures adhere, or with fix, the one that verifies and fixes lint's findings. Pipe it into .agents/skills/<name>/SKILL.md or hand it to an agent.",
   ),
 );
 

package/src/comments.ts

@@ -0,0 +1,36 @@
+import { scan } from "#highlight.ts";
+
+/** `@adhere` anywhere in a comment makes it a note for Jev. */
+const NOTE = /@adhere\b/;
+
+/**
+ * Whether a comment is a note for Jev: one that says `@adhere` anywhere in
+ * it, which stays when comments are taken out.
+ */
+export const isNote = (comment: string): boolean => NOTE.test(comment);
+
+/**
+ * A file's lines with its comments taken out, but for those `keep` keeps:
+ * each comment's text removed and its line breaks kept, so every line keeps
+ * its number, and a line with only the spaces before a comment left empty. A
+ * string, template literal, or regular expression that holds `//` or `/*`
+ * stays whole, as the highlighter reads it.
+ */
+export const withoutComments = (
+  lines: ReadonlyArray<string>,
+  keep: (comment: string) => boolean = () => false,
+): ReadonlyArray<string> => {
+  const code = lines.join("\n");
+  // No comment can start without one of these, so a file without them is sent as it is.
+  if (!code.includes("//") && !code.includes("/*")) return lines;
+  const tokens = scan(code);
+  // What the highlighter could not read, if anything, stays as it was.
+  const read = tokens.reduce((length, token) => length + token.text.length, 0);
+  const kept =
+    tokens
+      .map(({ text, kind }) =>
+        kind === "comment" && !keep(text) ? text.replace(/[^\n]/g, "") : text,
+      )
+      .join("") + code.slice(read);
+  return kept.split("\n").map((line, index) => (line === lines[index] ? line : line.trimEnd()));
+};