@starci/eslint-canon-be 3.0.7 → 3.0.9

package/jobs.mjs

@@ -0,0 +1,214 @@
+/**
+ * The rules that hold the fenced-job pattern (catalog R157 `BE_JOB_WRITE_OUTSIDE_OWNER`, R158 `BE_JOB_FENCE_REQUIRED`,
+ * R159 `BE_JOB_RUN_KEY`, R160 `BE_JOB_SHAPE`).
+ *
+ * A background job is a row whose `fencingToken` the claim bumps. A worker that lost its claim (a zombie) holds a stale token, so every
+ * write to the row is guarded by `expectedFencingToken` and an external effect carries an idempotency key that includes the token.
+ * `platform/jobs` is the ONE owner of the row: it declares the entity, the claim and the guarded writes, and nothing else writes it.
+ *
+ * Everything is found by TYPE ORIGIN (the `JobClaims`, `JobStep`, `RunKey` and `FencedProcessor` declared by `platform/jobs`, the entity
+ * class declared by that owner, typeorm receivers and query builders) and by the slot view (`be.feature.jobs.steps`, `be.feature.jobs`); the
+ * only names read are the contract's own members `runKey`, `jobId` and `expectedFencingToken`.
+ */
+import ts from "typescript"
+import { walk } from "./lib/ast.mjs"
+import { writtenEntityOrigins } from "./lib/entity-writes.mjs"
+import { hfsOf, inTestWorld } from "./lib/hfs.mjs"
+import { baseName, isOwnedType, ownerNameOf } from "./lib/ports.mjs"
+import { typeOrigins, typed } from "./lib/types.mjs"
+
+const isJobClaimsType = (context, node) => isOwnedType(context, node, { name: "JobClaims", capability: "jobs", tier: "platform" })
+const isJobStepType = (context, node) => isOwnedType(context, node, { name: "JobStep", capability: "jobs", tier: "platform" })
+const isFencedProcessorType = (context, node) => isOwnedType(context, node, { name: "FencedProcessor", capability: "jobs", tier: "platform" })
+const isRunKeyType = (context, node) => isOwnedType(context, node, { name: "RunKey", capability: "jobs", tier: "platform" })
+
+/** True for a file of the owner itself, and for the test composition. */
+const isOwnerOrTest = (hfs, file) => {
+    const tier = hfs.tierOf(file)
+    if (tier === "e2e" || tier === "fixtures" || inTestWorld(hfs, file)) return true
+    return tier === "platform" && ownerNameOf(hfs, file) === "jobs"
+}
+
+/** A write to an entity that `platform/jobs` declares (the job row) is made only by `platform/jobs`. */
+export const jobWriteOwner = {
+    meta: {
+        type: "problem",
+        docs: { description: "The job entity is written only by `platform/jobs`: no `update`, `increment`, `save`, `insert`, `delete` or query-builder write on it elsewhere." },
+        schema: [],
+        messages: {
+            foreign: "`{{call}}` writes the job row outside `platform/jobs`. The fencing token and the status of a job change only through `JobClaims` (`claim`, `advance`, `complete`, `fail`), each of which requires `expectedFencingToken`; a direct write lets a zombie worker overwrite the job a newer worker owns.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        if (isOwnerOrTest(hfs, context.filename)) return {}
+        return {
+            CallExpression(node) {
+                const origins = writtenEntityOrigins(context, node)
+                if (!origins.some((origin) => hfs.tierOf(origin.file) === "platform" && ownerNameOf(hfs, origin.file) === "jobs" && hfs.slotOf(origin.file) === "be.persistence")) return
+                context.report({ node, messageId: "foreign", data: { call: context.sourceCode.getText(node.callee) } })
+            },
+        }
+    },
+}
+
+/** The names the guarded-write contract fixes: the target job and the token the writer holds. */
+const TARGET = "jobId"
+const TOKEN = "expectedFencingToken"
+/** The property of a claimed job that holds the token it carries. */
+const CARRIED = "fencingToken"
+
+/** A property of a TypeScript type by name, or undefined. */
+const propertyOf = (type, name) => type.getProperty(name)
+
+/** True when the property is a required `number`. */
+const isRequiredNumber = (checker, property, location) => {
+    if (!property || (property.flags & ts.SymbolFlags.Optional) !== 0) return false
+    const type = checker.getTypeOfSymbolAtLocation(property, location)
+    return (type.flags & ts.TypeFlags.Number) !== 0
+}
+
+/** Calls on the `JobClaims` port, and what a guarded write is: required token, no cast to get around it, and `JobFencedOut` is not swallowed. */
+export const jobFenceRequired = {
+    meta: {
+        type: "problem",
+        docs: { description: "Every `JobClaims` method that writes an existing job declares a required `expectedFencingToken: number`, a call never casts around it, and a `catch` around a guarded write rethrows." },
+        schema: [],
+        messages: {
+            optionalToken: "`{{method}}` takes a job (`{{target}}`) but its parameter type does not require `{{token}}: number`. Every write to an existing job is guarded by the fencing token the caller holds: declare it required (non-optional, non-nullable) in the type.",
+            cast: "This argument of `{{call}}` uses a cast or a non-null assertion. The token a guarded write carries is the one the claim returned: pass it as typed, never `as`, `!` or `any` around it.",
+            swallowed: "This `catch` hides a failed guarded write: a `JobFencedOut` means a newer worker owns the job and this one must stop with no further effect. Do not catch around `JobClaims` writes in a step or processor; the `FencedProcessor` base class owns the failure path. Rethrow if you must catch.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        const owner = isOwnerOrTest(hfs, context.filename)
+        const { checker, toTs } = typed(context)
+        const claimsCall = (node) => node.type === "CallExpression" && node.callee.type === "MemberExpression" && !node.callee.computed && isJobClaimsType(context, node.callee.object)
+        return {
+            // The declaration side: in the owner, each member of the port that takes a job requires the token.
+            TSMethodSignature(node) {
+                if (!owner || hfs.tierOf(context.filename) !== "platform" || !isJobClaimsType(context, node.parent.parent?.id ?? node.parent)) return
+                const first = node.params?.[0]
+                if (!first) return
+                const tsNode = toTs(first)
+                const type = tsNode ? checker.getTypeAtLocation(tsNode) : undefined
+                // A parameter that already carries the token (the claimed job itself) is a derivation, not a write.
+                if (!type || !propertyOf(type, TARGET) || propertyOf(type, CARRIED)) return
+                if (!isRequiredNumber(checker, propertyOf(type, TOKEN), tsNode)) {
+                    context.report({ node: first, messageId: "optionalToken", data: { method: node.key?.name ?? "this method", target: TARGET, token: TOKEN } })
+                }
+            },
+            CallExpression(node) {
+                if (owner || !claimsCall(node)) return
+                for (const argument of node.arguments) {
+                    walk(argument, (child) => {
+                        if (child.type === "TSAsExpression" || child.type === "TSTypeAssertion" || child.type === "TSNonNullExpression") context.report({ node: child, messageId: "cast", data: { call: context.sourceCode.getText(node.callee) } })
+                    })
+                }
+            },
+            TryStatement(node) {
+                if (owner || !node.handler) return
+                let writes = false
+                walk(node.block, (child) => { if (claimsCall(child)) writes = true })
+                if (!writes) return
+                let rethrows = false
+                walk(node.handler.body, (child) => { if (child.type === "ThrowStatement") rethrows = true })
+                if (!rethrows) context.report({ node: node.handler, messageId: "swallowed" })
+            },
+        }
+    },
+}
+
+/** The class of an external effect of a step passes the key `JobClaims.runKey` made. */
+export const jobRunKey = {
+    meta: {
+        type: "problem",
+        docs: { description: "In a job step every call on an integration port passes a `RunKey` (made by `JobClaims.runKey`, which includes the fencing token), never a cast or a literal." },
+        schema: [],
+        messages: {
+            missing: "`{{call}}` is an external call from a job step without a `RunKey` argument. An effect that a zombie worker may repeat must be idempotent at the provider: pass `this.claims.runKey(job, \"<step>\")` (it includes the fencing token) as the idempotency key. A read belongs in the application layer, not in a step.",
+            forged: "This `RunKey` is built with a cast. Only `JobClaims.runKey(job, step)` makes one, so the key always carries the fencing token of the claim.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        if (hfs.slotOf(context.filename) !== "be.feature.jobs.steps") return {}
+        return {
+            CallExpression(node) {
+                const callee = node.callee
+                if (callee.type !== "MemberExpression" || callee.computed) return
+                const origins = typeOrigins(context, callee.object)
+                if (!origins.some((origin) => origin.module === null && hfs.tierOf(origin.file) === "integrations")) return
+                const keyArguments = node.arguments.filter((argument) => isRunKeyType(context, argument))
+                if (keyArguments.length === 0) {
+                    context.report({ node, messageId: "missing", data: { call: context.sourceCode.getText(callee) } })
+                    return
+                }
+                for (const argument of keyArguments) {
+                    walk(argument, (child) => { if (child.type === "TSAsExpression" || child.type === "TSTypeAssertion") context.report({ node: child, messageId: "forged" }) })
+                }
+            },
+        }
+    },
+}
+
+/** A processor extends the fenced base and is named after its job; a step implements `JobStep` in `steps/`. */
+export const jobShape = {
+    meta: {
+        type: "problem",
+        docs: { description: "`<job>.processor.ts` of `features/jobs/<job>/transport/queue/` declares a class extending `FencedProcessor`; `steps/<step>.step.ts` declares a class implementing `JobStep`; neither role exists elsewhere." },
+        schema: [],
+        messages: {
+            processorPlacement: "`{{name}}` is in a `.processor.ts` file outside `features/jobs/<job>/transport/queue/`. A job processor lives only in the queue transport of its job, so the jobs kind stays one place.",
+            processorStem: "The processor of job `{{job}}` is `{{job}}.processor.ts`, but this file is `{{stem}}.processor.ts`.",
+            notFenced: "`{{name}}` is a job processor that does not extend `FencedProcessor` of `platform/jobs`. The base class claims the job with a bumped fencing token and settles it through the guarded writes; a processor without it has no fence.",
+            stepPlacement: "`{{name}}` implements `JobStep` outside `features/jobs/<job>/steps/<step>.step.ts`.",
+            notStep: "`{{name}}` is in a step file but does not implement `JobStep` of `platform/jobs`.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        const file = context.filename
+        const found = hfs.classify(file)
+        const base = baseName(file)
+        const isProcessorFile = base.endsWith(".processor.ts")
+        const isStepFile = base.endsWith(".step.ts")
+        const inJob = found.slot === "be.feature.jobs.queue"
+        const inSteps = found.slot === "be.feature.jobs.steps"
+        const inPlatform = hfs.tierOf(file) === "platform" && ownerNameOf(hfs, file) === "jobs"
+        const check = (node) => {
+            const name = node.id?.name ?? "this class"
+            const extendsFenced = node.superClass ? isFencedProcessorType(context, node.superClass) : false
+            const implementsStep = (node.implements ?? []).some((entry) => isJobStepType(context, entry))
+            if (isProcessorFile && !inPlatform) {
+                if (!inJob) context.report({ node: node.id ?? node, messageId: "processorPlacement", data: { name } })
+                else {
+                    const stem = base.slice(0, -".processor.ts".length)
+                    if (found.bindings?.job !== undefined && found.bindings.job !== stem) context.report({ node: node.id ?? node, messageId: "processorStem", data: { job: found.bindings.job, stem } })
+                    if (!extendsFenced) context.report({ node: node.id ?? node, messageId: "notFenced", data: { name } })
+                }
+            }
+            if (isStepFile) {
+                if (!inSteps) context.report({ node: node.id ?? node, messageId: "stepPlacement", data: { name } })
+                else if (!implementsStep) context.report({ node: node.id ?? node, messageId: "notStep", data: { name } })
+            } else if (implementsStep && !inPlatform) context.report({ node: node.id ?? node, messageId: "stepPlacement", data: { name } })
+        }
+        return { ClassDeclaration: check, ClassExpression: check }
+    },
+}
+
+export const rules = {
+    "job-write-owner": jobWriteOwner,
+    "job-fence-required": jobFenceRequired,
+    "job-run-key": jobRunKey,
+    "job-shape": jobShape,
+}
+
+/** The level these laws ask for: `error`, switched off nowhere. */
+export const recommended = {
+    "starci-be/job-write-owner": "error",
+    "starci-be/job-fence-required": "error",
+    "starci-be/job-run-key": "error",
+    "starci-be/job-shape": "error",
+}

package/lib/ast.mjs

@@ -54,6 +54,13 @@ export const keyName = (node) => {
     return null
 }
 
+/** The decorators of a constructor parameter: on the parameter, its wrapper (`private readonly x`) or its inner identifier. */
+export const paramParts = (param) => {
+    const inner = param.type === "TSParameterProperty" ? param.parameter : param
+    const target = inner.type === "AssignmentPattern" ? inner.left : inner
+    return { target, decorators: [...new Set([...(param.decorators ?? []), ...(inner.decorators ?? []), ...(target.decorators ?? [])])] }
+}
+
 /** The name of a decorator (`@Foo` or `@Foo(...)`), else null. */
 export const decoratorName = (decorator) => {
     const expression = decorator?.expression

package/lib/config.mjs

@@ -1,7 +1,7 @@
 /**
  * The one flat config of a StarCi back end.
  *
- * A repository's `eslint.config.mjs` is a managed file (R05/R16), rendered by `hfs sync` as exactly:
+ * A repository's `eslint.config.mjs` is a managed file (R05/R16), rendered by `starci app sync` as exactly:
  *
  *     import { loadHfs, starciBeConfig } from "@starci/eslint-canon-be"
  *     export default starciBeConfig({ hfs: loadHfs(import.meta.url) })

package/lib/db-writes.mjs

@@ -6,7 +6,7 @@ import { staticText } from "./ast.mjs"
 import { isPackageType } from "./types.mjs"
 
 /** The `typeorm` types a call can write through. */
-export const RECEIVER_TYPES = Object.freeze(["EntityManager", "DataSource", "QueryRunner"])
+const RECEIVER_TYPES = Object.freeze(["EntityManager", "DataSource", "QueryRunner"])
 
 /** Statement text that changes rows. */
 export const WRITING_SQL = /(?:^|[\s;(])(?:insert\s+into|update\s+["`\w.]+\s+set|delete\s+from|truncate\b)/i

package/lib/doors.mjs

@@ -0,0 +1,81 @@
+/**
+ * What the door rules of the feature kinds (webhooks, realtime) read from a class: what is injected into it, which methods
+ * the framework enters, and which expression a call is made on. Every answer comes from a decorator's import, a value's
+ * declared type or a declaration's origin, never from a spelling.
+ */
+import ts from "typescript"
+import { walk } from "./ast.mjs"
+import { decoratorCallee, importOf, isImportedFrom } from "./import-source.mjs"
+import { typed } from "./types.mjs"
+
+/** True when the class carries a decorator that is `name` exported by `source`. */
+export const hasClassDecorator = (context, node, source, name) =>
+    (node.decorators ?? []).some((decorator) => isImportedFrom(context, decoratorCallee(decorator), source, name))
+
+/** The decorators of a method or class that are one of `names` exported by `source`. */
+export const decoratorsFrom = (context, node, source, names) =>
+    (node.decorators ?? []).filter((decorator) => isImportedFrom(context, decoratorCallee(decorator), source, names))
+
+/**
+ * Every value injected into a class: a constructor parameter (plain or a parameter property) and a property that
+ * carries a decorator which injects (`Inject` of Nest, a `@nestjs/typeorm` injector or a function declared in a
+ * `*.decorators.ts` file).
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {object} classNode - A `ClassDeclaration`.
+ * @returns {Array<{ node: object, annotation: object | undefined }>} The injected members, each with its declared type annotation.
+ */
+export const injectedMembers = (context, classNode) => {
+    const members = []
+    const constructor = classNode.body.body.find((member) => member.type === "MethodDefinition" && member.kind === "constructor")
+    for (const original of constructor?.value.params ?? []) {
+        const param = original.type === "TSParameterProperty" ? original.parameter : original
+        members.push({ node: original, annotation: param.typeAnnotation?.typeAnnotation })
+    }
+    for (const member of classNode.body.body) {
+        if (member.type !== "PropertyDefinition" || !(member.decorators ?? []).some((decorator) => isInjectorDecorator(context, decorator))) continue
+        members.push({ node: member, annotation: member.typeAnnotation?.typeAnnotation })
+    }
+    return members
+}
+
+/** True for a decorator that injects: `Inject` of Nest, a `@nestjs/typeorm` injector, or a function declared in a `*.decorators.ts` file. */
+const isInjectorDecorator = (context, decorator) => {
+    const callee = decoratorCallee(decorator)
+    if (callee?.type !== "Identifier") return false
+    const found = importOf(context, callee)
+    if (found?.source === "@nestjs/common" && found.imported === "Inject") return true
+    if (found?.source === "@nestjs/typeorm") return true
+    const symbol = aliasTarget(context, callee)
+    return (symbol?.getDeclarations() ?? []).some((declaration) => declaration.getSourceFile().fileName.split("\\").join("/").endsWith(".decorators.ts"))
+}
+
+/** The symbol an identifier names, with an import alias resolved to its target. */
+export const aliasTarget = (context, identifier) => {
+    const { checker, toTs } = typed(context)
+    const tsNode = toTs(identifier)
+    const symbol = tsNode && checker.getSymbolAtLocation(tsNode)
+    return symbol && (symbol.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(symbol) : symbol
+}
+
+/** The methods of a class (instance, non-constructor) that carry one of the decorators `names` of `source`. */
+export const methodsDecoratedBy = (context, classNode, source, names) =>
+    classNode.body.body.filter((member) => member.type === "MethodDefinition" && member.kind === "method" && !member.static && decoratorsFrom(context, member, source, names).length > 0)
+
+/**
+ * Every call made in a method body, closures included: `<receiver>.<method>(...)` as `{ call, receiver, method }`, and any
+ * other call as `{ call, receiver: null, method: null }`.
+ */
+export const callsOf = (method) => {
+    const calls = []
+    walk(method.value.body, (node) => {
+        if (node.type !== "CallExpression") return
+        const callee = node.callee
+        const member = callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" ? callee : null
+        calls.push({ call: node, receiver: member?.object ?? null, method: member?.property.name ?? null })
+    })
+    return calls
+}
+
+/** The parameters of a handler method, with the pattern a default value or a destructuring wraps unwrapped. */
+export const parametersOf = (method) => method.value.params.map((param) => (param.type === "TSParameterProperty" ? param.parameter : param))

package/lib/edition.mjs

@@ -0,0 +1,45 @@
+/**
+ * The edition gate of the back-end plugin.
+ *
+ * Edition applicability belongs to the HFS rule catalog, beside the law and its enforcer. A rule
+ * that the catalog does not judge in this app's edition still ships in the plugin, but its `create`
+ * returns no listeners. The plugin wiring therefore has one generic gate instead of edition checks
+ * scattered through rule bodies.
+ */
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { loadRuleCatalog } from "../runtime/scripts/hfs/slots.mjs"
+
+const RUNTIME = join(dirname(fileURLToPath(import.meta.url)), "..", "runtime")
+let catalogCache
+
+/** The bundled rule catalog, loaded once per lint process. */
+const bundledCatalog = () => {
+    catalogCache ??= loadRuleCatalog({ root: RUNTIME })
+    return catalogCache
+}
+
+/** A rule which intentionally registers no listeners in this edition. */
+const inactive = (rule) => Object.freeze({ ...rule, create: () => ({}) })
+
+/**
+ * The plugin view for one HFS edition.
+ *
+ * Full is the default edition and the catalog's superset, so it needs no runtime catalog read. This
+ * keeps the source checkout testable before `sync-runtime` refreshes the generated bundle; lite
+ * loads the package's bundled catalog in a published installation. Tests may inject a catalog to
+ * prove the generic filtering independently of generated copies.
+ */
+export const pluginForEdition = ({ plugin, hfs, catalog }) => {
+    const edition = hfs?.edition === undefined ? "full" : hfs.edition
+    if (edition !== "full" && edition !== "lite") {
+        throw new RangeError(`Unknown HFS edition ${JSON.stringify(edition)}; expected "full" or "lite"`)
+    }
+    if (edition === "full" && catalog === undefined) return plugin
+    const loaded = catalog ?? bundledCatalog()
+    const rules = Object.fromEntries(Object.entries(plugin.rules).map(([id, rule]) => [
+        id,
+        loaded.enforcerJudgedIn("eslint-be", id, edition) ? rule : inactive(rule),
+    ]))
+    return Object.freeze({ ...plugin, rules: Object.freeze(rules) })
+}

package/lib/entity-writes.mjs

@@ -0,0 +1,35 @@
+/**
+ * Which entities a database write call targets, found by TYPE: a write method called on a typeorm database receiver (`EntityManager`,
+ * `DataSource`, `QueryRunner`) or on a typeorm query builder, whose arguments (or, for a query builder, the arguments of any call
+ * of the same chain) are the entity class or an instance of it. No variable, class or table name is read.
+ */
+import { isDatabaseReceiver } from "./db-writes.mjs"
+import { typeOrigins } from "./types.mjs"
+
+/** The methods of a manager or query builder that change rows. */
+export const WRITE_METHODS = Object.freeze(["update", "save", "insert", "upsert", "delete", "remove", "increment", "decrement", "softDelete", "softRemove", "recover", "restore", "clear"])
+
+/** True when the node's type is a query builder of `typeorm` (`SelectQueryBuilder`, `UpdateQueryBuilder` ...). */
+const isQueryBuilder = (context, node) => typeOrigins(context, node).some((origin) => origin.module === "typeorm" && origin.name.endsWith("QueryBuilder"))
+
+/** The declarations (class origins) of the entities a database write call targets, or `[]` when the node is not such a call. */
+export const writtenEntityOrigins = (context, node) => {
+    const callee = node.callee
+    if (callee.type !== "MemberExpression" || callee.computed || callee.property.type !== "Identifier" || !WRITE_METHODS.includes(callee.property.name)) return []
+    if (!isDatabaseReceiver(context, callee.object) && !isQueryBuilder(context, callee.object)) return []
+    const candidates = [...node.arguments]
+    for (let link = callee.object; link; ) {
+        if (link.type === "CallExpression") {
+            candidates.push(...link.arguments)
+            link = link.callee.type === "MemberExpression" ? link.callee.object : null
+        } else if (link.type === "MemberExpression") link = link.object
+        else if (link.type === "TSNonNullExpression" || link.type === "AwaitExpression") link = link.expression ?? link.argument
+        else link = null
+    }
+    // The entity of a builder write may come later in the same chain (`.delete().from(Entity)`, `.insert().into(Entity)`).
+    for (let outer = node; outer.parent?.type === "MemberExpression" && outer.parent.object === outer && outer.parent.parent?.type === "CallExpression" && outer.parent.parent.callee === outer.parent; ) {
+        outer = outer.parent.parent
+        candidates.push(...outer.arguments)
+    }
+    return candidates.flatMap((candidate) => typeOrigins(context, candidate)).filter((origin) => origin.module === null)
+}

package/lib/hfs.mjs

@@ -4,8 +4,8 @@
  * A consuming `eslint.config.mjs` is the one line `export default starciBeConfig({ hfs: loadHfs(import.meta.url) })`.
  * The config lives in the be/ side folder of an app; `loadHfs` finds the app-root `hfs.json` one level up and gives every file
  * linted under that folder the view of the be side (paths relative to be/), with the slot manifest this package ships in
- * `runtime/` (a byte copy of the runtime's `knowledge/hfs/slots.yaml`, `scripts/lib/hfs-slots.mjs` and `scripts/lib/hfs-view.mjs`, refreshed by
- * `packages/hfs/scripts/sync-runtime.mjs`), and returns an object the factory puts in `settings.starci.hfs`.
+ * `runtime/` (a byte copy of the runtime's `knowledge/hfs/slots.yaml`, `scripts/hfs/slots.mjs` and `scripts/hfs/view.mjs`, refreshed by
+ * `scripts/hfs/sync-runtime.mjs`), and returns an object the factory puts in `settings.starci.hfs`.
  *
  * Every path-scoped rule asks `slotOf` here instead of testing a path with a regular expression: a rule never assumes
  * `/src/modules/` or `/src/tests/`. A rule that needs the manifest and finds no `settings.starci.hfs` stops the lint run
@@ -13,7 +13,7 @@
  */
 import { dirname, join } from "node:path"
 import { fileURLToPath } from "node:url"
-import { declaredHfsView, openHfsView } from "../runtime/scripts/lib/hfs-view.mjs"
+import { declaredHfsView, openHfsView } from "../runtime/scripts/hfs/view.mjs"
 
 const RUNTIME = join(dirname(fileURLToPath(import.meta.url)), "..", "runtime")
 

package/lib/path.mjs

@@ -4,12 +4,6 @@ export const normalizePath = (filename) => String(filename || "").replace(/\\/g,
 /** A spec file: the unit lane, where a fixture may build a deliberately wrong value. */
 export const isSpecFile = (filename) => /\.(?:spec|test)\.[cm]?[jt]sx?$|-spec\.[cm]?[jt]sx?$/.test(normalizePath(filename))
 
-/** Any file of the test lanes: a spec, or anything under `src/tests/`. */
-export const isTestLane = (filename) => {
-    const file = normalizePath(filename)
-    return isSpecFile(file) || file.includes("/src/tests/")
-}
-
 /** A migration: the one place schema-changing SQL is allowed to be written. */
 export const isMigrationFile = (filename) => /\/persistence\/migrations\/[^/]+\.[cm]?[jt]s$/.test(normalizePath(filename))
 

package/lib/persistence.mjs

@@ -6,6 +6,7 @@
  * `typeorm`'s; a file is the database capability's because the HFS slot manifest says so.
  */
 import { normalizePath } from "./path.mjs"
+import { ownerNameOf } from "./ports.mjs"
 import { typeOrigins } from "./types.mjs"
 
 /** The `typeorm` types a class must never receive except through the platform database capability. */
@@ -65,24 +66,14 @@ export const inDatabaseCapability = (hfs, file) => {
 }
 
 /**
- * Whether a file belongs to the migrate app.
+ * Whether a file is the command line of the back end: the cli app (slot `be.app.cli`) or the cli feature root (slot `be.cli`,
+ * `src/features/cli/`), where every one-off action runs, the migrate and seed commands among them.
  *
  * @param {object} hfs - The HFS view of the repository.
  * @param {string} file - A file path.
- * @returns {boolean} True for `be.app.migrate` files.
+ * @returns {boolean} True for the files of the cli app and the cli feature root.
  */
-export const inMigrateApp = (hfs, file) => hfs.slotOf(file) === "be.app.migrate"
-
-/**
- * Whether a file is the test world: slot `be.tests.world` (`src/tests/world/**`), the one test location that owns
- * the shared infrastructure (containers, apps/migrate bootstrap, teardown) and so may build and hold a `DataSource`.
- * Specs (unit and e2e) take `world.db.<connection>` instead (owner ruling on R83/R47, 2026-09-30).
- *
- * @param {object} hfs - The HFS view of the repository.
- * @param {string} file - A file path.
- * @returns {boolean} True for `be.tests.world` files.
- */
-export const inTestBootstrap = (hfs, file) => hfs.slotOf(file) === "be.tests.world"
+export const inCli = (hfs, file) => hfs.slotOf(file) === "be.app.cli" || hfs.slotOf(file) === "be.cli"
 
 /**
  * Whether a file is a migration: a `be.persistence` file below its `migrations/` folder.
@@ -113,11 +104,11 @@ export const connectionFileOf = (hfs, file, role) => {
     return connectionsOf(hfs).find((connection) => connection.name === name) ?? null
 }
 
-/** The platform capabilities that own a `persistence/` and so may hold an `EntityManager`. */
-const PERSISTENCE_CAPABILITIES = ["database", "inbox", "outbox", "lease"]
+/** The platform capabilities that own a `persistence/` and so may hold an `EntityManager` (a pattern capability is named by its folder). */
+const PERSISTENCE_CAPABILITIES = ["database", "inbox", "event-bus", "queue", "jobs", "saga", "outbox"]
 
 /**
- * Whether a class in this file may receive an `EntityManager`: an application handler, a domain service, a platform persistence capability.
+ * Whether a class in this file may receive an `EntityManager`: an application handler, a domain service, a projection, a typed queue producer (it takes the transaction of its caller), a platform persistence capability.
  *
  * @param {object} hfs - The HFS view of the repository.
  * @param {string} file - A file path.
@@ -128,7 +119,9 @@ export const mayHoldEntityManager = (hfs, file) => {
     const base = baseNameOf(file)
     if (found.slot === "be.feature.application") return base.endsWith(".handler.ts")
     if (found.slot === "be.domain") return base.endsWith(".service.ts")
-    return found.slot === "be.platform" && PERSISTENCE_CAPABILITIES.includes(found.bindings?.capability)
+    if (found.slot === "be.projections") return base.endsWith(".projection.ts")
+    if (found.slot === "be.queues") return base.endsWith(".queue.ts")
+    return typeof found.slot === "string" && found.slot.startsWith("be.platform") && PERSISTENCE_CAPABILITIES.includes(ownerNameOf(hfs, file))
 }
 
 /**

package/lib/ports.mjs

@@ -23,7 +23,10 @@ export const baseName = (file) => String(file).replace(/\\/g, "/").split("/").po
  */
 export const ownerNameOf = (hfs, file) => {
     const bindings = hfs.classify(file).bindings ?? {}
-    return bindings.capability ?? bindings.feature ?? null
+    if (bindings.capability ?? bindings.feature) return bindings.capability ?? bindings.feature
+    // A pattern slot names its capability literally (`src/modules/platform/event-bus/`), so no variable binds it: the owner folder is its name.
+    const root = hfs.ownerOf(file)
+    return root === null || root === undefined ? null : root.split("/").pop()
 }
 
 /**
@@ -33,7 +36,7 @@ export const ownerNameOf = (hfs, file) => {
  * @param {string} file - A file path.
  * @returns {string | null} The slot-relative path.
  */
-export const pathInSlot = (hfs, file) => {
+const pathInSlot = (hfs, file) => {
     const found = hfs.classify(file)
     if (!found.slot) return null
     const rel = hfs.relative(file)

package/lib/specifier.mjs

@@ -0,0 +1,27 @@
+/**
+ * Where an import specifier points. A `compilerOptions.paths` alias resolves through the program's own options, so a
+ * rule asks the same question TypeScript asks instead of maintaining a second alias table.
+ */
+import { posix } from "node:path"
+import { typed } from "./types.mjs"
+
+/**
+ * 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.
+ */
+export 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
+}

package/lib/transactions.mjs

@@ -0,0 +1,37 @@
+/**
+ * Questions a rule asks about database transactions: the callback of a `.transaction(...)` call and the variable an identifier
+ * resolves to. The receiver of `.transaction` is judged by its TYPE (typeorm's `EntityManager` or `DataSource`), never by its name.
+ */
+import { infraTypeOf } from "./persistence.mjs"
+
+/**
+ * The callback of a `.transaction(...)` call on a manager or data source, or null.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {object} node - A CallExpression.
+ * @returns {object | null} The arrow or function expression that receives the transactional manager.
+ */
+export const transactionCallback = (context, node) => {
+    const callee = node.callee
+    if (callee.type !== "MemberExpression" || callee.computed) return null
+    if (callee.property.type !== "Identifier" || callee.property.name !== "transaction") return null
+    const receiver = infraTypeOf(context, callee.object)
+    if (receiver !== "EntityManager" && receiver !== "DataSource") return null
+    const callback = node.arguments[node.arguments.length - 1]
+    return callback && (callback.type === "ArrowFunctionExpression" || callback.type === "FunctionExpression") ? callback : null
+}
+
+/**
+ * The variable an identifier resolves to, looking outward from the identifier's own scope.
+ *
+ * @param {object} sourceCode - The ESLint source code.
+ * @param {object} node - An Identifier.
+ * @returns {object | null} The scope variable.
+ */
+export const resolveVariable = (sourceCode, node) => {
+    for (let scope = sourceCode.getScope(node); scope; scope = scope.upper) {
+        const variable = scope.set.get(node.name)
+        if (variable) return variable
+    }
+    return null
+}

package/lib/transport-slots.mjs

@@ -2,13 +2,18 @@
  * The transport slots of the HFS manifest, in one place.
  *
  * A slot id is manifest vocabulary, not a path: every rule that judges "a transport file" asks this instead of spelling
- * the ids itself. The command-line slot carries its feature prefix in the manifest (`be.feature.transport.cli`).
+ * the ids itself. A cli command is no transport: it is an action runner of the cli feature root (slot `be.cli`). The
+ * webhook and realtime kinds hold their doors in slots of their own (`be.feature.webhooks.http`, `be.feature.realtime.graphql`, `be.feature.realtime.websocket`): a provider webhook and a
+ * push channel are doors like any other and answer to the door laws (default deny, bounded input, no envelope).
  */
 
+/** The slots of the feature kinds that are doors but are not an api's `transport/<protocol>/` folders. */
+export const KIND_DOOR_SLOTS = Object.freeze(["be.feature.webhooks.http", "be.feature.realtime.graphql", "be.feature.realtime.websocket"])
+
 /**
- * True for a slot that holds transport code (`be.transport.<protocol>` and the command-line slot).
+ * True for a slot that holds transport code (`be.transport.<protocol>` and the door slots of the webhook and realtime kinds).
  *
  * @param {string | null} slot - A slot id from `hfs.slotOf`.
  * @returns {boolean} Whether files of that slot are transport files.
  */
-export const isTransportSlot = (slot) => typeof slot === "string" && (slot.startsWith("be.transport.") || slot === "be.feature.transport.cli")
+export const isTransportSlot = (slot) => typeof slot === "string" && (slot.startsWith("be.transport.") || KIND_DOOR_SLOTS.includes(slot))