@starci/eslint-canon-be 3.0.7 → 3.0.9

package/lib/unit-spec.mjs

@@ -2,8 +2,12 @@
  * What is a unit spec, decided by the slot manifest and the file's role suffix, never by a path pattern.
  *
  * A unit spec is a `*.spec.ts` outside the folders that own the other test kinds (`src/tests/{e2e,integration,contract,world}`)
- * only. Only a `<name>.service.spec.ts` beside `<name>.service.ts` is a
- * legitimate unit spec (R47); the quality rules of R48 judge exactly those.
+ * only. Only a `<name>.<role>.spec.ts` beside `<name>.<role>.ts` is a legitimate unit spec (R47): of a spec-required unit role
+ * (`ruleParams.be.unitRoles`: a service, a cli command) anywhere its slot admits, and of any other LOGIC role (`ruleParams.be.logicRoles`: a policy,
+ * a client, a guard, a mapper, ...) inside a slot whose `coverage` is required, where the spec is optional (the file owes 100 per file, not a spec of
+ * its own). So is the spec of a door of a feature kind that has no service of its own
+ * (`<provider>.webhook.spec.ts`, `<channel>.gateway.spec.ts`, `<channel>.subscription.spec.ts` beside its door, in the kind's slot);
+ * the quality rules of R48 judge the service specs.
  */
 import { basename } from "node:path"
 
@@ -29,5 +33,62 @@ export const isUnitSpecFile = (hfs, filename) => {
 /** Whether a file is a `<name>.service.spec.ts` unit spec. */
 export const isServiceSpecFile = (hfs, filename) => /\.service\.spec\.ts$/.test(baseOf(filename)) && isUnitSpecFile(hfs, filename)
 
+/**
+ * The unit-tested roles of the back end: `ruleParams.be.unitRoles` of the slot manifest, the ONE list (`[{ role, spec, slot? }]`).
+ *
+ * @param {object} hfs - The HFS view.
+ * @returns {ReadonlyArray<{ role: string, spec: string, slot?: string }>} The roles.
+ */
+export const unitRoles = (hfs) => hfs.ruleParams.unitRoles ?? []
+
+/** Whether the slot that owns a file is measured at 100 per file (`coverage: required`): the home of the optional specs of the logic roles. */
+const inCoverageSlot = (hfs, filename) => {
+    const slot = hfs.slotOf(filename)
+    return slot !== null && hfs.slot(slot)?.coverage === "required"
+}
+
+/** The roles whose spec is legal but not required: every logic role that is not a spec-required unit role. */
+const optionalRoles = (hfs) => (hfs.ruleParams.logicRoles ?? []).filter((role) => !unitRoles(hfs).some((unit) => unit.role === role)).map((role) => ({ role, spec: `${role}.spec`, optional: true }))
+
+/** Whether a role admits a file by its slot (a role with no slot admits any slot; an optional logic role only a coverage-required slot). */
+const inRoleSlot = (hfs, role, filename) => (role.optional === true ? inCoverageSlot(hfs, filename) : role.slot === undefined || hfs.slotOf(filename) === role.slot)
+
+/**
+ * The unit-tested role whose spec a file is (`<name>.<role>.spec.ts`, in the role's slot), or null.
+ *
+ * @param {object} hfs - The HFS view.
+ * @param {string} filename - The linted file.
+ * @returns {object | null} The role entry.
+ */
+export const unitRoleOfSpec = (hfs, filename) => {
+    if (!isUnitSpecFile(hfs, filename)) return null
+    const name = baseOf(filename)
+    return [...unitRoles(hfs), ...optionalRoles(hfs)].find((role) => name.endsWith(`.${role.spec}.ts`) && inRoleSlot(hfs, role, filename)) ?? null
+}
+
+/**
+ * The unit-tested role whose subject a file is (`<name>.<role>.ts`, in the role's slot, outside the test tree), or null.
+ *
+ * @param {object} hfs - The HFS view.
+ * @param {string} filename - The linted file.
+ * @returns {object | null} The role entry.
+ */
+export const unitRoleOfSubject = (hfs, filename) => {
+    const name = baseOf(filename)
+    const slot = hfs.slotOf(filename)
+    if (!slot || slot.startsWith("be.tests.")) return null
+    return unitRoles(hfs).find((role) => name.endsWith(`.${role.role}.ts`) && !name.endsWith(`.${role.spec}.ts`) && inRoleSlot(hfs, role, filename)) ?? null
+}
+
 /** The `<name>` of a `<name>.service.spec.ts`. */
 export const serviceNameOfSpec = (filename) => baseOf(filename).replace(/\.service\.spec\.ts$/, "")
+
+/** The slots of the feature kinds whose door carries its own unit spec beside it. */
+const DOOR_SPEC_SLOTS = new Set(["be.feature.webhooks.http", "be.feature.realtime.graphql", "be.feature.realtime.websocket"])
+
+/** The door a `<name>.<role>.spec.ts` of a feature kind tests, or null: `payment.webhook.spec.ts` gives `payment.webhook.ts`. */
+export const doorOfSpec = (hfs, filename) => {
+    if (!isUnitSpecFile(hfs, filename) || !DOOR_SPEC_SLOTS.has(hfs.slotOf(filename) ?? "")) return null
+    const match = /^(.+.(?:webhook|gateway|subscription)).spec.ts$/.exec(baseOf(filename))
+    return match ? `${match[1]}.ts` : null
+}

package/module-layering.mjs

@@ -6,7 +6,7 @@
  * view; none of them reads a path pattern, and an alias is resolved through the program's own `compilerOptions.paths`:
  *
  *   - `import-owner-entry` - a cross-owner import targets the owner's `index.ts` (`@modules/domain/plan`,
- *     `@features/plan`), never a file inside it, and an alias that names a tier but no owner (`@modules/domain`) names
+ *     `@features/api/plan`), never a file inside it, and an alias that names a tier but no owner (`@modules/domain`) names
  *     nothing importable. A same-owner import is relative and never goes through the owner's own `index.ts`.
  *   - `no-self-module-alias` - inside an owner, imports are relative, never the owner's own alias.
  *   - `no-relative-capability-escape` - a relative import never walks out of its own owner.
@@ -20,7 +20,7 @@
 import { posix } from "node:path"
 import { hfsOf } from "./lib/hfs.mjs"
 import { baseName } from "./lib/ports.mjs"
-import { typed } from "./lib/types.mjs"
+import { resolveAlias } from "./lib/specifier.mjs"
 
 /** The tiers whose files belong to an owner with a root `index.ts`. */
 const OWNER_TIERS = new Set(["feature", "domain", "platform", "integrations"])
@@ -45,27 +45,6 @@ const absolute = (hfs, rel) => `${hfs.repoRoot.replace(/\\/g, "/")}/${rel}`
 /** The owner an import path (no extension, absolute) reaches: the owner of `<path>/index.ts`, which any file or folder of that owner shares. */
 const ownerOfTarget = (hfs, target) => ownerDirOf(hfs, `${target}/index.ts`)
 
-/**
- * The absolute path an alias specifier maps to under the program's `compilerOptions.paths`, or null when no pattern matches.
- *
- * @param {object} context - The ESLint rule context.
- * @param {string} specifier - An import specifier.
- * @returns {{ target: string, rest: string } | null} The absolute target without extension and the part the wildcard matched.
- */
-const resolveAlias = (context, specifier) => {
-  const options = typed(context).program.getCompilerOptions()
-  const base = options.baseUrl ?? options.pathsBasePath
-  if (!options.paths || typeof base !== "string") return null
-  for (const [pattern, targets] of Object.entries(options.paths)) {
-    if (!pattern.endsWith("/*") || !targets[0]) continue
-    const prefix = pattern.slice(0, -1)
-    if (!specifier.startsWith(prefix)) continue
-    const rest = specifier.slice(prefix.length)
-    return { target: posix.normalize(`${base.replace(/\\/g, "/")}/${targets[0].replace("*", rest)}`), rest }
-  }
-  return null
-}
-
 /** A specifier that names a directory by construction: `.`, `./`, `..`, `../`, or a trailing `/`. */
 const isBareFolderSpecifier = (specifier) =>
   specifier === "." || specifier === "./" || specifier === ".." || specifier === "../" || specifier.endsWith("/")
@@ -105,7 +84,7 @@ export const importOwnerEntry = {
     schema: [],
     messages: {
       barrel:
-        "`{{specifier}}` names a tier, not an owner. Import an owner's public entry, for example `@modules/domain/plan` or `@features/plan`.",
+        "`{{specifier}}` names a tier, not an owner. Import an owner's public entry, for example `@modules/domain/plan` or `@features/api/plan`.",
       deep:
         "`{{specifier}}` reaches into a file of another owner. Import the owner's public entry (its `index.ts`) and export what you need from there.",
       ownIndex:

package/module-shape.mjs

@@ -29,7 +29,7 @@
 import ts from "typescript"
 import { decoratorName, keyName, walk } from "./lib/ast.mjs"
 import { importsFrom } from "./lib/declared.mjs"
-import { hfsOf } from "./lib/hfs.mjs"
+import { hfsOf, inTestWorld } from "./lib/hfs.mjs"
 import { isDeclarationFile, isSpecFile, normalizePath } from "./lib/path.mjs"
 import { typed } from "./lib/types.mjs"
 
@@ -70,7 +70,7 @@ const isAppModule = (hfs, filename) => (hfs.slotOf(filename) ?? "").startsWith("
  * capability modules with `isGlobal: true` the way `apps/<app>/src/app.module.ts` does in production. A spec (integration,
  * contract, e2e) does not compose and stays refused: it calls `useTestWorld(...)` only.
  */
-const isWorld = (hfs, filename) => hfs.slotOf(filename) === "be.tests.world"
+const isWorld = inTestWorld
 
 const isTrue = (node) => node?.type === "Literal" && node.value === true
 

package/naming.mjs

@@ -30,7 +30,7 @@
  * that. Those are read by a person, which is why the law states them with the scars attached.
  */
 
-import { hfsOf } from "./lib/hfs.mjs"
+import { hfsOf, inTestWorld } from "./lib/hfs.mjs"
 import { normalizePath } from "./lib/path.mjs"
 
 /** A schema generation baked into an identifier. */
@@ -203,7 +203,7 @@ export const noBareVerbExport = {
 // -- no-default-export -------------------------------------------------------------------------------------------
 
 /** The one file kind that may default-export: a Jest global setup, whose API is a default function. */
-const isGlobalSetup = (context) => hfsOf(context).slotOf(context.filename) === "be.tests.world" && /\/global-(?:setup|teardown)\.ts$/.test(normalizePath(context.filename))
+const isGlobalSetup = (context) => inTestWorld(hfsOf(context), context.filename) && /\/global-(?:setup|teardown)\.ts$/.test(normalizePath(context.filename))
 
 /** Named exports only: a default export has no name to grep, rename or import-check. */
 export const noDefaultExport = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-be",
-  "version": "3.0.7",
+  "version": "3.0.9",
   "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
   "type": "module",
   "license": "UNLICENSED",
@@ -13,7 +13,7 @@
     "*.mjs",
     "lib/*.mjs",
     "runtime/**",
-    "!*.test.mjs",
+    "!*.spec.mjs",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -28,7 +28,9 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node --test \"*.test.mjs\""
+    "prepack": "node ../../hfs/prep-runtime.mjs",
+    "pretest": "node ../../hfs/prep-runtime.mjs",
+    "test": "node --test \"*.spec.mjs\""
   },
   "keywords": [
     "eslint",

package/project-graph.mjs

@@ -1,14 +1,14 @@
 /**
  * The rules that read the project graph: the findings of the architecture machine that sit on a TypeScript file.
  *
- * One graph per lint run: `scripts/lib/project-graph.mjs` (a byte copy in this package's runtime/) builds the machine's module
+ * One graph per lint run: `scripts/hfs/project-graph.mjs` (a byte copy in this package's runtime/) builds the machine's module
  * graph and slot manifest once for the repository, caches it, and each rule below reports the findings of its own codes on
  * the file ESLint is visiting, on the line the machine names. There is no second graph and no second judge: the list of
- * rules and their codes is `LINT_ENFORCERS` of the machine (scripts/checks/architecture/surface.mjs); `hfs check` keeps the
+ * rules and their codes is `LINT_ENFORCERS` of the machine (scripts/hfs/architecture/surface.mjs); `starci app check` keeps the
  * findings that have no TypeScript file to sit on. A graph that cannot be built stops the run with the machine's message.
  */
-import { LINT_ENFORCERS } from "./runtime/scripts/checks/architecture/surface.mjs"
-import { projectRule } from "./runtime/scripts/lib/project-rule.mjs"
+import { LINT_ENFORCERS } from "./runtime/scripts/hfs/architecture/surface.mjs"
+import { projectRule } from "./runtime/scripts/hfs/project-rule.mjs"
 import { hfsOf } from "./lib/hfs.mjs"
 import { dirname, join } from "node:path"
 import { fileURLToPath } from "node:url"
@@ -17,7 +17,10 @@ const RUNTIME = join(dirname(fileURLToPath(import.meta.url)), "runtime")
 const mine = LINT_ENFORCERS.filter((enforcer) => enforcer.plugins.includes("be"))
 
 /** The rules this law contributes to the plugin: one per graph enforcer of this profile. */
-export const rules = Object.fromEntries(mine.map((e) => [e.id, projectRule({ enforcer: e, runtimeRoot: RUNTIME, hfsOf })]))
+export const rules = Object.fromEntries(mine.map((enforcer) => [
+    enforcer.id,
+    projectRule({ enforcer, runtimeRoot: RUNTIME, hfsOf }),
+]))
 
 /** Every one at error. */
 export const recommended = Object.fromEntries(mine.map((e) => [`starci-be/${e.id}`, "error"]))

package/projections.mjs

@@ -0,0 +1,117 @@
+/**
+ * The rules that hold the projection pattern (catalog R161 `BE_PROJECTION_WRITE_OWNER`, R162 `BE_PROJECTION_SHAPE`).
+ *
+ * A projection is a read model: `modules/projections/<name>/` holds `<name>.projection.ts` (the only class that touches its table:
+ * `recompute*` writes it idempotently from the source facts and can replay from scratch, `get*` reads it) and
+ * `<name>.projection-entity.ts` (the table's entity). A reactor, a job or a cli command triggers a recompute; an api feature only calls `get*`.
+ * A projection publishes no event (R152 refuses `eventBus.publish` outside `modules/domain`).
+ *
+ * Entities are found by TYPE ORIGIN; the owner and the kind of a file by the slot view. The vocabulary `recompute` and `get` is the
+ * pattern's own method contract.
+ */
+import { writtenEntityOrigins } from "./lib/entity-writes.mjs"
+import { hfsOf, inTestWorld } from "./lib/hfs.mjs"
+import { baseName } from "./lib/ports.mjs"
+import { typed } from "./lib/types.mjs"
+
+const PROJECTION_SLOT = "be.projections"
+const ENTITY_SUFFIX = ".projection-entity.ts"
+const PROJECTION_SUFFIX = ".projection.ts"
+
+/** True for the test composition, which seeds and inspects tables directly. */
+const isTestComposition = (hfs, file) => {
+    const tier = hfs.tierOf(file)
+    return tier === "e2e" || tier === "fixtures" || inTestWorld(hfs, file)
+}
+
+/** The word a method name starts with (`recomputeUserXp` gives `recompute`), or null when the name has no camelCase boundary. */
+const verbOf = (name) => {
+    const match = /^[a-z]+/.exec(name)
+    return match && (match[0].length === name.length || /[A-Z]/.test(name[match[0].length])) ? match[0] : null
+}
+
+/** Only a projection writes its table, from its own `<name>.projection.ts`. */
+export const projectionWriteOwner = {
+    meta: {
+        type: "problem",
+        docs: { description: "A projection's entity is written only by the `*.projection.ts` of the same projection folder." },
+        schema: [],
+        messages: {
+            foreign: "`{{call}}` writes the read-model table of a projection from outside its `<name>.projection.ts`. A read model has one writer: its projection's `recompute*` method, which is idempotent and can replay from the source facts. Ask the projection to recompute (from a reactor or a job) instead of writing its table.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        const file = context.filename
+        if (isTestComposition(hfs, file)) return {}
+        return {
+            CallExpression(node) {
+                const entities = writtenEntityOrigins(context, node).filter((origin) => hfs.slotOf(origin.file) === PROJECTION_SLOT && baseName(origin.file).endsWith(ENTITY_SUFFIX))
+                if (entities.length === 0) return
+                const mine = hfs.slotOf(file) === PROJECTION_SLOT && baseName(file).endsWith(PROJECTION_SUFFIX)
+                if (mine && entities.every((origin) => hfs.ownerOf(origin.file) === hfs.ownerOf(file))) return
+                context.report({ node, messageId: "foreign", data: { call: context.sourceCode.getText(node.callee) } })
+            },
+        }
+    },
+}
+
+/** The slot of an owner's root file: its kind lives there (`trigger`). */
+const triggerOfOwner = (hfs, file) => {
+    const root = hfs.ownerOf(file)
+    const slot = root ? hfs.slotOf(`${root}/index.ts`) : null
+    return slot ? (hfs.slot(slot)?.trigger ?? null) : null
+}
+
+/** The projection class speaks only `recompute*` and `get*`, never exports its entity, and an api feature never recomputes. */
+export const projectionShape = {
+    meta: {
+        type: "problem",
+        docs: { description: "A `*.projection.ts` class has only `recompute*` and `get*` public methods, a projection's `index.ts` exports no projection entity, and an api feature calls only `get*`." },
+        schema: [],
+        messages: {
+            vocabulary: "`{{name}}` is a public method of a projection that is neither `recompute*` nor `get*`. A projection recomputes its table from the source facts (idempotent, replayable) or reads it; anything else belongs in a domain service.",
+            entityExported: "This `index.ts` exports from `{{source}}`. The entity of a projection stays inside its folder: the rest of the code reads through `get*` and never sees the table's shape.",
+            apiRecompute: "`{{call}}` recomputes a projection from an api feature. The api reads only through `get*`; a reactor, a job or a cli command keeps the read model current.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        const file = context.filename
+        const found = hfs.classify(file)
+        const base = baseName(file)
+        const inProjection = found.slot === PROJECTION_SLOT
+        const trigger = triggerOfOwner(hfs, file)
+        return {
+            MethodDefinition(node) {
+                if (!inProjection || !base.endsWith(PROJECTION_SUFFIX) || node.kind !== "method" || node.computed || node.key.type !== "Identifier") return
+                if (node.accessibility === "private" || node.accessibility === "protected" || node.key.type === "PrivateIdentifier") return
+                const verb = verbOf(node.key.name)
+                if (verb !== "recompute" && verb !== "get") context.report({ node: node.key, messageId: "vocabulary", data: { name: node.key.name } })
+            },
+            ExportNamedDeclaration(node) {
+                if (!inProjection || base !== "index.ts" || !node.source) return
+                if (String(node.source.value).endsWith(".projection-entity")) context.report({ node, messageId: "entityExported", data: { source: node.source.value } })
+            },
+            CallExpression(node) {
+                if (trigger !== "api" || node.callee.type !== "MemberExpression" || node.callee.computed || node.callee.property.type !== "Identifier") return
+                if (verbOf(node.callee.property.name) !== "recompute") return
+                const { checker, toTs } = typed(context)
+                const tsNode = toTs(node)
+                const declaration = tsNode ? checker.getResolvedSignature(tsNode)?.declaration : undefined
+                if (declaration && hfs.slotOf(declaration.getSourceFile().fileName) === PROJECTION_SLOT) context.report({ node, messageId: "apiRecompute", data: { call: context.sourceCode.getText(node.callee) } })
+            },
+        }
+    },
+}
+
+export const rules = {
+    "projection-write-owner": projectionWriteOwner,
+    "projection-shape": projectionShape,
+}
+
+/** The level these laws ask for: `error`, switched off nowhere. */
+export const recommended = {
+    "starci-be/projection-write-owner": "error",
+    "starci-be/projection-shape": "error",
+}

package/query-safety.mjs

@@ -15,7 +15,7 @@
  * - `query-needs-limit` (R69 `BE_QUERY_UNBOUNDED`) - `find`, `findBy` and `findAndCount` on an `EntityManager` carry `take`.
  * - `no-query-in-loop` (R77 `BE_QUERY_IN_LOOP`) - an `EntityManager` read does not run once per element of a loop.
  *
- * A migration is hand-written DDL run once by `apps/migrate`; its `queryRunner.query(...)` takes plain text.
+ * A migration is hand-written DDL run once by the cli migrate command; its `queryRunner.query(...)` takes plain text.
  */
 import { keyName } from "./lib/ast.mjs"
 import { hfsOf } from "./lib/hfs.mjs"

package/realtime.mjs

@@ -0,0 +1,181 @@
+/**
+ * The rules that hold the realtime kind (R184 `BE_REALTIME_SHAPE`, R185 `BE_REALTIME_WRITES`, R186 `BE_REALTIME_TOPIC_SCOPE`).
+ *
+ * A realtime door (`src/features/realtime/<channel>/transport/websocket/<channel>.gateway.ts` for a socket, `transport/graphql/<x>.subscription.ts` for a GraphQL
+ * subscription, slot `be.feature.realtime`) READS and PUSHES. It never writes: the push is fed by a reactor that calls the `RealtimeHub`
+ * of `platform/realtime`, and the door only subscribes a client to a topic of that hub.
+ *
+ *   - `realtime-shape` (R184): a `.gateway.ts` holds one `@WebSocketGateway` class whose handlers are `@SubscribeMessage`; a
+ *     `.subscription.ts` holds one `@Resolver` class whose operations are `@Subscription`. Each is the door its file role names, and
+ *     neither carries a query, a mutation or a REST route.
+ *   - `realtime-read-only` (R185): the only value injected into a realtime door is the `RealtimeHub` of `platform/realtime`. No
+ *     `EntityManager`, bus, queue, event bus or domain service reaches it.
+ *   - `realtime-topic-scope` (R186): the topic passed to `hub.subscribe` is built from the principal parameter of the handler
+ *     (`@CurrentPrincipal()` of `domain/identity`), so a client can only listen to what the principal owns.
+ *
+ * What a receiver is comes from its TYPE, what a decorator is from the import that binds it, and where a parameter comes
+ * from from the declaration its name resolves to. No rule here tests a path pattern or a variable name.
+ */
+import { walk } from "./lib/ast.mjs"
+import { aliasTarget, callsOf, hasClassDecorator, injectedMembers, methodsDecoratedBy, parametersOf } from "./lib/doors.mjs"
+import { hfsOf } from "./lib/hfs.mjs"
+import { decoratorCallee } from "./lib/import-source.mjs"
+import { baseName, isOwnedType, ownerNameOf } from "./lib/ports.mjs"
+
+/** The slot of realtime doors. */
+const DOOR_SLOTS = new Set(["be.feature.realtime.graphql", "be.feature.realtime.websocket"])
+
+/** The `RealtimeHub` port of `platform/realtime`. */
+const isHubType = (context, node) => isOwnedType(context, node, { name: "RealtimeHub", capability: "realtime", tier: "platform" })
+
+/** The decorators that make a class a door of one kind of realtime file, by file role. */
+const ROLES = {
+    gateway: { classDecorator: ["@nestjs/websockets", "WebSocketGateway"], operation: ["@nestjs/websockets", "SubscribeMessage"], foreign: [["@nestjs/graphql", ["Query", "Mutation", "ResolveField", "Subscription"]], ["@nestjs/common", ["Controller"]]] },
+    subscription: { classDecorator: ["@nestjs/graphql", "Resolver"], operation: ["@nestjs/graphql", "Subscription"], foreign: [["@nestjs/graphql", ["Query", "Mutation", "ResolveField"]], ["@nestjs/websockets", ["WebSocketGateway", "SubscribeMessage"]], ["@nestjs/common", ["Controller"]]] },
+}
+
+/** The role (`gateway` or `subscription`) a realtime file name carries, or null. */
+const roleOf = (filename) => /\.(gateway|subscription)\.ts$/.exec(baseName(filename))?.[1] ?? null
+
+/** The door classes of a file: every class with a class-level door decorator of the role. */
+const doorClasses = (context, program, role) => {
+    const found = []
+    walk(program, (node) => {
+        if (node.type === "ClassDeclaration" && hasClassDecorator(context, node, ...ROLES[role].classDecorator)) found.push(node)
+    })
+    return found
+}
+
+/** A realtime file is the one door its role names, and nothing else. */
+export const realtimeShape = {
+    meta: {
+        type: "problem",
+        docs: { description: "A realtime file is one door: a `.gateway.ts` holds one `@WebSocketGateway` class with `@SubscribeMessage` handlers, a `.subscription.ts` holds one `@Resolver` class with `@Subscription` operations, and neither carries a route, query or mutation." },
+        schema: [],
+        messages: {
+            door: "A `<channel>.{{role}}.ts` file declares exactly one `{{decorator}}` class (this one declares {{count}}). One file is one door.",
+            operations: "This {{role}} door has no `@{{operation}}` handler. A realtime door exists to serve a client one: it subscribes the client to a topic of the `RealtimeHub`.",
+            foreign: "`@{{name}}` has no place in a realtime {{role}} door. A realtime door only subscribes and pushes; a query, a mutation, a field resolver or a REST route belongs in an api feature, and the other realtime protocol in its own file.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        const role = roleOf(context.filename)
+        if (!DOOR_SLOTS.has(hfs.slotOf(context.filename) ?? "") || role === null) return {}
+        const spec = ROLES[role]
+        return {
+            "Program:exit"(program) {
+                const doors = doorClasses(context, program, role)
+                if (doors.length !== 1) {
+                    context.report({ node: program, messageId: "door", data: { role, decorator: `@${spec.classDecorator[1]}`, count: String(doors.length) } })
+                    return
+                }
+                if (methodsDecoratedBy(context, doors[0], ...spec.operation).length === 0) context.report({ node: doors[0], messageId: "operations", data: { role, operation: spec.operation[1] } })
+                walk(program, (node) => {
+                    if (node.type !== "Decorator") return
+                    for (const [source, names] of spec.foreign) {
+                        const hit = names.find((name) => hasDecorator(context, node, source, name))
+                        if (hit !== undefined) context.report({ node, messageId: "foreign", data: { name: hit, role } })
+                    }
+                })
+            },
+        }
+    },
+}
+
+/** True when one decorator node is `name` exported by `source`. */
+const hasDecorator = (context, decorator, source, name) => hasClassDecorator(context, { decorators: [decorator] }, source, name)
+
+/** A realtime door injects the hub and nothing else: it reads and pushes, it never writes. */
+export const realtimeReadOnly = {
+    meta: {
+        type: "problem",
+        docs: { description: "The only value a realtime door injects is the `RealtimeHub` of `platform/realtime`: no `EntityManager`, bus, queue, event bus or domain service." },
+        schema: [],
+        messages: {
+            injects: "`{{what}}` is injected into a realtime door. A realtime door reads and pushes only: it injects the `RealtimeHub` of `platform/realtime` and nothing that can write (an `EntityManager`, a `CommandBus`, an event bus, a queue, a domain service). The push is fed by a reactor that calls the hub; a write belongs in an api feature.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        if (!DOOR_SLOTS.has(hfs.slotOf(context.filename) ?? "") || roleOf(context.filename) === null) return {}
+        return {
+            ClassDeclaration(node) {
+                for (const { node: member, annotation } of injectedMembers(context, node)) {
+                    if (!annotation || !isHubType(context, annotation)) context.report({ node: member, messageId: "injects", data: { what: context.sourceCode.getText(member) } })
+                }
+            },
+        }
+    },
+}
+
+/** True when the parameter carries `@CurrentPrincipal()` declared by `domain/identity`, judged by the declaration the decorator resolves to. */
+const isPrincipalParameter = (context, hfs, param) =>
+    (param.decorators ?? []).some((decorator) => {
+        const callee = decoratorCallee(decorator)
+        if (callee?.type !== "Identifier") return false
+        const symbol = aliasTarget(context, callee)
+        return symbol?.getName() === "CurrentPrincipal" && (symbol.getDeclarations() ?? []).some((declaration) => ownerNameOf(hfs, declaration.getSourceFile().fileName) === "identity" && hfs.tierOf(declaration.getSourceFile().fileName) === "domain")
+    })
+
+/** True when the identifier resolves to one of the `names` (parameters of the handler). */
+const resolvesTo = (context, identifier, parameters) => {
+    for (let scope = context.sourceCode.getScope(identifier); scope; scope = scope.upper) {
+        const variable = scope.set.get(identifier.name)
+        if (!variable) continue
+        return variable.defs.some((definition) => definition.type === "Parameter" && parameters.has(definition.name))
+    }
+    return false
+}
+
+/** The topic a client subscribes to is built from the principal the handler receives. */
+export const realtimeTopicScope = {
+    meta: {
+        type: "problem",
+        docs: { description: "The topic passed to `RealtimeHub.subscribe` is built from the handler's `@CurrentPrincipal()` parameter." },
+        schema: [],
+        messages: {
+            scope: "The topic of this `subscribe` is not built from the principal. A realtime handler takes `@CurrentPrincipal() principal` and subscribes to a topic made from `principal.id` (plus any verified id), so one client cannot listen to another's channel. A topic taken only from client input is a leak.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        const role = roleOf(context.filename)
+        if (!DOOR_SLOTS.has(hfs.slotOf(context.filename) ?? "") || role === null) return {}
+        const [source, name] = ROLES[role].operation
+        return {
+            ClassDeclaration(node) {
+                for (const method of methodsDecoratedBy(context, node, source, name)) {
+                    const principals = new Set()
+                    for (const param of parametersOf(method)) {
+                        if (!isPrincipalParameter(context, hfs, param)) continue
+                        const target = param.type === "AssignmentPattern" ? param.left : param
+                        if (target.type === "Identifier") principals.add(target)
+                    }
+                    for (const { call, receiver, method: called } of callsOf(method)) {
+                        if (called !== "subscribe" || receiver === null || !isHubType(context, receiver)) continue
+                        let scoped = false
+                        walk(call.arguments[0], (child) => {
+                            if (child.type === "Identifier" && resolvesTo(context, child, principals)) scoped = true
+                        })
+                        if (!scoped) context.report({ node: call, messageId: "scope" })
+                    }
+                }
+            },
+        }
+    },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "realtime-shape": realtimeShape,
+    "realtime-read-only": realtimeReadOnly,
+    "realtime-topic-scope": realtimeTopicScope,
+}
+
+/** Every rule of this law at `error`. */
+export const recommended = {
+    "starci-be/realtime-shape": "error",
+    "starci-be/realtime-read-only": "error",
+    "starci-be/realtime-topic-scope": "error",
+}