@drkmttr/adhere 0.14.0 → 0.15.0

package/README.md

@@ -764,7 +764,7 @@ type UserId = typeof UserId.Type
 | [`typescript`](./presets/typescript/) | 11    | any TypeScript project                                | Data from outside checked at runtime, invalid states unrepresentable, errors never swallowed, resources released on every path, arguments not mutated, and tests that assert outcomes and stand alone.                                                                                          |
 | [`react`](./presets/react/)           | 10    | components and hooks                                  | Logic for an event in its handler rather than an effect, effects that clean up and ignore stale fetches, `useSyncExternalStore` for outside stores, state that neither copies props nor contradicts itself, and Server Functions and Server Components that guard what crosses to the client.   |
 | [`security`](./presets/security/)     | 4     | any project                                           | Secrets kept out of logs, error messages, and responses; parameterized SQL; no untrusted input in shell commands, `eval`, or file paths; and secrets compared in constant time. From OWASP's cheat sheets.                                                                                      |
-| [`effect`](./presets/effect/)         | 18    | code written with Effect                              | Steps sequenced with `Effect.gen`, instrumentation attached with `.pipe`, config read through a service and validated, secrets redacted, branded primitives and tagged unions, defects kept apart from typed errors, services built by layers, and tests with their own layers and `TestClock`. |
+| [`effect`](./presets/effect/)         | 16    | code written with Effect                              | Steps sequenced with `Effect.gen`, instrumentation attached with `.pipe`, config read through a service and validated, secrets redacted, branded primitives and tagged unions, defects kept apart from typed errors, services built by layers, and tests with their own layers and `TestClock`. |
 | [`alchemy`](./presets/alchemy/)       | 41    | code that deploys with [alchemy](https://alchemy.run) | Where Config and bindings are read, which resources keep their data, how secrets stay out of bundles and logs, authorization on public URLs, migrations, durable workflows, and custom providers.                                                                                               |
 
 - Name presets in the config's `presets`, or on the command line with
@@ -850,16 +850,21 @@ type UserId = typeof UserId.Type
   [effect-solutions](https://github.com/kitlangton/effect-solutions) docs and
   the [effect/platform](https://effect.website/docs/platform/introduction/)
   docs.
-- **Tests.** Four rules say `tests: only`, so they judge tests and nothing else:
-  `testing/test-clock-for-time`, `services/fresh-layer-per-test`,
-  `services/test-layers-are-in-memory`, and
+- **Tests.** Three rules say `tests: only`, so they judge tests and nothing else:
+  `testing/test-clock-for-time`, `services/fresh-layer-per-test`, and
   `config/tests-provide-values-directly`.
-- **Guidelines.** Two rules say "should": test layers are in memory, outside
-  integration tests, and tests provide config through a layer.
+- **Guidelines.** One rule says "should": a test of code that consumes config
+  provides it through a layer.
+- **Domain types.** The data rules judge the types services exchange, return,
+  or store. A shape that mirrors a payload until it is mapped, and a view's
+  props or state, are out of their scope.
 - **What the rules allow.** Config validation accepts `Config.mapEffect` as well
   as `Config.schema`, and the variants rule does not rule out a `switch`.
 - **Gone.** The rule that a command handler only parses input: the docs show
-  that pattern but do not ask for it.
+  that pattern but do not ask for it. The rule that test layers are in memory,
+  which flagged tests of real services: none of its findings labeled on the eval
+  or on darkmatter/agents was real. And the rule that service operations have no
+  requirements, which `leakingRequirements` below checks exactly.
 - **Left to a linter.** Effect's language service,
   [`@effect/tsgo`](https://github.com/Effect-TS/tsgo) on TypeScript 7, checks
   seven conventions exactly, which the preset checked through 0.7. Most are off
@@ -891,8 +896,7 @@ type UserId = typeof UserId.Type
 - **What the linter misses.** `leakingRequirements` sees a requirement in an
   operation's type, but not a service built by a factory function that takes its
   dependencies as arguments, whose types have no requirements to find. The
-  preset's `services/dependencies-through-layers` asks for that, and
-  `services/operations-have-no-requirements` for the style it goes with.
+  preset's `services/dependencies-through-layers` asks for that.
 
 </details>
 
@@ -1300,14 +1304,15 @@ about three bytes a token.
 
 Names and layouts from older versions:
 
-| Version           | What it had                                                                                      | What happens now                                                                                                                                                                                        |
-| ----------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| before 0.7        | A rule's examples were `reference` and `avoid` in a config, and a fence could be tagged `avoid`. | They still read as `must` and `never`.                                                                                                                                                                  |
-| through 0.7       | The `effect` preset checked seven conventions a linter checks exactly.                           | They are left to `@effect/tsgo`. The notes on `effect` under [Presets](#presets) say how to turn them on.                                                                                               |
-| before 0.13       | A rule was any `*.md` file in `.adhere/`, as `.adhere/data/brand-ports.md`.                      | A `*.md` file outside every rule's directory, but a `README.md`, refuses the run. The refusal says where each such file goes to keep its id, so `adhere-ignore` comments and `overrides` still name it. |
-| before 0.13       | `.adhere/tsconfig.json` included only `config.ts`.                                               | Make its `include` `["**/*.ts"]` to give rules written in TypeScript their types.                                                                                                                       |
-| 0.13.1            | The workspace's packages had a key of their own, `includeWorkspacePackages: true`.               | adhere no longer reads it, and a rule that still has it gets no packages. Write `reads: ["workspacePackages"]` in its place.                                                                            |
-| 0.13.1 and before | Prose around a `RULE.md`'s code was ignored.                                                     | Jev reads it after the description, as the rule's details, so a rule with prose is judged again once. Keep prose about the rule: why it holds, or where it does not apply.                              |
+| Version           | What it had                                                                                                  | What happens now                                                                                                                                                                                        |
+| ----------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| before 0.7        | A rule's examples were `reference` and `avoid` in a config, and a fence could be tagged `avoid`.             | They still read as `must` and `never`.                                                                                                                                                                  |
+| through 0.7       | The `effect` preset checked seven conventions a linter checks exactly.                                       | They are left to `@effect/tsgo`. The notes on `effect` under [Presets](#presets) say how to turn them on.                                                                                               |
+| before 0.13       | A rule was any `*.md` file in `.adhere/`, as `.adhere/data/brand-ports.md`.                                  | A `*.md` file outside every rule's directory, but a `README.md`, refuses the run. The refusal says where each such file goes to keep its id, so `adhere-ignore` comments and `overrides` still name it. |
+| before 0.13       | `.adhere/tsconfig.json` included only `config.ts`.                                                           | Make its `include` `["**/*.ts"]` to give rules written in TypeScript their types.                                                                                                                       |
+| 0.13.1            | The workspace's packages had a key of their own, `includeWorkspacePackages: true`.                           | adhere no longer reads it, and a rule that still has it gets no packages. Write `reads: ["workspacePackages"]` in its place.                                                                            |
+| 0.13.1 and before | Prose around a `RULE.md`'s code was ignored.                                                                 | Jev reads it after the description, as the rule's details, so a rule with prose is judged again once. Keep prose about the rule: why it holds, or where it does not apply.                              |
+| 0.14.0 and before | The `effect` preset had `services/test-layers-are-in-memory` and `services/operations-have-no-requirements`. | They are gone, and an `overrides` entry naming either refuses the run: remove it. `@effect/tsgo`'s `leakingRequirements` checks the second. `adhere-ignore` comments naming them suppress nothing.      |
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "private": false,
   "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
   "license": "MIT",
@@ -68,10 +68,10 @@
     }
   },
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.14.0",
-    "@drkmttr/adhere-darwin-x64": "0.14.0",
-    "@drkmttr/adhere-linux-arm64": "0.14.0",
-    "@drkmttr/adhere-linux-x64": "0.14.0",
-    "@drkmttr/adhere-win32-x64": "0.14.0"
+    "@drkmttr/adhere-darwin-arm64": "0.15.0",
+    "@drkmttr/adhere-darwin-x64": "0.15.0",
+    "@drkmttr/adhere-linux-arm64": "0.15.0",
+    "@drkmttr/adhere-linux-x64": "0.15.0",
+    "@drkmttr/adhere-win32-x64": "0.15.0"
   }
 }

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

@@ -1,8 +1,19 @@
 ---
-description: A test should supply config with Layer.succeed on the config service, and should not set environment variables or a ConfigProvider to do it.
+description: A test of code that consumes configuration should supply it with Layer.succeed on the config service, and should not set environment variables or a ConfigProvider to do it.
 tests: only
 ---
 
+Code that reads its settings from the environment in a test reads them from
+the environment in production too, so a test that sets them hides that the
+code skips the config service.
+
+A test whose subject is how configuration is read, such as its decoding,
+defaults, precedence, or fallback to the environment, has to supply raw
+inputs and is out of scope. So are values a test plants to check that they
+never leak, and the bindings of a separately deployed Worker. A test or
+fixture that sets the environment so the code under test reads its settings
+from there is in scope, even in a file that also tests a loader.
+
 ## Should
 
 ```ts

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

@@ -1,7 +1,19 @@
 ---
-description: A primitive with semantic meaning, such as an id, email, URL, port, or count, must be declared as a branded schema, never as a bare string or number. The rule judges where a type is declared, such as a schema field, an interface, or a type alias; a literal value, local variable, or parameter whose type is declared elsewhere is out of scope.
+description: A primitive with semantic meaning in a domain type, such as an id, email, URL, or port in a service's contract, an event, or a stored record, must be declared as a branded schema, never as a bare string or number.
 ---
 
+Two ids of different things are both strings, so nothing stops one being
+passed where the other belongs. A brand makes that mix-up a type error where
+the value crosses from one module to another.
+
+The rule judges where a domain type is declared: a schema field, interface, or
+type alias for what services exchange, return, or store. A shape that mirrors
+an external payload or a table row until it is mapped, a view's props or view
+model, and a literal, local variable, or parameter whose type is declared
+elsewhere are not domain types. A type the code's own modules pass between
+them, such as a reference to a thread, an issue, or a delivery, is a domain
+type even in a file that also mirrors a payload.
+
 ## Must
 
 ```ts
@@ -25,6 +37,6 @@ type AccountId = string;
 
 const Session = Schema.Struct({
   accountId: Schema.String,
-  retries: Schema.Number,
+  email: Schema.String,
 });
 ```

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

@@ -1,7 +1,19 @@
 ---
-description: Structured variants, alternatives that carry fields, must be Schema.TaggedClass members of a Schema.Union, never hand-written object types joined by a tag field. Simple alternatives without fields may be Schema.Literals. The rule judges declared union types and schemas; an object literal with a tag field is out of scope, and so is a type that mirrors a third-party format whose tag key that format fixes, such as the type of a Slack Block Kit block.
+description: Variants of a domain type, alternatives that carry fields and that a service returns, stores, or decodes, must be tagged schemas such as Schema.TaggedClass or Schema.TaggedStruct members of a Schema.Union, never TypeScript object types joined by a tag field.
 ---
 
+A tagged schema decodes each variant at the boundary and lets `Match.tag`
+check every case, where a hand-written union is neither validated nor checked
+for a case added later. Simple alternatives without fields may be
+Schema.Literals.
+
+The rule judges declared union types. A union used only inside one module,
+such as a view's state, a reducer's actions, or a function's own result, is
+not a domain type, and neither is a generic type, an object literal with a tag
+field, or a type that mirrors a third-party format whose tag key that format
+fixes, such as a Slack Block Kit block. A union that a service returns, or an
+event a module emits, is in scope even in a file that declares nothing else.
+
 ## Must
 
 ```ts
@@ -27,8 +39,9 @@ const renderResult = (result: Result) =>
 ## Never
 
 ```ts
-type Shape = { kind: "circle"; radius: number } | { kind: "square"; side: number };
+type Payment = { kind: "card"; last4: string } | { kind: "invoice"; dueDate: string };
 
-const area = (shape: Shape) =>
-  shape.kind === "circle" ? Math.PI * shape.radius ** 2 : shape.side ** 2;
+interface Payments {
+  readonly find: (id: PaymentId) => Effect.Effect<Payment, PaymentNotFound>;
+}
 ```

package/presets/effect/services/dependencies-through-layers/RULE.md

@@ -1,7 +1,17 @@
 ---
-description: A service that depends on other services must be a Context.Service built by a Layer that yields those services as it is constructed, never a factory function or class that takes services, clients, or their implementations as arguments and returns the service's operations with them built in. A helper that takes a client and one call's arguments and returns a single Effect is not a factory and is out of scope; the code that assembles the service from such helpers is in scope.
+description: A service that depends on other services must be a Context.Service built by a Layer that yields those services as it is constructed, never a function or class that takes other services' implementations as arguments and returns a service's implementation for its callers to wire by hand.
 ---
 
+A service wired by hand hides its dependencies from the types, so each caller
+builds them again, and a test cannot replace one with a layer.
+
+A function that the service's own Layer calls with the services it yielded is
+part of that Layer and is out of scope, and so is a decorator that takes a
+service and returns the same service. A boundary adapter that wraps a
+library's client, such as an SDK or a Promise API, takes no service and is out
+of scope. A function that builds a service from other services is in scope
+when code other than that service's Layer calls it.
+
 ## Must
 
 ```ts
@@ -31,8 +41,11 @@ export const UsersLive = Layer.effect(
 ## Never
 
 ```ts
-export const makeUsers = (database: Database["Service"], logger: Logger["Service"]) => ({
-  find: (id: UserId) =>
+export const makeUsers = (
+  database: Database["Service"],
+  logger: Logger["Service"],
+): Users["Service"] => ({
+  find: (id) =>
     Effect.gen(function* () {
       yield* logger.log(`finding ${id}`);
       return yield* database.findUser(id);

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

@@ -1,7 +1,13 @@
 ---
-description: A service must expose only readonly members, never mutable state.
+description: The interface a Context.Service exposes must hold only readonly members, never writable fields or mutable state, such as a Map, Set, or array, that its consumers could change, even through a readonly property.
 ---
 
+State the service's implementation keeps behind its operations is not part of
+its interface, and neither are a fixture's controls kept beside the service it
+provides. A plain interface that no Context.Service declares, such as a
+helper's registry or a connection's data, is out of scope. A Context.Service's
+interface is in scope however its file declares it.
+
 ## Must
 
 ```ts

package/presets/effect/services/operations-have-no-requirements/RULE.md

@@ -1,50 +0,0 @@
----
-description: A service's operations must have no requirements, typed Effect<A, E, never>, with their dependencies acquired when the service's Layer is built, never left in an operation's requirements type, as in Effect<A, E, Database>.
----
-
-## Must
-
-```ts
-class Users extends Context.Service<
-  Users,
-  {
-    readonly find: (id: UserId) => Effect.Effect<User, UserNotFound, never>;
-  }
->()("@app/Users") {}
-
-export const UsersLive = Layer.effect(
-  Users,
-  Effect.gen(function* () {
-    const database = yield* Database;
-    const logger = yield* Logger;
-    return Users.of({
-      find: (id) =>
-        Effect.gen(function* () {
-          yield* logger.log(`finding ${id}`);
-          return yield* database.findUser(id);
-        }),
-    });
-  }),
-);
-```
-
-## Never
-
-```ts
-class Users extends Context.Service<
-  Users,
-  {
-    readonly find: (id: UserId) => Effect.Effect<User, UserNotFound, Database | Logger>;
-  }
->()("@app/Users") {}
-
-export const UsersLive = Layer.succeed(Users, {
-  find: (id) =>
-    Effect.gen(function* () {
-      const database = yield* Database;
-      const logger = yield* Logger;
-      yield* logger.log(`finding ${id}`);
-      return yield* database.findUser(id);
-    }),
-});
-```

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

@@ -1,29 +0,0 @@
----
-description: A test implementation of a service should be built with Layer.sync or Layer.succeed over in-memory state, and should not reach a real database, network, or file. Integration tests that exercise the real service are not in scope.
-tests: only
----
-
-## Should
-
-```ts
-static readonly testLayer = Layer.sync(Cache, () => {
-  const store = new Map<string, string>()
-
-  const get = (key: string) => Effect.succeed(store.get(key) ?? null)
-  const set = (key: string, value: string) => Effect.sync(() => void store.set(key, value))
-
-  return { get, set }
-})
-```
-
-## Should not
-
-```ts
-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 })));
-```