@drkmttr/adhere 0.9.5 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.9.5",
+  "version": "0.11.0",
   "private": false,
   "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
   "license": "MIT",
@@ -32,7 +32,7 @@
     "start": "bun src/main.ts",
     "test": "vp test",
     "typecheck": "tsc --noEmit && bun run lint",
-    "build": "bun build --compile --minify --sourcemap src/main.ts --asset ./presets --outfile dist/adhere",
+    "build": "bun build --compile --minify --sourcemap --define ADHERE_BUILD=\"\\\"$(git describe --tags --dirty --always)\\\"\" src/main.ts --asset ./presets --outfile dist/adhere",
     "build:npm": "bun scripts/npm-packages.ts build",
     "release": "release-it"
   },
@@ -68,10 +68,10 @@
     }
   },
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.9.5",
-    "@drkmttr/adhere-darwin-x64": "0.9.5",
-    "@drkmttr/adhere-linux-arm64": "0.9.5",
-    "@drkmttr/adhere-linux-x64": "0.9.5",
-    "@drkmttr/adhere-win32-x64": "0.9.5"
+    "@drkmttr/adhere-darwin-arm64": "0.11.0",
+    "@drkmttr/adhere-darwin-x64": "0.11.0",
+    "@drkmttr/adhere-linux-arm64": "0.11.0",
+    "@drkmttr/adhere-linux-x64": "0.11.0",
+    "@drkmttr/adhere-win32-x64": "0.11.0"
   }
 }

package/presets/alchemy/apis/match-remote-errors-by-tag.md

@@ -2,13 +2,17 @@
 description: Errors that crossed RPC or a workflow replay must be matched by their tag and data fields, never with instanceof, prototype methods, or object identity, which do not survive serialization, and RPC arguments must be serializable values, never functions or class instances.
 ---
 
-```ts must
+## Must
+
+```ts
 const value = yield* stub.get(key).pipe(
   Effect.catchTag("KeyMissing", (error) => Effect.succeed(`missing: ${error.key}`)),
 );
 ```
 
-```ts never
+## Never
+
+```ts
 const value = yield* stub.get(key).pipe(
   Effect.catchAll((error) => (error instanceof KeyMissing ? Effect.succeed("missing") : Effect.fail(error))),
 );

package/presets/alchemy/apis/schemas-at-trust-boundaries.md

@@ -2,14 +2,18 @@
 description: Input from outside the stack, such as browsers, partners, or public URLs, should be validated with a schema through Effect RPC or HttpApi, while calls between the stack's own runtimes should use schemaless RPC through bindings, and unvalidated payloads should not cross a trust boundary.
 ---
 
-```ts should
+## Should
+
+```ts
 const Tasks = HttpApiGroup.make("tasks").add(
   HttpApiEndpoint.post("create", "/tasks", { payload: Schema.Struct({ title: Schema.String }) }),
 );
 const greeter = yield* Cloudflare.Workers.bindWorker(Greeter); // internal call
 ```
 
-```ts should not
+## Should not
+
+```ts
 fetch: Effect.gen(function* () {
   const request = yield* HttpServerRequest.HttpServerRequest;
   const body = (yield* request.json) as { title: string; ownerId: string }; // public URL, no validation

package/presets/alchemy/data/commit-migrations-then-deploy.md

@@ -2,12 +2,16 @@
 description: Migrations must be generated and reviewed ahead of time, committed with the schema, and applied from the committed files; a deploy, deploy hook, or Action must never generate migration SQL, and schema changes must never run from an HTTP route.
 ---
 
-```ts must
+## Must
+
+```ts
 // package.json: "db:generate": "drizzle-kit generate" (run locally, then commit ./drizzle)
 const db = yield* Cloudflare.D1.Database("AppDb", { migrations: "./drizzle" });
 ```
 
-```ts never
+## Never
+
+```ts
 // package.json: "deploy": "drizzle-kit generate && alchemy deploy"
 fetch: Effect.gen(function* () {
   if (url.pathname === "/setup") yield* sql`CREATE TABLE users (id text primary key)`;

package/presets/alchemy/data/hyperdrive-direct-origin.md

@@ -2,13 +2,17 @@
 description: A Hyperdrive connection's origin should be the database's direct endpoint, and clients that connect without Hyperdrive should use the provider's pooled endpoint; Hyperdrive should not point at a provider pooler, which stacks two poolers.
 ---
 
-```ts should
+## Should
+
+```ts
 const hyperdrive = yield* Cloudflare.Hyperdrive.Connection("AppHyperdrive", {
   origin: branch.origin,
   dev: branch.pooledOrigin,
 });
 ```
 
-```ts should not
+## Should not
+
+```ts
 const hyperdrive = yield* Cloudflare.Hyperdrive.Connection("AppHyperdrive", { origin: role.pooledOrigin });
 ```

package/presets/alchemy/data/migrations-use-direct-url.md

@@ -2,10 +2,14 @@
 description: A migration runner must connect with the database's direct URL, never Hyperdrive's runtime connection string or an Accelerate or pooled URL.
 ---
 
-```ts must
+## Must
+
+```ts
 export default defineConfig({ dialect: "postgresql", dbCredentials: { url: process.env.DIRECT_DATABASE_URL! } });
 ```
 
-```ts never
+## Never
+
+```ts
 export default defineConfig({ dialect: "postgresql", dbCredentials: { url: process.env.ACCELERATE_URL! } });
 ```

package/presets/alchemy/data/never-disable-tls-verification.md

@@ -2,13 +2,17 @@
 description: A database client or migration config must verify the server's TLS certificate, or connect inside the private network, never setting rejectUnauthorized: false or sslmode=no-verify to make a connection work.
 ---
 
-```ts must
+## Must
+
+```ts
 const url = new URL(connection.connectionString);
 url.searchParams.set("sslmode", "verify-full");
 const db = yield* Drizzle.Postgres(url.toString());
 ```
 
-```ts never
+## Never
+
+```ts
 export default defineConfig({
   dialect: "postgresql",
   dbCredentials: { url: process.env.DATABASE_URL!, ssl: { rejectUnauthorized: false } },

package/presets/alchemy/data/private-endpoint-at-runtime.md

@@ -2,11 +2,15 @@
 description: Service code should reach its database through the bound private connection, and should not use the public connection URI or TCP proxy, which is meant for laptops and CI.
 ---
 
-```ts should
+## Should
+
+```ts
 const conn = yield* Railway.ConnectPostgres(Db);
 const db = yield* Drizzle.Postgres(conn.connectionString);
 ```
 
-```ts should not
+## Should not
+
+```ts
 const db = yield* Drizzle.Postgres(Db.publicConnectionUri);
 ```

package/presets/alchemy/data/single-migration-owner.md

@@ -2,12 +2,16 @@
 description: Each database must have one migration owner: when a resource's migrations prop applies the directory, scripts and CI must never also run drizzle-kit migrate or prisma migrate against the same database.
 ---
 
-```ts must
+## Must
+
+```ts
 const branch = yield* Neon.Branch("Main", { project, migrations: "./migrations" });
 // package.json: "deploy": "alchemy deploy"
 ```
 
-```ts never
+## Never
+
+```ts
 const branch = yield* Neon.Branch("Main", { project, migrations: "./migrations" });
 // package.json: "deploy": "drizzle-kit migrate && alchemy deploy"
 ```

package/presets/alchemy/durable/idempotent-event-handlers.md

@@ -2,13 +2,17 @@
 description: A handler for events delivered at least once, such as Stripe webhooks, scheduled callbacks, or bucket and queue events, must be idempotent, upserting by a stable ID or deduplicating by event ID, never doing blind inserts, increments, or charges.
 ---
 
-```ts must
+## Must
+
+```ts
 yield* Stripe.consumeEvents([CustomerSubscriptionUpdated], (event) =>
   kv.put(`entitlement:${event.data.object.customer}`, JSON.stringify(entitlementOf(event))),
 );
 ```
 
-```ts never
+## Never
+
+```ts
 yield* Stripe.consumeEvents([InvoicePaid], (event) =>
   sql`UPDATE accounts SET credits = credits + 100 WHERE customer = ${event.data.object.customer}`,
 );

package/presets/alchemy/durable/io-inside-steps.md

@@ -2,7 +2,9 @@
 description: In a Workflow or Durable Function, every side effect, such as an HTTP call, binding call, or write, must run inside a task or step, and code outside steps must be deterministic, never doing I/O or reading the clock or randomness, because the body replays.
 ---
 
-```ts must
+## Must
+
+```ts
 export default Cloudflare.Workflow("Notify", Effect.fn(function* (input: { roomId: string; message: string }) {
   const stored = yield* Cloudflare.Workflows.task("store", kv.put(`notify:${input.roomId}`, input.message));
   yield* Cloudflare.Workflows.sleep("cooldown", "30 seconds");
@@ -10,7 +12,9 @@ export default Cloudflare.Workflow("Notify", Effect.fn(function* (input: { roomI
 }));
 ```
 
-```ts never
+## Never
+
+```ts
 export default Cloudflare.Workflow("Notify", Effect.fn(function* (input: { roomId: string; message: string }) {
   yield* kv.put(`notify:${input.roomId}:${Date.now()}`, input.message); // repeats on every replay
 }));

package/presets/alchemy/durable/no-self-triggering-bucket-writes.md

@@ -2,13 +2,17 @@
 description: A bucket-event handler that writes back into the bucket it listens to should filter its subscription by prefix or suffix so its own writes do not match, and should not subscribe to every object created in that bucket.
 ---
 
-```ts should
+## Should
+
+```ts
 yield* AWS.S3.consumeBucketEvents(bucket, { events: ["s3:ObjectCreated:*"], prefix: "incoming/" }, (stream) =>
   stream.pipe(Stream.runForEach((event) => putObject({ Key: `processed/${event.key}`, Body: "..." }))),
 );
 ```
 
-```ts should not
+## Should not
+
+```ts
 yield* AWS.S3.consumeBucketEvents(bucket, { events: ["s3:ObjectCreated:*"] }, (stream) =>
   stream.pipe(Stream.runForEach((event) => putObject({ Key: `processed/${event.key}`, Body: "..." }))), // triggers itself
 );

package/presets/alchemy/durable/stable-step-names.md

@@ -2,10 +2,14 @@
 description: Workflow task, sleep, and waitForEvent names are replay keys, so they must be stable across replays, never built from the clock, randomness, or other values that change between runs.
 ---
 
-```ts must
+## Must
+
+```ts
 yield* Cloudflare.Workflows.task("charge-card", chargeCard(input.orderId));
 ```
 
-```ts never
+## Never
+
+```ts
 yield* Cloudflare.Workflows.task(`charge-${Date.now()}`, chargeCard(input.orderId));
 ```

package/presets/alchemy/durable/webhook-state-is-truth.md

@@ -2,12 +2,16 @@
 description: Access to paid features must be gated on state recorded from Stripe webhooks in the app's own store, never granted because the user reached a success_url or return_url.
 ---
 
-```ts must
+## Must
+
+```ts
 const entitlement = yield* kv.get(`entitlement:${customerId}`);
 if (entitlement === null) return HttpServerResponse.empty({ status: 402 });
 ```
 
-```ts never
+## Never
+
+```ts
 if (url.pathname === "/welcome") {
   yield* kv.put(`entitlement:${customerId}`, "active"); // reached the success URL, not paid
 }

package/presets/alchemy/providers/diff-guards-unresolved-props.md

@@ -2,14 +2,18 @@
 description: A custom provider's diff must check isResolved(news) and return undefined before comparing props that may still be unresolved Outputs, never comparing them directly.
 ---
 
-```ts must
+## Must
+
+```ts
 diff: Effect.fn(function* ({ news, olds }) {
   if (!isResolved(news)) return undefined;
   if (news.region !== olds.region) return { action: "replace" } as const;
 }),
 ```
 
-```ts never
+## Never
+
+```ts
 diff: Effect.fn(function* ({ news, olds }) {
   if (news.region !== olds.region) return { action: "replace" } as const;
 }),

package/presets/alchemy/providers/idempotent-delete.md

@@ -1,14 +1,19 @@
 ---
-description: A custom provider's delete must treat a resource that is already gone as success, catching the not-found error, never failing when it runs again.
+description: The delete handler of a resource provider, the `delete:` lifecycle method given the resource's `output`, must treat a resource that is already gone as success, catching the not-found error, never failing when it runs again. Code outside a provider's delete handler, such as a runtime binding, a Worker route, or a storage client, is not in scope.
+level: warning
 ---
 
-```ts must
+## Must
+
+```ts
 delete: ({ output }) =>
   Effect.tryPromise(() => stripe.products.del(output.productId)).pipe(
     Effect.catchIf(isNotFound, () => Effect.void),
   ),
 ```
 
-```ts never
+## Never
+
+```ts
 delete: ({ output }) => Effect.promise(() => stripe.products.del(output.productId)),
 ```

package/presets/alchemy/providers/lazy-layer-construction.md

@@ -2,11 +2,15 @@
 description: A custom provider, credentials, or state-store Layer must defer resolving credentials and opening connections until an operation runs, never resolving credentials, connecting, or prompting while the Layer is built, because every CLI command builds it.
 ---
 
-```ts must
+## Must
+
+```ts
 export const PostgresState = Layer.effect(State, Effect.cached(makePostgresState(props)));
 ```
 
-```ts never
+## Never
+
+```ts
 export const PostgresState = Layer.effect(State, Effect.gen(function* () {
   const sql = postgres(process.env.DATABASE_URL!); // connects on every CLI command
   return makeState(sql);

package/presets/alchemy/providers/reconcile-from-observed-state.md

@@ -2,7 +2,9 @@
 description: A custom provider's reconcile must read the resource's live state and converge it in one flow that serves create, update, and adoption, never branching into separate create and update bodies on output === undefined or trusting olds as proof the resource exists.
 ---
 
-```ts must
+## Must
+
+```ts
 reconcile: Effect.fn(function* ({ news, output }) {
   let live = yield* observe(output);
   if (live === undefined) live = yield* create(news);
@@ -11,7 +13,9 @@ reconcile: Effect.fn(function* ({ news, output }) {
 }),
 ```
 
-```ts never
+## Never
+
+```ts
 reconcile: Effect.fn(function* ({ news, olds, output }) {
   if (output === undefined) return yield* create(news);
   yield* updateTags(output.id, olds.tags, news.tags);

package/presets/alchemy/resources/anchor-paths-with-import-meta.md

@@ -2,13 +2,17 @@
 description: A path prop such as main or rootDir on a resource declared outside the directory alchemy runs from must be anchored to the declaring file with import.meta, never given as a bare relative string, which resolves from the root instead.
 ---
 
-```ts must
+## Must
+
+```ts
 // backend/src/api.ts
 export default Cloudflare.Worker("Api", { main: import.meta.url }, program);
 export const Site = Cloudflare.Website.Vite("Site", { rootDir: path.resolve(import.meta.dirname, "../frontend") });
 ```
 
-```ts never
+## Never
+
+```ts
 // backend/src/api.ts
 export default Cloudflare.Worker("Api", { main: "src/api.ts" }, program); // resolves to <root>/src/api.ts
 ```

package/presets/alchemy/resources/idempotent-actions-and-seeds.md

@@ -2,7 +2,9 @@
 description: An Action body and a SQL file listed in importFiles must be safe to run again, using IF NOT EXISTS, ON CONFLICT, or upserts, never one-shot inserts or calls that duplicate data or fail when an interrupted deploy retries them.
 ---
 
-```ts must
+## Must
+
+```ts
 export const Migrate = Alchemy.Action("Migrate", Effect.fn(function* () {
   const db = yield* D1Client;
   yield* db.exec("CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)");
@@ -10,7 +12,9 @@ export const Migrate = Alchemy.Action("Migrate", Effect.fn(function* () {
 }));
 ```
 
-```ts never
+## Never
+
+```ts
 export const Seed = Alchemy.Action("Seed", Effect.fn(function* () {
   const db = yield* D1Client;
   yield* db.exec("CREATE TABLE users (id TEXT, name TEXT)");

package/presets/alchemy/resources/previews-reference-shared-resources.md

@@ -2,14 +2,18 @@
 description: Preview stages should reference a long-lived database or cluster with ref and create only cheap per-stage pieces such as a branch, and should not provision a whole project or cluster for every preview.
 ---
 
-```ts should
+## Should
+
+```ts
 const project = stage.startsWith("pr-")
   ? yield* Neon.Project.ref("AppDb", { stage: "staging" })
   : yield* Neon.Project("AppDb", { region: "aws-us-east-1" });
 const branch = yield* Neon.Branch("Branch", { project });
 ```
 
-```ts should not
+## Should not
+
+```ts
 const project = yield* Neon.Project("AppDb", { region: "aws-us-east-1" }); // a new project per PR
 const branch = yield* Neon.Branch("Branch", { project });
 ```

package/presets/alchemy/resources/protect-irreplaceable-data.md

@@ -2,11 +2,15 @@
 description: A bucket or database holding user or business data should be retained with RemovalPolicy.retain(), at least in production, and forceDestroy should be set only on buckets whose contents are disposable; irreplaceable data should not depend on the default destroy policy.
 ---
 
-```ts should
+## Should
+
+```ts
 const uploads = yield* Cloudflare.R2.Bucket("Uploads").pipe(RemovalPolicy.retain(stage === "prod"));
 const cache = yield* Cloudflare.R2.Bucket("Cache", { forceDestroy: true });
 ```
 
-```ts should not
+## Should not
+
+```ts
 const userUploads = yield* Cloudflare.R2.Bucket("UserUploads", { forceDestroy: true });
 ```

package/presets/alchemy/resources/remote-state-for-ci.md

@@ -2,7 +2,9 @@
 description: A stack deployed from CI or by more than one machine must use a shared state store such as Cloudflare.state() or AWS.state(), never Alchemy.localState(), which lives on one machine's disk where CI runners cannot see it.
 ---
 
-```ts must
+## Must
+
+```ts
 export default Alchemy.Stack("App", { providers: Cloudflare.providers(), state: Cloudflare.state() },
   Effect.gen(function* () {
     const api = yield* Api;
@@ -11,7 +13,9 @@ export default Alchemy.Stack("App", { providers: Cloudflare.providers(), state:
 );
 ```
 
-```ts never
+## Never
+
+```ts
 // deployed by .github/workflows/deploy.yml
 export default Alchemy.Stack("App", { providers: Cloudflare.providers(), state: Alchemy.localState() },
   Effect.gen(function* () {

package/presets/alchemy/resources/stable-logical-ids.md

@@ -2,12 +2,16 @@
 description: A resource's logical ID, its first argument, must stay the same from one deploy to the next, never built from timestamps, random values, UUIDs, or commit SHAs, because a new logical ID replaces the resource and deletes the old one with its data.
 ---
 
-```ts must
+## Must
+
+```ts
 const uploads = yield* Cloudflare.R2.Bucket("Uploads");
 const jobs = yield* AWS.SQS.Queue("Jobs");
 ```
 
-```ts never
+## Never
+
+```ts
 const uploads = yield* Cloudflare.R2.Bucket(`Uploads-${Date.now()}`);
 const db = yield* Neon.Project(`Db-${process.env.GITHUB_SHA}`);
 ```

package/presets/alchemy/resources/stage-unique-physical-names.md

@@ -2,7 +2,9 @@
 description: In a stack deployed to several stages, a resource whose physical name is global to an account or org should omit name, so alchemy derives one per stage, or derive it from the stage, and should not hardcode a single name every stage shares.
 ---
 
-```ts should
+## Should
+
+```ts
 const traces = yield* Axiom.Dataset("Traces", Stack.useSync(({ stage }) => ({
   name: `${stage}-traces`,
   kind: "otel:traces:v1" as const,
@@ -10,6 +12,8 @@ const traces = yield* Axiom.Dataset("Traces", Stack.useSync(({ stage }) => ({
 const branch = yield* Neon.Branch("Preview", { project });
 ```
 
-```ts should not
+## Should not
+
+```ts
 const traces = yield* Axiom.Dataset("Traces", { name: "app-traces", kind: "otel:traces:v1" });
 ```

package/presets/alchemy/runtime/bind-tag-not-implementation.md

@@ -2,7 +2,9 @@
 description: When a runtime is split into a Tag class and a make Layer, other runtimes must import and bind only the Tag, and only the Stack provides the Layer; another Worker or Function must never import or provide that implementation Layer.
 ---
 
-```ts must
+## Must
+
+```ts
 // src/Admin.ts
 import { Api } from "./Api.ts";
 
@@ -14,7 +16,9 @@ export default Cloudflare.Worker("Admin", { main: import.meta.url },
 );
 ```
 
-```ts never
+## Never
+
+```ts
 // src/Admin.ts
 import ApiLive, { Api } from "./Api.ts";
 

package/presets/alchemy/runtime/deterministic-config-defaults.md

@@ -2,12 +2,16 @@
 description: A Config default or fallback used by a runtime must be deterministic, because it is evaluated at deploy time and at runtime, never computed from the clock, randomness, or per-process values.
 ---
 
-```ts must
+## Must
+
+```ts
 const port = yield* Config.Number("PORT").pipe(Config.withDefault(3000));
 const region = yield* Config.String("REGION").pipe(Config.withDefault("us-east-1"));
 ```
 
-```ts never
+## Never
+
+```ts
 const instanceId = yield* Config.String("INSTANCE_ID").pipe(Config.withDefault(crypto.randomUUID()));
 const startedAt = yield* Config.String("STARTED_AT").pipe(Config.withDefault(new Date().toISOString()));
 ```

package/presets/alchemy/runtime/disposables-in-request-scope.md

@@ -2,7 +2,9 @@
 description: Connections, pools, sockets, and anything else with a finalizer must be acquired inside a handler or method, where the event's scope releases them, never at module scope or in a runtime's construction Effect, whose finalizers may never run.
 ---
 
-```ts must
+## Must
+
+```ts
 Effect.gen(function* () {
   const url = yield* Config.Redacted("DATABASE_URL");
   return {
@@ -18,7 +20,9 @@ Effect.gen(function* () {
 });
 ```
 
-```ts never
+## Never
+
+```ts
 Effect.gen(function* () {
   const pool = new Pool({ connectionString: process.env.DATABASE_URL }); // one pool for the isolate
   yield* Effect.addFinalizer(() => Effect.promise(() => pool.end())); // workerd never runs this

package/presets/alchemy/runtime/lambda-no-post-response-work.md

@@ -2,7 +2,9 @@
 description: In a Lambda handler, anything that must not be lost must be written durably, to a queue or a table, inside the handler before it responds, never left to a dangling promise, a forked fiber, or a finalizer, because Lambda freezes the instance after the response.
 ---
 
-```ts must
+## Must
+
+```ts
 fetch: Effect.gen(function* () {
   const event = yield* HttpServerRequest.schemaBodyJson(AuditEvent);
   yield* sendMessage({ MessageBody: JSON.stringify(event) });
@@ -10,7 +12,9 @@ fetch: Effect.gen(function* () {
 }),
 ```
 
-```ts never
+## Never
+
+```ts
 fetch: Effect.gen(function* () {
   const event = yield* HttpServerRequest.schemaBodyJson(AuditEvent);
   void fetch(AUDIT_URL, { method: "POST", body: JSON.stringify(event) }); // may never run

package/presets/alchemy/runtime/no-per-request-work-at-construction.md

@@ -2,7 +2,9 @@
 description: A runtime's construction Effect runs at deploy time and again at cold start, so it must only build resources, bindings, layers, and handler groups, never do per-request work such as queries, writes, bound calls, or starting consumers.
 ---
 
-```ts must
+## Must
+
+```ts
 Effect.gen(function* () {
   const table = yield* AWS.DynamoDB.Table("Jobs", { partitionKey: "id", attributes: { id: "S" } });
   const putItem = yield* AWS.DynamoDB.PutItem(table);
@@ -15,7 +17,9 @@ Effect.gen(function* () {
 });
 ```
 
-```ts never
+## Never
+
+```ts
 Effect.gen(function* () {
   const putItem = yield* AWS.DynamoDB.PutItem(table);
   yield* putItem({ Item: { id: { S: "seed" } } }); // runs at deploy and on every cold start