@drkmttr/adhere 0.6.0 → 0.7.0

package/presets/effect/services/fresh-layer-per-test.md

@@ -1,8 +1,8 @@
 ---
-description: Each it.effect provides its own layer. it.layer should be used only to share an expensive resource across a suite.
+description: Each it.effect must provide its own layer. it.layer must be used only to share an expensive resource across a suite, never a cheap one.
 ---
 
-```ts
+```ts must
 it.effect("starts at zero", () =>
   Effect.gen(function* () {
     const counter = yield* Counter;
@@ -18,3 +18,10 @@ it.effect("increments without leaking", () =>
   }).pipe(Effect.provide(Counter.layer)),
 );
 ```
+
+```ts never
+it.layer(Counter.layer)("Counter", (it) => {
+  it.effect("starts at zero", () => Effect.gen(function* () { /* ... */ }));
+  it.effect("increments", () => Effect.gen(function* () { /* ... */ }));
+});
+```

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

@@ -154,7 +154,7 @@ export const lintCommand = Command.make("lint", { preset, threshold, yes }, (inp
   }),
 ).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({
@@ -274,7 +274,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 {

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);

package/src/markdown.ts

@@ -1,26 +1,28 @@
-import { ConfigUnavailable, type Rule } from "#config.ts";
+import { ConfigUnavailable, type Example, type Rule } from "#config.ts";
 import { Effect, Schema } from "effect";
 
 /**
  * A rule as a Markdown file:
  *
  *     ---
- *     description: One sentence naming the pattern.
+ *     description: One sentence saying what code must be, or never be.
  *     threshold: 0.8
  *     ---
  *     Any prose, rendered on GitHub and ignored by adhere.
  *
- *     ```ts
- *     const reference = "the correct code"
+ *     ```ts must
+ *     const written = "code that must be written this way"
  *     ```
  *
- *     ```ts avoid
- *     const avoided = "what a violation looks like"
+ *     ```ts never
+ *     const avoided = "code that must never be written this way"
  *     ```
  *
- * 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.
+ * A fence's info string names its code with RFC 2119's words: `must` and
+ * `never` for a requirement, `should` and `should not` for a guideline. The
+ * first fence under each word is that example, and a rule has either or both.
+ * An untagged fence is the code to write, and without a fence the whole body
+ * is. `avoid`, the word before 0.7, means `never`. `threshold` is optional.
  */
 const FrontMatter = Schema.Struct({
   description: Schema.String,
@@ -29,7 +31,6 @@ 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]*$/gm;
-const AVOID = "avoid";
 
 const unquote = (value: string): string => {
   const trimmed = value.trim();
@@ -50,17 +51,27 @@ const parseFrontMatter = (block: string): Record<string, string> => {
   return fields;
 };
 
+type Word = Example["word"];
+
 interface Fence {
-  readonly avoid: boolean;
+  /** The word the info string names the code with; none for an untagged fence. */
+  readonly word: Word | undefined;
   readonly code: string;
 }
 
+/** `must not`, like `never` and the older `avoid`, names code never to write. */
+const wordOf = (info: string): Word | undefined => {
+  const words = info.trim().toLowerCase().split(/\s+/);
+  const not = words.includes("not");
+  if (words.includes("never") || words.includes("avoid")) return "never";
+  if (words.includes("should")) return not ? "should not" : "should";
+  if (words.includes("must")) return not ? "never" : "must";
+  return undefined;
+};
+
 const fencesOf = (body: string): ReadonlyArray<Fence> =>
   Array.from(body.matchAll(FENCE), (match) => ({
-    avoid: (match[2] ?? "")
-      .trim()
-      .split(/\s+/)
-      .some((word) => word.toLowerCase() === AVOID),
+    word: wordOf(match[2] ?? ""),
     code: (match[3] ?? "").trim(),
   }));
 
@@ -68,16 +79,32 @@ const fencesOf = (body: string): ReadonlyArray<Fence> =>
 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"> => {
+type Code = Pick<Rule, "must" | "never" | "should" | "shouldNot">;
+
+/**
+ * Each example the body has, under its word. An untagged fence is the code
+ * to write: `should` in a guideline, which a `should` or `should not` fence
+ * makes the rule, and `must` otherwise.
+ */
+const codeOf = (body: string): Code => {
   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);
+  if (fences.length === 0) {
+    const must = nonEmpty(body.trim());
+    return must === undefined ? {} : { must };
+  }
+  const first = (word: Word | undefined) =>
+    nonEmpty(fences.find((fence) => fence.word === word)?.code);
+  const guideline = fences.some((fence) => fence.word === "should" || fence.word === "should not");
+  const untagged = first(undefined);
+  const must = first("must") ?? (guideline ? undefined : untagged);
+  const never = first("never");
+  const should = first("should") ?? (guideline ? untagged : undefined);
+  const shouldNot = first("should not");
   return {
-    ...(reference === undefined ? {} : { reference }),
-    ...(avoid === undefined ? {} : { avoid }),
+    ...(must === undefined ? {} : { must }),
+    ...(never === undefined ? {} : { never }),
+    ...(should === undefined ? {} : { should }),
+    ...(shouldNot === undefined ? {} : { shouldNot }),
   };
 };
 
@@ -98,9 +125,16 @@ export const parseRuleMarkdown = (
       ),
     );
     const code = codeOf(match[2]);
-    if (code.reference === undefined && code.avoid === undefined) {
+    const requirement = code.must !== undefined || code.never !== undefined;
+    const guideline = code.should !== undefined || code.shouldNot !== undefined;
+    if (requirement && guideline) {
+      return yield* ConfigUnavailable.make({
+        message: `${file}: a rule is a requirement (must, never) or a guideline (should, should not), not both`,
+      });
+    }
+    if (!requirement && !guideline) {
       return yield* ConfigUnavailable.make({
-        message: `${file}: the body needs reference code, a fence tagged avoid, or both`,
+        message: `${file}: the body needs code, in a fence tagged must, never, should, or should not, or untagged`,
       });
     }
     return { ...front, ...code };