@starci/eslint-canon-be 1.2.2 → 1.7.0

package/cqrs.mjs

@@ -22,10 +22,6 @@
  * have reported on more correct files than wrong ones, which is precisely the failure mode this law
  * warns against - it would have taught everybody to disable it. The law's own "documented" tier for
  * CQRS-1 is the honest answer, not a gap to close.
- *
- * Rule 5 (CQRS-5) is the opposite case: a handler returning `{ success: false }` or `{ error }`
- * instead of throwing is a shape a parser CAN see, narrowly, without guessing at intent - and this
- * reference repository has two real handlers doing exactly that today.
  */
 
 import { normalizePath } from "./lib/path.mjs"
@@ -150,153 +146,23 @@ export const messageCarriesParamsOnly = {
   },
 }
 
-// -- CQRS-7 ----------------------------------------------------------------------------------------
-
-/**
- * A handler has its twin spec beside it.
- *
- * The check is the FILENAME, not the disk: a rule that stats the filesystem reports differently
- * depending on what else is checked out, and a rule whose answer depends on the working tree is one
- * nobody can reproduce. This rule fires on the handler and names the file that should exist; a gate
- * that walks the tree is what counts them.
- */
-export const handlerHasTwinSpec = {
-  meta: {
-    type: "problem",
-    docs: { description: "A CQRS handler declares its twin spec filename in the same folder." },
-    schema: [
-      {
-        type: "object",
-        properties: { specs: { type: "array", items: { type: "string" } } },
-        additionalProperties: false,
-      },
-    ],
-    messages: {
-      missing:
-        "`{{operation}}.handler.ts` has no `{{operation}}.handler.spec.ts` beside it. The decisions live in the handler, so an untested handler is an untested decision - and a spec in the same folder is found by whoever edits the handler rather than by whoever goes looking in a test tree.",
-    },
-  },
-  create(context) {
-    const filename = context.filename || context.getFilename()
-    const operation = handlerFile(filename)
-    if (!operation) return {}
-    const options = context.options && context.options[0]
-    const known = options && Array.isArray(options.specs) ? options.specs : null
-    if (!known) return {}
-    if (known.includes(`${operation}.handler.spec.ts`)) return {}
-    return {
-      "Program:exit"(node) {
-        context.report({ node, messageId: "missing", data: { operation } })
-      },
-    }
-  },
-}
-
-// -- CQRS-5 ----------------------------------------------------------------------------------------
-
-/** The property name that turns a returned object into an encoded failure, or null. */
-const encodedFailureKey = (node) => {
-  if (!node || node.type !== "ObjectExpression") return null
-  for (const prop of node.properties || []) {
-    if (prop.type !== "Property") continue
-    const key = prop.key
-    const name = key.type === "Identifier" ? key.name : key.type === "Literal" && typeof key.value === "string" ? key.value : null
-    if (!name) continue
-    // `error` is the encode regardless of what carries it - a caught exception, a message string,
-    // an upstream response. Its presence on a RETURNED object is the tell: the branch that found
-    // the failure chose to hand it back instead of throwing it.
-    if (name === "error") return name
-    // `success`/`ok` only encode failure at `false` - `success: true` on the happy path is not
-    // this pattern, and flagging it would report the correct half of every handler that uses this
-    // shape at all.
-    if ((name === "success" || name === "ok") && prop.value && prop.value.type === "Literal" && prop.value.value === false) {
-      return name
-    }
-  }
-  return null
-}
-
-/** The nearest enclosing method named `process`, or null. */
-const enclosingProcessMethod = (node) => {
-  for (let current = node.parent; current; current = current.parent) {
-    if (current.type === "MethodDefinition" && current.key && current.key.name === "process") return current
-  }
-  return null
-}
-
-/** The nearest enclosing class declaration, or null. */
-const enclosingClass = (node) => {
-  for (let current = node.parent; current; current = current.parent) {
-    if (current.type === "ClassDeclaration") return current
-  }
-  return null
-}
-
-/** A handler that cannot do its work throws the domain exception naming why - it does not return one. */
-export const noHandlerEncodedFailure = {
-  meta: {
-    type: "problem",
-    docs: {
-      description:
-        "A CQRS handler throws the domain exception that names a failure; it does not return a success/error shape (Law 5, CQRS-5).",
-    },
-    schema: [],
-    messages: {
-      encoded:
-        "`{{name}}`'s `process` returns an object carrying `{{key}}` instead of throwing. CQRS-5: a handler that cannot do its work throws the domain exception naming why; an encoded `{{key}}` field asks every caller to decode this shape its own way, and the REASON for the refusal never arrives - only the fact that there was one. Throw the exception that names why, in the branch that discovers it, and let the success path return the value itself.",
-    },
-  },
-  create(context) {
-    const filename = context.filename || context.getFilename()
-    const operation = handlerFile(filename)
-    if (!operation) return {}
-    return {
-      ReturnStatement(node) {
-        const key = encodedFailureKey(node.argument)
-        if (!key) return
-        // Scoped to `process` on a decorated handler, same as CQRS-3 - a private mapper in the
-        // same file returning an unrelated object shaped like `{ error: ... }` is not this
-        // handler's refusal path, and a rule that fired anywhere in the file would not be able to
-        // tell the two apart.
-        if (!enclosingProcessMethod(node)) return
-        const klass = enclosingClass(node)
-        if (!klass || !decoratorNames(klass).some((name) => HANDLER_DECORATORS.test(name))) return
-        context.report({ node: node.argument, messageId: "encoded", data: { name: operation, key } })
-      },
-    }
-  },
-}
-
 /** The rules this law contributes to the plugin. */
 export const rules = {
   "handler-overrides-process": handlerOverridesProcess,
   "message-carries-params-only": messageCarriesParamsOnly,
-  "handler-has-twin-spec": handlerHasTwinSpec,
-  "no-handler-encoded-failure": noHandlerEncodedFailure,
 }
 
 /**
  * The level this law asks for, as the plugin's own opinion.
  *
- * MEASURED AGAINST THE REFERENCE REPOSITORY, not estimated: 3 of 141 handlers override `execute`,
- * 2 of 138 messages carry something other than a single `params`, and 2 of 152 handlers return an
- * encoded failure (`sync-flashcard-quiz-session-progress.handler.ts` and
- * `sync-mock-interview-session-turns.handler.ts` both `return { success: false }` where a late sync
- * finds its session already closed). Debt above zero means the rule lands at `warn` with the count
- * beside it, gets burned down, and flips to `error` at zero - shipping at `error` with debt
- * outstanding blocks every commit that touches an offender.
- *
- * COUNT ONLY THIS RULE'S REPORTS when measuring. Inline `eslint-disable` comments in the source
- * refer to rules a minimal measuring config never loads, and eslint reports each of those as a
- * problem of its own - which inflated the first measurement of every rule here by the same seven
- * files, and this rule's by two.
+ * Both measured at zero debt in the reference repository (3 of 141 handlers overrode `execute` and
+ * 2 of 138 messages carried more than `params`; both were burned down), so both are `error`.
  *
- * `handler-has-twin-spec` is off by default because it needs the folder listing passed as an
- * option; a repository that wires it supplies the listing from its own gate.
+ * The twin-spec count rule and the encoded-failure rule are gone. Test selection follows behavior and
+ * risk, not a filename count; and HFS returns an expected refusal as a typed outcome union, so a
+ * handler that returns `{ success: false }` is no longer a defect this canon can call by shape.
  */
 export const recommended = {
-  "starci-be/handler-overrides-process": "error", // no=0 of 141 - burned down from 3
-  "starci-be/message-carries-params-only": "error", // no=0 of 138 - burned down from 2
-  "starci-be/handler-has-twin-spec": "off", // needs the folder listing as an option; a repo that wires it turns this on
-  "starci-be/no-handler-encoded-failure": "warn", // no=2 of 152 handlers - debt outstanding, burn down before flipping to error
+  "starci-be/handler-overrides-process": "error",
+  "starci-be/message-carries-params-only": "error",
 }

package/data-access.mjs

@@ -22,8 +22,20 @@
  *
  * Both remaining gaps are read by a person; a rule that guessed at either would fire on correct
  * code, which is how a correct rule gets disabled.
+ *
+ * `no-external-call-in-transaction` (R82 `BE_TRANSACTION_EXTERNAL_CALL`) refuses `fetch`, an HTTP
+ * client call or any method of a `*Client`/`*Sdk` receiver written inside `.transaction(async (tx) =>
+ * ...)`. Holding the transaction open for as long as the external call takes means a failure after
+ * partial commit, or a success the rollback then reverses with no way back; the fix is to commit
+ * first and call out after, or to write an outbox message inside the transaction instead.
+ *
+ * `named-entity-manager-only` (R83 `BE_UNNAMED_DATA_ACCESS`) holds the one way a use case reaches the
+ * database: the shared `EntityManager` injected through a named injector and called directly. It refuses a bare
+ * `@InjectEntityManager()`, any `.getRepository(...)` call, and an injected `DataSource` outside the platform
+ * database module and `apps/migrate`. `no-injected-repository` refuses `@InjectRepository` and `Repository<T>` in the same spirit.
  */
 
+import { walk } from "./lib/ast.mjs"
 import { normalizePath } from "./lib/path.mjs"
 
 /** A parameter property (`private readonly x: T`) wraps the parameter it declares. */
@@ -97,21 +109,28 @@ export const mustInjectEntityManager = {
 export const noInjectedRepository = {
   meta: {
     type: "problem",
-    docs: { description: "Persistence goes through `EntityManager`, never an injected repository." },
+    docs: { description: "Persistence goes through the shared `EntityManager`, never an injected repository." },
     schema: [],
     messages: {
       repo:
-        "Inject `EntityManager` instead of a repository. A repository is bound to ONE entity, so it cannot carry a transaction into a second table - and a use case that grows a second write then has to be rewritten rather than extended.",
+        "Inject the shared EntityManager with the named injector and call it directly. A repository is bound to ONE entity, so it cannot carry a transaction into a second table - and a use case that grows a second write then has to be rewritten rather than extended.",
     },
   },
   create(context) {
     return {
+      // `@InjectRepository(...)` is refused wherever it is written: a constructor parameter, a property, a method parameter.
+      Decorator(node) {
+        const expression = node.expression
+        if (expression.type === "CallExpression" && expression.callee.type === "Identifier" && expression.callee.name === "InjectRepository") {
+          context.report({ node, messageId: "repo" })
+        }
+      },
       MethodDefinition(node) {
         for (const original of constructorParams(node)) {
           const param = unwrapParam(original)
-          const byDecorator = paramDecorators(original).includes("InjectRepository")
-          const byType = REPOSITORY_TYPES.test(paramTypeName(param) || "")
-          if (byDecorator || byType) context.report({ node: param, messageId: "repo" })
+          // A decorated parameter is reported once, by the Decorator visitor.
+          if (paramDecorators(original).includes("InjectRepository")) continue
+          if (REPOSITORY_TYPES.test(paramTypeName(param) || "")) context.report({ node: param, messageId: "repo" })
         }
       },
     }
@@ -274,6 +293,129 @@ export const noEagerRelation = {
   },
 }
 
+// -- DATA-6 (R82) ------------------------------------------------------------------------------------
+
+const HTTP_RECEIVER = /^(?:axios|http|httpService|httpClient|axiosInstance)$/
+const HTTP_METHODS = new Set(["get", "post", "put", "patch", "delete", "head", "request"])
+/** A receiver named for an integration client or SDK: `stripeClient`, `this.paymentSdk`. */
+const EXTERNAL_RECEIVER = /(?:Client|Sdk)$/
+
+const calleeMethodName = (callee) =>
+  callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" ? callee.property.name : null
+
+const calleeReceiverName = (callee) => {
+  if (callee.type !== "MemberExpression") return null
+  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
+}
+
+/** Whether `node` is a call this law treats as reaching an external system: `fetch`, an HTTP client, or any method of a `*Client`/`*Sdk`. */
+const isExternalCall = (node) => {
+  if (node.type !== "CallExpression") return false
+  const { callee } = node
+  if (callee.type === "Identifier" && callee.name === "fetch") return true
+  const method = calleeMethodName(callee)
+  const receiver = calleeReceiverName(callee)
+  if (!method || !receiver) return false
+  if (HTTP_RECEIVER.test(receiver) && HTTP_METHODS.has(method)) return true
+  return EXTERNAL_RECEIVER.test(receiver)
+}
+
+/** A short label for a reported call: `stripeClient.charge`, `fetch`. */
+const describeCall = (node) => {
+  const { callee } = node
+  if (callee.type === "Identifier") return callee.name
+  const method = calleeMethodName(callee) ?? "?"
+  const receiver = calleeReceiverName(callee) ?? "?"
+  return `${receiver}.${method}`
+}
+
+/** No transaction spans an external call: commit first, then call out (or write an outbox message inside the transaction). */
+export const noExternalCallInTransaction = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "An HTTP or SDK call does not run inside `.transaction(async (tx) => ...)`.",
+    },
+    schema: [],
+    messages: {
+      external:
+        "`{{call}}` runs inside `.transaction(...)`. A database transaction held open for as long as an external call takes means: the call fails after the transaction already did its work and now has to be undone by hand, or the call succeeds and the transaction then rolls back, and the two systems disagree with no way back. Commit the transaction, then make the call - or write an outbox message inside the transaction and let a worker deliver it after commit.",
+    },
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        const callee = node.callee
+        if (callee.type !== "MemberExpression" || callee.computed) return
+        if (callee.property.type !== "Identifier" || callee.property.name !== "transaction") return
+        const callback = node.arguments[0]
+        if (!callback || (callback.type !== "ArrowFunctionExpression" && callback.type !== "FunctionExpression")) return
+        walk(callback.body, (child) => {
+          if (isExternalCall(child)) context.report({ node: child, messageId: "external", data: { call: describeCall(child) } })
+        })
+      },
+    }
+  },
+}
+
+// -- DATA-7 (R83) ------------------------------------------------------------------------------------
+
+/** Files that build the connections: the platform database module and the migrate app. */
+const CONNECTION_BUILDER = /(?:^|\/)(?:platform\/(?:databases?|db|datasource|typeorm)|apps\/migrate)\//
+
+/** The one way a use case reaches the database: the shared `EntityManager`, named, then called directly. */
+export const namedEntityManagerOnly = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "The shared EntityManager is injected through a named injector and called directly; no bare `@InjectEntityManager()`, no `getRepository`, no injected `DataSource` (data-access.md DATA-7, R83).",
+    },
+    schema: [],
+    messages: {
+      unnamed:
+        "`@InjectEntityManager()` names no connection, and this application registers more than one - so it points at whichever is default. Inject the shared EntityManager with the named injector (`InjectPrimaryEntityManager()`, `InjectAgentOsEntityManager()`, `InjectExpertAcademyEntityManager()`, or `@InjectEntityManager(<CONNECTION_TOKEN>)`) and call it directly.",
+      getRepository:
+        "`.getRepository(...)` binds a handle to ONE entity and hides which connection it came from. Inject the shared EntityManager with the named injector and call it directly: `manager.find(Entity, ...)`, `manager.save(Entity, ...)`, `tx.insert(Entity, ...)`.",
+      dataSource:
+        "`DataSource` is injected here to reach the database. Inject the shared EntityManager with the named injector and call it directly; a `DataSource` is built only by the platform database module.",
+    },
+  },
+  create(context) {
+    const filename = normalizePath(context.filename || context.getFilename())
+    if (/\.d\.[cm]?ts$/.test(filename) || /\.(?:spec|test)\.[cm]?[jt]sx?$/.test(filename)) return {}
+    const mayBuildConnections = CONNECTION_BUILDER.test(filename)
+    return {
+      Decorator(node) {
+        const expression = node.expression
+        if (expression.type !== "CallExpression" || expression.callee.type !== "Identifier") return
+        if (expression.callee.name === "InjectEntityManager" && expression.arguments.length === 0) {
+          context.report({ node, messageId: "unnamed" })
+        }
+      },
+      CallExpression(node) {
+        const callee = node.callee
+        if (callee.type !== "MemberExpression" || callee.computed) return
+        if (callee.property.type === "Identifier" && callee.property.name === "getRepository") {
+          context.report({ node, messageId: "getRepository" })
+        }
+      },
+      MethodDefinition(node) {
+        if (mayBuildConnections) return
+        for (const original of constructorParams(node)) {
+          const param = unwrapParam(original)
+          const byType = paramTypeName(param) === "DataSource"
+          const byDecorator = paramDecorators(original).some((name) => name === "InjectDataSource" || name === "InjectConnection")
+          if (byType || byDecorator) context.report({ node: param, messageId: "dataSource" })
+        }
+      },
+    }
+  },
+}
+
 /** The rules this law contributes to the plugin. */
 export const rules = {
   "must-inject-entity-manager": mustInjectEntityManager,
@@ -281,6 +423,8 @@ export const rules = {
   "require-entity-table-name": requireEntityTableName,
   "no-outer-manager-in-transaction": noOuterManagerInTransaction,
   "no-eager-relation": noEagerRelation,
+  "no-external-call-in-transaction": noExternalCallInTransaction,
+  "named-entity-manager-only": namedEntityManagerOnly,
 }
 
 /**
@@ -300,6 +444,8 @@ export const recommended = {
   "starci-be/require-entity-table-name": "error",
   "starci-be/no-outer-manager-in-transaction": "error",
   "starci-be/no-eager-relation": "error",
+  "starci-be/no-external-call-in-transaction": "error",
+  "starci-be/named-entity-manager-only": "error",
 }
 
 /** Path helper shared with the other backend law modules. */

package/default-deny.mjs

@@ -0,0 +1,116 @@
+/**
+ * The rules that hold the transport half of HFS default-deny (catalog R41 `BE_DEFAULT_DENY`).
+ *
+ * Every route needs a signed-in principal unless it says otherwise, and every body has a type:
+ *
+ *   - `no-untyped-body` refuses a `@Body()` (or `@Args()`) parameter with no type, `unknown`, `any`, `object`,
+ *     `{}` or `Record<string, unknown>`; it refuses `GraphQLJSON` as a tunnel around the schema; and it refuses
+ *     a `switch (input.operation)` in a transport file, because each operation is its own typed operation.
+ *   - `public-needs-reason` refuses `@Public()` without `{ reason: "<why>" }`. An open door states why it is
+ *     open, so the list of open doors can be read and reviewed.
+ *
+ * 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 { decoratorName, keyName, staticText } from "./lib/ast.mjs"
+import { isDeclarationFile, normalizePath } from "./lib/path.mjs"
+
+const BODY_DECORATORS = new Set(["Body", "Args"])
+
+const isUntyped = (annotation) => {
+    if (!annotation) return true
+    const type = annotation.typeAnnotation
+    if (!type) return true
+    if (["TSUnknownKeyword", "TSAnyKeyword", "TSObjectKeyword"].includes(type.type)) return true
+    if (type.type === "TSTypeLiteral" && type.members.length === 0) return true
+    if (type.type === "TSTypeReference" && type.typeName.type === "Identifier" && type.typeName.name === "Record") {
+        const value = type.typeArguments?.params?.[1] ?? type.typeParameters?.params?.[1]
+        return value?.type === "TSUnknownKeyword" || value?.type === "TSAnyKeyword"
+    }
+    return false
+}
+
+/** A body or argument carries a declared type, never `unknown`, `any` or GraphQLJSON. */
+export const noUntypedBody = {
+    meta: {
+        type: "problem",
+        docs: { description: "`@Body()` and `@Args()` parameters are typed; no GraphQLJSON tunnel; no `switch (input.operation)`." },
+        schema: [],
+        messages: {
+            untyped: "This `@{{decorator}}()` parameter has no useful type. Declare a DTO class or contract type so the framework validates the input.",
+            json: "`GraphQLJSON` tunnels untyped data through the schema. Declare an input type with the fields the operation needs.",
+            operationSwitch: "`switch` on an `operation` field dispatches several operations through one untyped door. Make each operation its own typed resolver or controller method.",
+        },
+    },
+    create(context) {
+        const filename = normalizePath(context.filename || context.getFilename())
+        if (isDeclarationFile(filename)) return {}
+        const inTransport = filename.includes("/transport/")
+        return {
+            Identifier(node) {
+                if (node.name === "GraphQLJSON" && !/^Import.*Specifier$/.test(node.parent?.type ?? "")) {
+                    context.report({ node, messageId: "json" })
+                }
+            },
+            SwitchStatement(node) {
+                const discriminant = node.discriminant
+                if (inTransport && discriminant.type === "MemberExpression" && keyName(discriminant.property) === "operation") {
+                    context.report({ node, messageId: "operationSwitch" })
+                }
+            },
+            Decorator(node) {
+                const name = decoratorName(node)
+                if (!BODY_DECORATORS.has(name)) return
+                const parameter = node.parent
+                if (!parameter) return
+                const bound = parameter.type === "TSParameterProperty" ? parameter.parameter : parameter
+                if (bound.type !== "Identifier" && bound.type !== "ObjectPattern" && bound.type !== "AssignmentPattern") return
+                const annotated = bound.type === "AssignmentPattern" ? bound.left : bound
+                if (isUntyped(annotated.typeAnnotation)) {
+                    context.report({ node, messageId: "untyped", data: { decorator: name } })
+                }
+            },
+        }
+    },
+}
+
+/** An open door states why it is open. */
+export const publicNeedsReason = {
+    meta: {
+        type: "problem",
+        docs: { description: "`@Public()` carries `{ reason: \"<why>\" }`." },
+        schema: [],
+        messages: {
+            reason: "`@Public()` has no reason. Write `@Public({ reason: \"<why this operation is open>\" })` so the open doors can be reviewed.",
+        },
+    },
+    create(context) {
+        const filename = normalizePath(context.filename || context.getFilename())
+        if (isDeclarationFile(filename)) return {}
+        return {
+            Decorator(node) {
+                if (decoratorName(node) !== "Public") return
+                const expression = node.expression
+                const argument = expression.type === "CallExpression" ? expression.arguments[0] : undefined
+                let reason = null
+                if (argument?.type === "ObjectExpression") {
+                    const property = argument.properties.find((item) => item.type === "Property" && keyName(item.key) === "reason")
+                    reason = property ? staticText(property.value) : null
+                }
+                if (reason === null || reason.trim() === "") context.report({ node, messageId: "reason" })
+            },
+        }
+    },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "no-untyped-body": noUntypedBody,
+    "public-needs-reason": publicNeedsReason,
+}
+
+/** Both start at error: an untyped door and an unexplained open door are the failures this law exists for. */
+export const recommended = {
+    "starci-be/no-untyped-body": "error",
+    "starci-be/public-needs-reason": "error",
+}