@drkmttr/adhere 0.9.5 → 0.11.0

package/presets/alchemy/runtime/resolve-config-and-bindings-at-construction.md

@@ -2,7 +2,9 @@
 description: In a Worker, Function, or Service, Config values and binding factories must be yielded in the outer construction Effect and captured for the handlers, never yielded for the first time inside fetch or another request handler, which does not run at deploy time, so nothing gets bound.
 ---
 
-```ts must
+## Must
+
+```ts
 export default Cloudflare.Worker("Api", { main: import.meta.url },
   Effect.gen(function* () {
     const apiKey = yield* Config.Redacted("API_KEY");
@@ -17,7 +19,9 @@ export default Cloudflare.Worker("Api", { main: import.meta.url },
 );
 ```
 
-```ts never
+## Never
+
+```ts
 export default Cloudflare.Worker("Api", { main: import.meta.url },
   Effect.gen(function* () {
     return {

package/presets/alchemy/secrets/let-alchemy-mint-infra-secrets.md

@@ -2,12 +2,16 @@
 description: A token the infrastructure owns, such as a webhook secret or bearer token, should be minted once with alchemy's Random or left for alchemy to provision, and should not be a hardcoded literal or regenerated on every deploy with crypto.randomUUID().
 ---
 
-```ts should
+## Should
+
+```ts
 export const WebhookSecret = Random("WebhookSecret");
 const auth = yield* BetterAuth({ basePath: "/api/auth", emailAndPassword: { enabled: true } });
 ```
 
-```ts should not
+## Should not
+
+```ts
 const webhookSecret = crypto.randomUUID(); // a new secret on every deploy
 const auth = yield* BetterAuth({ basePath: "/api/auth", secret: Redacted.make("dev-secret") });
 ```

package/presets/alchemy/secrets/none-in-browser-env.md

@@ -2,13 +2,17 @@
 description: A value in an env key that a framework inlines into the browser bundle, such as VITE_, NEXT_PUBLIC_, PUBLIC_, or NUXT_PUBLIC_, must be public configuration, never a secret, credential, or connection string, even wrapped in Redacted.
 ---
 
-```ts must
+## Must
+
+```ts
 const site = yield* Cloudflare.Website.Vite("Site", {
   env: { VITE_API_URL: api.url, STRIPE_SECRET_KEY: Config.Redacted("STRIPE_SECRET_KEY") },
 });
 ```
 
-```ts never
+## Never
+
+```ts
 const site = yield* Cloudflare.Website.Vite("Site", {
   env: { VITE_STRIPE_SECRET_KEY: Config.Redacted("STRIPE_SECRET_KEY"), VITE_DATABASE_URL: branch.connectionUri },
 });

package/presets/alchemy/secrets/redacted-until-use.md

@@ -2,7 +2,9 @@
 description: A secret should be read with Config.Redacted, passed to resources and env as Redacted, and unwrapped with Redacted.value only at the call that needs the raw string; it should not be read with Config.String or process.env, or unwrapped early into plain variables.
 ---
 
-```ts should
+## Should
+
+```ts
 const apiKey = yield* Config.Redacted("OPENAI_API_KEY");
 return {
   fetch: Effect.gen(function* () {
@@ -12,7 +14,9 @@ return {
 };
 ```
 
-```ts should not
+## Should not
+
+```ts
 const apiKey = Redacted.value(yield* Config.Redacted("OPENAI_API_KEY"));
 const webhook = process.env.SLACK_WEBHOOK_URL!;
 return { fetch: handler(apiKey, webhook) };

package/presets/alchemy/secrets/unwrap-before-compare-or-send.md

@@ -2,14 +2,18 @@
 description: A Redacted value must be unwrapped with Redacted.value before it is compared, sent, or serialized, never put into a template literal, string concatenation, String(), or JSON, where it becomes the literal text <redacted> and silently fails every check.
 ---
 
-```ts must
+## Must
+
+```ts
 const expected = yield* Config.Redacted("AUTH_TOKEN");
 if (request.headers.authorization !== `Bearer ${Redacted.value(expected)}`) {
   return HttpServerResponse.empty({ status: 401 });
 }
 ```
 
-```ts never
+## Never
+
+```ts
 const expected = yield* Config.Redacted("AUTH_TOKEN");
 if (request.headers.authorization !== `Bearer ${expected}`) { // compares against "Bearer <redacted>"
   return HttpServerResponse.empty({ status: 401 });

package/presets/alchemy/security/authorize-public-endpoints.md

@@ -2,7 +2,9 @@
 description: A handler behind a public URL, such as a Function URL, workers.dev route, or a Durable Object chosen by a client-supplied name, must authenticate the caller and check its access before doing protected work, never treating CORS, an obscure URL, or a trusted origin as authorization.
 ---
 
-```ts must
+## Must
+
+```ts
 fetch: Effect.gen(function* () {
   const request = yield* HttpServerRequest.HttpServerRequest;
   const user = yield* verifySession(request.headers.authorization);
@@ -11,7 +13,9 @@ fetch: Effect.gen(function* () {
 }),
 ```
 
-```ts never
+## Never
+
+```ts
 fetch: Effect.gen(function* () {
   const request = yield* HttpServerRequest.HttpServerRequest;
   const name = /^\/counters\/([^/]+)$/.exec(new URL(request.url).pathname)?.[1] ?? "default";

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/gen-for-sequencing.md

@@ -1,8 +1,10 @@
 ---
-description: Sequential effectful steps must be written with Effect.gen and yield*, never as nested flatMap or callback chains.
+description: Sequential effectful steps must be written with Effect.gen and yield*, never as nested flatMap or callback chains. A single flatMap or andThen in a flat pipe is out of scope; the rule is about a step whose callback holds further steps.
 ---
 
-```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

@@ -1,8 +1,10 @@
 ---
-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.
+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.
 ---
 
-```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

@@ -1,8 +1,10 @@
 ---
-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.
+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.
 ---
 
-```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

@@ -1,8 +1,10 @@
 ---
-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.
+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.
 ---
 
-```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* () {