@drkmttr/adhere 0.6.1 → 0.7.1

package/presets/effect/services/memoize-parameterized-layers.md

@@ -1,8 +1,8 @@
 ---
-description: The result of a parameterized layer constructor should be stored in a module constant before it is used in more than one place.
+description: The result of a parameterized layer constructor must be stored in a module constant before it is used in more than one place, never constructed again for each use.
 ---
 
-```ts
+```ts must
 const postgresLayer = Postgres.layer({ url: "postgres://localhost/mydb", poolSize: 10 });
 
 const goodAppLayer = Layer.merge(
@@ -10,3 +10,10 @@ const goodAppLayer = Layer.merge(
   OrderRepo.layer.pipe(Layer.provide(postgresLayer)),
 );
 ```
+
+```ts never
+const Live = Layer.merge(
+  Sessions.layer.pipe(Layer.provide(Redis.layer({ host: "localhost" }))),
+  RateLimits.layer.pipe(Layer.provide(Redis.layer({ host: "localhost" }))),
+);
+```

package/presets/effect/services/methods-have-no-requirements.md

@@ -1,8 +1,8 @@
 ---
-description: Service method signatures have no requirements. Dependencies should be acquired inside the layer, not declared on the method.
+description: Service method signatures must have no requirements. Dependencies must be acquired inside the layer, never declared on the method.
 ---
 
-```ts
+```ts must
 class Database extends Context.Service<
   Database,
   {
@@ -11,3 +11,10 @@ class Database extends Context.Service<
   }
 >()("@app/Database") {}
 ```
+
+```ts never
+class Orders extends Context.Service<
+  Orders,
+  { readonly save: (order: Order) => Effect.Effect<void, SaveError, Database> }
+>()("@app/Orders") {}
+```

package/presets/effect/services/no-mutable-state.md

@@ -1,8 +1,8 @@
 ---
-description: A service exposes readonly members and does not expose mutable state.
+description: A service must expose only readonly members, never mutable state.
 ---
 
-```ts
+```ts must
 class Logger extends Context.Service<
   Logger,
   {
@@ -10,3 +10,10 @@ class Logger extends Context.Service<
   }
 >()("@app/Logger") {}
 ```
+
+```ts never
+class Counter extends Context.Service<
+  Counter,
+  { count: number; readonly increment: () => Effect.Effect<void> }
+>()("@app/Counter") {}
+```

package/presets/effect/services/provide-at-entry.md

@@ -1,8 +1,8 @@
 ---
-description: Layers should be provided once at the program entry. A module that is not an entry point does not call Effect.provide.
+description: Layers must be provided once at the program entry. A module that is not an entry point must never call Effect.provide.
 ---
 
-```ts
+```ts must
 const appLayer = userServiceLayer.pipe(
   Layer.provideMerge(databaseLayer),
   Layer.provideMerge(loggerLayer),
@@ -16,3 +16,8 @@ const program = Effect.gen(function* () {
 
 const main = program.pipe(Effect.provide(appLayer));
 ```
+
+```ts never
+export const getUser = (id: string) =>
+  UserRepo.find(id).pipe(Effect.provide(UserRepo.layer));
+```

package/presets/effect/services/test-layers-are-in-memory.md

@@ -1,8 +1,8 @@
 ---
-description: A test implementation of a service should be built with Layer.sync or Layer.succeed over in-memory state.
+description: A test implementation of a service must be built with Layer.sync or Layer.succeed over in-memory state, never over a real database, network, or file.
 ---
 
-```ts
+```ts must
 static readonly testLayer = Layer.sync(Cache, () => {
   const store = new Map<string, string>()
 
@@ -12,3 +12,13 @@ static readonly testLayer = Layer.sync(Cache, () => {
   return { get, set }
 })
 ```
+
+```ts never
+const EmailTest = Layer.effect(
+  Email,
+  Effect.gen(function* () {
+    const smtp = yield* SmtpClient;
+    return Email.of({ send: (message) => smtp.deliver(message) });
+  }),
+).pipe(Layer.provide(SmtpClient.layer({ host: "localhost", port: 1025 })));
+```

package/presets/effect/testing/test-clock-for-time.md

@@ -1,8 +1,8 @@
 ---
-description: A test that depends on time uses TestClock. Real sleeps and it.live should be used only when real time is required.
+description: A test that depends on time must use TestClock. Real sleeps and it.live must be used only when real time is required.
 ---
 
-```ts
+```ts must
 it.effect("time-based test", () =>
   Effect.gen(function* () {
     const fiber = yield* Effect.delay(Effect.succeed("done"), "10 seconds").pipe(Effect.forkChild);
@@ -12,3 +12,12 @@ it.effect("time-based test", () =>
   }),
 );
 ```
+
+```ts never
+it.live("retries after a delay", () =>
+  Effect.gen(function* () {
+    yield* Effect.sleep("2 seconds");
+    expect(yield* attempts).toBe(2);
+  }),
+);
+```

package/presets/effect/testing/test-random.md

@@ -1,8 +1,8 @@
 ---
-description: A test that depends on randomness controls it with a fixed seed through Random.withSeed, not Math.random or an unseeded Random.
+description: A test that depends on randomness must control it with a fixed seed through Random.withSeed, never with Math.random or an unseeded Random.
 ---
 
-```ts
+```ts must
 const program = Effect.gen(function* () {
   const value1 = yield* Random.next;
   const value2 = yield* Random.next;
@@ -13,3 +13,10 @@ await Effect.runPromise(
   Effect.all([program.pipe(Random.withSeed("my-seed")), program.pipe(Random.withSeed("my-seed"))]),
 ); // => [[0.018368576514773527, 0.4010840628128671], [0.018368576514773527, 0.4010840628128671]]
 ```
+
+```ts never
+it("creates unique ids", () => {
+  const id = Math.random().toString(36).slice(2);
+  expect(id).toHaveLength(11);
+});
+```

package/skills/adhere/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: adhere
-description: Gather a repository's non-deterministic coding conventions into adhere rules (Markdown files with a description and reference code judged by Jev), configure adhere, run it, and calibrate thresholds. Use when setting up adhere in a repo, when the user asks to turn conventions, AGENTS.md guidance, ADRs, or review feedback into lint rules a normal linter cannot express, or when tuning adhere findings.
+description: Gather a repository's non-deterministic coding conventions into adhere rules (Markdown files with a description and code that must, or must never, be written, judged by Jev), configure adhere, run it, and calibrate thresholds. Use when setting up adhere in a repo, when the user asks to turn conventions, AGENTS.md guidance, ADRs, or review feedback into lint rules a normal linter cannot express, or when tuning adhere findings.
 ---
 
 # Gather adhere rules from a repo
 
 adhere is a linter for rules a normal linter cannot check. Each rule is one
-sentence plus a block of correct code; Jev judges every source file against it
-and returns a probability. Your job is to find the conventions a repo already
+sentence in RFC 2119's words plus code that must be written and code that must
+never be; Jev judges every source file against it and returns a probability. Your job is to find the conventions a repo already
 has, write the ones that need judgment as rule files, and tune until the
 report is trustworthy.
 
@@ -52,32 +52,39 @@ The path without `.md` is the rule id.
 
 ````md
 ---
-description: One sentence stating the pattern positively. Name what is done, then what it replaces.
+description: One sentence saying what code must be, then what it must never be.
 threshold: 0.8
 ---
 
 Optional prose for readers on GitHub. adhere ignores it.
 
-```ts
+```ts must
 // Correct code lifted from this repo, trimmed to the pattern.
 ```
 
-```ts avoid
+```ts never
 // 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, and only correct
+- `description` is one sentence, specific, in the same words as the fences:
+  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.
+- 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 `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.
+  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
+  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.
+- One pattern per file. Two patterns in one `must` block blur the probability.
 - `threshold` is optional. Start without it; set it in step 5 if needed.
 
 ## 4. Configure
@@ -110,11 +117,11 @@ adhere lint --threshold 0.9  # re-reads the cache, sends nothing
 
 Then, per rule, read the findings and decide:
 
-- Many hits at 0.70 to 0.80, mostly not violations: the description is too
+- Many hits at 0.80 to 0.90, mostly not violations: the description is too
   broad. Narrow it (say what is out of scope) or raise that rule's
   `threshold`. Prefer narrowing; a threshold hides, a sentence explains.
-- Hits on code that follows the pattern through a different API: the
-  reference is too specific. Use the repo's most general correct example.
+- Hits on code that follows the pattern through a different API: the `must`
+  block is too specific. Use the repo's most general correct example.
 - Zero hits: plant a deliberate violation in a scratch file, run, confirm the
   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.

package/src/cli.ts

@@ -68,6 +68,33 @@ const threshold = Flag.float("threshold").pipe(
   ),
 );
 
+const limit = Flag.integer("limit").pipe(
+  Flag.filter(
+    (checks) => checks >= 0,
+    (checks) => `--limit is a number of checks, 0 or more, not ${checks}.`,
+  ),
+  Flag.optional,
+  Flag.withDescription(
+    "Judge at most this many checks. The rest wait for a later run, which picks up where this one stopped, since judgments are cached. --limit 0 shows the plan and judges nothing.",
+  ),
+);
+
+const rpm = Flag.integer("rpm").pipe(
+  Flag.filter(
+    (requests) => requests > 0,
+    (requests) => `--rpm is a number of requests a minute, more than 0, not ${requests}.`,
+  ),
+  Flag.optional,
+  Flag.withDescription("Send at most this many requests to Jev a minute, evenly spaced."),
+);
+
+const filter = Flag.string("filter").pipe(
+  Flag.atLeast(0),
+  Flag.withDescription(
+    "Read only files whose path from the working directory matches this glob, such as 'src/**' or '**/*.service.ts'. Repeat it for more; a pattern starting with ! leaves out what it matches.",
+  ),
+);
+
 const yes = Flag.boolean("yes").pipe(
   Flag.withAlias("y"),
   Flag.withDefault(false),
@@ -114,53 +141,61 @@ const force = Flag.boolean("force").pipe(
 const chosenPresets = (flag: Option.Option<PresetName>): ReadonlyArray<PresetName> =>
   Option.isSome(flag) ? [flag.value] : [];
 
-export const auditLayer = (overrides: Overrides) =>
+export const auditLayer = (overrides: Overrides, filter: ReadonlyArray<string> = []) =>
   Layer.mergeAll(
-    SourceWalkerLive,
+    SourceWalkerLive(filter),
     AuditCacheLive,
     JevLive.pipe(Layer.provide([FetchHttpClient.layer, CredentialsLive])),
   ).pipe(Layer.provideMerge(AdhereConfigLive(overrides)));
 
 /** `adhere lint`: the audit. */
-export const lintCommand = Command.make("lint", { preset, threshold, yes }, (input) =>
-  Effect.gen(function* () {
-    const stdio = yield* Stdio.Stdio;
-    const plan = yield* planAudit;
-    yield* toStderr(`${describePlan(plan).join("\n")}\n`);
-    // A prompt draws on stdout, so it needs a terminal at both ends: none when
-    // the report is redirected, or in CI.
-    const interactive = (yield* stdio.stdinIsTerminal) && (yield* stdio.stdoutIsTerminal);
-    if (plan.requests > 0 && interactive && !input.yes) {
-      const send = yield* Prompt.run(
-        Prompt.confirm({ message: sendQuestion(plan), initial: true }),
+export const lintCommand = Command.make(
+  "lint",
+  { preset, threshold, yes, limit, rpm, filter },
+  (input) =>
+    Effect.gen(function* () {
+      const stdio = yield* Stdio.Stdio;
+      const plan = yield* planAudit({ limit: Option.getOrUndefined(input.limit) });
+      const limits = { filter: input.filter, rpm: Option.getOrUndefined(input.rpm) };
+      yield* toStderr(`${describePlan(plan, limits).join("\n")}\n`);
+      // A prompt draws on stdout, so it needs a terminal at both ends: none when
+      // the report is redirected, or in CI.
+      const interactive = (yield* stdio.stdinIsTerminal) && (yield* stdio.stdoutIsTerminal);
+      if (plan.requests > 0 && interactive && !input.yes) {
+        const send = yield* Prompt.run(
+          Prompt.confirm({ message: sendQuestion(plan), initial: true }),
+        );
+        if (!send) {
+          yield* toStderr("Nothing sent.\n");
+          return yield* Cancelled.make({});
+        }
+      }
+      const counter = counterFor(plan);
+      yield* counter.start;
+      const result = yield* executeAudit(plan, counter.update).pipe(
+        Effect.onExit((exit) => counter.finish(Exit.isFailure(exit))),
       );
-      if (!send) {
-        yield* toStderr("Nothing sent.\n");
-        return yield* Cancelled.make({});
+      const color = yield* stdio.stdoutIsTerminal;
+      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 });
       }
-    }
-    const counter = counterFor(plan);
-    yield* counter.start;
-    const result = yield* executeAudit(plan, counter.update).pipe(
-      Effect.onExit((exit) => counter.finish(Exit.isFailure(exit))),
-    );
-    const color = yield* stdio.stdoutIsTerminal;
-    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 });
-    }
-  }),
+    }),
 ).pipe(
   Command.withDescription(
-    "Audit the working directory against reference code from .adhere/config.ts or a preset, judged by Jev.",
+    "Audit the working directory against the rules in .adhere/ or a preset, judged by Jev.",
   ),
   Command.provide((input) =>
-    auditLayer({
-      presets: chosenPresets(input.preset),
-      threshold: Option.getOrUndefined(input.threshold),
-    }),
+    auditLayer(
+      {
+        presets: chosenPresets(input.preset),
+        threshold: Option.getOrUndefined(input.threshold),
+        rpm: Option.getOrUndefined(input.rpm),
+      },
+      input.filter,
+    ),
   ),
 );
 
@@ -274,7 +309,7 @@ export const skillCommand = Command.make("skill", {}, () => Console.log(skill.tr
 
 /** The whole CLI. Bare `adhere` prints its help. */
 export const cli = Command.make("adhere").pipe(
-  Command.withDescription("Lint a repository against reference code in .adhere/, judged by Jev."),
+  Command.withDescription("Lint a repository against the rules in .adhere/, judged by Jev."),
   Command.withExamples([
     { command: "adhere init", description: "Scaffold .adhere/config.ts and two example rules" },
     { command: "adhere validate", description: "Check the config and rules without calling Jev" },

package/src/config.ts

@@ -1,25 +1,79 @@
 import { type PresetName, presetNames } from "#presets.ts";
 import type { RuleSet } from "#rules.ts";
-import { Effect, Schema } from "effect";
+import { Effect, Schema, SchemaTransformation } from "effect";
 
 export type RuleId = string;
 
-export const Rule = Schema.Struct({
+/**
+ * A rule's examples, named in RFC 2119's words, which Jev reads as written. A
+ * requirement shows code that `must` be written and code that must `never`
+ * be. A guideline, which asks for less, shows code that `should` be written
+ * and code that `shouldNot` be.
+ */
+const RuleFields = Schema.Struct({
   description: Schema.String,
-  /** Correct code: the pattern a file should follow. */
+  must: Schema.optionalKey(Schema.String),
+  never: Schema.optionalKey(Schema.String),
+  should: Schema.optionalKey(Schema.String),
+  shouldNot: Schema.optionalKey(Schema.String),
+  threshold: Schema.optionalKey(Schema.Finite),
+});
+
+/** Before 0.7, a rule's examples were `reference` and `avoid`: read as `must` and `never`. */
+export const Rule = Schema.Struct({
+  ...RuleFields.fields,
   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",
-  ),
-);
+})
+  .pipe(
+    Schema.decodeTo(
+      RuleFields,
+      SchemaTransformation.transform({
+        decode: ({ reference, avoid, ...rule }) => ({
+          ...rule,
+          ...(rule.must === undefined && reference !== undefined ? { must: reference } : {}),
+          ...(rule.never === undefined && avoid !== undefined ? { never: avoid } : {}),
+        }),
+        encode: (rule) => rule,
+      }),
+    ),
+  )
+  .check(
+    Schema.makeFilter((rule) => {
+      const requirement = rule.must !== undefined || rule.never !== undefined;
+      const guideline = rule.should !== undefined || rule.shouldNot !== undefined;
+      return requirement && guideline
+        ? "a rule is a requirement (must, never) or a guideline (should, shouldNot), not both"
+        : requirement || guideline
+          ? undefined
+          : "a rule needs an example: must, never, should, or shouldNot";
+    }),
+  );
 export interface Rule extends Schema.Schema.Type<typeof Rule> {}
 
+/** One of a rule's examples, under the word it is written with. */
+export interface Example {
+  readonly word: "must" | "never" | "should" | "should not";
+  readonly code: string;
+}
+
+/** A rule's code to write and code not to write, each when the rule has it. */
+export interface Examples {
+  readonly good?: Example;
+  readonly bad?: Example;
+}
+
+/** A guideline's examples are `should` and `should not`; any other rule's, `must` and `never`. */
+export const examplesOf = (rule: Rule): Examples => {
+  const guideline = rule.should !== undefined || rule.shouldNot !== undefined;
+  const good = guideline ? rule.should : rule.must;
+  const bad = guideline ? rule.shouldNot : rule.never;
+  return {
+    ...(good === undefined ? {} : { good: { word: guideline ? "should" : "must", code: good } }),
+    ...(bad === undefined ? {} : { bad: { word: guideline ? "should not" : "never", code: bad } }),
+  };
+};
+
 export type Rules = Readonly<Record<RuleId, Rule>>;
 
 /** Rules inline, or a directory of Markdown rule files (see `markdown.ts`). */
@@ -86,7 +140,7 @@ export type Loaded<T extends { readonly rules?: unknown }> = Omit<T, "rules"> &
 };
 
 export const DEFAULT_MODEL = "jev-latest";
-export const DEFAULT_THRESHOLD = 0.7;
+export const DEFAULT_THRESHOLD = 0.8;
 
 /** A config with its presets folded in and every default applied. */
 export interface ResolvedConfig {
@@ -94,6 +148,8 @@ export interface ResolvedConfig {
   readonly threshold: number;
   readonly rules: Rules;
   readonly scopedRules?: RuleSet;
+  /** Requests to Jev a minute, at most. Unset, requests go out as fast as they are made. */
+  readonly rpm?: number;
 }
 
 /** Command-line values that apply on top of the config file. */
@@ -101,6 +157,8 @@ export interface Overrides {
   readonly presets?: ReadonlyArray<PresetName>;
   /** Replaces the config's global threshold. Per-rule thresholds still win. */
   readonly threshold?: number;
+  /** Throttles requests to Jev to at most this many a minute. */
+  readonly rpm?: number;
 }
 
 /** The presets a run applies, command-line ones first. */
@@ -129,6 +187,7 @@ export const resolveConfig = (
     model: config.model ?? last("model") ?? DEFAULT_MODEL,
     threshold: overrides.threshold ?? config.threshold ?? last("threshold") ?? DEFAULT_THRESHOLD,
     rules: Object.assign({}, ...applied.map((preset) => preset.rules), config.rules),
+    ...(overrides.rpm === undefined ? {} : { rpm: overrides.rpm }),
   };
 };
 

package/src/init.ts

@@ -15,39 +15,41 @@ export interface InitOptions {
 const CONFIG = `import type { Config } from "@drkmttr/adhere";
 
 export default {
-  threshold: 0.7,
+  threshold: 0.8,
 } satisfies Config;
 `;
 
 const SMALL_FILES = `---
-description: Prefer small focused files with one primary responsibility.
+description: A file should be small and focused, with one primary responsibility.
 threshold: 0.8
 ---
 
-Use this rule as a template for repository-specific conventions.
+A guideline, so its description and its code say should. A rule that must
+hold says must and never instead, as name-domain-actions does. Use this rule
+as a template for repository-specific conventions.
 
-\`\`\`ts
+\`\`\`ts should
 export const parsePort = (value: string) =>
   Port.make(Number.parseInt(value, 10));
 \`\`\`
 `;
 
 const NAME_EFFECTS = `---
-description: Name functions after the domain action they perform.
+description: A function must be named after the domain action it performs, never after a generic verb like handle.
 threshold: 0.8
 ---
 
-\`\`\`ts
+\`\`\`ts must
 export const loadCustomerProfile = (customerId: CustomerId) =>
   Effect.gen(function* () {
     return yield* CustomerStore.find(customerId);
   });
 \`\`\`
 
-A fence tagged \`avoid\` shows what a violation looks like. It is optional, and
+A fence tagged \`never\` shows what a violation looks like. It is optional, and
 a rule can have one without the block above.
 
-\`\`\`ts avoid
+\`\`\`ts never
 export const handle = (id: string) =>
   Effect.gen(function* () {
     return yield* CustomerStore.find(id);