@drkmttr/adhere 0.6.1 → 0.7.1

package/README.md

@@ -1,9 +1,9 @@
 # adhere
 
 A linter for rules a normal linter cannot check. A rule is a one-sentence
-description like "business logic should live in services", plus correct 
-reference code / code to avoid / or both. For each
-source file, adhere asks [Jev](https://typesafe.ai) (TypeSafe AI's System One
+description in RFC 2119's words, like "business logic must live in services",
+with code that must be written that way, code that must never be, 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`.
@@ -61,8 +61,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; a rule with only code to avoid shows that code,
-labeled `avoid:`, instead. On a terminal, the report is in color and the code
+hint is the rule's code that must be written; a rule with only code that must
+never be written shows that code, labeled `never:`, instead. On a terminal, the report is in color and the code
 in it is highlighted. 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 API key, or an unknown command or flag; a
@@ -73,8 +73,11 @@ refusal prints its reason.
 ```sh
 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 lint --threshold 0.9    # replace the config's threshold; per-rule thresholds still apply
 adhere lint --yes              # send the requests without asking first
+adhere lint --limit 500        # judge at most 500 checks; the rest wait for the next run
+adhere lint --rpm 30           # send at most 30 requests a minute
+adhere lint --filter 'src/**'  # read only the files a glob matches
 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
@@ -104,6 +107,21 @@ the report goes to stdout. A request Jev refuses stops the run with the file,
 the HTTP status, and Jev's reason. Files finished before it are cached, so
 running again continues from there.
 
+### Limiting a run
+
+Three flags bound what a run does. `--limit <checks>` judges at most that many
+checks, taken in path order; the rest wait, and since judgments are cached, the
+next run with the same limit picks up where this one stopped. `--limit 0` shows
+the plan and judges nothing. `--rpm <requests>` sends at most that many requests
+to Jev a minute, evenly spaced, retries included, and the plan says about how
+long they take. `--filter <glob>` reads only the files whose path from the
+working directory matches, such as `src/**` or `**/*.service.ts`; repeat it for
+more, and start a pattern with `!` to leave out what it matches. Together:
+
+```sh
+adhere lint --filter 'packages/api/**' --filter '!**/generated/**' --limit 200 --rpm 30
+```
+
 ### What gets read
 
 `adhere lint` reads the `.ts` files under the working directory, except `.d.ts`,
@@ -161,17 +179,17 @@ import type { Config } from "@drkmttr/adhere";
 
 export default {
   model: "jev-latest", // optional, default "jev-latest"
-  threshold: 0.7, // optional, default 0.7
+  threshold: 0.8, // optional, default 0.8
   presets: ["effect"], // optional, built-in rule sets
   rules: {
     "data/brand-meaningful-primitives": {
       description:
-        "A primitive with semantic meaning, such as an id, email, URL, port, or count, should be a branded schema.",
-      reference: `
+        "A primitive with semantic meaning, such as an id, email, URL, port, or count, must be a branded schema.",
+      must: `
 const UserId = Schema.String.pipe(Schema.brand("UserId"))
 type UserId = typeof UserId.Type
 `,
-      avoid: "type UserId = string", // optional: what a violation looks like
+      never: "type UserId = string", // optional: what a violation looks like
       threshold: 0.8, // optional per-rule override
     },
   },
@@ -196,44 +214,54 @@ config and the cache (neither is read as a rule). The path without `.md` is the
 rule id, so `.adhere/data/brand-ports.md` is `data/brand-ports`. When that
 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. A fence tagged `avoid` after its
-language holds code to avoid instead: what a violation looks like.
+A file is front matter, then a body. The body's code goes in fences tagged,
+after the language, with RFC 2119's words: `must` for code that must be
+written, and `never` for code that must never be, which is what a violation
+looks like. Prose around them renders on GitHub and is ignored. An untagged
+fence is code that must be written, and without a fence the whole body is.
+`avoid`, the tag before 0.7, reads as `never`.
 
 ````md
 ---
-description: A port is a branded, range-checked integer, not a bare number.
+description: A port must be a branded, range-checked integer, never a bare number.
 threshold: 0.8
 ---
 
 Why: a bare `number` accepts 70000 and -1.
 
-```ts
+```ts must
 const Port = Schema.Int.pipe(
   Schema.check(Schema.isBetween({ minimum: 1, maximum: 65535 })),
   Schema.brand("Port"),
 );
 ```
 
-Not this:
-
-```ts avoid
+```ts never
 const port: number = Number(process.env.PORT);
 ```
 ````
 
-`description` is required, with a reference, code to avoid, or both.
+`description` is required, with code under `must`, `never`, 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.
+Jev reads the code under the same words, and is asked whether the file
+diverges from the pattern `must` shows, with `never` as an example of
+diverging. Write the description in them too, so the rule and its code agree:
+"must" and "never", as above.
+
+A rule with only code that must never be written 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 that must never be written,
+under `must`, reads to Jev as the pattern to follow.
+
+A rule that is a guideline rather than a requirement says "should" instead:
+in its description, and in fences tagged `should` and `should not` (`should`
+and `shouldNot` inline in a config). Jev then reads the code under `should`
+and `should_not`. A rule is one or the other, so it cannot mix `must` or
+`never` with `should` or `should not`. In a config, `reference` and `avoid`,
+the names before 0.7, read as `must` and `never`.
 
 Nested `.adhere/` directories are also discovered, except under
 `node_modules/`, `dist/`, and the other skipped directories (above). A rule in
@@ -260,6 +288,22 @@ export default { presets: ["effect"], rules: "./docs/adhere" } satisfies Config;
 
 Rules read through `rules` apply project-wide.
 
+### Rule writing tips
+
+We've evaluated different ways of giving Jev a rule, to catch the most
+violations with the fewest false positives. In general:
+
+- Say "must" for what code must do and "never" for what it must not, in the
+  description and as the fence tags.
+- Give one example of each: one `must` block and one `never` block. Three of
+  each did no better, and several of one kind alone did worse.
+- For a guideline rather than a requirement, say "should" and "should not"
+  the same way.
+
+On the Effect preset, rules written this way cut the findings Jev got wrong at
+the default threshold from 6 to 1, and caught as many violations. For more
+about the evaluations, see [the eval](eval/README.md).
+
 ### Presets
 
 A preset has the shape of a config without `presets`: `rules`, and optionally
@@ -273,7 +317,7 @@ case the config file is optional.
 ### Precedence
 
 Highest first: `--threshold` on the command line, the config file, presets in
-order (a later preset wins), then the defaults `jev-latest` and `0.7`. A rule
+order (a later preset wins), then the defaults `jev-latest` and `0.8`. A rule
 in `rules` replaces a preset rule with the same id. A rule's own `threshold`
 beats all of the above for that rule.
 
@@ -281,10 +325,12 @@ beats all of the above for that rule.
 
 1. One Jev request per file. The state is the file's numbered lines and
    nothing else. Each rule is one `noul` (yes/no probability) question that
-   carries the rule's description, reference, and code to avoid: whether the
-   file diverges from the reference or, for a rule with only code to avoid,
-   whether it contains that code. Criteria for each answer draw the line at
-   the rule's scope, so a file with no code the rule is about is a no. Since
+   carries the rule's description and its code under its words, `must` and
+   `never` (or a guideline's `should` and `should_not`): whether the file
+   diverges from the pattern `must` shows, with `never` as an example of
+   diverging, or, for a rule with only code that must never be written,
+   whether the file contains that code. Criteria for each answer draw the line
+   at the rule's scope, so a file with no code the rule is about is a no. Since
    no rule sits in the shared state, a rule's probability depends only on the
    file and that rule, not on which other rules share the request. Every
    question shares the state cost of the request.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "private": false,
-  "description": "Lints a repository against reference code in .adhere/, judged by Jev.",
+  "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/darkmatter/adhere.git"
@@ -67,10 +67,10 @@
     }
   },
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.6.1",
-    "@drkmttr/adhere-darwin-x64": "0.6.1",
-    "@drkmttr/adhere-linux-arm64": "0.6.1",
-    "@drkmttr/adhere-linux-x64": "0.6.1",
-    "@drkmttr/adhere-win32-x64": "0.6.1"
+    "@drkmttr/adhere-darwin-arm64": "0.7.1",
+    "@drkmttr/adhere-darwin-x64": "0.7.1",
+    "@drkmttr/adhere-linux-arm64": "0.7.1",
+    "@drkmttr/adhere-linux-x64": "0.7.1",
+    "@drkmttr/adhere-win32-x64": "0.7.1"
   }
 }

package/presets/effect/basics/external-calls-are-resilient.md

@@ -1,8 +1,8 @@
 ---
-description: A call over the network, such as an HTTP request, a database query, or a third-party API, carries a timeout and a retry schedule. Calls through the platform FileSystem and Path services are local and are not in scope.
+description: A call over the network, such as an HTTP request, a database query, or a third-party API, must carry a timeout and a retry schedule. Calls through the platform FileSystem and Path services are local and are not in scope.
 ---
 
-```ts
+```ts must
 const retryPolicy = Schedule.exponential("100 millis").pipe(Schedule.both(Schedule.recurs(3)));
 
 const resilientCall = HttpClient.get("https://api.example.com/users").pipe(
@@ -11,3 +11,7 @@ const resilientCall = HttpClient.get("https://api.example.com/users").pipe(
   Effect.timeout("10 seconds"),
 );
 ```
+
+```ts never
+const response = yield* HttpClient.get(`https://api.example.com/users/${id}`);
+```

package/presets/effect/basics/fn-for-named-effects.md

@@ -1,11 +1,19 @@
 ---
-description: A named function that returns an Effect should be defined with Effect.fn so the call site is traced.
+description: A named function that returns an Effect must be defined with Effect.fn so the call site is traced. An Effect held in a constant, such as `const program = Effect.gen(...)`, is not a function and is not in scope.
 ---
 
-```ts
+```ts must
 const processUser = Effect.fn("processUser")(function* (userId: string) {
   yield* Effect.logInfo(`Processing user ${userId}`);
   const user = yield* getUser(userId);
   return yield* processData(user);
 });
 ```
+
+```ts never
+const loadUser = (id: string) =>
+  Effect.gen(function* () {
+    const repo = yield* UserRepo;
+    return yield* repo.find(id);
+  });
+```

package/presets/effect/basics/gen-for-sequencing.md

@@ -1,11 +1,19 @@
 ---
-description: Sequential effectful steps should be written with Effect.gen and yield*, not nested flatMap or callback chains.
+description: Sequential effectful steps must be written with Effect.gen and yield*, never as nested flatMap or callback chains.
 ---
 
-```ts
+```ts must
 const program = Effect.gen(function* () {
   const data = yield* fetchData;
   yield* Effect.logInfo(`Processing data: ${data}`);
   return yield* processData(data);
 });
 ```
+
+```ts never
+const page = fetchUser(id).pipe(
+  Effect.flatMap((user) =>
+    fetchOrders(user.id).pipe(Effect.flatMap((orders) => render(user, orders))),
+  ),
+);
+```

package/presets/effect/basics/instrument-with-pipe.md

@@ -1,8 +1,8 @@
 ---
-description: Timeouts, retries, logging, and spans should be attached with .pipe, not written into the body of the effect.
+description: Timeouts, retries, logging, and spans must be attached with .pipe, never written into the body of the effect.
 ---
 
-```ts
+```ts must
 const program = fetchData.pipe(
   Effect.timeout("5 seconds"),
   Effect.retry(Schedule.exponential("100 millis").pipe(Schedule.both(Schedule.recurs(3)))),
@@ -10,3 +10,10 @@ const program = fetchData.pipe(
   Effect.withSpan("fetchData"),
 );
 ```
+
+```ts never
+const report = Effect.gen(function* () {
+  const rows = yield* Effect.timeout(loadRows, "5 seconds");
+  return yield* Effect.withSpan(summarize(rows), "summarize");
+});
+```

package/presets/effect/cli/handlers-delegate.md

@@ -1,8 +1,8 @@
 ---
-description: A command handler parses input and calls a service. Business logic lives in the service.
+description: A command handler must only parse input and call a service. Business logic must live in the service, never in the handler.
 ---
 
-```ts
+```ts must
 const addCommand = Command.make("add", { text }, ({ text }) =>
   Effect.gen(function* () {
     const repo = yield* TaskRepo;
@@ -11,3 +11,14 @@ const addCommand = Command.make("add", { text }, ({ text }) =>
   }),
 ).pipe(Command.withDescription("Add a new task"));
 ```
+
+```ts never
+Command.make("rename", { from, to }, ({ from, to }) =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const text = yield* fs.readFileString(from);
+    yield* fs.writeFileString(to, text.replaceAll("draft", "final"));
+    yield* fs.remove(from);
+  }),
+);
+```

package/presets/effect/config/business-logic-depends-on-config-service.md

@@ -1,8 +1,8 @@
 ---
-description: Business logic depends on a config service. Config primitives should be read only inside that service's layer.
+description: Business logic must depend on a config service. Config primitives must be read only inside that service's layer, never in business logic.
 ---
 
-```ts
+```ts must
 class ApiConfig extends Context.Service<
   ApiConfig,
   {
@@ -20,3 +20,10 @@ class ApiConfig extends Context.Service<
   );
 }
 ```
+
+```ts never
+const sendInvoice = Effect.fn("sendInvoice")(function* (invoice: Invoice) {
+  const apiUrl = yield* Config.string("BILLING_API_URL");
+  return yield* post(apiUrl, invoice);
+});
+```

package/presets/effect/config/secrets-are-redacted.md

@@ -1,8 +1,8 @@
 ---
-description: A token, password, or key should be read with Config.redacted.
+description: A token, password, or key must be read with Config.redacted, never with Config.string.
 ---
 
-```ts
+```ts must
 const program = Effect.gen(function* () {
   const apiKey = yield* Config.redacted("API_KEY");
 
@@ -13,3 +13,7 @@ const program = Effect.gen(function* () {
   return headers;
 });
 ```
+
+```ts never
+const token = yield* Config.string("GITHUB_TOKEN");
+```

package/presets/effect/config/tests-provide-values-directly.md

@@ -1,8 +1,8 @@
 ---
-description: A test supplies config with Layer.succeed on the config service, not by setting environment variables or a ConfigProvider.
+description: A test must supply config with Layer.succeed on the config service, never by setting environment variables or a ConfigProvider.
 ---
 
-```ts
+```ts must
 Effect.runPromise(
   program.pipe(
     Effect.provide(
@@ -14,3 +14,9 @@ Effect.runPromise(
   ),
 );
 ```
+
+```ts never
+beforeAll(() => {
+  process.env.DATABASE_URL = "postgres://localhost/test";
+});
+```

package/presets/effect/config/validate-with-schema.md

@@ -1,8 +1,8 @@
 ---
-description: A config value with constraints should be read with Config.schema, not mapped and checked by hand.
+description: A config value with constraints must be read with Config.schema, never mapped and checked by hand.
 ---
 
-```ts
+```ts must
 const Port = Schema.NumberFromString.pipe(
   Schema.check(Schema.isInt()),
   Schema.check(Schema.isBetween({ minimum: 1, maximum: 65535 })),
@@ -16,3 +16,10 @@ const program = Effect.gen(function* () {
   return { port, env };
 });
 ```
+
+```ts never
+const timeoutMs = yield* Config.number("TIMEOUT_MS");
+if (timeoutMs <= 0 || timeoutMs > 60_000) {
+  return yield* Effect.die("TIMEOUT_MS out of range");
+}
+```

package/presets/effect/data/brand-meaningful-primitives.md

@@ -1,8 +1,8 @@
 ---
-description: A primitive with semantic meaning, such as an id, email, URL, port, or count, should be a branded schema.
+description: A primitive with semantic meaning, such as an id, email, URL, port, or count, must be a branded schema, never a bare string or number.
 ---
 
-```ts
+```ts must
 export const UserId = Schema.String.pipe(Schema.brand("UserId"));
 export type UserId = typeof UserId.Type;
 
@@ -15,3 +15,12 @@ export const Port = Schema.Int.pipe(
 );
 export type Port = typeof Port.Type;
 ```
+
+```ts never
+type AccountId = string;
+
+const Session = Schema.Struct({
+  accountId: Schema.String,
+  retries: Schema.Number,
+});
+```

package/presets/effect/data/decode-json-with-schema.md

@@ -1,8 +1,8 @@
 ---
-description: JSON crossing a boundary should be decoded with Schema.fromJsonString, not JSON.parse followed by a cast.
+description: JSON crossing a boundary must be decoded with Schema.fromJsonString, never with JSON.parse followed by a cast.
 ---
 
-```ts
+```ts must
 const MoveFromJson = Schema.fromJsonString(Move);
 
 const program = Effect.gen(function* () {
@@ -12,3 +12,7 @@ const program = Effect.gen(function* () {
   return json;
 });
 ```
+
+```ts never
+const settings = JSON.parse(text) as Settings;
+```

package/presets/effect/data/records-are-schema-classes.md

@@ -1,8 +1,8 @@
 ---
-description: Domain records should be defined with Schema.Class, not with a plain interface or type alias.
+description: Domain records must be defined with Schema.Class, never with a plain interface or type alias.
 ---
 
-```ts
+```ts must
 export class User extends Schema.Class<User>("User")({
   id: UserId,
   name: Schema.String,
@@ -14,3 +14,10 @@ export class User extends Schema.Class<User>("User")({
   }
 }
 ```
+
+```ts never
+interface Invoice {
+  readonly id: InvoiceId;
+  readonly total: Money;
+}
+```

package/presets/effect/data/variants-are-tagged-unions.md

@@ -1,8 +1,8 @@
 ---
-description: Structured variants should be Schema.TaggedClass in a Schema.Union and matched with Match.tag and Match.exhaustive.
+description: Structured variants must be Schema.TaggedClass in a Schema.Union, matched with Match.tag and Match.exhaustive, never a plain union checked with a switch.
 ---
 
-```ts
+```ts must
 export class Success extends Schema.TaggedClass<Success>("Success")("Success", {
   value: Schema.Number,
 }) {}
@@ -21,3 +21,10 @@ const renderResult = (result: Result) =>
     Match.exhaustive,
   );
 ```
+
+```ts never
+type Shape = { kind: "circle"; radius: number } | { kind: "square"; side: number };
+
+const area = (shape: Shape) =>
+  shape.kind === "circle" ? Math.PI * shape.radius ** 2 : shape.side ** 2;
+```

package/presets/effect/errors/catch-defects-at-boundaries-only.md

@@ -1,11 +1,15 @@
 ---
-description: Defects should be caught only at a system boundary for logging or shutdown, never in business logic.
+description: Defects must be caught only at a system boundary for logging or shutdown, never in business logic.
 ---
 
-```ts
+```ts must
 // At app entry: if config fails, nothing can proceed
 const main = Effect.gen(function* () {
   const config = yield* loadConfig.pipe(Effect.orDie);
   yield* Effect.log(`Starting on port ${config.port}`);
 });
 ```
+
+```ts never
+const price = computePrice(cart).pipe(Effect.catchDefect(() => Effect.succeed(0)));
+```

package/presets/effect/errors/defects-for-bugs.md

@@ -1,8 +1,8 @@
 ---
-description: A typed error should be for a failure the caller can handle. A bug or invariant violation should be a defect.
+description: A typed error must be for a failure the caller can handle. A bug or invariant violation must be a defect, never a typed error.
 ---
 
-```ts
+```ts must
 const recovered: Effect.Effect<string, ValidationError> = program.pipe(
   Effect.catchTag("HttpError", (error) =>
     Effect.gen(function* () {
@@ -17,3 +17,14 @@ const main = Effect.gen(function* () {
   yield* Effect.log(`Starting on port ${config.port}`);
 });
 ```
+
+```ts never
+class CacheCorrupted extends Schema.TaggedError<CacheCorrupted>()("CacheCorrupted", {
+  key: Schema.String,
+}) {}
+
+const entry = yield* cache.get(key);
+if (entry !== undefined && entry.key !== key) {
+  return yield* new CacheCorrupted({ key });
+}
+```

package/presets/effect/errors/domain-errors-are-tagged.md

@@ -1,8 +1,8 @@
 ---
-description: A domain failure should be a Schema.TaggedError with its own tag.
+description: A domain failure must be a Schema.TaggedError with its own tag, never a bare Error or a plain object.
 ---
 
-```ts
+```ts must
 class ValidationError extends Schema.TaggedError<ValidationError>()("ValidationError", {
   field: Schema.String,
   message: Schema.String,
@@ -13,3 +13,7 @@ class NotFoundError extends Schema.TaggedError<NotFoundError>()("NotFoundError",
   id: Schema.String,
 }) {}
 ```
+
+```ts never
+return yield* Effect.fail(new Error("Card declined"));
+```

package/presets/effect/errors/wrap-external-errors.md

@@ -1,8 +1,8 @@
 ---
-description: An error from an external library should be wrapped in a tagged error with a Schema.Defect field, not passed through raw.
+description: An error from an external library must be wrapped in a tagged error with a Schema.Defect field, never passed through raw.
 ---
 
-```ts
+```ts must
 class ApiError extends Schema.TaggedError<ApiError>()("ApiError", {
   endpoint: Schema.String,
   statusCode: Schema.Number,
@@ -22,3 +22,8 @@ const fetchUser = (id: string) =>
     ),
   );
 ```
+
+```ts never
+const charge = (amount: number) =>
+  Effect.tryPromise(() => stripe.charges.create({ amount, currency: "usd" }));
+```

package/presets/effect/platform/os-access-through-platform-services.md

@@ -1,8 +1,8 @@
 ---
-description: File, path, process, terminal, and HTTP access goes through Effect's platform services (FileSystem, Path, ChildProcess, Terminal, HttpClient, KeyValueStore), acquired with yield*, not through node: builtins, Bun globals, or fetch. The Bun implementations should be provided once at the entry point with BunServices.layer.
+description: File, path, process, terminal, and HTTP access must go through Effect's platform services (FileSystem, Path, ChildProcess, Terminal, HttpClient, KeyValueStore), acquired with yield*, never through node: builtins, Bun globals, or fetch. The Bun implementations must be provided once at the entry point with BunServices.layer.
 ---
 
-```ts
+```ts must
 import { Effect, FileSystem, Path } from "effect";
 import { HttpClient, HttpClientResponse } from "effect/unstable/http";
 import { BunRuntime, BunServices } from "@effect/platform-bun";
@@ -18,3 +18,9 @@ const program = Effect.gen(function* () {
 
 program.pipe(Effect.provide(BunServices.layer), BunRuntime.runMain);
 ```
+
+```ts never
+import { readFileSync } from "node:fs";
+
+const settings = readFileSync("settings.json", "utf8");
+```

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* () { /* ... */ }));
+});
+```