@starci/eslint-canon-be 1.1.0 → 1.2.0

package/data-access.mjs

@@ -1,14 +1,27 @@
 /**
  * The rules that hold `data-access.md`.
  *
- * Three rules, all reading a constructor parameter or a decorator, all exact - there is no
- * heuristic here and no judgement to get wrong, which is why all three can be switched on without
- * a burn-down in a codebase that already follows them.
+ * The first three read a constructor parameter or a decorator, all exact - there is no heuristic
+ * here and no judgement to get wrong, which is why all three can be switched on without a burn-down
+ * in a codebase that already follows them.
  *
- * The two rules canon does NOT try to enforce are worth naming so nobody adds them badly. Whether a
- * helper was handed the caller's transactional manager (DATA-4) needs the call graph, and whether a
- * relation should have been asked for at the call site (DATA-5) needs to know what the answer is
- * for. Both are read by a person; a rule that guessed would fire on correct code.
+ * The next two hold a narrower, exact slice of DATA-4 (Rule 5) and DATA-5 (Rule 6) - the slice of
+ * each that a single file settles on its own, with no call graph and no knowledge of intent needed.
+ *
+ * `no-outer-manager-in-transaction` catches the one shape of DATA-4 a parser can see: a
+ * `this.<field>.transaction(async (tx) => ...)` callback whose body reaches for `this.<field>`
+ * again instead of `tx`. That field held the manager from BEFORE the transaction opened, so a call
+ * through it runs and commits on its own - the exact "half of it was written" bug DATA-4 names. What
+ * it does NOT see, and cannot: whether a HELPER defined in another file was handed `tx` by ITS
+ * caller. That still needs the call graph and stays undecidable, same as the law says.
+ *
+ * `no-eager-relation` catches the one shape of DATA-5 a parser can see: `eager: true` written on a
+ * relation decorator. What it does NOT see: whether a call site correctly asked for a relation it
+ * needed. That still needs to know what the answer is for and stays undecidable, same as the law
+ * says.
+ *
+ * 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.
  */
 
 /** Forward-slash form of a filename, so Windows paths compare like every other path. */
@@ -149,24 +162,145 @@ export const requireEntityTableName = {
   },
 }
 
+// -- DATA-4 (Rule 5) --------------------------------------------------------------------------------
+
+/** Node types that rebind `this` - a `this.<field>` read past one of these belongs to a different call. */
+const REBINDS_THIS = /^(?:FunctionDeclaration|FunctionExpression|ClassDeclaration|ClassExpression)$/
+
+/** Walk every descendant of `node` that still runs under the SAME `this`, calling `visit` on each. */
+const walkPreservingThis = (node, visit) => {
+  if (!node || typeof node.type !== "string") return
+  visit(node)
+  for (const key of Object.keys(node)) {
+    if (key === "parent") continue
+    const value = node[key]
+    if (Array.isArray(value)) {
+      for (const child of value) {
+        if (child && typeof child.type === "string" && !REBINDS_THIS.test(child.type)) walkPreservingThis(child, visit)
+      }
+    } else if (value && typeof value.type === "string" && !REBINDS_THIS.test(value.type)) {
+      walkPreservingThis(value, visit)
+    }
+  }
+}
+
+/** Everything inside a transaction receives the transactional manager, not the outer injected one. */
+export const noOuterManagerInTransaction = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Inside `this.<field>.transaction(async (tx) => ...)`, every call uses `tx` - never `this.<field>` again (data-access.md DATA-4, Rule 5).",
+    },
+    schema: [],
+    messages: {
+      outerManager:
+        "This is inside `this.{{field}}.transaction(...)`, but it reaches for `this.{{field}}` again instead of `{{param}}`, the manager the callback received. `this.{{field}}` is the manager from BEFORE the transaction opened - a call through it runs and commits on its own, which is how half a write survives a rollback. Use `{{param}}`.",
+    },
+  },
+  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 object = callee.object
+        if (object.type !== "MemberExpression" || object.computed) return
+        if (object.object.type !== "ThisExpression") return
+        if (object.property.type !== "Identifier") return
+        const field = object.property.name
+        // Only the arrow-function callback is covered. A plain `function (tx) {}` callback does not
+        // inherit `this` from the enclosing method at all - TypeORM invokes it with no receiver, so
+        // `this.<field>` inside one throws rather than silently escaping the transaction, and this
+        // rule exists for the silent case.
+        const callback = node.arguments[0]
+        if (!callback || callback.type !== "ArrowFunctionExpression") return
+        const param = callback.params[0]
+        const paramName = param && param.type === "Identifier" ? param.name : "the transactional manager"
+        walkPreservingThis(callback.body, (descendant) => {
+          if (
+            descendant.type === "MemberExpression"
+            && !descendant.computed
+            && descendant.object.type === "ThisExpression"
+            && descendant.property.type === "Identifier"
+            && descendant.property.name === field
+          ) {
+            context.report({ node: descendant, messageId: "outerManager", data: { field, param: paramName } })
+          }
+        })
+      },
+    }
+  },
+}
+
+// -- DATA-5 (Rule 6) --------------------------------------------------------------------------------
+
+/** Relation decorators whose `eager` option can grant the relation to every caller. */
+const RELATION_DECORATORS = /^(?:ManyToOne|OneToOne|OneToMany|ManyToMany)$/
+
+/** A relation is asked for by the call site that needs it; the entity grants no relation eagerly. */
+export const noEagerRelation = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "A relation decorator carries no `eager: true` (data-access.md DATA-5, Rule 6).",
+    },
+    schema: [],
+    messages: {
+      eager:
+        "`@{{decorator}}(..., { eager: true })` grants this relation to every caller whether it asked for it or not, so a query that wants one column now pays for the whole tree. State the relation in the `relations` the call site writes, and drop `eager` here.",
+    },
+  },
+  create(context) {
+    return {
+      Decorator(node) {
+        const expression = node.expression
+        if (expression.type !== "CallExpression") return
+        if (expression.callee.type !== "Identifier" || !RELATION_DECORATORS.test(expression.callee.name)) return
+        for (const argument of expression.arguments) {
+          if (argument.type !== "ObjectExpression") continue
+          const eagerProperty = argument.properties.find(
+            (property) =>
+              property.type === "Property"
+              && !property.computed
+              && (property.key.name === "eager" || property.key.value === "eager"),
+          )
+          if (!eagerProperty) continue
+          if (eagerProperty.value.type === "Literal" && eagerProperty.value.value === true) {
+            context.report({ node, messageId: "eager", data: { decorator: expression.callee.name } })
+          }
+        }
+      },
+    }
+  },
+}
+
 /** The rules this law contributes to the plugin. */
 export const rules = {
   "must-inject-entity-manager": mustInjectEntityManager,
   "no-injected-repository": noInjectedRepository,
   "require-entity-table-name": requireEntityTableName,
+  "no-outer-manager-in-transaction": noOuterManagerInTransaction,
+  "no-eager-relation": noEagerRelation,
 }
 
 /**
  * The level this law asks for, as the plugin's own opinion.
  *
- * All three measured at zero debt in the reference repository, so all three ship at `error`. A
- * repository adopting them into an existing tree measures first and lands anything above zero at
- * `warn` with the count beside it.
+ * All five measured against the reference repository (`src/**`) before shipping. The original three
+ * measured at zero debt and ship at `error`. `no-outer-manager-in-transaction` also measured zero -
+ * every `.transaction(async (tx) => ...)` callback in the reference repository already uses only the
+ * parameter it was handed - and ships at `error`. `no-eager-relation` also measured zero - no entity
+ * in the reference repository declares `eager: true` - and ships at `error` as well; a repository
+ * adopting these into a tree that is not already clean measures first and lands anything above zero
+ * at `warn` with the count beside it.
  */
 export const recommended = {
   "starci-be/must-inject-entity-manager": "error",
   "starci-be/no-injected-repository": "error",
   "starci-be/require-entity-table-name": "error",
+  "starci-be/no-outer-manager-in-transaction": "error",
+  "starci-be/no-eager-relation": "error",
 }
 
 /** Path helper shared with the other backend law modules. */

package/e2e-flow.mjs

@@ -14,15 +14,23 @@
  *   - E2E-2 (named steps, not one long case). Counting `it` blocks would refuse a flow that is
  *     genuinely one step, and a rule whose first false positive is legitimate teaches authors that
  *     the rule is wrong rather than that they are.
- *   - E2E-5, E2E-6 and E2E-9 turn on WHAT is asserted or WHO is acting, which is meaning.
- *   - E2E-8 (one place stands the world up) is a fact about a repository's fixtures, not about a
- *     file, so it belongs to a gate that can see the tree rather than to a rule that sees one file.
+ *   - E2E-5, E2E-6 and E2E-9 turn on WHAT is asserted or WHO is acting, which is meaning. E2E-6 in
+ *     particular has no shape to deny: absence is proved through a stored row, a socket silence
+ *     window, or a rejected promise depending on the flow, and a rule narrow enough to accept all
+ *     three accepts everything. E2E-9's ban on a shared actor is a fact about TWO files at once,
+ *     which one file's AST cannot see.
+ *   - E2E-8 (one place stands the world up) is STILL a fact about a repository's fixtures for its
+ *     first half, not about one file, so THAT half belongs to a gate that can see the tree. Its
+ *     second half - "a spec file contains no wiring of its own" - is a per-file shape after all, the
+ *     same kind of shape `e2e-uses-production-transport` already refuses for buses and workers, and
+ *     is added below.
  *   - E2E-10 (a flow logs nothing) is already held: `no-console` and `no-framework-logger` in the
  *     observability law cover every call site, and a second rule saying the same thing in this lane
- *     would double every report.
+ *     would double every report. It stays undeclared here on purpose, not by oversight.
  *
- * The rules below enforce only exact syntax: transport bypass, absence of any persisted-state read,
- * direct provider imports, sleeps and branches. They do not pretend to judge business meaning.
+ * The rules below enforce only exact syntax: transport bypass, wiring built inline instead of
+ * through the shared world, absence of any persisted-state read, direct provider imports, sleeps and
+ * branches. They do not pretend to judge business meaning.
  */
 
 /** Files this law governs. A flow is a named lane, not every file that happens to touch a database. */
@@ -156,17 +164,59 @@ export const noBranchInFlowStep = {
   },
 }
 
+// -- E2E-8 (the per-file half: a spec builds no wiring of its own) --------------------------------
+
+/** A flow boots through the shared world; it does not build its own copy of the app. */
+export const noWiringInFlowSpec = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "An e2e spec boots through the shared world helper and builds no testing module of its own (E2E-8).",
+    },
+    schema: [],
+    messages: {
+      wiring:
+        "`Test.createTestingModule(...)` builds this flow's own copy of the app instead of booting through the shared world helper. E2E-8: the world is stood up in one place, and a spec file carries no wiring of its own - when the wiring changes, every flow that inlined its own module has to change with it, and two flows standing the world up slightly differently is how nobody learns where they differ. Boot through the shared helper and override only the one token this flow needs.",
+    },
+  },
+  create(context) {
+    if (!isE2eSpec(context.filename || context.getFilename())) return {}
+    return {
+      CallExpression(node) {
+        const callee = node.callee
+        if (!callee || callee.type !== "MemberExpression" || callee.computed) return
+        if (callee.object.type !== "Identifier" || callee.object.name !== "Test") return
+        if (callee.property.name !== "createTestingModule") return
+        context.report({ node: callee, messageId: "wiring" })
+      },
+    }
+  },
+}
+
 /** The rules this law contributes to the plugin. */
 export const rules = {
   "e2e-uses-production-transport": e2eUsesProductionTransport,
   "no-sleep-in-flow": noSleepInFlow,
   "no-branch-in-flow-step": noBranchInFlowStep,
+  "no-wiring-in-flow-spec": noWiringInFlowSpec,
 }
 
 /**
  * The level this law asks for, as the plugin's own opinion.
  *
- * Both are exact and both fire on a syntactic shape rather than on a judgement, so neither carries
- * the false-positive risk that would justify adopting it at `warn`.
+ * The first three are exact and fire on a syntactic shape rather than on a judgement, so none of
+ * them carries the false-positive risk that would justify adopting it at `warn`.
+ *
+ * `no-wiring-in-flow-spec` is exact in the SAME sense - `Test.createTestingModule(...)` is a fixed
+ * shape, not a guess - but it was measured at 60 of 77 e2e files in the reference repository
+ * building their own testing module rather than calling `bootFlowWorld`. That is real, pre-existing
+ * debt this task does not fix, so the rule lands at `warn` with the count rather than `error`,
+ * exactly like a rule that has not yet been burned down.
  */
-export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-be/${name}`, "error"]))
+export const recommended = {
+  "starci-be/e2e-uses-production-transport": "error",
+  "starci-be/no-sleep-in-flow": "error",
+  "starci-be/no-branch-in-flow-step": "error",
+  "starci-be/no-wiring-in-flow-spec": "warn", // no=60 of 77 - pre-existing, not burned down here
+}

package/event-delivery.mjs

@@ -1,40 +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" })
-        }
-      },
-    }
-  },
-}
-
-export const rules = { "nats-bridge-delivery-contract": natsBridgeDeliveryContract }
-
-export const recommended = {
-  "starci-be/nats-bridge-delivery-contract": "error",
-}
+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",
+}