@starci/eslint-canon-be 1.8.0 → 2.0.0

package/schema-authority.mjs

@@ -1,24 +1,59 @@
 /**
- * The rules that hold HFS schema authority and the persistence boundary (catalog R34, R36, R37).
+ * The rules that hold HFS schema authority and the persistence boundary (catalog R34, R37, R74).
  *
  * The schema changes by migration and by nothing else, and the SQL that touches it lives in one place:
  *
- *   - `no-runtime-schema` (R34 `BE_SCHEMA_AUTHORITY`) refuses everything that lets the running process decide
- *     the schema: a `synchronize` that is not the literal `false`, a `dataSource.synchronize()` call, a
- *     `migrationsRun` that is not the literal `false`, a `CREATE|ALTER|DROP TABLE` string outside
- *     `persistence/migrations/`, and an entity or migration glob. Only `apps/migrate` runs migrations.
- *   - `sql-text-only` (R36) keeps raw SQL text inside a `<name>.sql.ts` (the owning capability's `persistence/`,
- *     or a test builder's `src/tests/fixtures/builders/<area>.sql.ts`): `.query(...)` elsewhere takes an imported
- *     text constant, never a literal or template; `createQueryBuilder` is not used.
- *   - `no-repository-file` (R36) refuses a `*.repository.ts` file: repositories are banned (owner rule); SQL text lives
- *     in `<name>.sql.ts` and the capability's service runs it on the shared EntityManager.
- *   - `no-entity-in-contract` (R37 `BE_ENTITY_IN_CONTRACT`) keeps ORM entities out of the types that cross a
- *     boundary: `*.contracts.ts`, DTOs, resolver and controller signatures. A contract returns a projection.
+ *   - `no-runtime-schema` (R34 `BE_SCHEMA_AUTHORITY`) refuses everything that lets the running process decide the
+ *     schema: a DataSource / TypeORM options object (an object literal whose contextual TYPE is a `typeorm` or
+ *     `@nestjs/typeorm` options type) with no literal `synchronize: false`; a `synchronize` that is anything but
+ *     the literal `false`; `new DataSource(<not an object literal>)` whose options cannot be read; a
+ *     `dataSource.synchronize()` or `.dropDatabase()` call; the `migrationsRun` option in any form and a `runMigrations()` /
+ *     `undoLastMigration()` call outside `apps/migrate` and the test world; `dropSchema` set to anything but `false`; a schema
+ *     builder (`createSchemaBuilder()`, `.build()` of typeorm's `SchemaBuilder`); a `synchronize` key in the options of typeorm's
+ *     `@Entity` (a per-entity switch is a second authority); a lifecycle hook (`onModuleInit`, `onApplicationBootstrap`) that
+ *     writes rows through an `EntityManager` or `DataSource` (seeding runs in `apps/migrate`); a DDL statement in any string
+ *     outside the migrations of `persistence/`; and an entity or migration glob. Only `apps/migrate` runs migrations and seeds.
+ *   - `no-entity-in-contract` (R37 `BE_ENTITY_IN_CONTRACT`) keeps ORM entities out of the types that cross a boundary:
+ *     any type whose declaration carries `@Entity` (from `typeorm`), reached through the type arguments and properties of
+ *     a transport signature, the `execute` of a handler, or a `*.contracts.ts`, `*.command.ts` or `*.query.ts` file; and
+ *     entity files that import `@nestjs/graphql` or `class-validator` (an entity never reaches a contract).
+ *
+ * Where a file lives is asked of the slot view (`be.persistence` and its `migrations/` folder, the transport slots),
+ * never of a path pattern.
  */
-import { keyName, staticText, walk } from "./lib/ast.mjs"
-import { isDeclarationFile, isMigrationFile, normalizePath } from "./lib/path.mjs"
+import ts from "typescript"
+import { keyName, walk } from "./lib/ast.mjs"
+import { hfsOf, inTestWorld } from "./lib/hfs.mjs"
+import { baseName, isMigrationFile, packageOfFile } from "./lib/ports.mjs"
+import { isPackageType, typed } from "./lib/types.mjs"
+import { isDeclarationFile } from "./lib/path.mjs"
+
+/** Schema-changing statements: `CREATE|ALTER|DROP` of a structure, `TRUNCATE TABLE`, `ADD|DROP COLUMN`. */
+const DDL = /\b(?:(?:CREATE|ALTER|DROP)\s+(?:OR\s+REPLACE\s+)?(?:UNIQUE\s+)?(?:TEMP(?:ORARY)?\s+)?(?:TABLE|INDEX|TYPE|SCHEMA|VIEW|MATERIALIZED\s+VIEW|SEQUENCE|EXTENSION|DATABASE|TRIGGER|FUNCTION|PROCEDURE|DOMAIN|POLICY|PUBLICATION|COLLATION|ROLE)|TRUNCATE\s+TABLE|(?:ADD|DROP)\s+(?:COLUMN|CONSTRAINT))\b/i
+
+/** The packages whose option types describe a DataSource. */
+const OPTION_PACKAGES = new Set(["typeorm", "@nestjs/typeorm"])
+
+/** The DataSource operations that change the schema at runtime. */
+const SCHEMA_OPERATIONS = new Set(["synchronize", "dropDatabase"])
+
+/** The DataSource operations that run migrations: allowed only in `apps/migrate` and the test world that runs its bootstrap. */
+const MIGRATION_RUNNERS = new Set(["runMigrations", "undoLastMigration"])
+
+/** The typeorm types whose methods write rows. */
+const WRITER_TYPES = ["EntityManager", "DataSource", "QueryRunner"]
+
+/** The typeorm schema builder types. */
+const SCHEMA_BUILDER_TYPES = ["SchemaBuilder", "RdbmsSchemaBuilder"]
+
+/** The writes of an `EntityManager` that need no SQL text to be recognised. */
+const WRITE_METHODS = new Set(["insert", "save", "upsert", "update", "delete", "remove", "softRemove", "softDelete", "recover", "increment", "decrement", "clear"])
+
+/** A statement that writes rows. */
+const WRITE_SQL = /\b(?:INSERT\s+INTO|UPDATE\s+\S+\s+SET|DELETE\s+FROM|MERGE\s+INTO)\b/i
 
-const DDL = /\b(?:CREATE|ALTER|DROP)\s+TABLE\b/i
+/** The Nest lifecycle hooks that run at boot in every process that composes the provider. */
+const BOOT_HOOKS = new Set(["onModuleInit", "onApplicationBootstrap"])
 
 const isFalse = (node) => node?.type === "Literal" && node.value === false
 
@@ -32,39 +67,143 @@ const stringsUnder = (node) => {
     return found
 }
 
+/** The non-union, non-intersection constituents of a TypeScript type. */
+const leavesOf = (type) => (type.isUnionOrIntersection() ? type.types.flatMap(leavesOf) : [type])
+
+/** The `synchronize` members that typeorm declares on the contextual type of an object literal, as TypeScript declarations. */
+const synchronizeMembers = (context, node) => {
+    const { checker, toTs } = typed(context)
+    const tsNode = toTs(node)
+    const expected = tsNode ? checker.getContextualType(tsNode) : undefined
+    if (!expected) return []
+    return leavesOf(expected)
+        .flatMap((part) => checker.getPropertyOfType(part, "synchronize")?.declarations ?? [])
+        .filter((declaration) => OPTION_PACKAGES.has(packageOfFile(declaration.getSourceFile().fileName)))
+}
+
+/** A `synchronize` declared as a method is the DataSource operation, not the options flag. */
+const isMethod = (declaration) => ts.isMethodSignature(declaration) || ts.isMethodDeclaration(declaration)
+
+/** A `synchronize` declared on typeorm's `EntityOptions` is the per-entity switch, not the connection's. */
+const isEntityOption = (declaration) => ts.isInterfaceDeclaration(declaration.parent) && declaration.parent.name.text === "EntityOptions"
+
+/** Whether an object literal is contextually a DataSource options object: its expected type has a `synchronize` option (a property, not the `synchronize()` method, not an entity's) declared by `typeorm`. */
+const isOptionsObject = (context, node) => synchronizeMembers(context, node).some((declaration) => !isMethod(declaration) && !isEntityOption(declaration))
+
+/** Whether an object literal is the options of typeorm's `@Entity(...)`. */
+const isEntityOptions = (context, node) => synchronizeMembers(context, node).some(isEntityOption)
+
+/** Whether an object literal is contextually a DataSource (or a partial of one) whose `synchronize` is the method: its keys are overrides of operations, not configuration. */
+const isOperationsObject = (context, node) => {
+    const members = synchronizeMembers(context, node)
+    return members.length > 0 && members.every(isMethod)
+}
+
+/** Whether a file is `apps/migrate` (slot `be.app.migrate`) or the test world that runs its bootstrap: the only places that run migrations and seed. */
+const isMigrationHost = (hfs, filename) => hfs.slotOf(filename) === "be.app.migrate" || inTestWorld(hfs, filename)
+
+/** The SQL text of a call argument: a literal, a template, or the quasis of a tagged template. */
+const sqlTextOf = (argument) => (argument ? stringsUnder(argument).join(" ") : "")
+
+/**
+ * The first call under a lifecycle hook that writes rows: an `EntityManager`/`DataSource`/`QueryRunner` write method, a `.query(...)` whose
+ * text writes, or a call of another method of the same class (`this.seed()`) that does.
+ */
+const bootWriteOf = (context, method, klass, visited) => {
+    let found = null
+    walk(method.value.body, (node) => {
+        if (found || node.type !== "CallExpression") return
+        const callee = node.callee
+        if (callee.type !== "MemberExpression" || callee.computed || callee.property.type !== "Identifier") return
+        const name = callee.property.name
+        if (callee.object.type === "ThisExpression") {
+            const target = klass.body.body.find((member) => member.type === "MethodDefinition" && member.kind === "method" && !member.computed && keyName(member.key) === name)
+            if (target && !visited.has(target)) {
+                visited.add(target)
+                found = bootWriteOf(context, target, klass, visited)
+            }
+            return
+        }
+        if (!WRITER_TYPES.some((type) => isPackageType(context, callee.object, type, "typeorm"))) return
+        if (WRITE_METHODS.has(name) || (name === "query" && WRITE_SQL.test(sqlTextOf(node.arguments[0])))) found = node
+    })
+    return found
+}
+
+/** Whether an object literal has a property called `name`. */
+const hasKey = (objectNode, name) => objectNode.properties.some((property) => property.type === "Property" && !property.computed && keyName(property.key) === name)
+
 /** The schema is decided by migrations run by `apps/migrate`, never by the running process. */
 export const noRuntimeSchema = {
     meta: {
         type: "problem",
-        docs: { description: "No synchronize, no migrationsRun in a service, no runtime DDL, no entity or migration glob." },
+        docs: { description: "Every DataSource options object states `synchronize: false`; no `migrationsRun`, no runtime DDL, no entity or migration glob." },
         schema: [],
         messages: {
             synchronize: "`synchronize` is set to something other than the literal `false`. The schema changes by migration only; a boot-time ORM diff decides it otherwise.",
-            synchronizeCall: "`.synchronize()` builds the schema at runtime. Write a migration and let `apps/migrate` run it.",
-            migrationsRun: "`migrationsRun` is not the literal `false`. Only `apps/migrate` runs migrations, once per connection, before api and worker start.",
-            ddl: "A `CREATE|ALTER|DROP TABLE` string outside `persistence/migrations/`. Schema-changing SQL belongs in a migration.",
+            synchronizeMissing: "This DataSource options object does not state `synchronize: false`. Write the literal `false` in every options object, so what the connection may do to the schema is readable where it is built.",
+            optionsNotLiteral: "`new DataSource(...)` is given options that are not an object literal, so `synchronize: false` cannot be seen. Pass the options as an object literal that states `synchronize: false`.",
+            synchronizeCall: "`.{{name}}()` changes the schema at runtime. Write a migration and let `apps/migrate` run it.",
+            migrationsRun: "`migrationsRun` is banned. Only `apps/migrate` runs migrations, once per connection, before api and worker start.",
+            runMigrations: "`.{{name}}()` runs migrations outside `apps/migrate`. Only `apps/migrate` (and the test world, which runs its bootstrap) runs them, once per connection, before api and worker start.",
+            dropSchema: "`dropSchema` is set to something other than the literal `false`. A connection never drops the schema it opens; a migration changes it.",
+            schemaBuilder: "`{{name}}` builds or logs the schema from the entity metadata at runtime. The schema changes by migration only.",
+            entitySynchronize: "`synchronize` is set in the options of `@Entity`. A per-entity switch is a second schema authority next to the connection's literal `false`; delete the key.",
+            bootSeed: "`{{hook}}` writes rows (`{{call}}`), so every process that composes this provider seeds at boot. Seeding runs in `apps/migrate` only, once per connection.",
+            ddl: "A schema-changing statement (`CREATE|ALTER|DROP ...`) outside `persistence/migrations/`. Schema-changing SQL belongs in a migration.",
             glob: "`{{key}}` is found by glob. List the entities and migrations explicitly from each capability's `index.ts` so what runs is what was reviewed.",
         },
     },
     create(context) {
-        const filename = normalizePath(context.filename || context.getFilename())
+        const filename = context.filename || context.getFilename()
         if (isDeclarationFile(filename)) return {}
-        const migration = isMigrationFile(filename)
+        const hfs = hfsOf(context)
+        const migration = isMigrationFile(hfs, filename)
+        const migrationHost = isMigrationHost(hfs, filename)
         return {
+            ObjectExpression(node) {
+                if (isOptionsObject(context, node) && !hasKey(node, "synchronize")) context.report({ node, messageId: "synchronizeMissing" })
+            },
+            MethodDefinition(node) {
+                if (node.kind !== "method" || node.computed || !BOOT_HOOKS.has(keyName(node.key) ?? "") || migrationHost) return
+                const klass = node.parent?.parent
+                if (klass?.type !== "ClassDeclaration" && klass?.type !== "ClassExpression") return
+                const write = bootWriteOf(context, node, klass, new Set([node]))
+                if (write) context.report({ node: write, messageId: "bootSeed", data: { hook: keyName(node.key), call: context.sourceCode.getText(write.callee) } })
+            },
             Property(node) {
+                if (node.computed) return
                 const key = keyName(node.key)
-                if (key === "synchronize" && !isFalse(node.value)) {
+                if (key === "synchronize" && node.parent?.type === "ObjectExpression" && isEntityOptions(context, node.parent)) {
+                    context.report({ node, messageId: "entitySynchronize" })
+                } else if (key === "dropSchema" && !isFalse(node.value)) {
+                    context.report({ node, messageId: "dropSchema" })
+                } else if (key === "synchronize" && !isFalse(node.value)) {
+                    if (node.parent?.type === "ObjectExpression" && isOperationsObject(context, node.parent)) return
                     context.report({ node, messageId: "synchronize" })
-                } else if (key === "migrationsRun" && !isFalse(node.value)) {
+                } else if (key === "migrationsRun") {
                     context.report({ node, messageId: "migrationsRun" })
                 } else if ((key === "entities" || key === "migrations") && stringsUnder(node.value).some((text) => text.includes("*"))) {
                     context.report({ node, messageId: "glob", data: { key } })
                 }
             },
+            NewExpression(node) {
+                if (!isPackageType(context, node, "DataSource", "typeorm")) return
+                const options = node.arguments[0]
+                if (options && options.type !== "ObjectExpression") context.report({ node: options, messageId: "optionsNotLiteral" })
+            },
             CallExpression(node) {
-                if (node.callee.type !== "MemberExpression" || node.callee.computed) return
-                if (node.callee.property.type === "Identifier" && node.callee.property.name === "synchronize") {
-                    context.report({ node, messageId: "synchronizeCall" })
+                const callee = node.callee
+                if (callee.type !== "MemberExpression" || callee.computed || callee.property.type !== "Identifier") return
+                const name = callee.property.name
+                if (SCHEMA_OPERATIONS.has(name)) {
+                    if (isPackageType(context, callee.object, "DataSource", "typeorm")) context.report({ node, messageId: "synchronizeCall", data: { name } })
+                } else if (MIGRATION_RUNNERS.has(name)) {
+                    if (!migrationHost && isPackageType(context, callee.object, "DataSource", "typeorm")) context.report({ node, messageId: "runMigrations", data: { name } })
+                } else if (name === "createSchemaBuilder") {
+                    if (isPackageType(context, callee.object, "DataSource", "typeorm")) context.report({ node, messageId: "schemaBuilder", data: { name: "createSchemaBuilder()" } })
+                } else if (name === "build" || name === "log") {
+                    if (SCHEMA_BUILDER_TYPES.some((type) => isPackageType(context, callee.object, type, "typeorm"))) context.report({ node, messageId: "schemaBuilder", data: { name: `${name}()` } })
                 }
             },
             Literal(node) {
@@ -77,87 +216,134 @@ export const noRuntimeSchema = {
     },
 }
 
-/** A file that holds SQL text: `<name>.sql.ts`. */
-const SQL_FILE = /\.sql\.[cm]?ts$/
-/** A repository file, banned. */
-const REPOSITORY_FILE = /\.repository\.[cm]?ts$/
+// -- R37 -------------------------------------------------------------------------------------------
 
-/** Raw SQL text is written only in a `<name>.sql.ts`; everywhere else `.query(...)` takes an imported constant. */
-export const sqlTextOnly = {
-    meta: {
-        type: "problem",
-        docs: { description: "Raw SQL text only in a `<name>.sql.ts`; `.query(...)` elsewhere takes an imported text constant; no `createQueryBuilder`." },
-        schema: [],
-        messages: {
-            sql: "Raw SQL text outside a `<name>.sql.ts`. Write the statement as an exported constant in the owning capability's `persistence/<name>.sql.ts` (a test builder's in `src/tests/fixtures/builders/<area>.sql.ts`), import it, and pass values as numbered parameters.",
-            builder: "`createQueryBuilder(...)` is banned. Use `manager.find(Entity, { where, take })`, or a SQL text constant from a `<name>.sql.ts` run with `manager.query(...)`.",
-        },
-    },
-    create(context) {
-        const filename = normalizePath(context.filename || context.getFilename())
-        if (isDeclarationFile(filename) || isMigrationFile(filename)) return {}
-        const sqlFile = SQL_FILE.test(filename)
-        return {
-            CallExpression(node) {
-                const callee = node.callee
-                if (callee.type !== "MemberExpression" || callee.computed || callee.property.type !== "Identifier") return
-                const name = callee.property.name
-                if (name === "createQueryBuilder") context.report({ node, messageId: "builder" })
-                else if (!sqlFile && name === "query" && (staticText(node.arguments[0]) !== null || node.arguments[0]?.type === "TemplateLiteral")) {
-                    context.report({ node, messageId: "sql" })
-                }
-            },
+/** Whether a decorator is `typeorm`'s `Entity`, read through the checker so an aliased import counts. */
+const isEntityDecorator = (checker, decorator) => {
+    const callee = ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression
+    let symbol = checker.getSymbolAtLocation(callee)
+    if (symbol && symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol)
+    return symbol?.name === "Entity" && (symbol.declarations ?? []).some((declaration) => packageOfFile(declaration.getSourceFile().fileName) === "typeorm")
+}
+
+/** Whether a TypeScript declaration is a class carrying `@Entity`. */
+const carriesEntity = (checker, declaration) => ts.canHaveDecorators(declaration) && (ts.getDecorators(declaration) ?? []).some((decorator) => isEntityDecorator(checker, decorator))
+
+/**
+ * The name of an ORM entity a type reaches, or null: the type itself, a union or intersection member, a type argument
+ * (`Array<OrderEntity>`, `Promise<...>`), or a property of a type the repository declares. Types declared by a package
+ * or the language are not walked into, only through their type arguments.
+ */
+const entityReached = (checker, type, seen, depth) => {
+    if (!type || depth > 6 || seen.has(type)) return null
+    seen.add(type)
+    if (type.isUnionOrIntersection()) {
+        for (const part of type.types) {
+            const found = entityReached(checker, part, seen, depth + 1)
+            if (found) return found
         }
-    },
+        return null
+    }
+    const declarations = type.getSymbol()?.getDeclarations() ?? []
+    const entity = declarations.find((declaration) => carriesEntity(checker, declaration))
+    if (entity) return entity.name?.text ?? "an entity"
+    for (const argument of checker.getTypeArguments(type)) {
+        const found = entityReached(checker, argument, seen, depth + 1)
+        if (found) return found
+    }
+    const own = declarations.length > 0 && declarations.every((declaration) => !declaration.getSourceFile().isDeclarationFile)
+    if (!own) return null
+    for (const property of checker.getPropertiesOfType(type)) {
+        const declaration = property.valueDeclaration ?? property.declarations?.[0]
+        if (!declaration) continue
+        const found = entityReached(checker, checker.getTypeOfSymbolAtLocation(property, declaration), seen, depth + 1)
+        if (found) return found
+    }
+    return null
 }
 
-/** Repositories are banned: a `*.repository.ts` file is a finding. */
-export const noRepositoryFile = {
-    meta: {
-        type: "problem",
-        docs: { description: "No `*.repository.ts` file." },
-        schema: [],
-        messages: {
-            file: "Repository files are banned. Move the SQL text into the capability's `persistence/<name>.sql.ts` and run it from the capability's `*.service.ts` on the shared EntityManager.",
-        },
-    },
-    create(context) {
-        const filename = normalizePath(context.filename || context.getFilename())
-        if (isDeclarationFile(filename) || !REPOSITORY_FILE.test(filename)) return {}
-        return { Program(node) { context.report({ node, loc: { line: 1, column: 0 }, messageId: "file" }) } }
-    },
+const FUNCTION_TYPES = new Set(["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression", "TSDeclareFunction", "TSEmptyBodyFunctionExpression", "TSMethodSignature"])
+const PARAMETER_HOLDERS = new Set(["Identifier", "ObjectPattern", "ArrayPattern", "AssignmentPattern", "RestElement"])
+
+/** Which files carry boundary types, and how much of each: the whole file, or only the `execute` of a handler. */
+const boundaryOf = (hfs, filename) => {
+    const slot = hfs.slotOf(filename) ?? ""
+    const name = baseName(filename)
+    if (slot.startsWith("be.transport.") || slot === "be.feature.transport.cli") return "file"
+    if (/\.(?:contracts|command|query)\.ts$/.test(name)) return "file"
+    if (name.endsWith(".handler.ts")) return "execute"
+    return null
 }
 
-/** Files whose types cross a boundary: contracts, DTOs, resolvers, controllers. */
-const BOUNDARY_FILE = /\.contracts\.[cm]?ts$|\/dto\/|\.(?:request|response|input|type|args)\.[cm]?ts$|\.(?:resolver|controller)\.[cm]?ts$/
+/** The MethodDefinition a node sits in the signature of, or null. */
+const methodOf = (node) => {
+    let current = node
+    while (current && !FUNCTION_TYPES.has(current.type)) current = current.parent
+    return current?.parent?.type === "MethodDefinition" ? current.parent : null
+}
 
-/** An ORM entity type never appears in a contract, DTO, resolver or controller signature. */
+/** An ORM entity type never appears in a contract, DTO, command or query, transport signature or handler `execute`. */
 export const noEntityInContract = {
     meta: {
         type: "problem",
-        docs: { description: "No `*Entity` type in a contract, DTO, resolver or controller signature." },
+        docs: { description: "No type declared with `@Entity` is reachable from a transport signature, a handler `execute`, a `*.contracts.ts` or a message." },
         schema: [],
         messages: {
-            entity: "`{{name}}` is an ORM entity and leaks into a boundary type. Return a projection (a plain contract type) and pass a principal id and role instead of an entity.",
+            entity: "`{{name}}` is an ORM entity and is reachable from a boundary type. Return a projection (a plain contract type) and pass a principal id and role instead of an entity.",
+            entityImport: "An entity file imports `{{source}}`. An entity is a schema declaration only: GraphQL types and validators belong to the transport's own DTOs, never to the entity.",
         },
     },
     create(context) {
-        const filename = normalizePath(context.filename || context.getFilename())
-        if (isDeclarationFile(filename) || !BOUNDARY_FILE.test(filename) || filename.includes("/persistence/")) return {}
-        return {
-            TSTypeReference(node) {
-                if (node.typeName.type === "Identifier" && /Entity$/.test(node.typeName.name)) {
-                    context.report({ node, messageId: "entity", data: { name: node.typeName.name } })
+        const filename = context.filename || context.getFilename()
+        if (isDeclarationFile(filename)) return {}
+        const hfs = hfsOf(context)
+        const listeners = {}
+        if (baseName(filename).endsWith(".entity.ts")) {
+            listeners.ImportDeclaration = (node) => {
+                const source = String(node.source.value)
+                if (["@nestjs/graphql", "class-validator"].some((banned) => source === banned || source.startsWith(`${banned}/`))) {
+                    context.report({ node, messageId: "entityImport", data: { source } })
                 }
-            },
+            }
+        }
+        const boundary = boundaryOf(hfs, filename)
+        if (!boundary) return listeners
+        const { checker, toTs } = typed(context)
+        const reported = new Set()
+        const judge = (typeNode) => {
+            if (reported.has(typeNode)) return
+            const tsNode = toTs(typeNode)
+            if (!tsNode) return
+            const name = entityReached(checker, checker.getTypeFromTypeNode(tsNode), new Set(), 0)
+            if (name) {
+                reported.add(typeNode)
+                context.report({ node: typeNode, messageId: "entity", data: { name } })
+            }
         }
+        /** Whether a signature is one this file is judged on. */
+        const inScope = (node) => boundary === "file" || methodOf(node)?.key?.name === "execute"
+        listeners.TSTypeAnnotation = (node) => {
+            const holder = node.parent
+            const isParameter = PARAMETER_HOLDERS.has(holder.type) && (FUNCTION_TYPES.has(holder.parent?.type) || holder.parent?.type === "TSParameterProperty")
+            const isReturn = FUNCTION_TYPES.has(holder.type) && holder.returnType === node
+            const isMember = holder.type === "PropertyDefinition" || holder.type === "TSPropertySignature"
+            if ((isParameter || isReturn || (isMember && boundary === "file")) && inScope(holder)) judge(node.typeAnnotation)
+        }
+        listeners.TSTypeAliasDeclaration = (node) => {
+            if (boundary === "file") judge(node.typeAnnotation)
+        }
+        // `extends Command<OrderEntity>` and `implements ICQRSHandler<...>`: the heritage names what the class carries across
+        listeners.TSTypeParameterInstantiation = (node) => {
+            const parent = node.parent
+            const heritage = parent.type === "TSClassImplements" || parent.type === "TSInterfaceHeritage" || parent.type === "ClassDeclaration" || parent.type === "ClassExpression"
+            if (heritage) for (const param of node.params) judge(param)
+        }
+        return listeners
     },
 }
 
 // -- R74 -------------------------------------------------------------------------------------------
 
-const isMigrationPath = (filename) => /\/migrations\/[^/]+\.[cm]?ts$/.test(normalizePath(filename))
-
 const methodNamed = (klass, name) =>
     klass.body.body.find((member) => member.type === "MethodDefinition" && !member.computed && keyName(member.key) === name)
 
@@ -177,8 +363,8 @@ export const migrationDownReversible = {
         },
     },
     create(context) {
-        const filename = normalizePath(context.filename || context.getFilename())
-        if (isDeclarationFile(filename) || !isMigrationPath(filename) || /\.(?:spec|test)\.ts$/.test(filename)) return {}
+        const filename = context.filename || context.getFilename()
+        if (isDeclarationFile(filename) || !isMigrationFile(hfsOf(context), filename)) return {}
         const check = (node) => {
             if (!node.body) return
             const up = methodNamed(node, "up")
@@ -195,8 +381,6 @@ export const migrationDownReversible = {
 /** The rules this law contributes to the plugin. */
 export const rules = {
     "no-runtime-schema": noRuntimeSchema,
-    "sql-text-only": sqlTextOnly,
-    "no-repository-file": noRepositoryFile,
     "no-entity-in-contract": noEntityInContract,
     "migration-down-reversible": migrationDownReversible,
 }
@@ -204,8 +388,6 @@ export const rules = {
 /** All three start at error: HFS keeps no baseline and the schema migration lanes clear the debt first. */
 export const recommended = {
     "starci-be/no-runtime-schema": "error",
-    "starci-be/sql-text-only": "error",
-    "starci-be/no-repository-file": "error",
     "starci-be/no-entity-in-contract": "error",
     "starci-be/migration-down-reversible": "error",
 }

package/size-budget.mjs

@@ -2,91 +2,49 @@
  * The rules that hold the file size budget (catalog R20 `HFS_SIZE_GROWTH`, the file-level half).
  *
  * A source file has a hard-growth budget of `fileLines.hardGrowth` lines (`ruleParams.be.fileLines` of the
- * slot manifest, read through `lib/slots.mjs`). `file-size-growth` is the ratchet and fails only on a file that must not
+ * slot manifest, read through `settings.starci.hfs`, see `lib/hfs.mjs`). `file-size-growth` is the ratchet and fails only on a file that must not
  * be this long: a NEW file over the budget, or an existing file over the budget that is longer than its recorded size.
- * The recorded size is the file's line count at the parent commit (`git show HEAD:<file>`), or an entry of the
- * `recorded` option. A file may stay as large as it is; it may not grow, and it may not be born large.
+ * The recorded size is the file's line count at the parent commit (`git show HEAD:<file>`). A file may stay as large
+ * as it is; it may not grow, and it may not be born large. The rule takes no option: the budget is the manifest's, the
+ * baseline is git's.
  *
  * There is no soft-limit lint rule: a warning under a zero-warning gate is an exception in disguise. Listing the
  * files over the soft budget (`fileLines.soft`) is a report item of the hfs check, never a block.
- * There is no baseline file and no allowlist: the record is the repository's own history. A migration is exempt
- * (it is append-only and generated), and so is every test-lane file.
+ * There is no baseline file and no allowlist: the record is the repository's own history. A spec, a fixture and an e2e
+ * file are source files like any other. A migration is exempt (a file of the `be.persistence` slot named
+ * `<timestamp>-<name>.ts`: append-only, never edited), and so is a declaration file.
  */
-import { execFileSync } from "node:child_process"
-import { basename, dirname } from "node:path"
-import { isDeclarationFile, isMigrationFile, isTestLane, normalizePath } from "./lib/path.mjs"
-import { hfsParams } from "./lib/slots.mjs"
+import { basename } from "node:path"
+import { hfsOf } from "./lib/hfs.mjs"
+import { hardGrowthLines, lineCount, recordedLines } from "./runtime/scripts/lib/recorded-lines.mjs"
 
-const lineCount = (text) => {
-    const lines = text.split(/\r?\n/)
-    return lines.at(-1) === "" ? lines.length - 1 : lines.length
-}
+/** A migration is a file of the persistence slot named `<timestamp>-<name>.ts`. */
+const isMigration = (hfs, filename) => hfs.slotOf(filename) === "be.persistence" && /^\d{13,14}-[^/]+\.[cm]?ts$/.test(basename(filename))
 
 /** Whether a file is a source file this budget governs. */
-const governed = (filename) =>
-    /\.[cm]?tsx?$/.test(filename) &&
-    !isDeclarationFile(filename) &&
-    !isMigrationFile(filename) &&
-    !isTestLane(filename) &&
-    !filename.includes("/__generated__/")
-
-/**
- * The line count of a file at a git revision, or null when the file did not exist there or git is absent.
- *
- * @param {string} filename - Absolute path of the file.
- * @param {string} ref - The revision, `HEAD` by default (the parent of the commit being made).
- * @returns {number | null} The recorded line count.
- */
-export const recordedLines = (filename, ref = "HEAD") => {
-    try {
-        const text = execFileSync("git", ["-C", dirname(filename), "show", `${ref}:./${basename(filename)}`], {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-            maxBuffer: 64 * 1024 * 1024,
-        })
-        return lineCount(text)
-    } catch {
-        // no repository, no such revision, or a new file: all mean there is no recorded size to compare with
-        return null
-    }
-}
-
-const optionSchema = [
-    {
-        type: "object",
-        properties: {
-            max: { type: "integer", minimum: 1 },
-            ref: { type: "string" },
-            recorded: { type: "object", additionalProperties: { type: "integer", minimum: 0 } },
-        },
-        additionalProperties: false,
-    },
-]
+const governed = (hfs, filename) => /\.[cm]?tsx?$/.test(filename) && !/\.d\.[cm]?ts$/.test(filename) && !isMigration(hfs, filename)
 
 /** The ratchet: a file over the budget must not be new and must not grow. */
 export const fileSizeGrowth = {
     meta: {
         type: "problem",
         docs: { description: "A source file over the budget is neither new nor longer than its recorded size." },
-        schema: optionSchema,
+        schema: [],
         messages: {
             born: "This new file has {{lines}} lines, over the budget of {{max}}. A new file starts within the budget: split it by responsibility.",
             grew: "This file has {{lines}} lines, over the budget of {{max}}, and it was {{recorded}} at the parent commit. A file over the budget may not grow: move the new code into its own file.",
         },
     },
     create(context) {
-        const filename = normalizePath(context.filename || context.getFilename())
-        if (!governed(filename)) return {}
-        const options = context.options[0] ?? {}
-        const max = options.max ?? hfsParams.fileLines.hardGrowth
+        const filename = context.filename || context.getFilename()
+        const hfs = hfsOf(context)
+        if (!governed(hfs, filename)) return {}
+        const max = hardGrowthLines(hfs.ruleParams.fileLines)
         return {
             "Program:exit"(node) {
                 const lines = lineCount((context.sourceCode || context.getSourceCode()).text)
                 if (lines <= max) return
-                const listed = options.recorded
-                    ? Object.entries(options.recorded).find(([path]) => filename.endsWith(`/${path}`) || filename === path)
-                    : undefined
-                const recorded = listed ? listed[1] : recordedLines(context.filename || context.getFilename(), options.ref)
+                const recorded = recordedLines(filename)
                 const loc = { line: 1, column: 0 }
                 if (recorded === null) context.report({ node, loc, messageId: "born", data: { lines, max } })
                 else if (lines > recorded) context.report({ node, loc, messageId: "grew", data: { lines, max, recorded } })