@starci/eslint-canon-be 3.3.1 → 3.4.0

package/module-shape.mjs

@@ -12,11 +12,15 @@
  *     capability's representative module is reached through its `Inject*()` decorators, never by import. One owner may
  *     import its own modules (a transport module its feature's application module, a representative its sub-modules);
  *     the app composes every owner.
- *   - `capability-module-shape` holds the files of a capability: its representative `<c>.module.ts` extends the
- *     `ConfigurableModuleClass` of its own `<c>.module-definition.ts` (and may override only
- *     `static register(options: typeof OPTIONS_TYPE): DynamicModule`); that definition is a typed
- *     `ConfigurableModuleBuilder` with `.setExtras({ isGlobal: false }, ...)` and `.build()`; every sub-module and every
- *     feature module is a plain `@Module` class, and a feature has no module definition.
+ *   - `capability-module-shape` holds the definition of every module (owner ruling module-definition-everywhere): the representative
+ *     `<c>.module-definition.ts` of a capability is a typed `ConfigurableModuleBuilder` with `.setExtras({ isGlobal: false }, ...)`
+ *     and `.build()`; every other module's definition (a sub-module, a feature, a transport, a cli group) is
+ *     `.setClassMethodName("register").build()` with no extras; only a representative may override
+ *     `static register(options: typeof OPTIONS_TYPE): DynamicModule`.
+ *   - `module-definition-required` holds that every module has one: a `<x>.module.ts` of a feature, capability or projection has a
+ *     sibling `<x>.module-definition.ts` and `<x>.options.ts`, its class extends the `ConfigurableModuleClass` of that definition,
+ *     and a module of the product appears in an `imports` array only as `X.register(...)`, never as a bare class
+ *     (BE_MODULE_DEFINITION_MISSING).
  *   - `typed-module-definition` requires `ConfigurableModuleBuilder<Options>` to state its options type.
  *   - `static-module-register` allows one factory name, `register`, and requires it `static`: no `forRoot`, `forFeature`
  *     or `registerAsync`, because options are parsed once in `main.ts`.
@@ -25,6 +29,8 @@
  *   - `no-module-let` refuses mutable module-level state (`let` and `var` at the top of a file).
  *   - `one-module-per-file` allows one `@Module` class in a file, so one transport or application module has one home.
  */
+import { existsSync } from "node:fs"
+import { dirname, join } from "node:path"
 import ts from "typescript"
 import { decoratorName, keyName, walk } from "./lib/ast.mjs"
 import { importsFrom } from "./lib/declared.mjs"
@@ -294,7 +300,9 @@ export const oneModulePerFile = {
     },
 }
 
-const CAPABILITY_TIERS = new Set(["domain", "platform", "integrations"])
+const CAPABILITY_TIERS = new Set(["domain", "platform", "integrations", "projections"])
+/** The tiers whose `<x>.module.ts` files are modules of the product: every one of them has a module definition. */
+const MODULE_TIERS = new Set(["feature", "domain", "platform", "integrations", "projections", "queues", "events"])
 
 /** `{ inside, name }`: the owner-relative path of a file and the owner's directory name, or null outside an owner. */
 const insideOwner = (hfs, filename) => {
@@ -330,84 +338,170 @@ const builderChain = (newExpression) => {
     return calls
 }
 
+/** True when the argument is the string literal `register`. */
+const isRegisterName = (node) => node?.type === "Literal" && node.value === "register"
+
+/** The reasons a builder chain is not the module definition of its kind (an empty list when it is). */
+const chainFaults = (calls, representative) => {
+    const missing = []
+    const extras = calls.find((entry) => entry.name === "setExtras")
+    const named = calls.find((entry) => entry.name === "setClassMethodName")
+    if (representative) {
+        const defaults = extras?.call.arguments[0]
+        const localByDefault =
+            defaults?.type === "ObjectExpression" &&
+            defaults.properties.some((item) => item.type === "Property" && keyName(item.key) === "isGlobal" && item.value.type === "Literal" && item.value.value === false)
+        if (!localByDefault) missing.push("`.setExtras({ isGlobal: false }, ...)` is missing or does not default `isGlobal` to a literal `false`")
+        if (named && !isRegisterName(named.call.arguments[0])) missing.push('`.setClassMethodName(...)` names a factory other than "register"')
+    } else {
+        if (extras) missing.push("a sub-module, feature or transport module is never global, so it has no `.setExtras(...)`")
+        if (!named || !isRegisterName(named.call.arguments[0])) missing.push('`.setClassMethodName("register")` is missing')
+    }
+    if (calls.at(-1)?.name !== "build") missing.push("the chain does not end in `.build()`")
+    return missing
+}
+
+/** The module scope of a file: its kind, tier and name when it is a `<x>.module.ts` or `<x>.module-definition.ts` of a product tier, else null. */
+const moduleFileOf = (hfs, filename) => {
+    const base = filename.split("/").at(-1)
+    const suffix = base.endsWith(".module-definition.ts") ? ".module-definition.ts" : base.endsWith(".module.ts") ? ".module.ts" : null
+    if (!suffix) return null
+    const tier = hfs.tierOf(filename)
+    if (!MODULE_TIERS.has(tier)) return null
+    const name = base.slice(0, base.length - suffix.length)
+    const where = insideOwner(hfs, filename)
+    const representative = CAPABILITY_TIERS.has(tier) && where !== null && where.inside === `${where.name}${suffix}`
+    return { kind: suffix === ".module.ts" ? "module" : "definition", tier, name, representative }
+}
+
 /**
- * The shape of a capability's module files (BE-CONVENTION 1.2): the representative `<c>.module.ts` extends the
- * `ConfigurableModuleClass` of its own `<c>.module-definition.ts`; that definition builds a typed
- * `ConfigurableModuleBuilder` with `.setExtras({ isGlobal: false }, ...)` and `.build()`; every other module of the
- * capability, and every feature module, is a plain static `@Module` class with no definition and no `register`.
+ * The shape of a module's definition (BE-CONVENTION 1.2, owner ruling module-definition-everywhere): the representative
+ * module of a capability builds `new ConfigurableModuleBuilder<XOptions>().setExtras({ isGlobal: false }, ...).build()` and
+ * may override only `static register(options: typeof OPTIONS_TYPE): DynamicModule`; every other module (a sub-module, a feature,
+ * a transport, a cli group) builds `new ConfigurableModuleBuilder<XOptions>().setClassMethodName("register").build()` and
+ * declares nothing but its `@Module` metadata.
  */
 export const capabilityModuleShape = {
     meta: {
         type: "problem",
-        docs: { description: "A capability's representative module extends its module definition's `ConfigurableModuleClass`; sub-modules and feature modules are plain." },
+        docs: { description: "A module definition is a typed `ConfigurableModuleBuilder` chain of its kind; only a capability's representative module overrides `register`." },
         schema: [],
         messages: {
-            extendsBase: "The representative module of `{{name}}` must be `@Module({...}) export class X extends ConfigurableModuleClass {}` with `ConfigurableModuleClass` imported from `./{{name}}.module-definition`.",
             registerSignature: "The only `register` a capability module may declare is the override `static register(options: typeof OPTIONS_TYPE): DynamicModule`, with `OPTIONS_TYPE` from `./{{name}}.module-definition`.",
-            plain: "`{{class}}` is a sub-module or a feature module: a plain static `@Module` class with no base class, no `register` and no module definition. Only the capability's representative module `{{name}}.module.ts` is configurable.",
-            chain: "The module definition must be `new ConfigurableModuleBuilder<XOptions>().setExtras({ isGlobal: false }, (d, e) => ({ ...d, global: e.isGlobal })).build()`: {{missing}}.",
-            featureDefinition: "A feature has no module definition: feature modules are static. Delete this file and register the feature's providers in its `@Module`.",
+            plain: "`{{class}}` is a sub-module, feature module, transport module or cli group: it declares its providers in `@Module({...})` and has no `register` of its own. Only the representative module of a capability may override `register`.",
+            chain: "The module definition of this kind must be {{shape}}: {{missing}}.",
         },
     },
     create(context) {
         const filename = normalizePath(context.filename || context.getFilename())
-        if (isDeclarationFile(filename)) return {}
-        const hfs = hfsOf(context)
-        const where = insideOwner(hfs, filename)
-        if (!where) return {}
-        const base = filename.split("/").at(-1)
-        const isDefinition = base.endsWith(".module-definition.ts")
-        const isModuleFile = base.endsWith(".module.ts")
-        if (where.tier === "feature" && isDefinition) return { Program: (program) => context.report({ node: program, loc: { line: 1, column: 0 }, messageId: "featureDefinition" }) }
-        if (CAPABILITY_TIERS.has(where.tier) && isDefinition) {
+        if (isDeclarationFile(filename) || isSpecFile(filename)) return {}
+        const scope = moduleFileOf(hfsOf(context), filename)
+        if (!scope) return {}
+        if (scope.kind === "definition") {
+            const shape = scope.representative
+                ? "`new ConfigurableModuleBuilder<XOptions>().setExtras({ isGlobal: false }, (d, e) => ({ ...d, global: e.isGlobal })).build()`"
+                : '`new ConfigurableModuleBuilder<XOptions>().setClassMethodName("register").build()`'
             return {
                 Program(program) {
                     let found = false
                     walk(program, (node) => {
                         if (node.type !== "NewExpression" || node.callee.type !== "Identifier" || node.callee.name !== "ConfigurableModuleBuilder") return
                         found = true
-                        const calls = builderChain(node)
-                        const extras = calls.find((entry) => entry.name === "setExtras")
-                        const defaults = extras?.call.arguments[0]
-                        const localByDefault =
-                            defaults?.type === "ObjectExpression" &&
-                            defaults.properties.some((item) => item.type === "Property" && keyName(item.key) === "isGlobal" && item.value.type === "Literal" && item.value.value === false)
-                        const missing = []
-                        if (!localByDefault) missing.push("`.setExtras({ isGlobal: false }, ...)` is missing or does not default `isGlobal` to a literal `false`")
-                        if (calls.at(-1)?.name !== "build") missing.push("the chain does not end in `.build()`")
-                        if (missing.length > 0) context.report({ node, messageId: "chain", data: { missing: missing.join("; ") } })
+                        const missing = chainFaults(builderChain(node), scope.representative)
+                        if (missing.length > 0) context.report({ node, messageId: "chain", data: { shape, missing: missing.join("; ") } })
                     })
-                    if (!found) context.report({ node: program, loc: { line: 1, column: 0 }, messageId: "chain", data: { missing: "no `new ConfigurableModuleBuilder<XOptions>()` is built here" } })
+                    if (!found) context.report({ node: program, loc: { line: 1, column: 0 }, messageId: "chain", data: { shape, missing: "no `new ConfigurableModuleBuilder<XOptions>()` is built here" } })
                 },
             }
         }
-        if (!isModuleFile || (where.tier !== "feature" && !CAPABILITY_TIERS.has(where.tier))) return {}
-        const importedFrom = new Map()
-        const representative = CAPABILITY_TIERS.has(where.tier) && where.inside === `${where.name}.module.ts`
         return {
             ClassDeclaration(node) {
                 if (!isModuleClass(node)) return
-                if (!representative) {
-                    const hasRegister = node.body.body.some((member) => member.type === "MethodDefinition" && member.key.type === "Identifier" && member.key.name === "register")
-                    if (node.superClass || hasRegister) context.report({ node: node.id ?? node, messageId: "plain", data: { class: node.id?.name ?? "This class", name: where.name } })
-                    return
-                }
-                const base = node.superClass
-                const imported = base?.type === "Identifier" ? importedFrom.get(base.name) : null
-                if (!imported || imported.name !== "ConfigurableModuleClass" || imported.source !== `./${where.name}.module-definition`) {
-                    context.report({ node: node.id ?? node, messageId: "extendsBase", data: { name: where.name } })
-                }
                 for (const member of node.body.body) {
-                    if (member.type === "MethodDefinition" && member.key.type === "Identifier" && member.key.name === "register" && !isRegisterOverride(member)) {
-                        context.report({ node: member, messageId: "registerSignature", data: { name: where.name } })
-                    }
+                    if (member.type !== "MethodDefinition" || member.key.type !== "Identifier" || member.key.name !== "register") continue
+                    if (!scope.representative) context.report({ node: member, messageId: "plain", data: { class: node.id?.name ?? "This class" } })
+                    else if (!isRegisterOverride(member)) context.report({ node: member, messageId: "registerSignature", data: { name: scope.name } })
                 }
             },
+        }
+    },
+}
+
+/** True when a class declaration carries the Nest `Module` decorator. */
+const isModuleDeclaration = (declaration) => {
+    if (!ts.isClassDeclaration(declaration)) return false
+    return (ts.getDecorators(declaration) ?? []).some((decorator) => {
+        const expression = ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression
+        return ts.isIdentifier(expression) && expression.text === "Module"
+    })
+}
+
+/** The array of an `imports` property (the `@Module({ imports })` metadata or a dynamic module literal), else null. */
+const importsArrayOf = (property) => (!property.computed && keyName(property.key) === "imports" && property.value.type === "ArrayExpression" ? property.value : null)
+
+/** The PascalCase options type name a module file name implies: `sepay-feed-http` gives `SepayFeedHttpOptions`. */
+const optionsTypeOf = (name) => `${name.replace(/(?:^|-)(\w)/g, (_, letter) => letter.toUpperCase())}Options`
+
+/**
+ * Every Nest module has a module definition and is registered through it (owner ruling module-definition-everywhere): its
+ * `<x>.module.ts` has a sibling `<x>.module-definition.ts` and `<x>.options.ts`, its class extends the `ConfigurableModuleClass`
+ * of that definition, and a module of the product is listed in an `imports` array only as `X.register(...)`, never as a bare
+ * class. The `AppModule` of an app root and the test world are composition roots and are not judged here.
+ */
+export const moduleDefinitionRequired = {
+    meta: {
+        type: "problem",
+        docs: { description: "A module has a sibling module definition and options file, extends its `ConfigurableModuleClass`, and is imported only as `X.register(...)`." },
+        schema: [],
+        messages: {
+            missingDefinition: '`{{name}}.module.ts` has no sibling `{{name}}.module-definition.ts`. Every module builds its base class: `export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } = new ConfigurableModuleBuilder<{{type}}>().setClassMethodName("register").build()`.',
+            missingOptions: "`{{name}}.module.ts` has no sibling `{{name}}.options.ts`. Declare `export type {{type}} = Record<string, never>` there (with a one-line doc saying the module takes no options yet), or its real options.",
+            extendsBase: "`{{class}}` must be `@Module({...}) export class {{class}} extends ConfigurableModuleClass {}` with `ConfigurableModuleClass` imported from `./{{name}}.module-definition`.",
+            unregistered: "`{{name}}` is imported as a bare class. Every module is registered through its definition: write `{{name}}.register({...})` (`{}` when it takes no options).",
+        },
+    },
+    create(context) {
+        const filename = normalizePath(context.filename || context.getFilename())
+        if (isDeclarationFile(filename) || isSpecFile(filename)) return {}
+        const hfs = hfsOf(context)
+        if (inTestWorld(hfs, filename)) return {}
+        const scope = moduleFileOf(hfs, filename)
+        const importedFrom = new Map()
+        const { checker, toTs } = typed(context)
+        const isModuleClassIdentifier = (identifier) => {
+            const tsNode = toTs(identifier)
+            let symbol = tsNode ? checker.getSymbolAtLocation(tsNode) : undefined
+            if (symbol && symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol)
+            return (symbol?.declarations ?? []).some((declaration) => !/[\\/]node_modules[\\/]/.test(declaration.getSourceFile().fileName) && isModuleDeclaration(declaration))
+        }
+        return {
             ImportDeclaration(node) {
                 for (const specifier of node.specifiers) {
                     if (specifier.type === "ImportSpecifier") importedFrom.set(specifier.local.name, { name: specifier.imported.name ?? specifier.imported.value, source: String(node.source.value) })
                 }
             },
+            Program(program) {
+                if (scope?.kind !== "module") return
+                const siblings = dirname(filename)
+                const type = optionsTypeOf(scope.name)
+                if (!existsSync(join(siblings, `${scope.name}.module-definition.ts`))) context.report({ node: program, loc: { line: 1, column: 0 }, messageId: "missingDefinition", data: { name: scope.name, type } })
+                if (!existsSync(join(siblings, `${scope.name}.options.ts`))) context.report({ node: program, loc: { line: 1, column: 0 }, messageId: "missingOptions", data: { name: scope.name, type } })
+            },
+            ClassDeclaration(node) {
+                if (scope?.kind !== "module" || !isModuleClass(node)) return
+                const base = node.superClass
+                const imported = base?.type === "Identifier" ? importedFrom.get(base.name) : null
+                if (!imported || imported.name !== "ConfigurableModuleClass" || imported.source !== `./${scope.name}.module-definition`) {
+                    context.report({ node: node.id ?? node, messageId: "extendsBase", data: { class: node.id?.name ?? "This class", name: scope.name } })
+                }
+            },
+            Property(node) {
+                const array = importsArrayOf(node)
+                if (!array) return
+                for (const entry of array.elements) {
+                    if (entry?.type === "Identifier" && isModuleClassIdentifier(entry)) context.report({ node: entry, messageId: "unregistered", data: { name: entry.name } })
+                }
+            },
         }
     },
 }
@@ -418,6 +512,7 @@ export const rules = {
     "is-global-only-in-app": isGlobalOnlyInApp,
     "no-cross-owner-module-import": noCrossOwnerModuleImport,
     "capability-module-shape": capabilityModuleShape,
+    "module-definition-required": moduleDefinitionRequired,
     "typed-module-definition": typedModuleDefinition,
     "static-module-register": staticModuleRegister,
     "no-new-injectable": noNewInjectable,
@@ -431,6 +526,7 @@ export const recommended = {
     "starci-be/is-global-only-in-app": "error",
     "starci-be/no-cross-owner-module-import": "error",
     "starci-be/capability-module-shape": "error",
+    "starci-be/module-definition-required": "error",
     "starci-be/typed-module-definition": "error",
     "starci-be/static-module-register": "error",
     "starci-be/no-new-injectable": "error",

package/operations.mjs

@@ -11,8 +11,9 @@
  * a path pattern.
  */
 import ts from "typescript"
+import { keyName, walk } from "./lib/ast.mjs"
 import { hfsOf } from "./lib/hfs.mjs"
-import { decoratorCallee, isImportedFrom } from "./lib/import-source.mjs"
+import { decoratorArguments, decoratorCallee, isImportedFrom } from "./lib/import-source.mjs"
 import { isTransportSlot } from "./lib/transport-slots.mjs"
 import { typed } from "./lib/types.mjs"
 
@@ -155,6 +156,167 @@ const unwrapPromise = (annotation) => {
     return node ?? null
 }
 
+/** The canon request and reply annotations of one HTTP method. */
+const operationReferences = (context, method) => {
+    const hfs = hfsOf(context)
+    const { checker, toTs } = typed(context)
+    const params = method.value.params.filter((param) => (param.decorators ?? []).some((decorator) => isImportedFrom(context, decoratorCallee(decorator), "@nestjs/common", "Body")))
+    return {
+        request: params.map((param) => canonReference(hfs, checker, toTs, param.typeAnnotation ?? param.parameter?.typeAnnotation)).find((reference) => reference?.name === "OperationRequest") ?? null,
+        reply: canonReference(hfs, checker, toTs, unwrapPromise(method.value.returnType)),
+    }
+}
+
+/** A route's table must be the nonempty result of the canon defineOperations, including an imported app table. */
+export const operationRouteEvidence = (context) => {
+    const hfs = hfsOf(context)
+    const { program, checker } = typed(context)
+    let tables
+    const declaredTables = () => {
+        if (tables) return tables
+        tables = new Set()
+        const visit = (node) => {
+            if (ts.isCallExpression(node) && isCanonType(hfs, checker, checker.getSymbolAtLocation(node.expression), "defineOperations")) {
+                const table = checker.getTypeAtLocation(node)
+                if (checker.getPropertiesOfType(table).length > 0) tables.add(table)
+            }
+            ts.forEachChild(node, visit)
+        }
+        for (const source of program.getSourceFiles()) {
+            if (!source.isDeclarationFile && hfs.slotOf(source.fileName)) visit(source)
+        }
+        return tables
+    }
+    return (method) => {
+        const { request, reply } = operationReferences(context, method)
+        return request?.table != null && reply?.name === "OperationReply" && request.table === reply.table && declaredTables().has(request.table)
+    }
+}
+
+/** A symbol declared by the app's domain identity capability, rather than a same-named local decorator or enum. */
+const identityExport = (context, node, name) => {
+    if (!node) return false
+    const hfs = hfsOf(context)
+    const { checker, toTs } = typed(context)
+    const target = toTs(node)
+    if (!target) return false
+    return declarationsOfSymbol(checker, checker.getSymbolAtLocation(target)).some((declaration) => {
+        const file = declaration.getSourceFile().fileName
+        return declaration.name?.text === name && hfs.tierOf(file) === "domain" && hfs.ownerOf(file)?.split("/").pop() === "identity"
+    })
+}
+
+const REST_REASONS = new Set(["Health", "AuthHandshake", "SignedWebhook"])
+const FILE_INTERCEPTORS = ["FileInterceptor", "FilesInterceptor", "AnyFilesInterceptor", "FileFieldsInterceptor"]
+
+/** A stream actually returned by this method; importing or mentioning a stream constructor proves nothing. */
+const returnsBytes = (context, method) => {
+    const seen = new Set()
+    const isBytes = (expression) => {
+        if (!expression || seen.has(expression)) return false
+        seen.add(expression)
+        if (["AwaitExpression", "TSAsExpression", "TSTypeAssertion", "TSNonNullExpression"].includes(expression.type)) return isBytes(expression.argument ?? expression.expression)
+        if (expression.type === "NewExpression" && isImportedFrom(context, expression.callee, "@nestjs/common", "StreamableFile")) return true
+        if (expression.type === "CallExpression" && isImportedFrom(context, expression.callee, ["node:fs", "fs"], "createReadStream")) return true
+        if (expression.type !== "Identifier") return false
+        for (let scope = context.sourceCode.getScope(expression); scope; scope = scope.upper) {
+            const variable = scope.set.get(expression.name)
+            if (variable) return variable.defs.some((definition) => definition.type === "Variable" && isBytes(definition.node.init))
+        }
+        return false
+    }
+    let found = false
+    walk(method.value.body, (node) => {
+        if (node.type === "ReturnStatement" && isBytes(node.argument)) found = true
+    }, { intoFunctions: false })
+    return found
+}
+
+/** True when a class declaration implements the `CanActivate` of `@nestjs/common` (resolved by symbol, not by spelling). */
+const implementsCanActivate = (checker, declaration) =>
+    (declaration.heritageClauses ?? []).some((clause) => clause.token === ts.SyntaxKind.ImplementsKeyword && clause.types.some((type) => {
+        const symbol = checker.getSymbolAtLocation(type.expression)
+        return declarationsOfSymbol(checker, symbol).some((found) => found.name?.text === "CanActivate" && /[\/]@nestjs[\/]common[\/]/.test(String(found.getSourceFile().fileName)))
+    }))
+
+/**
+ * True when the identity capability that declares `Credential` also declares the canon `CredentialGuard`, a class implementing
+ * `CanActivate`. The decorator only selects the credential kind; this guard is what authenticates it.
+ */
+const credentialGuardDeclared = (context, decoratorCallee_) => {
+    const hfs = hfsOf(context)
+    const { program, checker, toTs } = typed(context)
+    const target = toTs(decoratorCallee_)
+    const home = declarationsOfSymbol(checker, target ? checker.getSymbolAtLocation(target) : undefined).find((declaration) => declaration.name?.text === "Credential")
+    const owner = home && hfs.ownerOf(home.getSourceFile().fileName)
+    if (!owner) return false
+    for (const source of program.getSourceFiles()) {
+        if (source.isDeclarationFile || hfs.ownerOf(source.fileName) !== owner) continue
+        const found = source.statements.some((statement) => ts.isClassDeclaration(statement) && statement.name?.text === "CredentialGuard" && implementsCanActivate(checker, statement))
+        if (found) return true
+    }
+    return false
+}
+
+/**
+ * Credential-guarded route (BE_REST_DOOR_EVIDENCE, owner delegation 2026-10-16): the route, or its controller class, carries
+ * `@Credential({ kind: "<literal>" })` imported from the domain identity capability, and that capability declares a
+ * `CredentialGuard implements CanActivate`. A same-named local decorator, a `@UseGuards` of any other guard and a non-literal kind prove nothing.
+ */
+const credentialGuardEvidence = (context, method) => {
+    const carriers = [...(method.decorators ?? []), ...(method.parent?.parent?.decorators ?? [])]
+    for (const decorator of carriers) {
+        const callee = decoratorCallee(decorator)
+        if (!identityExport(context, callee, "Credential")) continue
+        const options = decoratorArguments(decorator)[0]
+        const kind = options?.type === "ObjectExpression" ? options.properties.find((property) => property.type === "Property" && keyName(property.key) === "kind")?.value : null
+        if (kind?.type === "Literal" && typeof kind.value === "string" && kind.value !== "" && credentialGuardDeclared(context, callee)) return true
+    }
+    return false
+}
+
+/** Route-level evidence for probes, auth handshakes, signed webhooks, redirects, byte transfers and credential-guarded routes. */
+export const restExceptionEvidence = (context, method) => {
+    if (credentialGuardEvidence(context, method)) return true
+    for (const decorator of method.decorators ?? []) {
+        const callee = decoratorCallee(decorator)
+        if (isImportedFrom(context, callee, "@nestjs/common", "Redirect")) return true
+        if (identityExport(context, callee, "Public")) {
+            const options = decoratorArguments(decorator)[0]
+            const reason = options?.type === "ObjectExpression" ? options.properties.find((property) => property.type === "Property" && keyName(property.key) === "reason")?.value : null
+            if (reason?.type === "MemberExpression" && !reason.computed && REST_REASONS.has(keyName(reason.property)) && identityExport(context, reason.object, "PublicReason")) return true
+        }
+        if (isImportedFrom(context, callee, "@nestjs/common", "UseInterceptors") && decoratorArguments(decorator).some((argument) => argument.type === "CallExpression" && isImportedFrom(context, argument.callee, "@nestjs/platform-express", FILE_INTERCEPTORS))) return true
+    }
+    return returnsBytes(context, method)
+}
+
+/** Public REST JSON is exposed through the app's declared operation table. */
+export const restRouteDeclared = {
+    meta: {
+        type: "problem",
+        docs: { description: "Every REST route outside probes, auth handshakes, signed webhooks and byte transfers uses a declared operation table." },
+        schema: [],
+        messages: {
+            undeclared: "[BE_REST_ROUTE_UNDECLARED] This REST route is absent from the app's defineOperations table. Serve public v1 JSON through @Body() request: OperationRequest<Table> and Promise<OperationReply<Table>> of the same declared table; otherwise expose it through GraphQL.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        if (!isTransportSlot(hfs.slotOf(context.filename))) return {}
+        const declared = operationRouteEvidence(context)
+        return {
+            MethodDefinition(node) {
+                if (node.kind !== "method" || node.static) return
+                if (!(node.decorators ?? []).some((decorator) => isImportedFrom(context, decoratorCallee(decorator), "@nestjs/common", HTTP_ROUTES))) return
+                const controller = node.parent?.parent
+                if (!(controller?.decorators ?? []).some((decorator) => isImportedFrom(context, decoratorCallee(decorator), "@nestjs/common", "Controller"))) return
+                if (!restExceptionEvidence(context, node) && !declared(node)) context.report({ node: node.key, messageId: "undeclared" })
+            },
+        }
+    },
+}
+
 /** An operation route takes the table's `OperationRequest` and answers its `OperationReply`, of one table. */
 export const operationRouteDrivenByTable = {
     meta: {
@@ -192,10 +354,12 @@ export const operationRouteDrivenByTable = {
 export const rules = {
     "operation-contract-decidable": operationContractDecidable,
     "operation-route-driven-by-table": operationRouteDrivenByTable,
+    "rest-route-declared": restRouteDeclared,
 }
 
 /** Every rule of this law at `error`. */
 export const recommended = {
     "starci-be/operation-contract-decidable": "error",
     "starci-be/operation-route-driven-by-table": "error",
+    "starci-be/rest-route-declared": "error",
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-be",
-  "version": "3.3.1",
+  "version": "3.4.0",
   "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
   "type": "module",
   "license": "MIT",

package/realtime.mjs

@@ -5,13 +5,15 @@
  * 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
+ *   - `realtime-shape` (R184): a `.gateway.ts` holds one `@WebSocketGateway` class whose handlers are `@SubscribeMessage`, or a
+ *     push-only gateway whose `@WebSocketServer` streams take the server's typed principal; 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.
+ *     (`@CurrentPrincipal()` of `domain/identity`, or `Principal` of `platform/cqrs` for a push-only stream), 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.
@@ -46,15 +48,37 @@ const doorClasses = (context, program, role) => {
     return found
 }
 
+/** The framework supplies this server property; no inbound message supplies a stream's principal. */
+const hasSocketServer = (context, node) => node.body.body.some((member) =>
+    member.type === "PropertyDefinition" && hasClassDecorator(context, member, "@nestjs/websockets", "WebSocketServer"))
+
+/** The authenticated principal port the socket middleware passes to a push-only stream. */
+const isStreamPrincipal = (context, param) => isOwnedType(context, param, { name: "Principal", capability: "cqrs", tier: "platform" })
+
+/** Subscriptions on the platform's hub, including those inside closures. */
+const hubSubscriptions = (context, method) => callsOf(method).filter(({ receiver, method: called }) =>
+    called === "subscribe" && receiver !== null && isHubType(context, receiver))
+
+/** The nonstatic methods a push-only gateway uses to feed its socket server. */
+const streamMethods = (context, node) => {
+    if (!hasSocketServer(context, node)) return []
+    return node.body.body.filter((member) => member.type === "MethodDefinition" && member.kind === "method" && !member.static
+        && hubSubscriptions(context, member).length > 0)
+}
+
+/** An inbound handler or a push-only stream taking the server's authenticated principal. */
+const hasOperation = (context, node, role) => methodsDecoratedBy(context, node, ...ROLES[role].operation).length > 0
+    || (role === "gateway" && streamMethods(context, node).some((method) => parametersOf(method).some((param) => isStreamPrincipal(context, param))))
+
 /** 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." },
+        docs: { description: "A realtime file is one door: a `.gateway.ts` holds one `@WebSocketGateway` class with `@SubscribeMessage` handlers or principal-typed push streams through `@WebSocketServer`, 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`.",
+            operations: "This {{role}} door has no `@{{operation}}` handler or principal-typed push stream through `@WebSocketServer`. A realtime door 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.",
         },
     },
@@ -70,7 +94,7 @@ export const realtimeShape = {
                     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] } })
+                if (!hasOperation(context, doors[0], role)) 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) {
@@ -128,14 +152,37 @@ const resolvesTo = (context, identifier, parameters) => {
     return false
 }
 
+/** A method's principal parameters, declared by the identity decorator or the push stream's platform type. */
+const principalParameters = (context, hfs, method, push) => {
+    const principals = new Set()
+    for (const param of parametersOf(method)) {
+        if (!isPrincipalParameter(context, hfs, param) && !(push && isStreamPrincipal(context, param))) continue
+        const target = param.type === "AssignmentPattern" ? param.left : param
+        if (target.type === "Identifier") principals.add(target)
+    }
+    return principals
+}
+
+/** The hub topic must use the method's principal declaration rather than a shadowing identifier. */
+const checkMethodTopics = (context, hfs, method, push) => {
+    const principals = principalParameters(context, hfs, method, push)
+    for (const { call } of hubSubscriptions(context, method)) {
+        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 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." },
+        docs: { description: "The topic passed to `RealtimeHub.subscribe` is built from the handler's `@CurrentPrincipal()` parameter or the push-only stream's platform `Principal` 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.",
+            scope: "The topic of this `subscribe` is not built from the principal. A realtime handler takes `@CurrentPrincipal() principal`, or a push-only stream takes the platform `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) {
@@ -145,21 +192,11 @@ export const realtimeTopicScope = {
         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" })
-                    }
+                const handlers = methodsDecoratedBy(context, node, source, name)
+                for (const method of handlers) checkMethodTopics(context, hfs, method, false)
+                if (role !== "gateway") return
+                for (const method of streamMethods(context, node)) {
+                    if (!handlers.includes(method)) checkMethodTopics(context, hfs, method, true)
                 }
             },
         }