@starci/eslint-canon-be 3.0.8 → 3.0.10

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",
+}

package/feature-thin.mjs

@@ -0,0 +1,237 @@
+/**
+ * The rule that holds the thin-feature law (R203 `BE_FEATURE_THIN`).
+ *
+ * A file of the feature tier whose role is one of `ruleParams.be.thinRoles` of the slot manifest
+ * (`<name>.handler.ts`, `<name>.resolver.ts`, `<name>.consumer.ts`, `<name>.processor.ts`, `<name>.step.ts`,
+ * `<name>.webhook.ts`, `<name>.mapper.ts`, ...) is a door: it maps its parameters and makes ONE delegating
+ * call into the modules (a service, the command or query bus, the event bus, a queue producer). No branch,
+ * loop, `try` or `throw` on business data and no computation lives in it - the logic belongs to the modules,
+ * where every file is unit-covered at 100, and orchestration (step order, compensation, claim, fencing,
+ * retry) belongs to the platform. A `mapper` file holds only property mapping: `*.mapper.ts` calls, `new`, and the shape conversions `map` and `toISOString`
+ * expressions, no delegating call at all.
+ *
+ * Kind comes from the SLOT and the TIER (`hfs.tierOf(filename)`, `hfs.ruleParams.thinRoles`), the role from
+ * the file-name suffix the closed role vocabulary defines - never a path regex. What a receiver is comes
+ * from its TYPE (`Logger` of `platform/logging`, `WebhookSignatureService` of `platform/http-security`) and
+ * from whether the member is injected (`injectedMembers`); what a free function is comes from the file its
+ * import resolves to. A job `step` records its fence through `JobClaims` (`advance`, `runKey`) and a webhook proves its signature through `verify`: those gate calls
+ * are free, the one effect each makes is the delegating call. `.spec.ts` and `.d.ts` are never judged, and neither is a file whose tier is not
+ * `feature` or whose role is not a thin role. A clean thin file is never flagged: that is the bar.
+ */
+import { keyName, walk } from "./lib/ast.mjs"
+import { aliasTarget, injectedMembers } from "./lib/doors.mjs"
+import { hfsOf } from "./lib/hfs.mjs"
+import { importOf } from "./lib/import-source.mjs"
+import { baseName, isLoggerType, isOwnedType } from "./lib/ports.mjs"
+
+/** The statements and expressions that are a decision, a repetition or an exit: none lives in a thin file. */
+const BRANCH_NODES = new Set(["IfStatement", "SwitchStatement", "ConditionalExpression", "ForStatement", "ForInStatement", "ForOfStatement", "WhileStatement", "DoWhileStatement", "TryStatement", "ThrowStatement", "LogicalExpression"])
+
+/** The expressions that compute a value (a `TemplateLiteral` with an expression joins them). */
+const COMPUTE_NODES = new Set(["BinaryExpression", "UnaryExpression", "UpdateExpression", "AssignmentExpression"])
+
+/** The nodes a function can be: the walk for calls and the nesting test use the same set. */
+const FUNCTION_NODES = new Set(["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression", "MethodDefinition"])
+
+/** What one decision or loop node is called in a message. */
+const BRANCH_WHAT = {
+    IfStatement: "an `if`",
+    SwitchStatement: "a `switch`",
+    ConditionalExpression: "a ternary",
+    ForStatement: "a `for`",
+    ForInStatement: "a `for-in`",
+    ForOfStatement: "a `for-of`",
+    WhileStatement: "a `while`",
+    DoWhileStatement: "a `do-while`",
+    TryStatement: "a `try`",
+    ThrowStatement: "a `throw`",
+}
+
+/** The wraps a call may sit under while still being the call of its statement. */
+const STATEMENT_WRAPPERS = new Set(["AwaitExpression", "TSAsExpression", "TSSatisfiesExpression", "TSNonNullExpression", "ChainExpression"])
+
+/** The closed-vocabulary role a file name carries (`<name>.<role>.ts` gives `<role>`), or null. */
+const roleOf = (filename) => /\.([a-z][a-z0-9-]*)\.ts$/.exec(baseName(filename))?.[1] ?? null
+
+/** The `WebhookSignatureService` of `platform/http-security` - the `verify` a webhook door may call. */
+const isSignatureReceiver = (context, node) => isOwnedType(context, node, { name: "WebhookSignatureService", capability: "http-security", tier: "platform" })
+
+/** The shape conversions a mapper may make on a value it received: a collection mapped item by item and a date written as text. They decide nothing and compute nothing. */
+const MAPPER_SHAPE_METHODS = new Set(["map", "toISOString"])
+
+/** The `JobClaims` port of `platform/jobs` - the fence a job step records itself through (`advance`, `runKey`): bookkeeping the fenced-job pattern requires, free beside the step's one delegating call. */
+const isClaimsReceiver = (context, node) => isOwnedType(context, node, { name: "JobClaims", capability: "jobs", tier: "platform" })
+
+/** The `Logger` port of `platform/logging` - the one call that is always free. */
+const isLoggerReceiver = isLoggerType
+
+/** The name of a thin file's law is `feature-thin` (R203). */
+export const featureThin = {
+    meta: {
+        type: "problem",
+        docs: { description: "A feature-tier file of a thin role maps its parameters and makes one delegating call into the modules: no branch, loop, `try`, `throw` or computation, and no call other than the one delegate, a modules function in mapping position, a `*.mapper.ts` function or the Logger." },
+        schema: [],
+        messages: {
+            branch: "{{what}} is a decision or a repetition in a thin file. A feature `<name>.{{role}}.ts` maps its parameters and makes one delegating call into the modules; a branch, a loop, a `try` or a `throw` is business logic that belongs in a service of the modules (where a unit spec covers it) - and orchestration (step order, compensation, claim, fencing, retry) belongs to the platform.",
+            compute: "{{what}} computes a value in a thin file. A feature `<name>.{{role}}.ts` maps its parameters and hands them over; an expression that computes is logic that belongs in the modules. Map the value there and read it back.",
+            call: "`{{what}}` is a call a thin file does not make. It calls exactly one injected member (a service, a bus `execute`, an event bus, a queue producer) or one function of the modules, and pure `*.mapper.ts` functions and the `Logger` port are free{{webhook}}; everything else - parsing, mapping by hand, a helper, a second dependency - is logic that belongs in the modules.",
+            many: "`{{name}}` makes a second delegating call here. A thin file makes exactly one; a second is orchestration - step order, compensation, claim, fencing, retry - and belongs to a capability of the platform or inside the service the file calls.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        const name = baseName(context.filename)
+        if (name.endsWith(".spec.ts") || name.endsWith(".d.ts")) return {}
+        const role = roleOf(name)
+        if (role === null || !(hfs.ruleParams.thinRoles ?? []).includes(role)) return {}
+        if (hfs.tierOf(context.filename) !== "feature") return {}
+        const sourceCode = context.sourceCode
+        const mapperFile = role === "mapper"
+
+        /** The injected member names of a class: constructor parameter properties and properties carrying an injector decorator. */
+        const memberNames = new Map()
+        const injectedNamesOf = (classNode) => {
+            if (memberNames.has(classNode)) return memberNames.get(classNode)
+            const names = new Set()
+            for (const { node } of injectedMembers(context, classNode)) {
+                if (node.type === "TSParameterProperty" && node.parameter.type === "Identifier") names.add(node.parameter.name)
+                else if (node.type === "PropertyDefinition") {
+                    const key = keyName(node.key)
+                    if (key !== null) names.add(key)
+                }
+            }
+            memberNames.set(classNode, names)
+            return names
+        }
+
+        /**
+         * The class `this` binds at a node's position: the nearest enclosing class, or null when a non-arrow
+         * function or an object-literal method rebinds `this` in between (a method's own `FunctionExpression`
+         * value is skipped - a method's `this` is the class).
+         */
+        const thisClassOf = (node) => {
+            for (let parent = node.parent; parent; parent = parent.parent) {
+                if (parent.type === "ClassDeclaration" || parent.type === "ClassExpression") return parent
+                if (parent.type === "FunctionDeclaration") return null
+                if (parent.type === "FunctionExpression" && parent.parent?.type !== "MethodDefinition") return null
+            }
+            return null
+        }
+
+        /** The member name of `this.<member>` the call's receiver names, when it is an injected member of the enclosing class. */
+        const injectedMemberOf = (object, call) => {
+            if (object.type !== "MemberExpression" || object.computed || object.object.type !== "ThisExpression" || object.property.type !== "Identifier") return null
+            const classNode = thisClassOf(call)
+            if (classNode === null) return null
+            const member = object.property.name
+            return injectedNamesOf(classNode).has(member) ? member : null
+        }
+
+        /** True for a call `f(...)` where `f` is imported from a `*.mapper.ts` (the pure mapping functions). */
+        const isMapperCall = (callee) => {
+            if (callee.type !== "Identifier") return false
+            const found = importOf(context, callee)
+            return found !== null && /(?:^|\/)[^/]+\.mapper(?:\.[cm]?[jt]s)?$/.test(found.source.replace(/\\/g, "/"))
+        }
+
+        /** True for a call `f(...)` where `f` is imported and its declaration lives outside the feature tier (a function of the modules). */
+        const isModulesCall = (callee) => {
+            if (callee.type !== "Identifier" || importOf(context, callee) === null) return false
+            const symbol = aliasTarget(context, callee)
+            return (symbol?.getDeclarations() ?? []).some((declaration) => hfs.tierOf(declaration.getSourceFile().fileName) !== "feature")
+        }
+
+        /** True when the call IS the statement it sits in: `f(...)`, `await f(...)`, `return (await) f(...)`, or the whole body of a concise arrow. */
+        const isStatementCall = (call) => {
+            let current = call
+            while (STATEMENT_WRAPPERS.has(current.parent?.type)) current = current.parent
+            const parent = current.parent
+            return parent?.type === "ExpressionStatement" || parent?.type === "ReturnStatement" || (parent?.type === "ArrowFunctionExpression" && parent.body === current)
+        }
+
+        /**
+         * What one call is to a thin file: `delegating` (the one call into the modules a file may make),
+         * `free` (a mapper, a logger method, a webhook `verify`, a job step's `JobClaims` fence call, a modules function in a mapping position)
+         * or `call` (a call a thin file does not make). A `mapper` file holds only mapper calls and `new`.
+         */
+        const classify = (call) => {
+            const callee = call.callee
+            if (callee.type === "Identifier" && isMapperCall(callee)) return "free"
+            const member = callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" ? callee : null
+            if (mapperFile && member !== null && MAPPER_SHAPE_METHODS.has(member.property.name) && injectedMemberOf(member.object, call) === null) return "free"
+            // a cli group command shows its help without a sub-command: the `help` of the command nest-commander gives it
+            if (role === "cli" && member !== null && member.property.name === "help" && member.object.type === "MemberExpression" && member.object.object.type === "ThisExpression" && member.object.property.type === "Identifier" && member.object.property.name === "command") return "free"
+            if (mapperFile) return "call"
+            if (callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" && injectedMemberOf(callee.object, call) !== null) {
+                if (isLoggerReceiver(context, callee.object)) return "free"
+                if (role === "webhook" && callee.property.name === "verify" && isSignatureReceiver(context, callee.object)) return "free"
+                if (role === "step" && isClaimsReceiver(context, callee.object)) return "free"
+                return "delegating"
+            }
+            if (callee.type === "Identifier" && isModulesCall(callee)) return isStatementCall(call) ? "delegating" : "free"
+            return "call"
+        }
+
+        /** Every root function of the file (a method body, function or arrow not nested in another function and not inside a decorator subtree). */
+        const rootFunctionsOf = (program) => {
+            const roots = []
+            walk(program, (node) => {
+                if (!FUNCTION_NODES.has(node.type)) return
+                for (let parent = node.parent; parent; parent = parent.parent) {
+                    if (parent.type === "Decorator" || FUNCTION_NODES.has(parent.type)) return
+                }
+                if (node.type === "MethodDefinition" && node.kind === "constructor") return
+                roots.push(node)
+            })
+            return roots
+        }
+
+        /** The name a `many` message reports for a function root. */
+        const nameOf = (fn) => {
+            if (fn.type === "MethodDefinition") return keyName(fn.key) ?? "the method"
+            if (fn.type === "FunctionDeclaration" && fn.id?.type === "Identifier") return fn.id.name
+            const parent = fn.parent
+            if (parent?.type === "VariableDeclarator" && parent.id.type === "Identifier") return parent.id.name
+            if ((parent?.type === "PropertyDefinition" || parent?.type === "Property") && keyName(parent.key)) return keyName(parent.key)
+            return "the function"
+        }
+
+        const visitors = {}
+        for (const type of BRANCH_NODES) {
+            visitors[type] = (node) => context.report({ node, messageId: "branch", data: { what: type === "LogicalExpression" ? `a \`${node.operator}\`` : BRANCH_WHAT[type], role } })
+        }
+        for (const type of COMPUTE_NODES) {
+            visitors[type] = (node) => context.report({ node, messageId: "compute", data: { what: `an \`${node.operator}\``, role } })
+        }
+        visitors.TemplateLiteral = (node) => {
+            if (node.expressions.length > 0) context.report({ node, messageId: "compute", data: { what: "a template literal with an expression", role } })
+        }
+        visitors["Program:exit"] = (program) => {
+            for (const root of rootFunctionsOf(program)) {
+                const body = root.type === "MethodDefinition" ? root.value?.body : root.body
+                if (!body) continue
+                let delegating = 0
+                walk(body, (node) => {
+                    if (node.type !== "CallExpression") return
+                    const kind = classify(node)
+                    if (kind === "call") context.report({ node, messageId: "call", data: { what: sourceCode.getText(node.callee), webhook: role === "webhook" ? ", plus `verify` of the signature service" : "" } })
+                    else if (kind === "delegating") {
+                        delegating += 1
+                        if (delegating === 2) context.report({ node, messageId: "many", data: { name: nameOf(root) } })
+                    }
+                })
+            }
+        }
+        return visitors
+    },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "feature-thin": featureThin,
+}
+
+/** Every rule of this law at `error`. */
+export const recommended = {
+    "starci-be/feature-thin": "error",
+}

package/idempotency.mjs

@@ -9,8 +9,8 @@
  *   - `inbox-dedupe-required` judges every DELIVERY method of a service. Doors (consumers, `SignedWebhook` controllers) are
  *     thin (R88): they map the delivery and dispatch one message, so the claim lives in the `*.service.ts` the handler calls,
  *     inside its transaction. A delivery method is a public method of a `<name>.service.ts` whose FIRST parameter has an
- *     `eventId` property, read by the parameter's TYPE. The FIRST awaited expression of such a method must be
- *     `claim(source, eventId)` on a receiver whose type is the `Inbox` port of `platform/inbox`, and the method must return
+ *     `eventId` property, read by the parameter's TYPE. Its first awaited work is the Inbox claim, directly or inside
+ *     the callback of its own EntityManager transaction, with that callback's manager, and the method must return
  *     early when the claim answers `false`. A lookalike `Inbox` declared by another owner, a renamed receiver and a
  *     property injection are all judged by the receiver's type, so only the real port satisfies the rule; a keyword or a
  *     class name never does.
@@ -20,12 +20,15 @@
  *   if ((await this.inbox.claim(source, id)) === false) { return }
  *   const fresh = await this.inbox.claim(source, id)
  *   if (!fresh) return
- * Whether the handler has side effects BEFORE its first await stays a review question (the call graph is not read).
+ * A transaction delivery returns or awaits one transaction as its sole statement. The actual selected inline callback
+ * claims with its own manager in its first statement, then returns on false; no outer work runs after a duplicate.
+ * Direct-claim synchronous effects, getters and called helpers stay review questions (the call graph is not read).
  */
 import { hfsOf } from "./lib/hfs.mjs"
 import { walk } from "./lib/ast.mjs"
-import { baseName, isOwnedType } from "./lib/ports.mjs"
-import { typed } from "./lib/types.mjs"
+import { baseName, isOwnedType, ownerNameOf } from "./lib/ports.mjs"
+import { resolveVariable } from "./lib/transactions.mjs"
+import { isPackageType, typed } from "./lib/types.mjs"
 
 /** The `Inbox` port of `platform/inbox`. */
 const isInboxType = (context, node) => isOwnedType(context, node, { name: "Inbox", capability: "inbox", tier: "platform" })
@@ -73,6 +76,52 @@ const firstAwait = (body) => {
     return first
 }
 
+/** True when an expression evaluates a call, construction or write before the designated call completes. */
+const hasPriorEffect = (expression, call) => {
+    let found = false
+    walk(expression, (node) => {
+        if (["CallExpression", "NewExpression", "AssignmentExpression", "UpdateExpression"].includes(node.type)
+            && node !== call && node.range[1] < call.range[1]) found = true
+    }, { intoFunctions: false })
+    return found
+}
+
+/** The first awaited claim in the actual callback of a sole, returned or awaited EntityManager transaction. */
+const transactionClaim = (context, body) => {
+    if (body.body.length !== 1) return null
+    const outer = body.body[0]
+    const expression = outer.type === "ReturnStatement" ? outer.argument
+        : outer.type === "ExpressionStatement" && outer.expression.type === "AwaitExpression" ? outer.expression : null
+    const call = expression?.type === "AwaitExpression" ? expression.argument : expression
+    const callee = call?.callee
+    if (call?.type !== "CallExpression" || callee.type !== "MemberExpression" || callee.computed
+        || callee.property.type !== "Identifier" || callee.property.name !== "transaction"
+        || !isPackageType(context, callee.object, "EntityManager", "typeorm") || hasPriorEffect(call, call)) return null
+    // TypeORM runs arg0 when it is a function, otherwise arg1. Never accept a later, ignored callback.
+    const isolation = call.arguments[0]
+    const callback = call.arguments.length === 1 ? isolation
+        : call.arguments.length === 2 && isolation.type === "Literal"
+            && ["READ UNCOMMITTED", "READ COMMITTED", "REPEATABLE READ", "SERIALIZABLE"].includes(isolation.value)
+            ? call.arguments[1] : null
+    if (!callback || !["ArrowFunctionExpression", "FunctionExpression"].includes(callback.type)
+        || !callback.async || callback.body.type !== "BlockStatement" || callback.params.length !== 1) return null
+    const manager = callback.params[0]
+    if (manager.type !== "Identifier" || !isPackageType(context, manager, "EntityManager", "typeorm")) return null
+    const awaited = firstAwait(callback.body)
+    const parent = awaited?.parent
+    const statement = parent?.type === "VariableDeclarator" && parent.init === awaited
+        && parent.parent.declarations.length === 1 ? parent.parent
+        : ["UnaryExpression", "BinaryExpression"].includes(parent?.type) ? parent.parent
+            : parent?.type === "ExpressionStatement" ? parent : null
+    if (statement !== callback.body.body[0] || statement?.parent !== callback.body) return null
+    const claim = awaited.argument
+    const argument = claim?.type === "CallExpression" ? claim.arguments[2] : null
+    const managerBinding = resolveVariable(context.sourceCode, manager)
+    const argumentBinding = argument?.type === "Identifier" ? resolveVariable(context.sourceCode, argument) : null
+    if (!managerBinding || managerBinding.defs[0]?.name !== manager || !argumentBinding
+        || argumentBinding !== managerBinding || hasPriorEffect(statement, claim)) return null
+    return awaited
+}
 /** Whether a parameter's type has an `eventId` property: the shape of a delivery. */
 const isDeliveryParam = (context, param) => {
     const target = param.type === "TSParameterProperty" ? param.parameter : param.type === "AssignmentPattern" ? param.left : param
@@ -99,13 +148,15 @@ export const inboxDedupeRequired = {
         const filename = context.filename || context.getFilename()
         const slot = hfs.slotOf(filename)
         if (!baseName(filename).endsWith(".service.ts") || !slot || slot.startsWith("be.tests.")) return {}
+        // The event bus publishes events (their shape carries an `eventId`) and its runtime claims the inbox before a consumer runs: no delivery method here.
+        if (slot.startsWith("be.platform") && ownerNameOf(hfs, filename) === "event-bus") return {}
         return {
             MethodDefinition(node) {
                 if (node.kind !== "method" || node.static || node.key.type === "PrivateIdentifier" || !node.value.body) return
                 if (node.accessibility === "private" || node.accessibility === "protected") return
                 const first = node.value.params[0]
                 if (!first || !isDeliveryParam(context, first)) return
-                const awaited = firstAwait(node.value.body)
+                const awaited = transactionClaim(context, node.value.body) ?? firstAwait(node.value.body)
                 const call = awaited?.argument
                 const claims = call?.type === "CallExpression"
                     && call.callee.type === "MemberExpression"