@drkmttr/adhere 0.9.4 → 0.10.0

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