@starci/eslint-canon-be 3.0.7 → 3.0.9

package/cookies.mjs

@@ -0,0 +1,106 @@
+/**
+ * The rule that holds the cookie half of the back-end transport law (catalog R141 `BE_COOKIE_ATTRIBUTES`).
+ *
+ * No back-end door writes a cookie under the canon today (the session travels as a bearer or as the front end's own httpOnly
+ * cookie), so this law is built ahead of the first one: a cookie a door writes through the response of Express or Fastify
+ * states `httpOnly: true`, carries `secure` and has `sameSite` `lax` or `strict`, judged on the TYPE of its options (a spread
+ * `as const` constant keeps its literals), and a `Set-Cookie` header is never written by hand, because a hand-written header
+ * states none of the three. The call is recognised by where its signature is declared (the `express` or `fastify` family of
+ * packages), never by the name of the receiver.
+ */
+import ts from "typescript"
+import { moduleOf, typed } from "./lib/types.mjs"
+
+/** The packages whose response types declare the cookie writers: Express with its typings, and Fastify with its cookie plugin. */
+const RESPONSE_PACKAGES = new Set([
+    "express",
+    "express-serve-static-core",
+    "@types/express",
+    "@types/express-serve-static-core",
+    "fastify",
+    "@fastify/cookie",
+])
+
+/** The response methods that write a cookie by name, value and options, and the ones that write a header by name. */
+const COOKIE_WRITERS = new Set(["cookie", "setCookie"])
+const HEADER_WRITERS = new Set(["setHeader", "append", "header", "set", "appendHeader"])
+const SAME_SITE = new Set(["lax", "strict"])
+
+/** The declaration a call resolves to, when it is a method of a response type of the express or fastify family; else null. */
+const responseMethodOf = (checker, toTs, call) => {
+    const tsCall = toTs(call)
+    const declaration = tsCall ? checker.getResolvedSignature(tsCall)?.declaration : undefined
+    if (!declaration || !(ts.isMethodSignature(declaration) || ts.isMethodDeclaration(declaration)) || !declaration.name) return null
+    const file = String(declaration.getSourceFile().fileName).split("\\").join("/")
+    const pkg = moduleOf(declaration, file)
+    return pkg !== null && RESPONSE_PACKAGES.has(pkg) ? declaration.name.getText() : null
+}
+
+/** The present (non-nullish) members of a property's type on an options type, or [] when the property is absent or only nullish. */
+const presentParts = (checker, type, name, at) => {
+    const symbol = type.getProperty(name)
+    if (!symbol) return []
+    const propertyType = checker.getTypeOfSymbolAtLocation(symbol, at)
+    const parts = propertyType.isUnion() ? propertyType.types : [propertyType]
+    return parts.filter((part) => !(part.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Null | ts.TypeFlags.Void)))
+}
+
+const isBooleanLiteral = (part, value) => Boolean(part.flags & ts.TypeFlags.BooleanLiteral) && part.intrinsicName === String(value)
+
+/** The attributes a written cookie is missing, judged on the type of its options. */
+const missingAttributes = (checker, type, at) => {
+    const missing = []
+    const httpOnly = presentParts(checker, type, "httpOnly", at)
+    if (httpOnly.length === 0 || !httpOnly.every((part) => isBooleanLiteral(part, true))) missing.push("`httpOnly: true`")
+    const secure = presentParts(checker, type, "secure", at)
+    if (secure.length === 0 || !secure.every((part) => isBooleanLiteral(part, true))) missing.push("`secure: true`")
+    const sameSite = presentParts(checker, type, "sameSite", at)
+    if (sameSite.length === 0 || !sameSite.every((part) => part.isStringLiteral() && SAME_SITE.has(part.value))) missing.push('`sameSite: "lax"` or `"strict"`')
+    return missing
+}
+
+/** A cookie a door writes states httpOnly, secure and sameSite, and no door writes `Set-Cookie` by hand. */
+export const responseCookieAttributes = {
+    meta: {
+        type: "problem",
+        docs: { description: "A cookie written through an Express or Fastify response states `httpOnly: true`, `secure: true` and `sameSite` `lax` or `strict`; `Set-Cookie` is never written as a header." },
+        schema: [],
+        messages: {
+            attributes:
+                "This cookie is written without {{missing}}. A cookie left to the defaults is readable by page script, travels over plain HTTP and is sent on cross-site requests: pass one options constant, declared `as const` by the owner of the cookie, that states `httpOnly: true`, `secure: true` and `sameSite` `lax` or `strict`.",
+            raw: "`Set-Cookie` is written here as a header, which states none of `httpOnly`, `secure` and `sameSite`. Write the cookie through the response's `cookie(name, value, options)` with an options constant that states all three.",
+        },
+    },
+    create(context) {
+        const { checker, toTs } = typed(context)
+        return {
+            CallExpression(node) {
+                if (node.callee.type !== "MemberExpression") return
+                const method = responseMethodOf(checker, toTs, node)
+                if (method === null) return
+                if (COOKIE_WRITERS.has(method)) {
+                    const options = node.arguments[2]
+                    const tsOptions = options ? toTs(options) : undefined
+                    const missing = tsOptions ? missingAttributes(checker, checker.getTypeAtLocation(tsOptions), tsOptions) : ["`httpOnly: true`", "`secure: true`", '`sameSite: "lax"` or `"strict"`']
+                    if (missing.length > 0) context.report({ node, messageId: "attributes", data: { missing: missing.join(", ") } })
+                    return
+                }
+                if (!HEADER_WRITERS.has(method)) return
+                const name = node.arguments[0]
+                const tsName = name ? toTs(name) : undefined
+                const type = tsName ? checker.getTypeAtLocation(tsName) : undefined
+                if (type?.isStringLiteral() && type.value.toLowerCase() === "set-cookie") context.report({ node, messageId: "raw" })
+            },
+        }
+    },
+}
+
+/** Every rule this module ships, by the name a config switches it on under. */
+export const rules = {
+    "response-cookie-attributes": responseCookieAttributes,
+}
+
+/** The level a consuming repository switches this on at. */
+export const recommended = {
+    "starci-be/response-cookie-attributes": "error",
+}

package/cqrs.mjs

@@ -118,8 +118,9 @@ export const handlerOverridesProcess = {
 /** Statements and expressions that are a decision or a repetition: none of them belongs in a handler. */
 const DECISION_NODES = new Set(["IfStatement", "SwitchStatement", "ConditionalExpression", "LogicalExpression", "ForStatement", "ForInStatement", "ForOfStatement", "WhileStatement", "DoWhileStatement", "TryStatement", "ThrowStatement"])
 
-/** True when a type annotation is a domain service: a class named `*Service` declared in a `*.service.ts` file. */
-const isServiceType = (context, annotation) => typeOrigins(context, annotation).some((origin) => origin.module === null && origin.name.endsWith("Service") && origin.file.endsWith(".service.ts"))
+/** The one collaborator a handler may hold: a domain service (a class named `*Service` declared in a `*.service.ts` file) or a projection (a class declared in a `*.projection.ts` file of slot `be.projections`). */
+const isServiceType = (context, hfs, annotation) => typeOrigins(context, annotation).some((origin) => origin.module === null
+    && ((origin.name.endsWith("Service") && origin.file.endsWith(".service.ts")) || (origin.file.endsWith(".projection.ts") && hfs.slotOf(origin.file) === "be.projections")))
 
 /** The injected members of a class: constructor parameters and decorated properties, with the type annotation of each. */
 const injectedMembers = (node) => {
@@ -140,10 +141,10 @@ const injectedMembers = (node) => {
 export const handlerIsThin = {
     meta: {
         type: "problem",
-        docs: { description: "A CQRS handler injects only `*Service` classes (and the template's Logger) and its `process` is one `return this.<service>.<method>(...)`." },
+        docs: { description: "A CQRS handler injects only `*Service` classes or projections (and the template's Logger) and its `process` is one `return this.<service>.<method>(...)`." },
         schema: [],
         messages: {
-            dependency: "`{{what}}` is injected into a handler. A handler holds services (and the Logger the `ICQRSHandler` template needs) and nothing else: an `EntityManager`, a bus, a client or any other infrastructure is the business of a `*.service.ts`, which is the one file that is unit-tested. Move the work into a service and inject that.",
+            dependency: "`{{what}}` is injected into a handler. A handler holds services or projections (and the Logger the `ICQRSHandler` template needs) and nothing else: an `EntityManager`, a bus, a client or any other infrastructure is the business of a `*.service.ts`, which is the one file that is unit-tested. Move the work into a service and inject that.",
             branch: "`{{what}}` is a decision or a loop in a handler. The `process` of a handler only maps its input and returns what one service method answers; every branch belongs in the service, where it is covered by the service spec.",
             body: "`process` of `{{name}}` must be the single statement `return this.<service>.<method>(<mapped input>)` (with or without `await`). Any other statement is logic that no unit spec covers: move it into the service.",
             call: "`process` of `{{name}}` must call exactly one method of an injected `*Service` and return its result: this makes {{count}} call(s), or calls something that is not an injected service.",
@@ -158,7 +159,7 @@ export const handlerIsThin = {
             const name = node.id?.name ?? "this handler"
             const services = new Set()
             for (const injected of injectedMembers(node)) {
-                if (injected.annotation && isServiceType(context, injected.annotation)) {
+                if (injected.annotation && isServiceType(context, hfs, injected.annotation)) {
                     if (injected.name !== null) services.add(injected.name)
                 } else if (!injected.annotation || !isLoggerType(context, injected.annotation)) {
                     context.report({ node: injected.report, messageId: "dependency", data: { what: sourceCode.getText(injected.param) } })
@@ -405,18 +406,9 @@ export const noUseCase = {
 
 // -- no-event-bus ------------------------------------------------------------------------------------------------
 
-/** The in-process event names of `@nestjs/cqrs`. */
-const EVENT_NAMES = new Set(["EventBus", "EventsHandler", "IEventHandler"])
-
-/** The package of the second in-process event system. */
-const EVENT_EMITTER_PACKAGE = "@nestjs/event-emitter"
-
-/** The Node and RxJS classes that are an in-process event bus when constructed or extended: package -> class names. */
-const BUS_CLASSES = { events: new Set(["EventEmitter"]), "node:events": new Set(["EventEmitter"]), rxjs: new Set(["Subject", "BehaviorSubject", "ReplaySubject", "AsyncSubject"]) }
-
-/** The bus class a constructed or extended expression is declared as (by declaration origin), else null. */
-const busClassOf = (context, node) => {
-    const origin = typeOrigins(context, node).find((entry) => entry.module !== null && BUS_CLASSES[entry.module]?.has(entry.name))
+/** The bus class a constructed or extended expression is declared as (by declaration origin), else null. `classes` is the `ruleParams.be.eventBus.classes` map: module specifier -> class names. */
+const busClassOf = (context, node, classes) => {
+    const origin = typeOrigins(context, node).find((entry) => entry.module !== null && classes[entry.module]?.includes(entry.name))
     return origin ? origin.name : null
 }
 
@@ -434,20 +426,22 @@ const holdsFunctions = (checker, type) => {
     return args.length > 0 && isFunctionType(args[args.length - 1])
 }
 
-/** No in-process events: a side effect that must happen anyway is an outbox message. */
+/** No in-process events: a side effect that must happen anyway is an event published through the bus. */
 export const noEventBus = {
     meta: {
         type: "problem",
         docs: { description: "`EventBus`, `@EventsHandler`, `IEventHandler` and `@nestjs/event-emitter` are not used." },
         schema: [],
         messages: {
-            event: "`{{name}}` is an in-process event mechanism. Events die with the process and run outside the transaction: write an outbox message in the transaction and consume it in `transport/message/` instead.",
-            bus: "`{{name}}` is constructed or extended here as an in-process event bus. A `*TransitionEmitter`, a Subject used as a channel or an EventEmitter subclass has the same failure as `EventBus`: listeners live in one process and run outside the transaction. Write an outbox message in the transaction and consume it in `transport/message/`; a state a caller waits for is read from the database.",
-            registry: "`{{name}}` stores callbacks that other code registers and this class later calls: a hand-rolled listener list is an in-process event bus. Write an outbox message in the transaction and consume it in `transport/message/` instead.",
+            event: "`{{name}}` is an in-process event mechanism. Events die with the process and run outside the transaction: publish an event with `eventBus.publish(event, tx)` in the transaction and consume it in `transport/message/` instead.",
+            bus: "`{{name}}` is constructed or extended here as an in-process event bus. A `*TransitionEmitter`, a Subject used as a channel or an EventEmitter subclass has the same failure as `EventBus`: listeners live in one process and run outside the transaction. Publish an event with `eventBus.publish(event, tx)` in the transaction and consume it in `transport/message/`; a state a caller waits for is read from the database.",
+            registry: "`{{name}}` stores callbacks that other code registers and this class later calls: a hand-rolled listener list is an in-process event bus. Publish an event with `eventBus.publish(event, tx)` in the transaction and consume it in `transport/message/` instead.",
         },
     },
     create(context) {
         const report = (node, name) => context.report({ node, messageId: "event", data: { name } })
+        const eventBus = hfsOf(context).ruleParams.eventBus
+        const eventNames = new Set(eventBus.imports[CQRS_PACKAGE] ?? [])
         const { checker, toTs } = typed(context)
         /** Collects, per class, the functions-collection properties and the registrations made on them. */
         const checkClass = (classNode) => {
@@ -483,21 +477,23 @@ export const noEventBus = {
             ClassDeclaration(node) {
                 checkClass(node)
                 if (node.superClass) {
-                    const name = busClassOf(context, node.superClass)
+                    const name = busClassOf(context, node.superClass, eventBus.classes)
                     if (name) context.report({ node: node.superClass, messageId: "bus", data: { name } })
                 }
             },
             ClassExpression(node) { checkClass(node) },
             NewExpression(node) {
-                const name = busClassOf(context, node.callee)
+                const name = busClassOf(context, node.callee, eventBus.classes)
                 if (name) context.report({ node, messageId: "bus", data: { name } })
             },
             ...moduleReferences(({ node, source, value, names }) => {
-                if (value === EVENT_EMITTER_PACKAGE) report(source, value)
-                else if (value === CQRS_PACKAGE) for (const name of names) if (EVENT_NAMES.has(name)) report(node, name)
+                const members = eventBus.imports[value]
+                if (members === undefined) return
+                if (members.length === 0) report(source, value)
+                else for (const name of names) if (members.includes(name)) report(node, name)
             }),
             MemberExpression(node) {
-                if (node.computed || node.property.type !== "Identifier" || !EVENT_NAMES.has(node.property.name)) return
+                if (node.computed || node.property.type !== "Identifier" || !eventNames.has(node.property.name)) return
                 if (node.object.type === "Identifier" && importOf(context, node.object)?.source === CQRS_PACKAGE && importOf(context, node.object).imported === "*") report(node, node.property.name)
             },
         }

package/data-access.mjs

@@ -9,7 +9,7 @@
  * - `must-inject-entity-manager` - a constructor parameter typed `EntityManager` carries the named injector of a declared
  *   connection. A lookalike (`InjectFooEntityManager`) or a bare `InjectEntityManager()` is not one.
  * - `named-entity-manager-only` - no property injection of an `EntityManager`, `DataSource` or `QueryRunner`; a
- *   `DataSource` or `QueryRunner` is injected only in the platform database capability and the migrate app; no
+ *   `DataSource` or `QueryRunner` is injected only in the platform database capability and the cli app; no
  *   `getRepository(...)` on a manager or data source; and outside those places no type reference, awaited value,
  *   or `provide:` token is a `DataSource` or `QueryRunner` (a wrapper service that exposes one is the same door), and no
  *   class receives a wrapper class that exposes one.
@@ -24,11 +24,12 @@
 
 import ts from "typescript"
 import { walk } from "./lib/ast.mjs"
-import { hfsOf } from "./lib/hfs.mjs"
+import { hfsOf, inTestWorld } from "./lib/hfs.mjs"
+import { resolveVariable, transactionCallback } from "./lib/transactions.mjs"
 import {
     declaredInjectorNames,
     inDatabaseCapability,
-    inMigrateApp, inTestBootstrap,
+    inCli,
     implementsMigration,
     infraTypeOf,
     injectionSites,
@@ -69,18 +70,18 @@ export const namedEntityManagerOnly = {
         type: "problem",
         docs: {
             description:
-                "No property injection of an `EntityManager`, `DataSource` or `QueryRunner`; a `DataSource` or `QueryRunner` only in the platform database capability, the migrate app and the test world (`src/tests/world`); no `getRepository`.",
+                "No property injection of an `EntityManager`, `DataSource` or `QueryRunner`; a `DataSource` or `QueryRunner` only in the platform database capability, the cli app and the test world (`src/tests/world`); no `getRepository`.",
         },
         schema: [],
         messages: {
             property:
                 "`{{type}}` is injected as a class property. Property injection hides the dependency from the constructor and the app module. Receive the named-injector `EntityManager` as a constructor parameter.",
             infra:
-                "`{{type}}` is injected here. A `DataSource` or `QueryRunner` is built and held only by the platform database capability, the migrate app and the test world in `src/tests/world`; specs take `world.db.<connection>`; everything else injects the shared `EntityManager` through its named injector and calls it directly.",
+                "`{{type}}` is injected here. A `DataSource` or `QueryRunner` is built and held only by the platform database capability, the cli app and the test world in `src/tests/world`; specs take `world.db.<connection>`; everything else injects the shared `EntityManager` through its named injector and calls it directly.",
             exposed:
-                "`{{type}}` is written here outside the platform database capability, the migrate app and the test world. A wrapper service that returns, holds or hands out a connection is the same door as injecting it: the connection is opened and held only by `platform/database`, and everything else calls the shared EntityManager through its named injector.",
+                "`{{type}}` is written here outside the platform database capability, the cli app and the test world. A wrapper service that returns, holds or hands out a connection is the same door as injecting it: the connection is opened and held only by `platform/database`, and everything else calls the shared EntityManager through its named injector.",
             token:
-                "This provider is bound to a `{{type}}`. A token that resolves to a connection object is a second door to the database: only `platform/database`, the migrate app and the test world provide one.",
+                "This provider is bound to a `{{type}}`. A token that resolves to a connection object is a second door to the database: only `platform/database`, the cli app and the test world provide one.",
             wrapper:
                 "`{{wrapper}}` exposes a `{{type}}` through `{{member}}`, and this class receives it. A connection wrapper is not a service dependency: inject the shared EntityManager with its named injector and call it directly.",
             getRepository:
@@ -90,7 +91,7 @@ export const namedEntityManagerOnly = {
     create(context) {
         const hfs = hfsOf(context)
         const filename = context.filename || context.getFilename()
-        const mayHoldConnections = inDatabaseCapability(hfs, filename) || inMigrateApp(hfs, filename) || inTestBootstrap(hfs, filename) || isMigrationFile(hfs, filename)
+        const mayHoldConnections = inDatabaseCapability(hfs, filename) || inCli(hfs, filename) || inTestWorld(hfs, filename) || isMigrationFile(hfs, filename)
         const CONNECTION_TYPES = new Set(["DataSource", "QueryRunner"])
         /** The connection type (DataSource / QueryRunner) a value or written type is declared as, else null. */
         const connectionTypeOf = (node) => {
@@ -286,26 +287,6 @@ export const requireEntityTableName = {
 
 // -- transactions ----------------------------------------------------------------------------------
 
-/** The callback of a `.transaction(...)` call on a manager or data source, or null. */
-const transactionCallback = (context, node) => {
-    const callee = node.callee
-    if (callee.type !== "MemberExpression" || callee.computed) return null
-    if (callee.property.type !== "Identifier" || callee.property.name !== "transaction") return null
-    const receiver = infraTypeOf(context, callee.object)
-    if (receiver !== "EntityManager" && receiver !== "DataSource") return null
-    const callback = node.arguments[node.arguments.length - 1]
-    return callback && (callback.type === "ArrowFunctionExpression" || callback.type === "FunctionExpression") ? callback : null
-}
-
-/** The variable an identifier resolves to, looking outward from the identifier's own scope. */
-const resolveVariable = (sourceCode, node) => {
-    for (let scope = sourceCode.getScope(node); scope; scope = scope.upper) {
-        const variable = scope.set.get(node.name)
-        if (variable) return variable
-    }
-    return null
-}
-
 /** The leftmost expression of a member chain: `this.deps.em` gives the `this`. */
 const rootOf = (expression) => {
     let current = expression

package/default-deny.mjs

@@ -13,6 +13,7 @@
  * The `APP_GUARD` registration and the app-level guard live in the composition check, not here: a rule reading
  * one file cannot see which module the app registered.
  */
+import { isTransportSlot } from "./lib/transport-slots.mjs"
 import { decoratorName, keyName } from "./lib/ast.mjs"
 import { isOwnedEnumMember } from "./lib/declared.mjs"
 import { hfsOf } from "./lib/hfs.mjs"
@@ -49,7 +50,7 @@ export const noUntypedBody = {
         const filename = normalizePath(context.filename || context.getFilename())
         if (isDeclarationFile(filename)) return {}
         const slot = hfsOf(context).slotOf(filename) ?? ""
-        const inTransport = slot.startsWith("be.transport.") || slot.startsWith("be.feature.transport.")
+        const inTransport = isTransportSlot(slot) || slot.startsWith("be.feature.transport.")
         return {
             Identifier(node) {
                 if (node.name === "GraphQLJSON" && !/^Import.*Specifier$/.test(node.parent?.type ?? "")) {

package/e2e-flow.mjs

@@ -1,8 +1,8 @@
 /**
- * The rules that hold `e2e-flow.md` (catalog R48 `BE_SPEC_QUALITY`, the e2e half).
+ * The rules that hold the e2e half of `knowledge/patterns/be/test.yaml` (catalog R48 `BE_SPEC_QUALITY`).
  *
  * A rule earns its place by being exact: it fires on a syntactic or typed shape, never on a judgement, or it becomes
- * something authors learn to work around. What these four enforce is transport bypass (a bus or an actor called
+ * something authors learn to work around. What these four rules enforce is transport bypass (a bus or an actor called
  * directly), a sleep instead of a poll, a branch inside a step, and a testing module built inside a spec instead of
  * booted by the test world (`useTestWorld({ apps })`, `src/tests/world/`). They do not pretend to judge business meaning: whether a file is one flow, whether
  * its steps are named, and what the absence of an effect is proved by are read by a person.
@@ -13,7 +13,7 @@
  */
 import { basename } from "node:path"
 import ts from "typescript"
-import { hfsOf } from "./lib/hfs.mjs"
+import { hfsOf, inTestWorld } from "./lib/hfs.mjs"
 import { isPackageType, typeOrigins, typed } from "./lib/types.mjs"
 
 /** Files this law governs. A flow is a named lane, not every file that happens to touch a database. */
@@ -172,7 +172,7 @@ export const noBranchInFlowStep = {
             !call.callee.computed &&
             call.callee.property.type === "Identifier" &&
             call.callee.property.name === "waitFor" &&
-            typeOrigins(context, call.callee.object).some((origin) => hfs.slotOf(origin.file) === "be.tests.world")
+            typeOrigins(context, call.callee.object).some((origin) => inTestWorld(hfs, origin.file))
 
         /** True when this node sits inside the callback of an `it(...)` or `test(...)`, and not inside a `waitFor` probe. */
         const insideStep = (node) => {

package/event-bus.mjs

@@ -0,0 +1,237 @@
+/**
+ * The rules that hold the event-bus and queue patterns (catalog R152 `BE_OUTBOX_WRITE_TX`, R153 `BE_EVENT_CONSUMER_SHAPE`,
+ * R154 `BE_QUEUE_PRODUCER_SHAPE`).
+ *
+ * The one durable path of an event is: a domain service writes the outbox row in ITS transaction (`eventBus.publish(event, tx)`), the
+ * relay hands the row to Kafka, a consumer in `transport/message` receives it and dispatches one command. A queue job takes the same
+ * path through a typed producer (`<queue>Queue.enqueueX(payload, tx)`) and BullMQ. Raw Kafka and BullMQ clients are owned by
+ * `platform/event-bus` and `platform/queue` (R90 `BE_INFRA_OWNER`); Nest's in-process buses are refused by `no-event-bus`.
+ *
+ * Every rule identifies what it judges by TYPE ORIGIN (the `EventBus` port declared by `platform/event-bus`, the `QueueOutbox` port of
+ * `platform/queue`, typeorm's `EntityManager`) and by the slot view (tiers, `be.transport.message`, `be.queues`); none matches a
+ * variable, class or method name written in the source, except the contract's own members `publish`, `eventName` and `eventId`.
+ */
+import ts from "typescript"
+import { walk } from "./lib/ast.mjs"
+import { hfsOf, inTestWorld } from "./lib/hfs.mjs"
+import { infraTypeOf } from "./lib/persistence.mjs"
+import { baseName, isOwnedType, ownerNameOf } from "./lib/ports.mjs"
+import { resolveVariable, transactionCallback } from "./lib/transactions.mjs"
+import { typeOrigins, typed } from "./lib/types.mjs"
+
+/** The `EventBus` port of `platform/event-bus`. */
+const isEventBusType = (context, node) => isOwnedType(context, node, { name: "EventBus", capability: "event-bus", tier: "platform" })
+
+/** The `EventConsumer` port of `platform/event-bus`. */
+const isEventConsumerType = (context, node) => isOwnedType(context, node, { name: "EventConsumer", capability: "event-bus", tier: "platform" })
+
+/** The `EventDelivery` type of `platform/event-bus`. */
+const isEventDeliveryType = (context, node) => isOwnedType(context, node, { name: "EventDelivery", capability: "event-bus", tier: "platform" })
+
+/** The `QueueOutbox` port of `platform/queue`. */
+const isQueueOutboxType = (context, node) => isOwnedType(context, node, { name: "QueueOutbox", capability: "queue", tier: "platform" })
+
+/** True for a file the rules leave alone: the owners themselves, and the test composition (the world, e2e and fixtures). */
+const isExempt = (hfs, file) => {
+    const tier = hfs.tierOf(file)
+    if (tier === "e2e" || tier === "fixtures" || inTestWorld(hfs, file)) return true
+    return tier === "platform" && ["event-bus", "queue"].includes(ownerNameOf(hfs, file))
+}
+
+/** The index of the parameter of a signature declaration typed as typeorm's `EntityManager`, or -1. */
+const transactionParameterIndex = (checker, declaration) => {
+    const parameters = declaration?.parameters ?? []
+    return parameters.findIndex((parameter) => {
+        const type = checker.getTypeAtLocation(parameter)
+        const symbol = type.getSymbol?.()
+        return symbol?.getName() === "EntityManager" && String(symbol.declarations?.[0]?.getSourceFile().fileName ?? "").replace(/\\/g, "/").includes("/node_modules/typeorm/")
+    })
+}
+
+/**
+ * What an expression passed as the transaction is: the transactional manager a `.transaction(async (manager) => ...)` callback
+ * receives, or a function parameter typed as the `EntityManager` (a helper that runs inside the caller's transaction).
+ * The injected shared manager (`this.entityManager`), a local alias and any other expression are not proof of a transaction.
+ */
+const isTransactionManager = (context, argument) => {
+    if (argument?.type !== "Identifier") return false
+    const variable = resolveVariable(context.sourceCode, argument)
+    const definition = variable?.defs[0]
+    if (definition?.type !== "Parameter") return false
+    const owner = definition.node
+    const call = owner.parent
+    if (call?.type === "CallExpression" && transactionCallback(context, call) === owner) return true
+    if (owner.parent?.type === "FunctionExpression" && owner.parent.parent?.kind === "constructor") return false
+    if (owner.parent?.kind === "constructor") return false
+    return infraTypeOf(context, definition.name) === "EntityManager"
+}
+
+/** The outbox-writing call a node is: `{ kind: "publish", argument }` or `{ kind: "producer", argument }`, or null. */
+const outboxWriteOf = (context, hfs, node) => {
+    const callee = node.callee
+    if (callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" && callee.property.name === "publish" && isEventBusType(context, callee.object)) {
+        return { kind: "publish", argument: node.arguments[1], expected: 1 }
+    }
+    const { checker, toTs } = typed(context)
+    const tsNode = toTs(node)
+    const declaration = tsNode ? checker.getResolvedSignature(tsNode)?.declaration : undefined
+    if (!declaration) return null
+    const file = declaration.getSourceFile().fileName
+    if (hfs.tierOf(file) !== "queues") return null
+    const index = transactionParameterIndex(checker, declaration)
+    return index < 0 ? null : { kind: "producer", argument: node.arguments[index], expected: index }
+}
+
+/** `eventBus.publish(event, tx)` and a queue producer's `enqueueX(payload, tx)` are called only from `modules/domain`, inside its transaction. */
+export const outboxWriteTx = {
+    meta: {
+        type: "problem",
+        docs: { description: "The outbox is written only by a domain service, with the transaction manager of its own transaction." },
+        schema: [],
+        messages: {
+            foreignTier: "`{{call}}` writes the outbox outside `modules/domain`. An event or a queue job is a consequence of a domain change: the domain service that makes the change publishes it inside the same transaction. A handler, a consumer or a job asks a domain service to act, and an integration or a platform capability never publishes.",
+            noTransaction: "`{{call}}` does not pass the transaction manager of its own transaction. The outbox row must commit or roll back with the domain change: call it inside `this.entityManager.transaction(async (manager) => { ... })` and pass that `manager` (or a function parameter typed `EntityManager` that the transaction hands down). The injected shared manager, an alias or an outer manager is not the transaction.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        if (isExempt(hfs, context.filename)) return {}
+        const inDomain = hfs.tierOf(context.filename) === "domain"
+        return {
+            CallExpression(node) {
+                const write = outboxWriteOf(context, hfs, node)
+                if (!write) return
+                const call = context.sourceCode.getText(node.callee)
+                if (!inDomain) context.report({ node, messageId: "foreignTier", data: { call } })
+                else if (!isTransactionManager(context, write.argument)) context.report({ node, messageId: "noTransaction", data: { call } })
+            },
+        }
+    },
+}
+
+/** The `eventName` literal of the event class an expression names (`typeof OrderPlacedEvent` has a static `eventName`), or null. */
+const eventNameOf = (context, expression) => {
+    const { checker, toTs } = typed(context)
+    const tsNode = toTs(expression)
+    if (!tsNode) return null
+    const property = checker.getTypeAtLocation(tsNode).getProperty("eventName")
+    if (!property) return null
+    const type = checker.getTypeOfSymbolAtLocation(property, tsNode)
+    return type.isStringLiteral() ? type.value : null
+}
+
+/** True when the node is a `.eventId` member read on a value typed as the `EventDelivery` of `platform/event-bus`. */
+const readsDeliveryEventId = (context, node) =>
+    node.type === "MemberExpression" && !node.computed && node.property.type === "Identifier" && node.property.name === "eventId" && isEventDeliveryType(context, node.object)
+
+/** The kebab stem of an event name: dots become dashes. */
+const stemOfEvent = (name) => name.split(".").join("-")
+
+/** A message consumer is the one door of an event: placed in `transport/message`, named after its event, and it forwards the event id. */
+export const eventConsumerShape = {
+    meta: {
+        type: "problem",
+        docs: { description: "A class implementing `EventConsumer` is `transport/message/<event>.consumer.ts`, named after its event class's `eventName`, and forwards `delivery.eventId`; a `.consumer.ts` implements `EventConsumer`." },
+        schema: [],
+        messages: {
+            placement: "`{{name}}` implements `EventConsumer` outside a `.consumer.ts` file of the message transport (`transport/message/<event>.consumer.ts`). A consumer is a transport door: move it there.",
+            notConsumer: "This `.consumer.ts` file declares `{{name}}`, which does not implement `EventConsumer` of `platform/event-bus`. The message transport holds only event consumers.",
+            eventUnknown: "`{{name}}.event` must be an event class whose static `eventName` is a string literal (`static readonly eventName = \"order.placed\"`), so the consumer and its contract entry are one name.",
+            stem: "The consumer of `{{event}}` is `{{expected}}.consumer.ts`, but this file is `{{actual}}.consumer.ts`. A consumer is named after the event it handles (dots become dashes).",
+            noEventId: "`{{name}}.handle` never reads `delivery.eventId`. Delivery is at least once: pass the event id to the command so the domain service claims it in `platform/inbox` inside its own transaction and a redelivery is a no-op.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        const file = context.filename
+        if (isExempt(hfs, file)) return {}
+        const inTransport = hfs.slotOf(file) === "be.transport.message"
+        const isConsumerFile = baseName(file).endsWith(".consumer.ts")
+        const check = (node) => {
+            const name = node.id?.name ?? "this class"
+            const implementsConsumer = (node.implements ?? []).some((entry) => isEventConsumerType(context, entry))
+            if (!implementsConsumer) {
+                if (inTransport && isConsumerFile) context.report({ node: node.id ?? node, messageId: "notConsumer", data: { name } })
+                return
+            }
+            if (!inTransport || !isConsumerFile) {
+                context.report({ node: node.id ?? node, messageId: "placement", data: { name } })
+                return
+            }
+            const eventProperty = node.body.body.find((member) => member.type === "PropertyDefinition" && !member.computed && member.key.type === "Identifier" && member.key.name === "event")
+            const event = eventProperty?.value ? eventNameOf(context, eventProperty.value) : null
+            if (event === null) context.report({ node: eventProperty ?? node.id ?? node, messageId: "eventUnknown", data: { name } })
+            else {
+                const actual = baseName(file).slice(0, -".consumer.ts".length)
+                if (stemOfEvent(event) !== actual) context.report({ node: node.id ?? node, messageId: "stem", data: { event, expected: stemOfEvent(event), actual } })
+            }
+            const handle = node.body.body.find((member) => member.type === "MethodDefinition" && !member.computed && member.key.type === "Identifier" && member.key.name === "handle")
+            const body = handle?.value?.body
+            let forwarded = false
+            if (body) walk(body, (child) => { if (readsDeliveryEventId(context, child)) forwarded = true })
+            if (!forwarded) context.report({ node: handle ?? node.id ?? node, messageId: "noEventId", data: { name } })
+        }
+        return { ClassDeclaration: check, ClassExpression: check }
+    },
+}
+
+/** The functions of an exported class or the exported functions of a `.queue.ts`: the producers. */
+const producersOf = (program) => {
+    const found = []
+    for (const statement of program.body) {
+        const declaration = statement.type === "ExportNamedDeclaration" || statement.type === "ExportDefaultDeclaration" ? statement.declaration : null
+        if (!declaration) continue
+        if (declaration.type === "FunctionDeclaration") {
+            found.push(declaration)
+        } else if (declaration.type === "ClassDeclaration") {
+            for (const member of declaration.body.body) if (member.type === "MethodDefinition" && member.kind === "method" && member.value) found.push(member.value)
+        } else if (declaration.type === "VariableDeclaration") {
+            for (const item of declaration.declarations) if (item.init && (item.init.type === "ArrowFunctionExpression" || item.init.type === "FunctionExpression")) found.push(item.init)
+        }
+    }
+    return found
+}
+
+/** A producer of a queue passes its own transaction parameter to the outbox, and nothing else writes the outbox there. */
+export const queueProducerShape = {
+    meta: {
+        type: "problem",
+        docs: { description: "In `modules/queues/<queue>/<queue>.queue.ts` every producer that writes the `QueueOutbox` takes a `tx` parameter typed `EntityManager` and passes it as the transaction." },
+        schema: [],
+        messages: {
+            noTransaction: "This producer writes the queue outbox without passing its own `tx` parameter (typed `EntityManager`) as the first argument. A queue job is enqueued inside the caller's transaction: declare `tx: EntityManager` and call `outbox.write(tx, ...)`.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        const file = context.filename
+        if (hfs.slotOf(file) !== "be.queues" || !baseName(file).endsWith(".queue.ts")) return {}
+        return {
+            "Program:exit"(program) {
+                for (const producer of producersOf(program)) {
+                    const parameters = producer.params.filter((param) => param.type === "Identifier")
+                    const tx = parameters.find((param) => infraTypeOf(context, param) === "EntityManager")
+                    walk(producer.body, (node) => {
+                        if (node.type !== "CallExpression" || node.callee.type !== "MemberExpression" || !isQueueOutboxType(context, node.callee.object)) return
+                        const first = node.arguments[0]
+                        const passes = tx !== undefined && first?.type === "Identifier" && first.name === tx.name && resolveVariable(context.sourceCode, first)?.defs[0]?.name === tx
+                        if (!passes) context.report({ node, messageId: "noTransaction" })
+                    })
+                }
+            },
+        }
+    },
+}
+
+export const rules = {
+    "outbox-write-tx": outboxWriteTx,
+    "event-consumer-shape": eventConsumerShape,
+    "queue-producer-shape": queueProducerShape,
+}
+
+/** The level these laws ask for: `error`, switched off nowhere. */
+export const recommended = {
+    "starci-be/outbox-write-tx": "error",
+    "starci-be/event-consumer-shape": "error",
+    "starci-be/queue-producer-shape": "error",
+}