@starci/eslint-canon-be 3.0.8 → 3.0.10

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/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))

package/lib/unit-spec.mjs

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

package/module-layering.mjs

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

package/module-shape.mjs

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

package/naming.mjs

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

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@starci/eslint-canon-be",
-  "version": "3.0.8",
+  "version": "3.0.10",
   "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
   "type": "module",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "private": false,
   "exports": {
     ".": "./index.mjs"
   },
   "main": "./index.mjs",
   "files": [
+    "LICENSE",
     "*.mjs",
     "lib/*.mjs",
     "runtime/**",
@@ -28,6 +29,8 @@
     "access": "public"
   },
   "scripts": {
+    "prepack": "node ../../hfs/prep-runtime.mjs",
+    "pretest": "node ../../hfs/prep-runtime.mjs",
     "test": "node --test \"*.spec.mjs\""
   },
   "keywords": [

package/project-graph.mjs

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

package/projections.mjs

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

package/query-safety.mjs

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