@drkmttr/adhere 0.9.5 → 0.10.0

package/presets/alchemy/security/github-secret-not-variable.md

@@ -2,11 +2,15 @@
 description: A sensitive CI value, such as a token, key, password, or connection string, must be stored with GitHub.Secret, never with GitHub.Variable, which is plain text and visible in logs.
 ---
 
-```ts must
+## Must
+
+```ts
 yield* GitHub.Secret("CloudflareToken", { owner, repository, name: "CLOUDFLARE_API_TOKEN", value: token.value });
 yield* GitHub.Variable("AwsRegion", { owner, repository, name: "AWS_REGION", value: "us-east-1" });
 ```
 
-```ts never
+## Never
+
+```ts
 yield* GitHub.Variables({ owner, repository, variables: { CLOUDFLARE_API_TOKEN: token.value } });
 ```

package/presets/alchemy/security/identity-from-verified-session.md

@@ -2,13 +2,17 @@
 description: The acting user must come from the session or token verified in that request, never from an ID in the request body, query, or headers, and never from a user cached in a process-wide layer.
 ---
 
-```ts must
+## Must
+
+```ts
 const session = yield* auth.getSession();
 if (session === null) return yield* Effect.fail(new Unauthorized());
 const rows = yield* sql`SELECT * FROM uploads WHERE owner_id = ${session.user.id}`;
 ```
 
-```ts never
+## Never
+
+```ts
 const { ownerId } = yield* HttpServerRequest.schemaBodyJson(Schema.Struct({ ownerId: Schema.String }));
 const rows = yield* sql`SELECT * FROM uploads WHERE owner_id = ${ownerId}`;
 ```

package/presets/alchemy/security/keep-auth-protections-on.md

@@ -2,7 +2,9 @@
 description: Auth configuration must keep state, PKCE, origin and CSRF checks, ID-token verification, and email verification enabled, never disable them or merge accounts by email alone to work around an error or a cross-origin setup.
 ---
 
-```ts must
+## Must
+
+```ts
 const auth = yield* BetterAuth({
   trustedOrigins: [siteOrigin],
   emailAndPassword: { enabled: true, requireEmailVerification: true },
@@ -10,7 +12,9 @@ const auth = yield* BetterAuth({
 });
 ```
 
-```ts never
+## Never
+
+```ts
 const auth = yield* BetterAuth({
   trustedOrigins: ["*"],
   advanced: { disableCSRFCheck: true },

package/presets/alchemy/security/least-privilege-bindings.md

@@ -2,12 +2,16 @@
 description: A runtime should bind the narrowest capability its calls need, a Read or Write binding when it only reads or only writes, and should not bind ReadWrite for one-sided use.
 ---
 
-```ts should
+## Should
+
+```ts
 const bucket = yield* Cloudflare.R2.ReadBucket(Uploads);
 return { fetch: Effect.gen(function* () { return yield* bucket.get("report.json"); }) };
 ```
 
-```ts should not
+## Should not
+
+```ts
 const bucket = yield* Cloudflare.R2.ReadWriteBucket(Uploads); // only get is ever called
 return { fetch: Effect.gen(function* () { return yield* bucket.get("report.json"); }) };
 ```

package/presets/alchemy/security/least-privilege-ci-credentials.md

@@ -2,7 +2,9 @@
 description: Credentials a stack mints for CI should be scoped to what the app deploys, using a GitHub OIDC role pinned to the repository on AWS and a trimmed permission list on Cloudflare, and should not grant AdministratorAccess or unused write scopes.
 ---
 
-```ts should
+## Should
+
+```ts
 const role = yield* AWS.IAM.Role("GitHubDeploy", {
   assumeRolePolicyDocument: { Version: "2012-10-17", Statement: [{
     Effect: "Allow", Principal: { Federated: oidc.openIDConnectProviderArn },
@@ -13,7 +15,9 @@ const role = yield* AWS.IAM.Role("GitHubDeploy", {
 });
 ```
 
-```ts should not
+## Should not
+
+```ts
 const role = yield* AWS.IAM.Role("GitHubDeploy", {
   assumeRolePolicyDocument: { Version: "2012-10-17", Statement: [{
     Effect: "Allow", Principal: { Federated: oidc.openIDConnectProviderArn },

package/presets/alchemy/security/lookup-failure-is-not-anonymous.md

@@ -2,14 +2,18 @@
 description: Only a null session may be treated as anonymous; a failed session lookup must stay in the error channel or map to a server error, never be collapsed into signed out.
 ---
 
-```ts must
+## Must
+
+```ts
 const session = yield* auth.getSession().pipe(
   Effect.mapError(() => new AuthenticationUnavailable()),
 );
 if (session === null) return yield* Effect.fail(new Unauthorized());
 ```
 
-```ts never
+## Never
+
+```ts
 const session = yield* auth.getSession().pipe(Effect.orElseSucceed(() => null));
 if (session === null) return yield* Effect.fail(new Unauthorized());
 ```

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

@@ -2,7 +2,9 @@
 description: A call over the network, such as an HTTP request, a database query, or a third-party API, should carry a timeout and a retry schedule, and should not go out bare. A call through a client that already applies both, such as an HttpClient built with a timeout and retryTransient or an SDK with its own retries, has them. Calls through the platform FileSystem and Path services are local and are not in scope.
 ---
 
-```ts should
+## Should
+
+```ts
 const retryPolicy = Schedule.exponential("100 millis").pipe(Schedule.both(Schedule.recurs(3)));
 
 const resilientCall = HttpClient.get("https://api.example.com/users").pipe(
@@ -12,6 +14,8 @@ const resilientCall = HttpClient.get("https://api.example.com/users").pipe(
 );
 ```
 
-```ts should not
+## Should not
+
+```ts
 const response = yield* HttpClient.get(`https://api.example.com/users/${id}`);
 ```

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

@@ -2,7 +2,9 @@
 description: Sequential effectful steps must be written with Effect.gen and yield*, never as nested flatMap or callback chains.
 ---
 
-```ts must
+## Must
+
+```ts
 const program = Effect.gen(function* () {
   const data = yield* fetchData;
   yield* Effect.logInfo(`Processing data: ${data}`);
@@ -10,7 +12,9 @@ const program = Effect.gen(function* () {
 });
 ```
 
-```ts never
+## Never
+
+```ts
 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

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

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

@@ -2,7 +2,9 @@
 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 must
+## Must
+
+```ts
 class ApiConfig extends Context.Service<
   ApiConfig,
   {
@@ -21,7 +23,9 @@ class ApiConfig extends Context.Service<
 }
 ```
 
-```ts never
+## Never
+
+```ts
 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

@@ -2,7 +2,9 @@
 description: A token, password, or key must be read with Config.redacted, never with Config.string.
 ---
 
-```ts must
+## Must
+
+```ts
 const program = Effect.gen(function* () {
   const apiKey = yield* Config.redacted("API_KEY");
 
@@ -14,6 +16,8 @@ const program = Effect.gen(function* () {
 });
 ```
 
-```ts never
+## Never
+
+```ts
 const token = yield* Config.string("GITHUB_TOKEN");
 ```

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

@@ -1,8 +1,11 @@
 ---
 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.
+tests: only
 ---
 
-```ts should
+## Should
+
+```ts
 Effect.runPromise(
   program.pipe(
     Effect.provide(
@@ -15,7 +18,9 @@ Effect.runPromise(
 );
 ```
 
-```ts should not
+## Should not
+
+```ts
 beforeAll(() => {
   process.env.DATABASE_URL = "postgres://localhost/test";
 });

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

@@ -2,7 +2,9 @@
 description: A config value with constraints must be validated as it is read, with Config.schema or Config.mapOrFail, never checked by hand after reading.
 ---
 
-```ts must
+## Must
+
+```ts
 const Port = Schema.NumberFromString.pipe(
   Schema.check(Schema.isInt()),
   Schema.check(Schema.isBetween({ minimum: 1, maximum: 65535 })),
@@ -28,7 +30,9 @@ const program = Effect.gen(function* () {
 });
 ```
 
-```ts never
+## Never
+
+```ts
 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

@@ -2,7 +2,9 @@
 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 must
+## Must
+
+```ts
 export const UserId = Schema.String.pipe(Schema.brand("UserId"));
 export type UserId = typeof UserId.Type;
 
@@ -16,7 +18,9 @@ export const Port = Schema.Int.pipe(
 export type Port = typeof Port.Type;
 ```
 
-```ts never
+## Never
+
+```ts
 type AccountId = string;
 
 const Session = Schema.Struct({

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

@@ -2,7 +2,9 @@
 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.
 ---
 
-```ts must
+## Must
+
+```ts
 export class Success extends Schema.TaggedClass<Success>("Success")("Success", {
   value: Schema.Number,
 }) {}
@@ -22,7 +24,9 @@ const renderResult = (result: Result) =>
   );
 ```
 
-```ts never
+## Never
+
+```ts
 type Shape = { kind: "circle"; radius: number } | { kind: "square"; side: number };
 
 const area = (shape: Shape) =>

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

@@ -2,7 +2,9 @@
 description: Defects must be caught only at a system boundary for logging or shutdown, never in business logic.
 ---
 
-```ts must
+## Must
+
+```ts
 // At app entry: if config fails, nothing can proceed
 const main = Effect.gen(function* () {
   const config = yield* loadConfig.pipe(Effect.orDie);
@@ -10,6 +12,8 @@ const main = Effect.gen(function* () {
 });
 ```
 
-```ts never
+## Never
+
+```ts
 const price = computePrice(cart).pipe(Effect.catchDefect(() => Effect.succeed(0)));
 ```

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

@@ -2,7 +2,9 @@
 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 must
+## Must
+
+```ts
 const recovered: Effect.Effect<string, ValidationError> = program.pipe(
   Effect.catchTag("HttpError", (error) =>
     Effect.gen(function* () {
@@ -18,7 +20,9 @@ const main = Effect.gen(function* () {
 });
 ```
 
-```ts never
+## Never
+
+```ts
 class CacheCorrupted extends Schema.TaggedError<CacheCorrupted>()("CacheCorrupted", {
   key: Schema.String,
 }) {}

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

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

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

@@ -2,7 +2,9 @@
 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.
 ---
 
-```ts must
+## Must
+
+```ts
 class Users extends Context.Service<
   Users,
   {
@@ -26,7 +28,9 @@ export const UsersLive = Layer.effect(
 );
 ```
 
-```ts never
+## Never
+
+```ts
 export const makeUsers = (database: Database["Service"], logger: Logger["Service"]) => ({
   find: (id: UserId) =>
     Effect.gen(function* () {

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

@@ -1,8 +1,11 @@
 ---
 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.
+tests: only
 ---
 
-```ts must
+## Must
+
+```ts
 it.effect("starts at zero", () =>
   Effect.gen(function* () {
     const counter = yield* Counter;
@@ -19,7 +22,9 @@ it.effect("increments without leaking", () =>
 );
 ```
 
-```ts never
+## Never
+
+```ts
 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

@@ -2,7 +2,9 @@
 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 must
+## Must
+
+```ts
 const postgresLayer = Postgres.layer({ url: "postgres://localhost/mydb", poolSize: 10 });
 
 const goodAppLayer = Layer.merge(
@@ -11,7 +13,9 @@ const goodAppLayer = Layer.merge(
 );
 ```
 
-```ts never
+## Never
+
+```ts
 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/no-mutable-state.md

@@ -2,7 +2,9 @@
 description: A service must expose only readonly members, never mutable state.
 ---
 
-```ts must
+## Must
+
+```ts
 class Logger extends Context.Service<
   Logger,
   {
@@ -11,7 +13,9 @@ class Logger extends Context.Service<
 >()("@app/Logger") {}
 ```
 
-```ts never
+## Never
+
+```ts
 class Counter extends Context.Service<
   Counter,
   { count: number; readonly increment: () => Effect.Effect<void> }

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

@@ -2,7 +2,9 @@
 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>.
 ---
 
-```ts must
+## Must
+
+```ts
 class Users extends Context.Service<
   Users,
   {
@@ -26,7 +28,9 @@ export const UsersLive = Layer.effect(
 );
 ```
 
-```ts never
+## Never
+
+```ts
 class Users extends Context.Service<
   Users,
   {

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

@@ -1,8 +1,11 @@
 ---
 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
 ---
 
-```ts should
+## Should
+
+```ts
 static readonly testLayer = Layer.sync(Cache, () => {
   const store = new Map<string, string>()
 
@@ -13,7 +16,9 @@ static readonly testLayer = Layer.sync(Cache, () => {
 })
 ```
 
-```ts should not
+## Should not
+
+```ts
 const EmailTest = Layer.effect(
   Email,
   Effect.gen(function* () {

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

@@ -1,8 +1,11 @@
 ---
 description: A test that depends on time must use TestClock, never a real sleep or it.live, unless the test needs real time.
+tests: only
 ---
 
-```ts must
+## Must
+
+```ts
 it.effect("time-based test", () =>
   Effect.gen(function* () {
     const fiber = yield* Effect.delay(Effect.succeed("done"), "10 seconds").pipe(Effect.forkChild);
@@ -13,7 +16,9 @@ it.effect("time-based test", () =>
 );
 ```
 
-```ts never
+## Never
+
+```ts
 it.live("retries after a delay", () =>
   Effect.gen(function* () {
     yield* Effect.sleep("2 seconds");

package/skills/adhere/SKILL.md

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