@starci/eslint-canon-be 1.2.1 → 1.7.0

package/error-handling.mjs

@@ -0,0 +1,207 @@
+/**
+ * The rules that hold HFS errors and their handling (catalog R38 `BE_ERROR_HOME`, R40 `BE_LOGGER_REQUIRED`).
+ *
+ * TWO RULES, ONE HABIT: a failure is either named where its owner lives, or it is visible.
+ *
+ *   - `catch-must-account` refuses a `catch` (and a promise `.catch`) that swallows. A handler passes when it
+ *     rethrows, when it logs through a logger port, or when it returns an outcome that carries the caught
+ *     error as its `cause`. An empty handler, and one that returns `null` or `false` and moves on, turns a
+ *     real failure into "nothing happened" - the payment error that became `unavailable` with no trace.
+ *   - `error-home` keeps every error where its semantic owner is. A class deriving from `DomainError` lives in
+ *     `<capability>/errors/`; the retired `exceptions/` capability, the retired `AbstractException` base, a bare
+ *     `throw new Error(...)`, a framework `HttpException`, and a domain that throws a platform error are all
+ *     refused. Expected business results are typed unions, not exceptions, and are outside this rule.
+ *
+ * This file replaces the Academy `AbstractException` laws: those rules pinned a central exception family that
+ * HFS no longer has, and a rule that survives its standard as "off" is a rule nobody can trust.
+ */
+import { some, walk } from "./lib/ast.mjs"
+import { isDeclarationFile, isTestLane, normalizePath } from "./lib/path.mjs"
+
+const LOG_METHODS = new Set(["error", "warn", "info", "debug", "log", "fatal", "verbose", "trace"])
+
+/** The object a member call is made on, as the last identifier of its chain (`this.logger.error` gives `logger`). */
+const receiverName = (callee) => {
+    const object = callee.object
+    if (object.type === "Identifier") return object.name
+    if (object.type === "MemberExpression" && !object.computed && object.property.type === "Identifier") return object.property.name
+    return null
+}
+
+/** `logger.error(...)`, `this.log.warn(...)`: a call on a logger port. `console` is never one. */
+const isLoggerCall = (node) => {
+    if (node.type !== "CallExpression" || node.callee.type !== "MemberExpression" || node.callee.computed) return false
+    if (node.callee.property.type !== "Identifier" || !LOG_METHODS.has(node.callee.property.name)) return false
+    const receiver = receiverName(node.callee)
+    return receiver !== null && receiver !== "console" && /log/i.test(receiver)
+}
+
+/** True when `name` is used as a value in `node` (not just as the object of `name.message`). */
+const carriesCaught = (node, name) => {
+    if (!name) return false
+    let carried = false
+    walk(node, (child) => {
+        if (child.type !== "Identifier" || child.name !== name) return
+        const parent = child.parent
+        if (parent?.type === "MemberExpression" && parent.object === child) return
+        carried = true
+    })
+    return carried
+}
+
+/**
+ * Whether a handler block accounts for the failure.
+ *
+ * @param {object} body - The block of the handler.
+ * @param {string | null} param - The caught error's name, when the handler names it.
+ * @returns {boolean} True when it rethrows, logs, or returns an outcome carrying the error.
+ */
+const accounts = (body, param) =>
+    some(
+        body,
+        (node) =>
+            node.type === "ThrowStatement" ||
+            isLoggerCall(node) ||
+            (node.type === "ReturnStatement" && node.argument !== null && carriesCaught(node.argument, param)),
+        { intoFunctions: false },
+    )
+
+const paramName = (fn) => (fn.params?.[0]?.type === "Identifier" ? fn.params[0].name : null)
+
+/** Every failure is rethrown, logged, or returned as an outcome carrying its cause. */
+export const catchMustAccount = {
+    meta: {
+        type: "problem",
+        docs: { description: "A catch rethrows, logs through a logger port, or returns an outcome that carries the cause." },
+        schema: [],
+        messages: {
+            empty: "This `catch` is empty, so the failure vanishes. Rethrow it, log it through the logger port, or return a typed outcome carrying it as `cause`.",
+            swallowed:
+                "This `catch` neither rethrows, logs, nor returns an outcome carrying the caught error, so the failure leaves no trace. Rethrow it, log it through the logger port, or return a typed outcome with `cause`.",
+        },
+    },
+    create(context) {
+        const checkBlock = (reportNode, body, param) => {
+            if (body.body.length === 0) context.report({ node: reportNode, messageId: "empty" })
+            else if (!accounts(body, param)) context.report({ node: reportNode, messageId: "swallowed" })
+        }
+        return {
+            CatchClause(node) {
+                checkBlock(node, node.body, node.param?.type === "Identifier" ? node.param.name : null)
+            },
+            CallExpression(node) {
+                if (node.callee.type !== "MemberExpression" || node.callee.computed) return
+                if (node.callee.property.type !== "Identifier" || node.callee.property.name !== "catch") return
+                const handler = node.arguments[0]
+                if (!handler || (handler.type !== "ArrowFunctionExpression" && handler.type !== "FunctionExpression")) return
+                if (handler.body.type === "BlockStatement") {
+                    checkBlock(handler, handler.body, paramName(handler))
+                } else if (!isLoggerCall(handler.body) && !carriesCaught(handler.body, paramName(handler))) {
+                    context.report({ node: handler, messageId: "swallowed" })
+                }
+            },
+        }
+    },
+}
+
+/** The framework exceptions that carry an HTTP status and no identity. */
+const FRAMEWORK_EXCEPTIONS = new Set([
+    "BadRequestException",
+    "NotFoundException",
+    "UnauthorizedException",
+    "ForbiddenException",
+    "InternalServerErrorException",
+    "HttpException",
+    "ConflictException",
+    "NotAcceptableException",
+    "RequestTimeoutException",
+    "GoneException",
+    "PayloadTooLargeException",
+    "UnsupportedMediaTypeException",
+    "UnprocessableEntityException",
+    "NotImplementedException",
+    "BadGatewayException",
+    "ServiceUnavailableException",
+    "GatewayTimeoutException",
+])
+
+const BUILTIN_ERRORS = new Set(["Error", "TypeError", "RangeError", "SyntaxError", "ReferenceError", "EvalError", "URIError"])
+
+/** `<capability>/errors/` under a module tier or a feature, or the platform `errors` capability itself. */
+const ERRORS_HOME =
+    /\/src\/(?:modules\/(?:domain|platform|integrations)\/[^/]+|features\/[^/]+)\/(?:[^/]+\/)*errors\/|\/src\/modules\/platform\/errors\//
+const PLATFORM_ERRORS = /\/src\/modules\/platform\/errors\//
+const RETIRED_HOME = /\/src\/modules\/(?:domain|platform|integrations)\/exceptions\//
+const DOMAIN_TIER = /\/src\/modules\/domain\//
+const HEALTH_PROBE = /\/health(?:z)?\.controller\.ts$|\/health\//
+
+/** An error class is declared at its owner, extends `DomainError`, and is never a bare or framework throw. */
+export const errorHome = {
+    meta: {
+        type: "problem",
+        docs: { description: "Errors live in `<capability>/errors/`, extend DomainError, and no bare or framework error escapes." },
+        schema: [],
+        messages: {
+            place: "`{{name}}` is an error of this capability but is declared outside its `errors/` folder. Move it to the `errors/` folder of the capability that owns its meaning.",
+            retiredHome: "This file sits in a retired `exceptions/` capability. Errors belong to the capability that owns their meaning, in its `errors/` folder.",
+            retiredBase: "`{{name}}` extends `AbstractException`, the retired central base. Extend `DomainError` from `platform/errors` and keep the class in its capability's `errors/`.",
+            mustExtendDomainError: "`{{name}}` extends the built-in `{{parent}}`. Extend `DomainError` so the error carries a stable `code` and a `cause`.",
+            bareError: "`throw new Error(...)` carries a sentence and no code, so nothing downstream can group or map it. Throw a `DomainError` subclass of the owning capability.",
+            framework: "`throw new {{name}}(...)` carries an HTTP status and no identity. Throw a `DomainError` subclass and let the transport map its code to a status.",
+            platformThrown: "A domain capability throws `{{name}}`, a platform error. Translate it into an error of this capability so platform details do not cross the boundary.",
+        },
+    },
+    create(context) {
+        const filename = normalizePath(context.filename || context.getFilename())
+        if (isDeclarationFile(filename)) return {}
+        const listeners = {}
+        if (RETIRED_HOME.test(filename)) {
+            listeners.Program = (node) => context.report({ node, messageId: "retiredHome" })
+        }
+        if (isTestLane(filename)) return listeners
+        const inHome = ERRORS_HOME.test(filename)
+        const platformImports = new Set()
+        listeners.ImportDeclaration = (node) => {
+            if (typeof node.source.value !== "string" || !/(?:^|\/)platform\//.test(node.source.value)) return
+            for (const specifier of node.specifiers) platformImports.add(specifier.local.name)
+        }
+        listeners.ClassDeclaration = (node) => {
+            const parent = node.superClass
+            if (!node.id || !parent || parent.type !== "Identifier") return
+            if (parent.name === "AbstractException") {
+                context.report({ node: parent, messageId: "retiredBase", data: { name: node.id.name } })
+            } else if (BUILTIN_ERRORS.has(parent.name)) {
+                if (!PLATFORM_ERRORS.test(filename)) {
+                    context.report({ node: parent, messageId: "mustExtendDomainError", data: { name: node.id.name, parent: parent.name } })
+                }
+            } else if (/Error$/.test(parent.name) && !inHome) {
+                context.report({ node: node.id, messageId: "place", data: { name: node.id.name } })
+            }
+        }
+        listeners.ThrowStatement = (node) => {
+            const thrown = node.argument
+            if (!thrown || thrown.type !== "NewExpression" || thrown.callee.type !== "Identifier") return
+            const name = thrown.callee.name
+            if (name === "Error") {
+                context.report({ node: thrown, messageId: "bareError" })
+            } else if (FRAMEWORK_EXCEPTIONS.has(name) && !HEALTH_PROBE.test(filename)) {
+                context.report({ node: thrown, messageId: "framework", data: { name } })
+            } else if (DOMAIN_TIER.test(filename) && name !== "DomainError" && /Error$/.test(name) && platformImports.has(name)) {
+                context.report({ node: thrown, messageId: "platformThrown", data: { name } })
+            }
+        }
+        return listeners
+    },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "catch-must-account": catchMustAccount,
+    "error-home": errorHome,
+}
+
+/** Both start at error: HFS has no baseline, and the migration lanes clear the debt before a repository adopts them. */
+export const recommended = {
+    "starci-be/catch-must-account": "error",
+    "starci-be/error-home": "error",
+}

package/event-delivery.mjs

@@ -1,93 +1,93 @@
-const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
-
-/** The NATS bridge rejects self-echo and claims redelivery before local fan-out. */
-export const natsBridgeDeliveryContract = {
-  meta: {
-    type: "problem",
-    docs: { description: "The central NATS bridge preserves cross-instance delivery invariants." },
-    schema: [],
-    messages: {
-      origin: "Drop envelopes whose producer id matches this instance before local emit.",
-      digest: "Claim/check the envelope digest before local emit so redelivery is idempotent.",
-    },
-  },
-  create(context) {
-    if (!normalizePath(context.filename || context.getFilename()).endsWith(
-      "/event/nats/nats-bridge.service.ts",
-    )) return {}
-    return {
-      "Program:exit"(node) {
-        const source = context.sourceCode || context.getSourceCode()
-        const text = source.getText()
-        const originIndex = text.search(/parsed\.id\s*===\s*this\.instanceService\.getId\(\)/)
-        const digestIndex = text.indexOf("parsed.digest")
-        const emitIndex = text.indexOf("this.eventEmitter.emit")
-        if (originIndex < 0 || emitIndex < 0 || originIndex > emitIndex) {
-          context.report({ node, messageId: "origin" })
-        }
-        if (digestIndex < 0 || emitIndex < 0 || digestIndex > emitIndex) {
-          context.report({ node, messageId: "digest" })
-        }
-      },
-    }
-  },
-}
-
-const isEmitCallOnEventEmitterService = (node) =>
-  node.callee.type === "MemberExpression" &&
-  !node.callee.computed &&
-  node.callee.property.type === "Identifier" &&
-  node.callee.property.name === "emit" &&
-  node.callee.object.type === "MemberExpression" &&
-  !node.callee.object.computed &&
-  node.callee.object.property.type === "Identifier" &&
-  node.callee.object.property.name === "eventEmitterService"
-
-const findObjectProperty = (objectExpression, name) => {
-  if (!objectExpression || objectExpression.type !== "ObjectExpression") return null
-  return objectExpression.properties.find(
-    (property) => property.type === "Property" &&
-      !property.computed &&
-      (property.key.name === name || property.key.value === name),
-  ) || null
-}
-
-/** DELIVERY Rule 2 (DELIVERY-2): transport is declared per event in one config, never at the call site. */
-export const noCallSiteTransportOverride = {
-  meta: {
-    type: "problem",
-    docs: {
-      description: "DELIVERY Rule 2 (DELIVERY-2): transport is declared per event in the central config; it is never chosen at the call site.",
-    },
-    schema: [],
-    messages: {
-      callsite: "DELIVERY Rule 2 (DELIVERY-2): do not pass `options.useLocal`/`options.useNats` to `eventEmitterService.emit(...)`. Transport is part of the event's definition in the central config, not a per-call decision -- a call site choosing it is a promise the config never made and a reader has to guess at.",
-    },
-  },
-  create(context) {
-    return {
-      CallExpression(node) {
-        if (!isEmitCallOnEventEmitterService(node)) return
-        const args = node.arguments[0]
-        const optionsProperty = findObjectProperty(args, "options")
-        if (!optionsProperty) return
-        const optionsValue = optionsProperty.value
-        const hasUseLocal = findObjectProperty(optionsValue, "useLocal")
-        const hasUseNats = findObjectProperty(optionsValue, "useNats")
-        if (hasUseLocal || hasUseNats) {
-          context.report({ node: optionsProperty, messageId: "callsite" })
-        }
-      },
-    }
-  },
-}
-
-export const rules = {
-  "nats-bridge-delivery-contract": natsBridgeDeliveryContract,
-  "no-call-site-transport-override": noCallSiteTransportOverride,
-}
-
-export const recommended = {
-  "starci-be/nats-bridge-delivery-contract": "error",
-  "starci-be/no-call-site-transport-override": "error",
-}
+import { normalizePath } from "./lib/path.mjs"
+
+/** The NATS bridge rejects self-echo and claims redelivery before local fan-out. */
+export const natsBridgeDeliveryContract = {
+  meta: {
+    type: "problem",
+    docs: { description: "The central NATS bridge preserves cross-instance delivery invariants." },
+    schema: [],
+    messages: {
+      origin: "Drop envelopes whose producer id matches this instance before local emit.",
+      digest: "Claim/check the envelope digest before local emit so redelivery is idempotent.",
+    },
+  },
+  create(context) {
+    if (!normalizePath(context.filename || context.getFilename()).endsWith(
+      "/event/nats/nats-bridge.service.ts",
+    )) return {}
+    return {
+      "Program:exit"(node) {
+        const source = context.sourceCode || context.getSourceCode()
+        const text = source.getText()
+        const originIndex = text.search(/parsed\.id\s*===\s*this\.instanceService\.getId\(\)/)
+        const digestIndex = text.indexOf("parsed.digest")
+        const emitIndex = text.indexOf("this.eventEmitter.emit")
+        if (originIndex < 0 || emitIndex < 0 || originIndex > emitIndex) {
+          context.report({ node, messageId: "origin" })
+        }
+        if (digestIndex < 0 || emitIndex < 0 || digestIndex > emitIndex) {
+          context.report({ node, messageId: "digest" })
+        }
+      },
+    }
+  },
+}
+
+const isEmitCallOnEventEmitterService = (node) =>
+  node.callee.type === "MemberExpression" &&
+  !node.callee.computed &&
+  node.callee.property.type === "Identifier" &&
+  node.callee.property.name === "emit" &&
+  node.callee.object.type === "MemberExpression" &&
+  !node.callee.object.computed &&
+  node.callee.object.property.type === "Identifier" &&
+  node.callee.object.property.name === "eventEmitterService"
+
+const findObjectProperty = (objectExpression, name) => {
+  if (!objectExpression || objectExpression.type !== "ObjectExpression") return null
+  return objectExpression.properties.find(
+    (property) => property.type === "Property" &&
+      !property.computed &&
+      (property.key.name === name || property.key.value === name),
+  ) || null
+}
+
+/** DELIVERY Rule 2 (DELIVERY-2): transport is declared per event in one config, never at the call site. */
+export const noCallSiteTransportOverride = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "DELIVERY Rule 2 (DELIVERY-2): transport is declared per event in the central config; it is never chosen at the call site.",
+    },
+    schema: [],
+    messages: {
+      callsite: "DELIVERY Rule 2 (DELIVERY-2): do not pass `options.useLocal`/`options.useNats` to `eventEmitterService.emit(...)`. Transport is part of the event's definition in the central config, not a per-call decision -- a call site choosing it is a promise the config never made and a reader has to guess at.",
+    },
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (!isEmitCallOnEventEmitterService(node)) return
+        const args = node.arguments[0]
+        const optionsProperty = findObjectProperty(args, "options")
+        if (!optionsProperty) return
+        const optionsValue = optionsProperty.value
+        const hasUseLocal = findObjectProperty(optionsValue, "useLocal")
+        const hasUseNats = findObjectProperty(optionsValue, "useNats")
+        if (hasUseLocal || hasUseNats) {
+          context.report({ node: optionsProperty, messageId: "callsite" })
+        }
+      },
+    }
+  },
+}
+
+export const rules = {
+  "nats-bridge-delivery-contract": natsBridgeDeliveryContract,
+  "no-call-site-transport-override": noCallSiteTransportOverride,
+}
+
+export const recommended = {
+  "starci-be/nats-bridge-delivery-contract": "error",
+  "starci-be/no-call-site-transport-override": "error",
+}

package/idempotency.mjs

@@ -0,0 +1,101 @@
+/**
+ * The rule that holds inbox dedupe (catalog R80 `BE_INBOX_DEDUPE_MISSING`).
+ *
+ * A sender that gets no timely reply resends: a payment provider retries a webhook, a queue
+ * redelivers a message it never saw acknowledged. The standard is one inbox table keyed by
+ * `(source, event id)` in front of every door delivery can repeat through, so a repeat is a no-op
+ * instead of a second charge, a second email or a second state transition.
+ *
+ *   - `inbox-dedupe-required` refuses a `@Public()` webhook controller method, or an outbox/queue
+ *     consumer, whose file shows no reference to an inbox or dedupe port. A consumer is recognized
+ *     by more than its filename: `<event>.consumer.ts` under `transport/message/` (the
+ *     `be.transport.message` slot) still counts, and so does a method decorated `@EventPattern`,
+ *     `@MessagePattern`, `@OnEvent` or `@Process`, or a class whose name ends `Consumer` or
+ *     `OutboxConsumer`, wherever that file sits. A class that only PUBLISHES - the producer half of
+ *     an outbox, typically `*-outbox.service.ts` / `*OutboxService` - carries none of those shapes
+ *     and is not flagged: it has no repeat delivery to dedupe unless it also consumes.
+ *
+ * This reads one file's text for the shape of a claim (`inbox`, `dedupe`, `idempoten*` naming a
+ * port, a field or a call) - it cannot see whether the call actually runs before the side effect,
+ * which needs the call graph and stays a review question, same as `no-outer-manager-in-transaction`
+ * says for its own undecidable half.
+ */
+import { decoratorName, keyName, staticText } from "./lib/ast.mjs"
+import { isTestLane, normalizePath } from "./lib/path.mjs"
+
+const INBOX_REFERENCE = /inbox|dedupe|idempoten/i
+const CONSUMER_FILE = /\/transport\/message\/[^/]+\.consumer\.ts$/
+const WEBHOOK_FILE = /\/transport\/http\/[^/]*webhook[^/]*\.controller\.ts$/i
+/** A class whose name alone says it consumes a delivery, regardless of where the file sits. */
+const CONSUMER_CLASS_NAME = /(?:Outbox)?Consumer$/
+/** A method decorator that binds a handler to an incoming message or event, not just a filename convention. */
+const CONSUMER_DECORATORS = new Set(["EventPattern", "MessagePattern", "OnEvent", "Process"])
+
+/** The route or reason text a `@Public()` decorator's argument carries, lower-cased. */
+const publicReason = (node) => {
+    const expression = node.expression
+    const argument = expression.type === "CallExpression" ? expression.arguments[0] : undefined
+    if (argument?.type !== "ObjectExpression") return ""
+    const property = argument.properties.find((item) => item.type === "Property" && keyName(item.key) === "reason")
+    return (property ? staticText(property.value) : null)?.toLowerCase() ?? ""
+}
+
+/** A webhook door: the file is named for one, the open door names its reason, or the route itself does. */
+const isWebhookController = (filename, sourceText, publicDecorators) =>
+    WEBHOOK_FILE.test(filename)
+    || publicDecorators.some((node) => /webhook/.test(publicReason(node)))
+    || /@Controller\(\s*["'`][^"'`]*webhook/i.test(sourceText)
+
+/** Delivery this instance can receive more than once shows a claim against the inbox before it acts. */
+export const inboxDedupeRequired = {
+    meta: {
+        type: "problem",
+        docs: { description: "A `@Public()` webhook handler and an outbox/queue consumer claim the event through the shared inbox before they act." },
+        schema: [],
+        messages: {
+            webhook: "This webhook controller has no reference to an inbox or dedupe port. A sender that gets no timely reply resends the same event; claim `(source, event id)` in the shared inbox before acting, so a repeat delivery is a no-op.",
+            consumer: "This consumer has no reference to an inbox or dedupe port. A queue redelivers a message it never saw acknowledged; claim `(source, event id)` in the shared inbox before acting, so a redelivery is a no-op.",
+        },
+    },
+    create(context) {
+        const filename = normalizePath(context.filename || context.getFilename())
+        if (isTestLane(filename)) return {}
+        let isConsumer = CONSUMER_FILE.test(filename)
+        const publicDecorators = []
+        return {
+            Decorator(node) {
+                const name = decoratorName(node)
+                if (name === "Public") publicDecorators.push(node)
+                else if (CONSUMER_DECORATORS.has(name)) isConsumer = true
+            },
+            ClassDeclaration(node) {
+                if (node.id && CONSUMER_CLASS_NAME.test(node.id.name)) isConsumer = true
+            },
+            ClassExpression(node) {
+                if (node.id && CONSUMER_CLASS_NAME.test(node.id.name)) isConsumer = true
+            },
+            "Program:exit"(node) {
+                const sourceCode = context.sourceCode || context.getSourceCode()
+                const text = sourceCode.getText()
+                if (INBOX_REFERENCE.test(text)) return
+                if (isConsumer) {
+                    context.report({ node, messageId: "consumer" })
+                    return
+                }
+                if (publicDecorators.length && isWebhookController(filename, text, publicDecorators)) {
+                    context.report({ node, messageId: "webhook" })
+                }
+            },
+        }
+    },
+}
+
+/** The rule this law contributes to the plugin. */
+export const rules = {
+    "inbox-dedupe-required": inboxDedupeRequired,
+}
+
+/** Starts at error: a duplicate charge or a duplicate side effect is never a warning. */
+export const recommended = {
+    "starci-be/inbox-dedupe-required": "error",
+}