@starci/eslint-canon-be 1.0.0

package/observability.mjs

@@ -0,0 +1,141 @@
+/**
+ * The rules that hold `observability.md`.
+ *
+ * Two rules and one config line, covering the three ways a log escapes the pipeline: the framework's
+ * own logger, `console`, and a name fused with its data. The third is the one worth a rule of its
+ * own, because it is the only one that still LOOKS like structured logging - the call goes through
+ * the right service and produces an unqueryable line anyway.
+ *
+ * `no-console` is not reimplemented here: the standard rule already does it exactly, and shipping a
+ * second implementation of a rule everybody has would be a maintenance cost with no gain. It is
+ * named in `recommended` so a consuming repository switches it on with the others.
+ *
+ * OBSERVABILITY-4 and -5 are judgements a rule cannot make. Whether a log records a decision or
+ * merely an arrival needs to know what the code is FOR, and no parser knows that.
+ */
+
+/** Log methods the house service exposes. */
+const LOG_METHODS = new Set(["log", "error", "warn", "info", "debug", "verbose"])
+
+/** The house logging service, by the name it is injected under. */
+const LOGGER_RECEIVER = "winstonService"
+
+/** The framework logger this replaces. */
+const FRAMEWORK_LOGGER = "Logger"
+
+/** The package the framework logger comes from. */
+const FRAMEWORK_PACKAGE = "@nestjs/common"
+
+/** Whether a call's receiver is the house logging service, injected or via `this`. */
+const isLoggerReceiver = (node) => {
+  if (node.type === "Identifier") return node.name === LOGGER_RECEIVER
+  if (node.type === "MemberExpression" && !node.computed) return node.property.name === LOGGER_RECEIVER
+  return false
+}
+
+// -- OBSERVABILITY-1 -------------------------------------------------------------------------------
+
+/** Logs leave through the house service, never the framework's own logger. */
+export const noFrameworkLogger = {
+  meta: {
+    type: "problem",
+    docs: { description: "Only the house logging service logs; the framework's `Logger` is refused." },
+    schema: [],
+    messages: {
+      imported:
+        "`Logger` from `{{pkg}}` bypasses the correlation id and the transport configuration the house service wires up - the line is written in the right SHAPE and still arrives without the context every other line carries, or does not arrive at all. Inject the house logging service.",
+      constructed:
+        "`new Logger(...)` - same bypass, reached through a local construction rather than the import. Inject the house logging service.",
+    },
+  },
+  create(context) {
+    return {
+      ImportDeclaration(node) {
+        if (node.source.value !== FRAMEWORK_PACKAGE) return
+        for (const specifier of node.specifiers || []) {
+          if (specifier.type !== "ImportSpecifier") continue
+          if (specifier.imported && specifier.imported.name === FRAMEWORK_LOGGER) {
+            context.report({ node: specifier, messageId: "imported", data: { pkg: FRAMEWORK_PACKAGE } })
+          }
+        }
+      },
+      // caught separately so an aliased import cannot walk past the check above
+      NewExpression(node) {
+        if (node.callee.type === "Identifier" && node.callee.name === FRAMEWORK_LOGGER) {
+          context.report({ node, messageId: "constructed" })
+        }
+      },
+    }
+  },
+}
+
+// -- OBSERVABILITY-2 -------------------------------------------------------------------------------
+
+/** The event name is a member of a closed set, never a string built at the call site. */
+export const noInterpolatedLogMessage = {
+  meta: {
+    type: "problem",
+    docs: { description: "A log call's first argument is an enum member, not a built string." },
+    schema: [],
+    messages: {
+      built:
+        "The first argument to `{{method}}(...)` names WHAT happened and must come from the log-name enum. A string built here fuses the name with the data, so in one move the name stops being groupable and the data stops being queryable - and the day somebody rewords it, every dashboard built on it goes quiet. Pass the enum member, and put the variable part in the data object beside it.",
+    },
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        const callee = node.callee
+        if (callee.type !== "MemberExpression" || callee.computed) return
+        const method = callee.property.name
+        if (!LOG_METHODS.has(method)) return
+        if (!isLoggerReceiver(callee.object)) return
+
+        const first = node.arguments[0]
+        if (!first) return
+        const built = first.type === "TemplateLiteral"
+          || (first.type === "BinaryExpression" && first.operator === "+")
+          || (first.type === "Literal" && typeof first.value === "string")
+        if (built) context.report({ node: first, messageId: "built", data: { method } })
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "no-framework-logger": noFrameworkLogger,
+  "no-interpolated-log-message": noInterpolatedLogMessage,
+}
+
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * Both measured at zero debt in the reference repository ONCE the sanctioned exit is scoped:
+ * `no-framework-logger` reports four sites under the standalone-agent folder, and those are the
+ * exit rather than the debt. An agent running outside the request lifecycle has no request to
+ * correlate and no transport configured, so the house service would give it a dependency and
+ * nothing else. Scope that folder off in the consuming config -- once, by path -- rather than
+ * letting per-line suppressions accumulate until nobody can see how wide the exception has grown.
+ *
+ * `no-console` is the standard rule rather than a house one, listed here so a repository switches
+ * all three on together: it is the third way out of the pipeline, and leaving it off makes the
+ * other two decorative.
+ */
+export const recommended = {
+  "starci-be/no-framework-logger": "error",
+  "starci-be/no-interpolated-log-message": "error",
+  "no-console": "error",
+}
+
+/**
+ * Paths where a plain logger is sanctioned -- programs with no request to correlate.
+ *
+ * Exported so a consuming config and a measuring gate use the SAME list. Two copies of an exemption
+ * is how one of them silently grows.
+ */
+export const standaloneProgramGlobs = [
+  "src/modules/playground-agent-core/**",
+  "apps/playground-*-agent/**",
+  "apps/cli/**",
+]

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@starci/eslint-canon-be",
+  "version": "1.0.0",
+  "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "private": false,
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "main": "./index.mjs",
+  "files": [
+    "*.mjs",
+    "!*.test.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "peerDependencies": {
+    "eslint": ">=9"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test \"*.test.mjs\""
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "starci",
+    "canon"
+  ]
+}

package/testing.mjs

@@ -0,0 +1,353 @@
+/**
+ * The rules that hold `testing.md`.
+ *
+ * MOST OF THAT LAW IS NOT MACHINE-CHECKABLE, and pretending otherwise would be worse than
+ * checking nothing. No rule can tell whether a file represents a business flow, whether the
+ * unhappy path it covers drags a critical flow behind it, or whether the decision branches are
+ * covered - those are read by a person.
+ *
+ * What a rule CAN see is the two shapes that are wrong on their face regardless of intent: a spec
+ * whose every assertion is about a call rather than a result, and an end-to-end spec that never
+ * reads any state back. Both were measured before being written: eight specs and one e2e file in
+ * the source repository, which is why the second lands with a carve-out rather than at zero.
+ */
+
+/** Forward-slash form of a filename, so Windows paths compare like every other path. */
+const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
+
+/** The fast lane: a plain unit spec, excluding every other suffix that also ends in `spec.ts`. */
+const isUnitSpec = (filename) => {
+  const file = normalizePath(filename)
+  if (!/\.spec\.ts$/.test(file)) return false
+  return !/\.(?:e2e|int|harness)-spec\.ts$/.test(file)
+}
+
+/** The flow lane. */
+const isE2eSpec = (filename) => /\.e2e-spec\.ts$/.test(normalizePath(filename))
+
+/** The paid model-quality lane. */
+const isHarnessSpec = (filename) => /\.harness-spec\.ts$/.test(normalizePath(filename))
+
+/** Test-only helpers whose only authority is the harness lane. */
+const isHarnessHelper = (filename) => /\/src\/tests\/helpers\//.test(normalizePath(filename))
+
+/**
+ * Matchers that assert a CALL happened rather than what came out of it.
+ *
+ * Each is legitimate as a second assertion - "the mail went out" is a real observable effect. The
+ * rule fires only when a whole file has nothing else.
+ */
+const CALL_MATCHERS = new Set([
+  "toHaveBeenCalled",
+  "toHaveBeenCalledWith",
+  "toHaveBeenCalledTimes",
+  "toHaveBeenLastCalledWith",
+  "toHaveBeenNthCalledWith",
+  "toBeCalled",
+  "toBeCalledWith",
+  "toBeCalledTimes",
+  "toHaveReturned",
+])
+
+/** Names that mean the test read state back out of the database. */
+const STATE_READERS = /^(?:entityManager|dataSource|EntityManager|DataSource|getRepository|queryRunner)$/
+
+/**
+ * The matcher a given `expect(...)` call ends in.
+ *
+ * Climbs the member chain so modifiers pass through: `expect(x).not.toHaveBeenCalled()` answers
+ * `toHaveBeenCalled`, and `expect(p).resolves.toBe(1)` answers `toBe`.
+ */
+const matcherOf = (expectCall) => {
+  let cursor = expectCall
+  let last = null
+  while (cursor.parent && cursor.parent.type === "MemberExpression" && cursor.parent.object === cursor) {
+    last = cursor.parent.property && cursor.parent.property.name
+    cursor = cursor.parent
+  }
+  return last
+}
+
+// -- TESTING-6 -------------------------------------------------------------------------------------
+
+/** A spec whose every assertion is about a call restates the source instead of testing it. */
+export const noCallOnlySpec = {
+  meta: {
+    type: "problem",
+    docs: { description: "A unit spec asserts a result or a state change, not only that a call happened." },
+    schema: [],
+    messages: {
+      callOnly:
+        "Every assertion in this spec is `{{matchers}}` - it restates the handler's own source. Rename a collaborator's method and this file goes red; change the business rule to a wrong value and it stays green. Assert what came back, or what changed. A call assertion is legitimate as a SECOND assertion, where the call itself is the observable effect.",
+    },
+  },
+  create(context) {
+    if (!isUnitSpec(context.filename || context.getFilename())) return {}
+    let assertions = 0
+    let callAssertions = 0
+    const seen = new Set()
+    return {
+      CallExpression(node) {
+        if (!node.callee || node.callee.type !== "Identifier" || node.callee.name !== "expect") return
+        const matcher = matcherOf(node)
+        if (matcher === null) return
+        assertions += 1
+        if (!CALL_MATCHERS.has(matcher)) return
+        callAssertions += 1
+        seen.add(matcher)
+      },
+      "Program:exit"(node) {
+        // the file asserts nothing at all, or asserts something other than a call somewhere
+        if (assertions === 0 || callAssertions !== assertions) return
+        context.report({ node, messageId: "callOnly", data: { matchers: [...seen].join(", ") } })
+      },
+    }
+  },
+}
+
+// -- TESTING-2 -------------------------------------------------------------------------------------
+
+/** An end-to-end spec that never reads state back proves only that the server replied. */
+export const e2eAssertsPersistedState = {
+  meta: {
+    type: "problem",
+    docs: { description: "An e2e spec reads state back rather than asserting only on the response." },
+    schema: [],
+    messages: {
+      noState:
+        "This e2e never reads any state back - it asserts on responses alone, so the flow can stop persisting and this file stays green. Read the row, the balance or the entitlement out of the database and assert THAT. A flow that genuinely has no persisted consequence needs an eslint-disable naming what it observes instead.",
+    },
+  },
+  create(context) {
+    if (!isE2eSpec(context.filename || context.getFilename())) return {}
+    let readsState = false
+    return {
+      Identifier(node) {
+        if (STATE_READERS.test(node.name)) readsState = true
+      },
+      "Program:exit"(node) {
+        if (readsState) return
+        context.report({ node, messageId: "noState" })
+      },
+    }
+  },
+}
+
+// -- TESTING-9 -------------------------------------------------------------------------------------
+
+/** Provider SDKs. Importing one into a flow test is a real model call by any other name. */
+const PROVIDER_PACKAGES = /^(?:@anthropic-ai\/|openai$|openai\/|ollama$|@google\/generative-ai|@mistralai\/|cohere-ai)/
+
+/**
+ * The harness's own model helpers, which exist to reach a provider.
+ *
+ * Matched WITHOUT the `tests/` prefix: an e2e sits beside the helper folder, so the import it
+ * actually writes is the relative `../helpers/models.service`, and a pattern anchored on the
+ * absolute path never sees it.
+ */
+const HARNESS_MODEL_HELPERS = /helpers\/models(?:\.service)?$/
+
+/** An e2e never calls a model; the harness is the only lane that does. */
+export const noModelCallInE2e = {
+  meta: {
+    type: "problem",
+    docs: { description: "An e2e spec never reaches a model provider." },
+    schema: [],
+    messages: {
+      provider:
+        "`{{source}}` reaches a model provider from an e2e. A model call costs money, takes seconds and answers differently every time - so this makes the flow suite expensive, slow and flaky at once, and the assertion has to be loosened until it stops catching anything. Stub the model and assert what can actually break: the entitlement, the quota, the persisted answer. Judging the answer itself belongs in the harness.",
+    },
+  },
+  create(context) {
+    if (!isE2eSpec(context.filename || context.getFilename())) return {}
+    return {
+      ImportDeclaration(node) {
+        const source = node.source && node.source.value
+        if (typeof source !== "string") return
+        if (!PROVIDER_PACKAGES.test(source) && !HARNESS_MODEL_HELPERS.test(source)) return
+        context.report({ node, messageId: "provider", data: { source } })
+      },
+    }
+  },
+}
+
+// -- TESTING-3 -------------------------------------------------------------------------------------
+
+/** CQRS application buses are internal dispatchers, never production entry points. */
+const APPLICATION_BUSES = new Set(["CommandBus", "QueryBus", "EventBus"])
+
+/** Methods whose direct invocation skips the transport owned by production. */
+const INTERNAL_ENTRY_METHODS = new Set(["execute", "process"])
+
+/** An e2e enters through a production transport rather than an application object. */
+export const e2eUsesProductionTransport = {
+  meta: {
+    type: "problem",
+    docs: { description: "An e2e enters through GraphQL, HTTP, socket, broker or scheduler transport." },
+    schema: [],
+    messages: {
+      busImport:
+        "`{{name}}` is an application dispatcher, not a production transport. An e2e must enter through GraphQL, HTTP, a real socket, a broker message or the scheduler boundary so routing, guards, validation and serialization are part of the proof.",
+      direct:
+        "Direct `.{{method}}()` invocation skips the production transport and starts inside the application. Move this decision/wiring test to the integration lane, or drive the flow through GraphQL, HTTP, a real socket, broker or scheduler boundary.",
+    },
+  },
+  create(context) {
+    if (!isE2eSpec(context.filename || context.getFilename())) return {}
+    return {
+      ImportDeclaration(node) {
+        if (!node.source || node.source.value !== "@nestjs/cqrs") return
+        for (const specifier of node.specifiers) {
+          if (specifier.type !== "ImportSpecifier") continue
+          const imported = specifier.imported && (specifier.imported.name || specifier.imported.value)
+          if (!APPLICATION_BUSES.has(imported)) continue
+          context.report({ node: specifier, messageId: "busImport", data: { name: imported } })
+        }
+      },
+      CallExpression(node) {
+        const callee = node.callee
+        if (!callee || callee.type !== "MemberExpression" || callee.computed) return
+        const method = callee.property && callee.property.name
+        if (!INTERNAL_ENTRY_METHODS.has(method)) return
+        context.report({ node: callee.property, messageId: "direct", data: { method } })
+      },
+    }
+  },
+}
+
+// -- TESTING-10 ------------------------------------------------------------------------------------
+
+/** Official provider clients that a harness may call without a house routing layer. */
+const DIRECT_PROVIDER_PACKAGES = /^(?:@anthropic-ai\/sdk(?:\/|$)|openai(?:\/|$)|@google\/genai(?:\/|$)|@google\/generative-ai(?:\/|$)|@mistralai\/(?:mistralai|mistralai-ts)(?:\/|$)|cohere-ai(?:\/|$)|ollama(?:\/|$))/
+
+/** Helpers that hide a model call or impersonate the production gateway. */
+const FORBIDDEN_HARNESS_HELPERS = /(?:^|\/)(?:models(?:\.service)?|harness-invoke(?:\.service)?)$/
+
+/** Consumer/CLI credential authorities that are never provider API credentials. */
+const FORBIDDEN_HARNESS_AUTH = /(?:CLAUDE_CODE_OAUTH_TOKEN|claude-code-token|sk-ant-oat|OAUTH_BETA|CHATGPT_(?:SESSION|AUTH)_TOKEN|CODEX_(?:SESSION|AUTH)_TOKEN|auth-profile)/i
+
+/** Imported symbols that reveal a fake production gateway in the harness lane. */
+const FORBIDDEN_HARNESS_SYMBOLS = new Set([
+  "AiInvokeService",
+  "HarnessInvokeService",
+  "createHarnessInvoke",
+])
+
+/** Return the static property name of an object/member property when one exists. */
+const propertyName = (property) => {
+  if (!property) return null
+  if (property.type === "Identifier") return property.name
+  if (property.type === "Literal") return property.value
+  return null
+}
+
+/** Find the `AiInvokeService` token in a `Pick<AiInvokeService, ...>` type. */
+const aiInvokePickToken = (sourceCode) => {
+  const tokens = sourceCode.getTokens(sourceCode.ast)
+  for (let index = 0; index < tokens.length - 2; index += 1) {
+    if (tokens[index].value !== "Pick" || tokens[index + 1].value !== "<") continue
+    if (tokens[index + 2].value === "AiInvokeService") return tokens[index + 2]
+  }
+  return null
+}
+
+/** A harness calls one explicit provider SDK and never disguises it as `AiInvokeService`. */
+export const harnessCallsProviderDirectly = {
+  meta: {
+    type: "problem",
+    docs: { description: "A model-quality harness calls an approved provider SDK directly with provider API credentials." },
+    schema: [],
+    messages: {
+      missingProvider:
+        "This harness imports no approved provider SDK. A model-quality harness calls the declared provider client directly; a house helper, tier or gateway override can make it green about a model production does not use.",
+      gateway:
+        "`{{name}}` impersonates or replaces the production AI gateway from a harness. Reuse the production prompt builder and parser around a direct provider SDK call instead.",
+      helper:
+        "`{{source}}` hides the provider call behind a house harness helper. Import and call the approved provider SDK in this harness; only credential loading may be shared.",
+      consumerAuth:
+        "`{{authority}}` is a consumer or CLI credential authority, not a provider-issued server API key. Read an explicit harness API-key environment variable instead.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    const harness = isHarnessSpec(filename)
+    const authScope = harness || isHarnessHelper(filename)
+    if (!authScope) return {}
+
+    let hasProviderImport = false
+    return {
+      ImportDeclaration(node) {
+        const source = node.source && node.source.value
+        if (typeof source !== "string") return
+        if (harness && DIRECT_PROVIDER_PACKAGES.test(source)) hasProviderImport = true
+        if (harness && FORBIDDEN_HARNESS_HELPERS.test(source.replace(/\.(?:ts|js)$/, ""))) {
+          context.report({ node, messageId: "helper", data: { source } })
+        }
+        if (!harness) return
+        for (const specifier of node.specifiers) {
+          const imported = specifier.imported && (specifier.imported.name || specifier.imported.value)
+          const local = specifier.local && specifier.local.name
+          const name = imported || local
+          if (!FORBIDDEN_HARNESS_SYMBOLS.has(name)) continue
+          context.report({ node: specifier, messageId: "gateway", data: { name } })
+        }
+      },
+      Literal(node) {
+        if (typeof node.value !== "string" || !FORBIDDEN_HARNESS_AUTH.test(node.value)) return
+        context.report({ node, messageId: "consumerAuth", data: { authority: node.value } })
+      },
+      Property(node) {
+        if (!harness || propertyName(node.key) !== "provide") return
+        if (!node.value || node.value.type !== "Identifier" || node.value.name !== "AiInvokeService") return
+        context.report({ node, messageId: "gateway", data: { name: "provide: AiInvokeService" } })
+      },
+      CallExpression(node) {
+        if (!harness || !node.callee || node.callee.type !== "MemberExpression") return
+        if (propertyName(node.callee.property) !== "overrideProvider") return
+        const argument = node.arguments && node.arguments[0]
+        if (!argument || argument.type !== "Identifier" || argument.name !== "AiInvokeService") return
+        context.report({ node, messageId: "gateway", data: { name: "overrideProvider(AiInvokeService)" } })
+      },
+      "Program:exit"(node) {
+        if (!harness) return
+        const sourceCode = context.sourceCode || context.getSourceCode()
+        const pickToken = aiInvokePickToken(sourceCode)
+        if (pickToken) {
+          context.report({ node: pickToken, messageId: "gateway", data: { name: 'Pick<AiInvokeService, "run">' } })
+        }
+        if (!hasProviderImport) context.report({ node, messageId: "missingProvider" })
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "no-call-only-spec": noCallOnlySpec,
+  "e2e-asserts-persisted-state": e2eAssertsPersistedState,
+  "no-model-call-in-e2e": noModelCallInE2e,
+  "e2e-uses-production-transport": e2eUsesProductionTransport,
+  "harness-calls-provider-directly": harnessCallsProviderDirectly,
+}
+
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * MEASURED WITH THE RULES THEMSELVES against the reference repository, which is the only count
+ * worth writing down: 1 call-only spec of 181, and 1 e2e of 48 that never reads state back.
+ *
+ * That number was wrong twice before it was right, and both ways are worth knowing. A grep-based
+ * estimate said EIGHT - it counted files whose assertions merely INCLUDED a call matcher, which is
+ * the shape this rule deliberately permits. A first run of the rule itself said THREE - it counted
+ * eslint's own complaints about inline `eslint-disable` comments referring to rules the measuring
+ * config never loaded. Count only the reports carrying this rule's own id.
+ *
+ * Both land at `warn` with the count, get burned down, and flip to `error` at zero.
+ */
+export const recommended = {
+  "starci-be/no-call-only-spec": "error", // no=0 of 182 - burned down from 1
+  "starci-be/e2e-asserts-persisted-state": "error", // no=0 of 47 - burned down from 1
+  "starci-be/no-model-call-in-e2e": "error", // no=0 of 47
+  "starci-be/e2e-uses-production-transport": "error",
+  "starci-be/harness-calls-provider-directly": "error",
+}

package/transport.mjs

@@ -0,0 +1,103 @@
+const normalize = (filename) => String(filename || "").replace(/\\/g, "/")
+
+/** The decorator's own name, whether it was written `@Controller` or `@Controller("x")`. */
+const decoratorName = (node) => {
+  const expression = node.expression
+  if (!expression) return null
+  if (expression.type === "Identifier") return expression.name
+  if (expression.type === "CallExpression" && expression.callee.type === "Identifier") {
+    return expression.callee.name
+  }
+  return null
+}
+
+/** The route string, or "" for `@Controller()` and for a path given as an object. */
+const routeOf = (node) => {
+  const expression = node.expression
+  if (!expression || expression.type !== "CallExpression") return ""
+  const first = expression.arguments[0]
+  if (first && first.type === "Literal" && typeof first.value === "string") return first.value
+  return ""
+}
+
+/**
+ * Which of the four sanctioned reasons this file shows, if any.
+ *
+ * READ OFF THE FILE, NOT OFF A LIST. A registry of blessed routes rots the moment somebody adds a
+ * route and forgets it; the evidence here is the same evidence a reader would use.
+ */
+const reasonFor = (route, filename, text) => {
+  const path = normalize(filename)
+  // a probe answers when the app is degraded, before the feature layer is necessarily up
+  if (/^healthz?$/.test(route) || /\/health(z)?[./]/.test(path)) return "probe"
+  // something outside posts to a URL we gave it, and it will never send a GraphQL document
+  if (/webhook/i.test(route) || /webhook/i.test(path)) return "external"
+  // bytes, not fields: multipart in, stream out
+  if (/FileInterceptor|FilesInterceptor|AnyFilesInterceptor|StreamableFile|@Res\s*\(|createReadStream/.test(text)) {
+    return "bytes"
+  }
+  // a machine registering itself, with no user session to carry
+  if (/^(pods|internal|agents)\//.test(route)) return "machine"
+  // an identity that is not a user session - a platform operator or a service token
+  if (/^api\/ops(\/|$)/.test(route) || /Operator[A-Za-z]*Guard|ServiceToken|OPS_TOKEN/.test(text)) {
+    return "operator"
+  }
+  return null
+}
+
+/** A REST door exists only where GraphQL cannot go, and the file has to show which case it is. */
+export const restDoorNeedsAReason = {
+  meta: {
+    type: "problem",
+    docs: { description: "A @Controller is permitted only where GraphQL cannot serve." },
+    schema: [],
+    messages: {
+      unjustified:
+        "This REST door shows none of the four reasons a door may not be GraphQL: an external system posting to a fixed URL, a payload of bytes rather than fields, a machine with no user session, or an identity that is not one. A plain JSON read belongs in the GraphQL schema, where the client already is.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    const text = (context.sourceCode || context.getSourceCode()).getText()
+    return {
+      Decorator(node) {
+        if (decoratorName(node) !== "Controller") return
+        if (reasonFor(routeOf(node), filename, text)) return
+        context.report({ node, messageId: "unjustified" })
+      },
+    }
+  },
+}
+
+/** A door is a door whatever its transport, and every door in this repository lives in features/. */
+export const doorLivesInFeatures = {
+  meta: {
+    type: "problem",
+    docs: { description: "HTTP doors sit under features/, beside the GraphQL ones." },
+    schema: [],
+    messages: {
+      wrongTree:
+        "A @Controller under src/modules/ is a door parked among the capabilities it calls, where it reads as one and gets imported like one. Every GraphQL door in this repository already lives under features/; transport was never what decided the address.",
+    },
+  },
+  create(context) {
+    const path = normalize(context.filename || context.getFilename())
+    if (!/\/src\/modules\//.test(path)) return {}
+    return {
+      Decorator(node) {
+        if (decoratorName(node) !== "Controller") return
+        context.report({ node, messageId: "wrongTree" })
+      },
+    }
+  },
+}
+
+export const rules = {
+  "rest-door-needs-a-reason": restDoorNeedsAReason,
+  "door-lives-in-features": doorLivesInFeatures,
+}
+
+export const recommended = {
+  "starci-be/rest-door-needs-a-reason": "error",
+  "starci-be/door-lives-in-features": "error",
+}