@starci/eslint-canon-be 3.0.7 → 3.0.9

package/runtime/scripts/lib/stack-services.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseYaml } from '../../engine/yaml.mjs';
+import { words } from './dockerfile.mjs';
 
 /**
  * The services of a repository's own stack definition, read from `.starcistacks/application-stacks.yaml` and the compose
@@ -14,11 +15,11 @@ import { parseYaml } from '../../engine/yaml.mjs';
  * service and is returned as `proxy`.
  */
 export const STACKS_DIRECTORY = '.starcistacks';
-export const STACKS_FILE = 'application-stacks.yaml';
+const STACKS_FILE = 'application-stacks.yaml';
 export const DEFAULT_ENVIRONMENT = 'dev';
 
 /** Test-only value the `*_FILE` secret variables of a compose service become (the file variable is replaced by the plain variable of the same name). Never a real secret: the test stack listens on loopback only. */
-export const TEST_SECRET_VALUE = 'starci-test-secret';
+const TEST_SECRET_VALUE = 'starci-test-secret';
 
 const NOT_RUN_ROLES = new Set(['service', 'observability']);
 const NOT_RUN_PROFILES = new Set(['app']);
@@ -44,8 +45,6 @@ const KNOWN_IMAGES = Object.freeze({
   clickhouse: { kind: 'database', aliases: ['clickhouse', 'database', 'db'], probe: { tcp: true } },
   kafka: { kind: 'queue', aliases: ['kafka', 'queue', 'broker'], probe: { tcp: true } },
   redpanda: { kind: 'queue', aliases: ['redpanda', 'kafka', 'queue', 'broker'], probe: { tcp: true } },
-  rabbitmq: { kind: 'queue', aliases: ['rabbitmq', 'amqp', 'queue', 'broker'], probe: { tcp: true } },
-  nats: { kind: 'queue', aliases: ['nats', 'queue', 'broker'], probe: { tcp: true } },
   elasticsearch: { kind: 'search', aliases: ['elasticsearch', 'elastic', 'search'], probe: { tcp: true } },
   opensearch: { kind: 'search', aliases: ['opensearch', 'search'], probe: { tcp: true } },
 });
@@ -58,14 +57,14 @@ const KNOWN_IMAGES = Object.freeze({
 export const STATEFUL_KINDS = Object.freeze(new Set(['database', 'cache', 'identity', 'storage', 'mail', 'queue', 'search']));
 
 /** The repository name of an image reference: `quay.io/keycloak/keycloak:26.0` -> `keycloak`. */
-export const repositoryOf = image => {
+const repositoryOf = image => {
   const withoutDigest = image.split('@')[0];
   const lastSegment = withoutDigest.split('/').at(-1) ?? withoutDigest;
   return lastSegment.split(':')[0];
 };
 
 /** The repository path of an image reference without its tag: `quay.io/keycloak/keycloak:26.0` -> `quay.io/keycloak/keycloak`. */
-export const imagePathOf = image => {
+const imagePathOf = image => {
   const withoutDigest = image.split('@')[0];
   const lastSlash = withoutDigest.lastIndexOf('/');
   const colon = withoutDigest.indexOf(':', lastSlash + 1);
@@ -73,30 +72,7 @@ export const imagePathOf = image => {
 };
 
 /** True when the image reference carries a tag or digest (an external image, not a placeholder of the repository's own build). */
-export const isTagged = image => image.includes('@') || image.slice(image.lastIndexOf('/') + 1).includes(':');
-
-/** The shell-like words of a compose `command` string, double and single quotes grouping a word. */
-const words = text => {
-  const out = [];
-  let current = '';
-  let quote = null;
-  let started = false;
-  for (const char of text) {
-    if (quote) {
-      if (char === quote) quote = null;
-      else current += char;
-    } else if (char === '"' || char === "'") {
-      quote = char;
-      started = true;
-    } else if (/\s/u.test(char)) {
-      if (started || current) out.push(current);
-      current = '';
-      started = false;
-    } else current += char;
-  }
-  if (started || current) out.push(current);
-  return out;
-};
+const isTagged = image => image.includes('@') || image.slice(image.lastIndexOf('/') + 1).includes(':');
 
 const asList = value => (Array.isArray(value) ? value : value === undefined || value === null ? [] : [value]);
 
@@ -129,7 +105,7 @@ const mountsOf = (value, directory) => {
       continue;
     }
     const parts = String(entry).split(':');
-    // A Windows drive letter is not a separator: `C:\x:/y` keeps its drive.
+    // A Windows drive letter is not a separator: a `<drive>:<path>:/y` mount keeps its drive.
     const source = /^[A-Za-z]$/u.test(parts[0]) && parts.length > 2 ? `${parts.shift()}:${parts.shift()}` : parts.shift();
     const target = parts.shift();
     if (!source || !target || !(source.startsWith('.') || path.isAbsolute(source))) continue;

package/runtime/scripts/lib/ts-ast.mjs

@@ -0,0 +1,35 @@
+// ts-ast.mjs — the small reads the hfs checks share over TypeScript's own AST: a node's name or
+// literal text, a node's 1-based position, a named property's initializer text. `ts` is the caller's
+// already-resolved compiler (see package-at.mjs loadTypescript); nothing here resolves a package.
+
+/** The text of an identifier or a string-literal-like `node`, or null (property names, literal specifiers). */
+export const nameText = (ts, node) => (node && (ts.isIdentifier(node) || ts.isStringLiteralLike(node)) ? node.text : null);
+
+/** The text of a string-literal-like `node` (a string literal or a no-substitution template), or null. */
+export const literalText = (ts, node) => (node && ts.isStringLiteralLike(node) ? node.text : null);
+
+/** The 1-based {line, column} of `node` in `sourceFile`. */
+export const sourceLocation = (sourceFile, node) => {
+  const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+  return { line: position.line + 1, column: position.character + 1 };
+};
+
+/**
+ * The `.text` of `key`'s property initializer in `text` (parsed as `file`): a property assignment
+ * inside an object literal, or — `declaration: true` — a class property declaration. `kind` is
+ * 'string' (a string-literal-like initializer) or 'identifier'. The last match wins; null when none.
+ */
+export function propertyText(ts, text, { file = 'source.ts', key, declaration = false, kind = 'string' } = {}) {
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  let value = null;
+  const visit = (node) => {
+    const isProp = declaration ? ts.isPropertyDeclaration(node) : ts.isPropertyAssignment(node);
+    if (isProp && node.name && ts.isIdentifier(node.name) && node.name.text === key && node.initializer) {
+      const ok = kind === 'identifier' ? ts.isIdentifier(node.initializer) : ts.isStringLiteralLike(node.initializer);
+      if (ok) value = node.initializer.text;
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return value;
+}

package/runtime/scripts/{checks/common.mjs → lib/walk.mjs}

@@ -1,23 +1,13 @@
+// walk.mjs - filesystem walking helpers: isInside (containment) and walkFiles (depth-first file listing).
 import fs from 'node:fs';
 import path from 'node:path';
-import {fileURLToPath} from 'node:url';
 
-/** Whether `target` is `root` itself or inside it (filesystem paths, either separator). */
-export function isInside(root, target) {
+/** Whether `target` is `root` itself or inside it (filesystem paths, either separator). `includeSelf: false` excludes `target === root`. */
+export function isInside(root, target, { includeSelf = true } = {}) {
   const relative = path.relative(root, target);
-  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+  if (relative === '') return includeSelf;
+  return !relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative);
 }
-
-/** True when this module is the process entry point (`node file.mjs`, not an import). */
-/** The real path of a file, or its resolved path when it cannot be read (a missing file is never the entry module). */
-const realPathOf = (file) => { try { return fs.realpathSync.native(path.resolve(file)); } catch { return path.resolve(file); } };
-/**
- * True when the module at `metaUrl` is the process entry point. Both sides are compared as REAL paths: Node gives a module
- * its symlink-resolved URL, while argv[1] keeps the path it was started with, so an entry reached through a node_modules
- * junction or symlink (a lane worktree, an npx shim) would otherwise look like an import and silently do nothing.
- */
-export const isMain = (metaUrl, argv = process.argv) => Boolean(argv[1]) && realPathOf(argv[1]) === realPathOf(fileURLToPath(metaUrl));
-
 /**
  * Every entry under `dir` that is not a directory, depth-first; `filter` sees the entry name and full
  * path. `sorted` sorts each directory's entries by name (default: readdir order). `exclude`

package/schema-authority.mjs

@@ -8,11 +8,11 @@
  *     `@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
+ *     `undoLastMigration()` call outside the cli (apps/cli and src/features/cli) 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.
+ *     writes rows through an `EntityManager` or `DataSource` (seeding is a cli command); a DDL statement in any string
+ *     outside the migrations of `persistence/`; and an entity or migration glob. Only the cli (its migrate and seed commands) 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
@@ -22,9 +22,11 @@
  * never of a path pattern.
  */
 import ts from "typescript"
+import { isTransportSlot } from "./lib/transport-slots.mjs"
 import { keyName, walk } from "./lib/ast.mjs"
 import { hfsOf, inTestWorld } from "./lib/hfs.mjs"
 import { baseName, isMigrationFile, packageOfFile } from "./lib/ports.mjs"
+import { inCli } from "./lib/persistence.mjs"
 import { isPackageType, typed } from "./lib/types.mjs"
 import { isDeclarationFile } from "./lib/path.mjs"
 
@@ -37,7 +39,7 @@ 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. */
+/** The DataSource operations that run migrations: allowed only in the cli (apps/cli, src/features/cli) and the test world. */
 const MIGRATION_RUNNERS = new Set(["runMigrations", "undoLastMigration"])
 
 /** The typeorm types whose methods write rows. */
@@ -99,8 +101,8 @@ const isOperationsObject = (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)
+/** Whether a file is the cli (the cli app or the cli feature root, whose migrate and seed commands run them) or the test world: the only places that run migrations and seed. */
+const isMigrationHost = (hfs, filename) => inCli(hfs, filename) || 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(" ") : "")
@@ -133,7 +135,7 @@ const bootWriteOf = (context, method, klass, visited) => {
 /** 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. */
+/** The schema is decided by migrations run by the cli migrate command, never by the running process. */
 export const noRuntimeSchema = {
     meta: {
         type: "problem",
@@ -143,13 +145,13 @@ export const noRuntimeSchema = {
             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.",
             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.",
+            synchronizeCall: "`.{{name}}()` changes the schema at runtime. Write a migration and let the cli migrate command run it.",
+            migrationsRun: "`migrationsRun` is banned. Only the cli migrate command (`cli migrate run`) runs migrations, once per connection, before api and worker start.",
+            runMigrations: "`.{{name}}()` runs migrations outside the cli. Only the cli migrate command (and the test world, over the same connections) 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.",
+            bootSeed: "`{{hook}}` writes rows (`{{call}}`), so every process that composes this provider seeds at boot. Seeding is a cli command, run 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.",
         },
@@ -269,7 +271,7 @@ const PARAMETER_HOLDERS = new Set(["Identifier", "ObjectPattern", "ArrayPattern"
 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 (isTransportSlot(slot)) return "file"
     if (/\.(?:contracts|command|query)\.ts$/.test(name)) return "file"
     if (name.endsWith(".handler.ts")) return "execute"
     return null

package/service-deps.mjs

@@ -11,7 +11,7 @@
  *     token: it is either a broken provider or a raw string/number injection.
  *   - `no-repository-class` (R83): a class that receives or returns an `EntityManager`, a typeorm `Repository`, a
  *     `DataSource` or a `QueryRunner` in any member lives only where the manager may be held (an application handler,
- *     a domain service, a platform persistence capability), in the migrate app, in the test world or in a migration.
+ *     a domain service, a platform persistence capability), in the cli app, in the test world or in a migration.
  *     A per-entity persistence class anywhere else is a repository under another name.
  *   - `no-test-double-in-source` (R89): a class, function or constant of production source is not named as a test
  *     double (`Mock`, `Fake`, `Stub` as a PascalCase or camelCase word). A double lives in a spec or `src/tests`;
@@ -21,9 +21,10 @@
  * slot view. A name is read only for the fixed vocabulary of the double markers, as whole words.
  */
 import ts from "typescript"
-import { hfsOf } from "./lib/hfs.mjs"
+import { paramParts } from "./lib/ast.mjs"
+import { hfsOf, inTestWorld } from "./lib/hfs.mjs"
 import { isSpecFile, normalizePath } from "./lib/path.mjs"
-import { implementsMigration, inMigrateApp, inTestBootstrap, isMigrationFile, mayHoldEntityManager } from "./lib/persistence.mjs"
+import { implementsMigration, inCli, isMigrationFile, mayHoldEntityManager } from "./lib/persistence.mjs"
 import { typed, typeOrigins } from "./lib/types.mjs"
 
 // -- provider-param-token --------------------------------------------------------------------------
@@ -31,13 +32,6 @@ import { typed, typeOrigins } from "./lib/types.mjs"
 /** The convention's injector vocabulary: `Inject` or `Inject<Thing>`. */
 const INJECT_NAME = /^Inject(?:[A-Z][A-Za-z0-9]*)?$/
 
-/** The decorators of a constructor parameter: on the parameter, its wrapper (`private readonly x`) or its inner identifier. */
-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 ?? [])])] }
-}
-
 /** True when a decorator expression is a call of an `Inject*` function, or of anything typed `TypedParameterDecorator<T>`. */
 const isInjector = (context, decorator) => {
     const expression = decorator.expression
@@ -140,11 +134,11 @@ const persistenceMember = (context, classNode) => {
 export const noRepositoryClass = {
     meta: {
         type: "problem",
-        docs: { description: "A class with a member typed `EntityManager`, `Repository`, `DataSource` or `QueryRunner` lives only in an application handler, a domain service, a platform persistence capability, the migrate app, the test world or a migration." },
+        docs: { description: "A class with a member typed `EntityManager`, `Repository`, `DataSource` or `QueryRunner` lives only in an application handler, a domain service, a platform persistence capability, the cli app, the test world or a migration." },
         schema: [],
         messages: {
             statements:
-                "`{{name}}` is exported and takes an `EntityManager` as its first parameter: a statement module is a repository without a class. Put the SQL text in `<name>.sql.ts` and run it with `this.entityManager.query(...)` from the capability `*.service.ts` or the application `*.handler.ts`; only `platform/database`, `apps/migrate` and `src/tests` take a manager in a free function.",
+                "`{{name}}` is exported and takes an `EntityManager` as its first parameter: a statement module is a repository without a class. Put the SQL text in `<name>.sql.ts` and run it with `this.entityManager.query(...)` from the capability `*.service.ts` or the application `*.handler.ts`; only `platform/database`, the cli (`apps/cli`, `src/features/cli`) and `src/tests` take a manager in a free function.",
             repository:
                 "`{{name}}` takes or holds a `{{type}}` in `{{member}}` but is not an application handler, a domain service or a platform persistence capability. A class wrapping the manager per entity is a repository whatever it is called: it hides which connection and transaction a call runs in and cannot be unit-tested with a token double. Move the queries into the handler or the domain service that owns the use, and call the injected EntityManager directly.",
         },
@@ -153,7 +147,7 @@ export const noRepositoryClass = {
         const hfs = hfsOf(context)
         const filename = context.filename || context.getFilename()
         const file = normalizePath(filename)
-        if (mayHoldEntityManager(hfs, file) || inMigrateApp(hfs, file) || inTestBootstrap(hfs, file) || isMigrationFile(hfs, file) || (hfs.slotOf(file) ?? "").startsWith("be.tests.")) return {}
+        if (mayHoldEntityManager(hfs, file) || inCli(hfs, file) || inTestWorld(hfs, file) || isMigrationFile(hfs, file) || (hfs.slotOf(file) ?? "").startsWith("be.tests.")) return {}
         const check = (node) => {
             if (implementsMigration(context, node)) return
             const found = persistenceMember(context, node)

package/service-isolation.mjs

@@ -0,0 +1,72 @@
+/**
+ * The rule that keeps the services of one product apart (catalog R168 `BE_SERVICE_ISOLATION`).
+ *
+ * A back-end service is a Nest app at `be/apps/<service>/` of the one repository; services share the `be/src` libraries and talk
+ * to each other only through the wire (a client of the sibling's API, or the events of its vendored contract under
+ * `be/contracts/<service>/`). One service importing a file of another service's `apps/<other>/` folder reaches into a sibling's
+ * composition and options, which makes the two one deployable. The check asks the HFS slot view which app owns a file (the owner of
+ * an `apps/<app>/src/` slot) for both the importing file and the file the specifier resolves to, through a relative path or the
+ * program's own `compilerOptions.paths`; it never matches a path by name.
+ */
+import { posix } from "node:path"
+import { hfsOf } from "./lib/hfs.mjs"
+import { resolveAlias } from "./lib/specifier.mjs"
+
+/** The app slots: the slot ids of a service app's `apps/<app>/src/` folder. */
+const isAppSlot = (slotId) => typeof slotId === "string" && slotId.startsWith("be.app.")
+
+const isRelative = (specifier) => specifier === "." || specifier === ".." || specifier.startsWith("./") || specifier.startsWith("../")
+
+/** Calls `check(node, specifier)` for every import and re-export that names a module. */
+const onSpecifiers = (check) => ({
+  ImportDeclaration(node) {
+    check(node.source, node.source.value)
+  },
+  ExportNamedDeclaration(node) {
+    if (node.source) check(node.source, node.source.value)
+  },
+  ExportAllDeclaration(node) {
+    if (node.source) check(node.source, node.source.value)
+  },
+})
+
+/** A file of one service app imports no file of a sibling service app. */
+export const serviceIsolation = {
+  meta: {
+    type: "problem",
+    docs: { description: "A service app (`apps/<service>/`) imports no file of a sibling service app; services share only the `src` libraries and meet through the wire." },
+    schema: [],
+    messages: {
+      sibling:
+        "`{{specifier}}` reaches into the service app `{{other}}` from `{{self}}`. Services share only the `src` libraries; call the sibling through its API client or consume its events through the vendored contract (`be/contracts/{{other}}/`).",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    const hfs = hfsOf(context)
+    if (!isAppSlot(hfs.slotOf(filename))) return {}
+    const self = hfs.ownerOf(filename)
+    if (!self) return {}
+    return onSpecifiers((node, specifier) => {
+      if (typeof specifier !== "string") return
+      const target = isRelative(specifier)
+        ? posix.normalize(`${posix.dirname(filename.replaceAll("\\", "/"))}/${specifier}`)
+        : resolveAlias(context, specifier)?.target
+      if (!target) return
+      const reached = [`${target}.ts`, `${target}/index.ts`].find((candidate) => isAppSlot(hfs.slotOf(candidate)))
+      if (!reached) return
+      const other = hfs.ownerOf(reached)
+      if (!other || other === self) return
+      context.report({ node, messageId: "sibling", data: { specifier, self: posix.basename(posix.dirname(self)), other: posix.basename(posix.dirname(other)) } })
+    })
+  },
+}
+
+export const rules = {
+  "service-isolation": serviceIsolation,
+}
+
+/** The level this law asks for: `error`, switched off nowhere. */
+export const recommended = {
+  "starci-be/service-isolation": "error",
+}

package/size-budget.mjs

@@ -9,14 +9,15 @@
  * 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.
+ * files over the soft budget (`fileLines.soft`) is a report item of the starci app check, never a block.
  * 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 { basename } from "node:path"
 import { hfsOf } from "./lib/hfs.mjs"
-import { hardGrowthLines, lineCount, recordedLines } from "./runtime/scripts/lib/recorded-lines.mjs"
+import { recordedLines } from "./runtime/scripts/api/git/recorded-lines.mjs"
+import { hardGrowthLines, lineCount } from "./runtime/scripts/lib/line-count.mjs"
 
 /** 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))

package/test-world.mjs

@@ -4,7 +4,7 @@
  * Unit specs sit beside their subject. Everything else lives under `src/tests/`, one folder per kind:
  *   - `world/`        the ONLY test infrastructure (slot `be.tests.world`): `global-setup.ts` starts (or attaches to) the stack
  *                     the repository declares in `.starcistacks/<env>` (the test-world library) - every service of it runs
- *                     REAL behind toxiproxy - and runs `apps/migrate`'s exported bootstrap once; `use-test-world.ts` exports
+ *                     REAL behind toxiproxy - and runs the migrations once over the cli app's connections; `use-test-world.ts` exports
  *                     `useTestWorld({ apps } | { modules })` -> `world.apps.<name>.api`, `world.db.<connection>`,
  *                     `world.infra.<service>` (`latency(ms)`, `cut()`, `restore()` on the real service),
  *                     `world.fake.<provider>` (network-edge fakes of external SaaS with failNext/replayWebhook/delay),
@@ -18,6 +18,7 @@
  * Receivers and origins are judged by type and by the slot of their declaring file, never by name.
  */
 import { hfsOf } from "./lib/hfs.mjs"
+import { inCli } from "./lib/persistence.mjs"
 import { isPackageType, typeOrigins } from "./lib/types.mjs"
 
 /** Every test slot under `src/tests/` except the world, where the infrastructure lives. */
@@ -36,7 +37,7 @@ const isEnvMember = (node) => node?.type === "MemberExpression" && isProcessEnv(
 /**
  * The world is the only infrastructure location. Refused in fixtures, integration, e2e and contract specs: importing a
  * migration (a class declared in a `be.persistence` `migrations/` file, or a value whose type is an array of them) or
- * anything the migrate app declares; importing typeorm's `DataSource` or a testcontainers package; calling
+ * anything the cli app declares; importing typeorm's `DataSource` or a testcontainers package; calling
  * `runMigrations`/`synchronize`/`dropDatabase`/`createSchema`... on a typeorm receiver; constructing a container; writing
  * `process.env`. Migration behaviour is tested by the e2e world.
  */
@@ -46,7 +47,7 @@ export const testsInfraOnlyInWorld = {
         docs: { description: "Only src/tests/world starts infrastructure, migrates, holds a DataSource or writes process.env." },
         schema: [],
         messages: {
-            migration: "This test imports a migration or the migrate app. The schema is prepared once by `src/tests/world/global-setup.ts` running the real `apps/migrate` bootstrap; migration behaviour is tested through the e2e world.",
+            migration: "This test imports a migration or the cli. The schema is prepared once by `src/tests/world/global-setup.ts`, which runs the migrations over the cli app's connections; migration behaviour is tested through the e2e world.",
             call: "`{{name}}` builds or changes the schema outside `src/tests/world`. The world migrates once; a test uses `world.db.<connection>`.",
             infra: "This test imports or starts infrastructure (testcontainers, typeorm's DataSource). It belongs to `src/tests/world`; a test uses `useTestWorld(...)` and `world.db.<connection>`.",
             env: "This test writes `process.env`. The environment is set once by `src/tests/world`; a test takes the world as it is.",
@@ -57,7 +58,7 @@ export const testsInfraOnlyInWorld = {
         const filename = context.filename || context.getFilename()
         if (!OUTSIDE_WORLD.has(hfs.slotOf(filename))) return {}
         const isMigrationDecl = (file) => hfs.slotOf(file) === "be.persistence" && /\/migrations\/[^/]+$/.test(hfs.relative(file))
-        const fromMigrate = (file) => hfs.slotOf(file) === "be.app.migrate"
+        const fromMigrate = (file) => inCli(hfs, file)
         const migrationTyped = (node) => {
             const services = context.sourceCode.parserServices
             const checker = services.program.getTypeChecker()

package/testing.mjs

@@ -1,5 +1,5 @@
 /**
- * The rules that hold `testing.md` (catalog R47 `BE_TEST_TOPOLOGY` and R48 `BE_SPEC_QUALITY`).
+ * The rules that hold `knowledge/patterns/be/test.yaml` (catalog R47 `BE_TEST_TOPOLOGY` and R48 `BE_SPEC_QUALITY`).
  *
  * MOST OF THAT LAW IS NOT MACHINE-CHECKABLE, and pretending otherwise would be worse than checking nothing. No rule
  * can tell whether a file represents a business flow, whether the unhappy path it covers drags a critical flow
@@ -8,7 +8,7 @@
  *
  *   - a spec whose every assertion is about a call rather than a result (`no-call-only-spec`);
  *   - a unit spec of anything but a service, a service with no `<name>.service.spec.ts` beside it, a service spec with no
- *     service beside it, and a file of a kind the convention bans (`.test.ts`, `int-spec`, `harness-spec`)
+ *     service beside it, and a file of a kind the convention bans (`.test.ts`, `.int-spec.ts`, `.harness-spec.ts`)
  *     (`unit-test-colocated`);
  *   - an e2e that never reads persisted state back, and an e2e that reaches a model provider
  *     (`e2e-asserts-persisted-state`, `no-model-call-in-e2e`);
@@ -24,17 +24,17 @@
 
 import { statSync } from "node:fs"
 import { basename, dirname, join } from "node:path"
-import { hfsOf } from "./lib/hfs.mjs"
+import { hfsOf, inTestWorld } from "./lib/hfs.mjs"
 import { isPackageType, typeOrigins } from "./lib/types.mjs"
-import { isServiceSpecFile, isUnitSpecFile, serviceNameOfSpec } from "./lib/unit-spec.mjs"
+import { doorOfSpec, isUnitSpecFile, unitRoleOfSpec, unitRoleOfSubject } from "./lib/unit-spec.mjs"
 
 /** The file name of a linted path, in forward-slash form. */
 const baseOf = (filename) => basename(String(filename || "").replace(/\\/g, "/"))
 
-/** Test kind 1 of exactly two: a unit spec, `<name>.spec.ts` beside its subject. */
+/** Test kind `spec`: a unit spec, `<name>.service.spec.ts` beside its service. */
 const isUnitSpec = (filename) => /\.spec\.ts$/.test(baseOf(filename))
 
-/** Test kind 2 of exactly two: `*.e2e-spec.ts`. */
+/** Test kind `e2e-spec`: `*.e2e-spec.ts` under `src/tests/e2e/` (`integration-spec` and `contract-spec` are the other two kinds of the tests slots). */
 const isE2eSpec = (filename) => /\.e2e-spec\.ts$/.test(baseOf(filename))
 
 /**
@@ -121,23 +121,23 @@ const exists = (path) => {
   }
 }
 
-/** Kinds of test file the convention bans: `.test.ts`, `*.int-spec.ts`, `*.harness-spec.ts` (any spec kind other than `spec` and `e2e-spec`). */
+/** Kinds of test file the convention bans: `.test.ts`, `*.int-spec.ts`, `*.harness-spec.ts` (any spec kind other than `spec`, `e2e-spec`, `integration-spec` and `contract-spec`). */
 const BANNED_TEST_FILE = /(?:\.test|\.int-spec|\.harness-spec)\.[cm]?[jt]sx?$/
 
 /**
  * Unit specs are for services only: every `<name>.service.ts` has its `<name>.service.spec.ts` beside it, every unit spec is
- * one of those, and there are no other kinds of test file.
+ * one of those, and there are no kinds of test file beyond `spec`, `e2e-spec`, `integration-spec` and `contract-spec`.
  */
 export const unitTestColocated = {
   meta: {
     type: "problem",
-    docs: { description: "Only a `<name>.service.ts` is unit-tested: it has its `<name>.service.spec.ts` beside it, any other unit spec is a finding, and there are only the spec kinds `spec`, `e2e-spec`, `integration-spec` and `contract-spec`." },
+    docs: { description: "Only the unit-tested roles (`ruleParams.be.unitRoles`: a `<name>.service.ts`, a cli command `<name>.cli.ts` of `src/features/cli`) own a REQUIRED unit spec, each beside it as `<name>.<role>.spec.ts`; any other logic role (`ruleParams.be.logicRoles`: policy, client, guard, mapper, ...) inside a slot whose coverage is required may have one; any other unit spec is a finding, and there are only the spec kinds `spec`, `e2e-spec`, `integration-spec` and `contract-spec`." },
     schema: [],
     messages: {
-      suffix: "`{{name}}` is a banned kind of test file. A test is a `<name>.service.spec.ts` unit beside its service or a `*.e2e-spec.ts` flow under `src/tests/e2e/`; there is no `.test.ts`, `int-spec` or `harness-spec`.",
-      notService: "`{{name}}` is a unit spec of something that is not a service. Only `<name>.service.ts` is unit-tested; a handler, resolver, controller, consumer, mapper, entity, guard, module, policy, helper or composition is covered through the service tests and the e2e flows. Delete this spec and move any business rule it checks into a service.",
-      orphan: "`{{name}}` has no service beside it. A unit spec is `<name>.service.spec.ts` next to `<name>.service.ts` and tests that one service; move it beside its service, or rename it after the service it tests.",
-      missing: "This service has no spec. Add `{{spec}}` beside it: it builds the service with `Test.createTestingModule`, provides only its constructor dependencies as typed doubles and asserts results or state.",
+      suffix: "`{{name}}` is a banned kind of test file. A test is a `<name>.service.spec.ts` unit beside its service, or a `*.e2e-spec.ts`, `*.integration-spec.ts` or `*.contract-spec.ts` under its `src/tests/` folder; there is no `.test.ts`, `.int-spec.ts` or `.harness-spec.ts`.",
+      notService: "`{{name}}` is a unit spec of something that carries no unit-tested logic here. A unit spec sits beside a `<name>.<role>.ts` of a spec-required role (a service, a cli command of `src/features/cli`) or of a logic role (`ruleParams.be.logicRoles`: policy, client, guard, mapper, ...) inside the logic of `src/modules/**`, where every file owes 100 per file; a feature file (handler, resolver, controller, consumer, processor, step, ...) is thin (BE_FEATURE_THIN) and is proven by the integration and e2e flows, and an entity, module or composition is declaration. Delete this spec and move any business rule it checks into a service, policy or mapper of `src/modules/**`.",
+      orphan: "`{{name}}` has nothing beside it to test. A unit spec is `<name>.<role>.spec.ts` next to the `<name>.<role>.ts` it tests (a service, or a cli command of `src/features/cli`; the roles are `ruleParams.be.unitRoles`); move it beside its subject, or rename it after the subject it tests.",
+      missing: "This unit-tested subject has no spec. Add `{{spec}}` beside it: it builds the subject with `Test.createTestingModule`, provides only its constructor dependencies as typed doubles and asserts results or state.",
     },
   },
   create(context) {
@@ -149,17 +149,20 @@ export const unitTestColocated = {
       return { Program(node) { context.report({ node, messageId: "suffix", data: { name } }) } }
     }
     if (isUnitSpecFile(hfs, filename)) {
-      if (!isServiceSpecFile(hfs, filename)) return { Program(node) { context.report({ node, messageId: "notService", data: { name } }) } }
-      if (exists(join(dirname(filename), `${serviceNameOfSpec(filename)}.service.ts`))) return {}
+      const door = doorOfSpec(hfs, filename)
+      if (door !== null) return exists(join(dirname(filename), door)) ? {} : { Program(node) { context.report({ node, messageId: "orphan", data: { name } }) } }
+      const role = unitRoleOfSpec(hfs, filename)
+      if (!role) return { Program(node) { context.report({ node, messageId: "notService", data: { name } }) } }
+      const subject = `${name.slice(0, -`.${role.spec}.ts`.length)}.${role.role}.ts`
+      if (exists(join(dirname(filename), subject))) return {}
       return { Program(node) { context.report({ node, messageId: "orphan", data: { name } }) } }
     }
-    if (!name.endsWith(".service.ts")) return {}
-    // a service outside the test tree; the slot manifest says where the tests live
-    const slot = hfs.slotOf(filename)
-    if (!slot || slot.startsWith("be.tests.")) return {}
-    const stem = join(dirname(filename), name.slice(0, -".ts".length))
-    if (exists(`${stem}.spec.ts`)) return {}
-    return { Program(node) { context.report({ node, messageId: "missing", data: { spec: `${name.slice(0, -".ts".length)}.spec.ts` } }) } }
+    // a unit-tested subject outside the test tree (ruleParams.be.unitRoles): its spec sits beside it
+    const role = unitRoleOfSubject(hfs, filename)
+    if (!role) return {}
+    const spec = `${name.slice(0, -`.${role.role}.ts`.length)}.${role.spec}.ts`
+    if (exists(join(dirname(filename), spec))) return {}
+    return { Program(node) { context.report({ node, messageId: "missing", data: { spec } }) } }
   },
 }
 
@@ -175,7 +178,7 @@ const isStateReader = (context, node) => STATE_TYPES.some((name) => isPackageTyp
 /** The handle `useTestWorld` answers, by where its type is declared: the `@starci/test-world` package or the repository's world slot. */
 const isWorldHandle = (context, node) => {
   const hfs = hfsOf(context)
-  return typeOrigins(context, node).some((origin) => origin.name === "TestWorld" && (origin.module === "@starci/test-world" || hfs.slotOf(origin.file) === "be.tests.world"))
+  return typeOrigins(context, node).some((origin) => origin.name === "TestWorld" && (origin.module === "@starci/test-world" || inTestWorld(hfs, origin.file)))
 }
 
 /** The name a non-computed member access reads, or null. */
@@ -302,7 +305,7 @@ export const noApiShapedE2eFilename = {
 // -- TESTING-7 -------------------------------------------------------------------------------------
 
 /** Test infrastructure: the fixtures and the test world, where the shared model stub lives (slots `be.tests.fixtures`, `be.tests.world`). */
-const isTestInfrastructure = (hfs, filename) => ["be.tests.fixtures", "be.tests.world"].includes(hfs.slotOf(filename))
+const isTestInfrastructure = (hfs, filename) => hfs.slotOf(filename) === "be.tests.fixtures" || inTestWorld(hfs, filename)
 
 /** Bare markers a stub returns when nobody gave it a real answer to stand in for. */
 const MARKER_STRINGS = new Set(["stubbed", "stub", "ok", "test", "mock", "fake", "todo", "tbd", "n/a", "pending", ""])