@starci/eslint-canon-be 3.0.7 → 3.0.9

package/runtime/scripts/{checks → hfs}/architecture/config.mjs

@@ -2,8 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { slash } from '../../lib/path-key.mjs';
 import { readJsonFile as readJson } from '../../lib/json.mjs';
-import { isInside } from '../common.mjs';
-import { openHfs } from '../../lib/hfs-slots.mjs';
+import { isInside } from '../../lib/walk.mjs';
+import { openHfs } from '../slots.mjs';
 
 
 /** A file's identity: its resolved real path, or the resolved path when it does not exist. */
@@ -120,9 +120,10 @@ function workspaceDirectories(root, { packageRoot: appPackageRoot = root, side =
         }
         candidates = next;
       }
-      if (!candidates.length) throw Error(`Workspace pattern matched no package directories: ${normalized}.`);
       // npm expands a `*` segment to the directories that hold a package.json and skips the rest (an empty or untracked folder is
-      // HFS_EMPTY_DIR / HFS_SLOT_UNDECLARED, never a reason to analyse nothing); a literal workspace path must resolve.
+      // HFS_EMPTY_DIR / HFS_SLOT_UNDECLARED, never a reason to analyse nothing); a literal workspace path must resolve. A `*`
+      // pattern may match nothing: every app declares the same workspaces (fe/apps/*, fe/packages/*, HFS_MONO_WORKSPACES) whether
+      // or not it has a package yet, and the root patterns are held to that fixed list by the rule, not here.
       const wildcard = segments.includes('*');
       for (const candidate of candidates) admit(candidate, `workspace ${normalized}`, !wildcard);
     }
@@ -262,13 +263,13 @@ const GRAMMAR_PACKAGE = '@starci/grammar';
 function derivedGrammar(root, packageRoot, workspaces, apps = []) {
   const styleSources = apps.map(app => `apps/${app.name}/src/app/globals.css`).filter(relative => existingRegularFile(root, relative));
   if (!styleSources.length) return null;
-  // The apps have no package.json of their own: the app root's one manifest declares their dependencies, and it is a consumer
-  // when it declares the Grammar package; so is every workspace package that does.
+  // Every fe app and package is an npm workspace that declares what it imports (HFS_MONO_WORKSPACE_DEP): each workspace that
+  // declares the Grammar package is a consumer, and so is the app root's manifest when it does.
   const declaresGrammar = (pkg) => Boolean(pkg && [pkg.dependencies, pkg.peerDependencies, pkg.devDependencies].some(section => section && Object.hasOwn(section, GRAMMAR_PACKAGE)));
   const appManifest = slash(path.relative(root, path.join(packageRoot, 'package.json')));
   const consumerManifests = declaresGrammar(readJson(path.join(packageRoot, 'package.json'))) ? [appManifest] : [];
   for (const workspace of workspaces) {
-    if (!workspace.startsWith('packages/')) continue;
+    if (!workspace.startsWith('packages/') && !workspace.startsWith('apps/')) continue;
     const manifest = `${workspace}/package.json`;
     const pkg = readJson(path.join(root, ...manifest.split('/')));
     if (declaresGrammar(pkg)) consumerManifests.push(manifest);
@@ -298,7 +299,9 @@ export function loadArchitectureConfig(repositoryRoot, { hfs } = {}) {
   if (!projects.length) throw Error('The repository has no tsconfig.json to derive a TypeScript project from.');
   const backend = {
     modules: ['src/modules'],
-    features: ['src/features'],
+    // The layered feature root is the api kind (src/features/api/<feature>/: application/ and transport/<protocol>/); the cli
+    // feature root (src/features/cli/) has its own shape, held by its slot and the cli rules.
+    features: ['src/features/api'],
     apps: ['apps'],
     moduleRegistration: { providerIdentity: 'exported-class-token', handlerDecorators: [...DECLARED_HANDLER_DECORATORS] },
   };

package/runtime/scripts/{checks → hfs}/architecture/connection-map.mjs

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { machineKit, pascal, upperSnake } from './machine-ast.mjs';
-import { locateDeclaration } from '../../lib/hfs-slots.mjs';
+import { locateDeclaration } from '../slots.mjs';
 
 /**
  * R84 `connection-map` (BE_CONNECTION_DUPLICATE), folding RED01 and RED02. One physical database is one connection, one
@@ -14,11 +14,14 @@ import { locateDeclaration } from '../../lib/hfs-slots.mjs';
  *   - a connection file for a name hfs.json does not declare is refused;
  *   - `getEntityManagerToken(` and `InjectEntityManager(` (from @nestjs/typeorm) resolve their argument through the
  *     checker to a connection name and may be called only in that connection's decorators file, once; the DataSource
- *     forms only in platform/database, the migrate app and the test fixtures; an exported `Inject*EntityManager`
+ *     forms only in platform/database, the cli app and the test fixtures; an exported `Inject*EntityManager`
  *     anywhere else (a capability-specific injector, a duplicate) is refused;
  *   - inside one app every connection is passed to the platform/database module registration once;
+ *   - a connection whose hfs.json `isolation` is `schema` reads `<PREFIX>_SCHEMA` in its config (a context is its own database or its own
+ *     schema of a shared one; splitting it out later is an env change only);
  *   - in every `.starcistacks/<env>/runtime/env` two connections whose `<PREFIX>_HOST`, `<PREFIX>_PORT` and
- *     `<PREFIX>_NAME` (or `_DATABASE`, whichever the config reads) resolve to one triple are the same database.
+ *     `<PREFIX>_NAME` (or `_DATABASE`, whichever the config reads) resolve to one triple are the same database, unless both are
+ *     `isolation: schema` with different `<PREFIX>_SCHEMA` values (two contexts as schemas of one database).
  */
 export const CONNECTION_RULE_IDS = ['BE_CONNECTION_DUPLICATE'];
 
@@ -92,12 +95,14 @@ export function checkConnectionMap(input) {
       report(configRel, `Connection ${connection.name} needs ${configRel}, the one place its ${connection.envPrefix}_* keys are read.`, { connection: connection.name });
       continue;
     }
+    let readsSchema = false;
     kit.walk(configFile.sourceFile, node => {
       let key = null;
       if (ts.isStringLiteralLike(node) && ENV_KEY.test(node.text)) key = node.text;
       else if (ts.isPropertyAccessExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'env'
         && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === 'process' && ENV_KEY.test(node.name.text)) key = node.name.text;
       if (key === null) return true;
+      if (key === `${connection.envPrefix}_SCHEMA`) readsSchema = true;
       const own = key.startsWith(`${connection.envPrefix}_`);
       const foreign = declared.find(other => other !== connection && key.startsWith(`${other.envPrefix}_`));
       if (!own || foreign) {
@@ -105,6 +110,7 @@ export function checkConnectionMap(input) {
       }
       return false;
     });
+    if (connection.isolation === 'schema' && !readsSchema) report(configRel, `Connection ${connection.name} is isolated as a schema of a shared database (hfs.json isolation), so ${configRel} must read ${connection.envPrefix}_SCHEMA and hand it to the data source; splitting the context out into its own database is then an env change only.`, { connection: connection.name });
   }
   for (const file of databaseFiles) {
     const match = /^(.+)\.(connection|decorators|config)\.ts$/u.exec(path.posix.basename(file.rel));
@@ -133,8 +139,8 @@ export function checkConnectionMap(input) {
             if (perDecorators.get(value) > 1) report(file.rel, `${home} resolves connection ${value} more than once; one connection has one injector.`, { ...kit.at(file.rel, file.sourceFile, node), connection: value });
           }
         } else if (binding?.module === TYPEORM && SOURCE_CALLS.has(binding.name)) {
-          const allowed = file.rel.startsWith(`${DATABASE_DIR}/`) || slotIs('be.app.migrate') || slotIs('be.tests.fixtures');
-          if (!allowed) report(file.rel, `${binding.name}() reaches the DataSource outside platform/database and the migrate app; inject the shared EntityManager of the connection instead.`, kit.at(file.rel, file.sourceFile, node));
+          const allowed = file.rel.startsWith(`${DATABASE_DIR}/`) || slotIs('be.app.cli') || slotIs('be.cli') || slotIs('be.tests.fixtures');
+          if (!allowed) report(file.rel, `${binding.name}() reaches the DataSource outside platform/database and the cli; inject the shared EntityManager of the connection instead.`, kit.at(file.rel, file.sourceFile, node));
         }
       }
       const exportedName = (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && ts.isVariableStatement(node.parent?.parent) && kit.isExported(node.parent.parent)) ? node.name.text
@@ -189,7 +195,7 @@ export function checkConnectionMap(input) {
     const rel = path.relative(config.root, path.join(stacksRoot, env, 'runtime', 'env')).split(path.sep).join('/');
     const values = readEnvFiles(path.join(stacksRoot, env, 'runtime', 'env'));
     if (!values || values.size === 0) { stacksSkipped += 1; continue; }
-    const seen = new Map();
+    const seen = new Map(); // host|port|database -> [{name, isolation, schema}]
     let resolved = 0;
     for (const connection of declared) {
       const configFile = kit.graphFile(`${DATABASE_DIR}/${connection.name}.config.ts`);
@@ -200,9 +206,15 @@ export function checkConnectionMap(input) {
       if (!host || !port || !database) continue;
       resolved += 1;
       const triple = `${host.toLowerCase()}|${port}|${database}`;
-      if (seen.has(triple)) {
-        report(rel, `Connections ${seen.get(triple)} and ${connection.name} resolve to the same database (${host}:${port}/${database}) in stack ${env}; one physical database is one connection.`, { connection: connection.name, env });
-      } else seen.set(triple, connection.name);
+      const schema = connection.isolation === 'schema' ? (values.get(`${connection.envPrefix}_SCHEMA`) ?? '') : null;
+      const sharing = seen.get(triple) ?? [];
+      // Two contexts may share one database only as distinct, named schemas; a context that is its own database shares it with nobody.
+      const clash = sharing.find(other => schema === null || other.schema === null || other.schema === schema);
+      if (clash) {
+        report(rel, `Connections ${clash.name} and ${connection.name} resolve to the same database (${host}:${port}/${database}${schema !== null && clash.schema === schema ? `, schema ${schema || '(none)'}` : ''}) in stack ${env}; contexts share a database only as distinct schemas (isolation schema, a different ${connection.envPrefix}_SCHEMA), otherwise one physical database is one connection.`, { connection: connection.name, env });
+      }
+      sharing.push({ name: connection.name, schema });
+      seen.set(triple, sharing);
     }
     if (resolved) stacksChecked += 1; else stacksSkipped += 1;
   }

package/runtime/scripts/hfs/architecture/context-coupling.mjs

@@ -0,0 +1,88 @@
+import path from 'node:path';
+import { contextModelOf } from './context-map.mjs';
+import { machineKit } from './machine-ast.mjs';
+import { entitiesOf } from './sql-owner.mjs';
+
+/**
+ * R175 `context-coupling` (BE_CONTEXT_COUPLING). Bounded contexts are coupled by events only, never by their schema or their code:
+ *   - an entity relation (`OneToOne`, `OneToMany`, `ManyToOne`, `ManyToMany` imported from typeorm) whose target class is an entity of a capability
+ *     of another context is refused;
+ *   - a migration foreign key (`REFERENCES <table>` in a string of a migration file) onto a table whose entity belongs to another context is refused;
+ *   - a domain or projection file imports no file of a capability of another context (its entities, services or SQL).
+ * A capability's context is the connection its persistence arrays are registered on (context-map.mjs). A file or table with no proven context
+ * (a platform capability, a capability registered nowhere) is never judged, and the table of a foreign key is looked up through the entities the
+ * program declares, never guessed from a name.
+ */
+export const CONTEXT_COUPLING_RULE_IDS = ['BE_CONTEXT_COUPLING'];
+
+const RULE = 'BE_CONTEXT_COUPLING';
+const TYPEORM = 'typeorm';
+const RELATIONS = new Set(['OneToOne', 'OneToMany', 'ManyToOne', 'ManyToMany']);
+// The table identifier after the SQL keyword REFERENCES, optionally schema-qualified and quoted.
+const REFERENCES = /\bREFERENCES\s+(?:"?[A-Za-z0-9_]+"?\s*\.\s*)?"?([A-Za-z0-9_]+)"?/giu;
+
+export function checkContextCoupling(input) {
+  const { graph } = input;
+  const kit = machineKit(input);
+  const { ts, resolver } = kit;
+  const model = contextModelOf(kit, graph);
+  const { tables } = entitiesOf(kit, graph);
+  const violations = [];
+  const seen = new Set();
+  const once = (key, violation) => { if (!seen.has(key)) { seen.add(key); violations.push({ ruleId: RULE, ...violation }); } };
+  const counts = { relations: 0, foreignKeys: 0, imports: 0 };
+  const covered = new Set(); // `${fromRel}|${targetRoot}` pairs a relation already reported, so the import edge is not a second finding
+
+  for (const file of graph.files.values()) {
+    if (file.slot !== 'be.persistence' || !file.owner) continue;
+    const base = path.posix.basename(file.rel);
+    const ownContext = model.contextOfCapability(file.owner.root);
+    if (!ownContext) continue;
+    const checker = kit.checkerOf(file.sourceFile);
+    if (base.endsWith('.entity.ts')) {
+      kit.walk(file.sourceFile, node => {
+        if (!ts.isDecorator(node) || !ts.isCallExpression(node.expression)) return true;
+        const binding = kit.importBinding(checker, node.expression.expression);
+        if (binding?.module !== TYPEORM || !RELATIONS.has(binding.name)) return true;
+        counts.relations += 1;
+        const argument = node.expression.arguments[0];
+        const target = argument && (ts.isArrowFunction(argument) || ts.isFunctionExpression(argument)) && !ts.isBlock(argument.body) ? model.unparen(argument.body) : null;
+        if (!target || !(ts.isIdentifier(target) || ts.isPropertyAccessExpression(target))) return true;
+        const home = kit.declarationsOf(checker, ts.isPropertyAccessExpression(target) ? target.name : target).map(kit.ownerOfDeclaration).find(Boolean);
+        const targetContext = home ? model.contextOfCapability(home.root) : null;
+        if (!home || !targetContext || targetContext === ownContext) return true;
+        covered.add(`${file.rel}|${home.root}`);
+        once(`${file.rel}|${node.getStart()}`, { ...kit.at(file.rel, file.sourceFile, node), message: `A ${binding.name} relation in ${file.owner.root} (context ${ownContext}) targets an entity of ${home.root} (context ${targetContext}); a relation never crosses a context. Keep the other context's id as a plain column and fill a local copy or a projection from its events.`, context: ownContext, targetContext });
+        return true;
+      });
+    }
+    if (file.rel.slice(file.owner.root.length + 1).startsWith('persistence/migrations/')) {
+      kit.walk(file.sourceFile, node => {
+        if (!(ts.isStringLiteralLike(node) || ts.isTemplateExpression(node))) return true;
+        const text = ts.isTemplateExpression(node) ? node.head.text + node.templateSpans.map(span => ` ${span.literal.text}`).join('') : node.text;
+        for (const match of text.matchAll(REFERENCES)) {
+          counts.foreignKeys += 1;
+          const entity = tables.get(match[1].toLowerCase());
+          const targetContext = entity ? model.contextOfCapability(entity.owner) : null;
+          if (!entity || !targetContext || targetContext === ownContext) continue;
+          once(`${file.rel}|${node.getStart()}|${match[1]}`, { ...kit.at(file.rel, file.sourceFile, node), message: `A foreign key in ${file.rel} references table ${entity.table} of ${entity.owner} (context ${targetContext}), but this migration belongs to context ${ownContext}; a foreign key never crosses a context. Keep the id as a plain column and validate it through the other context's API or a local copy fed by its events.`, context: ownContext, targetContext, table: entity.table });
+        }
+        return true;
+      });
+    }
+  }
+
+  for (const edge of graph.edges) {
+    const from = graph.files.get(edge.from);
+    const to = graph.files.get(edge.to);
+    if (!from?.owner || !to?.owner || from.owner.root === to.owner.root) continue;
+    const fromContext = model.contextOfFile(edge.from);
+    const toContext = model.contextOfFile(edge.to);
+    if (!fromContext || !toContext || fromContext === toContext) continue;
+    counts.imports += 1;
+    if (covered.has(`${edge.from}|${to.owner.root}`)) continue;
+    once(`${edge.from}|${edge.to}|${edge.line}`, { path: edge.from, line: edge.line, column: edge.column, message: `${from.owner.root} (context ${fromContext}) imports ${to.owner.root} (context ${toContext}); a context never imports another context's entities, services or SQL. Keep a local copy fed by its events, or read a projection.`, context: fromContext, targetContext: toContext });
+  }
+  void resolver;
+  return { violations, coverage: { status: 'checked', ...counts } };
+}

package/runtime/scripts/hfs/architecture/context-map.mjs

@@ -0,0 +1,237 @@
+import path from 'node:path';
+import { pascal } from './machine-ast.mjs';
+import { DATABASE_DIR } from './connection-map.mjs';
+
+const camel = name => { const text = pascal(name); return text[0].toLowerCase() + text.slice(1); };
+
+/**
+ * Where the persistence arrays of every capability are registered: the object literals (`DatabaseModule.register` connections and the
+ * migrate/cli app's) that list `<c>Entities` / `<c>Migrations` of a capability's `persistence/connection.ts` under a connection `name`.
+ * The one walk BE_SCHEMA_OWNER and the bounded-context rules (R174 to R178) share, so a capability's context is decided once, by origin.
+ *
+ * @param {{kit: object, graph: object, persistenceOf: (rel: string) => ({root: string, capability: string, folder: string, below: string[]} | null)}} input
+ * @returns {{registered: Map<string, {name: string, connections: Map<string, {file: object, node: object}>}>, registrations: number, all: Array<{file: object, node: object, connection: string | null}>}}
+ *   `registered`: capability root -> its name and the connections it is registered on (first site each).
+ */
+export function collectRegistrations({ kit, graph, persistenceOf }) {
+  const { ts } = kit;
+  const unparen = node => { let current = node; while (current && (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isSatisfiesExpression?.(current) || ts.isNonNullExpression(current))) current = current.expression; return current; };
+  const returned = declaration => {
+    const fn = ts.isVariableDeclaration(declaration) && declaration.initializer ? unparen(declaration.initializer) : declaration;
+    if (!(ts.isArrowFunction(fn) || ts.isFunctionDeclaration(fn) || ts.isFunctionExpression(fn) || ts.isMethodDeclaration(fn)) || !fn.body) return null;
+    if (!ts.isBlock(fn.body)) return fn.body;
+    const statements = fn.body.statements.filter(ts.isReturnStatement);
+    return statements.length === 1 ? statements[0].expression ?? null : null;
+  };
+  const propertySources = new Map(); // property name -> [{declaration, initializer, checker}] over the program
+  const assignmentsOf = name => {
+    if (propertySources.has(name)) return propertySources.get(name);
+    const list = [];
+    for (const file of graph.files.values()) {
+      if (!file.sourceFile.text.includes(name)) continue;
+      const checker = kit.checkerOf(file.sourceFile);
+      kit.walk(file.sourceFile, node => {
+        if (ts.isPropertyAssignment(node) && kit.propertyNameText(node.name) === name && ts.isObjectLiteralExpression(node.parent)) {
+          // the property of the type the literal is checked against, so a typed const and a typed return meet the same declaration
+          const contextual = checker.getContextualType(node.parent)?.getProperty(name);
+          const symbol = contextual ?? checker.getSymbolAtLocation(node.name);
+          list.push({ declaration: symbol?.declarations?.[0] ?? null, initializer: node.initializer, checker });
+        }
+        return true;
+      });
+    }
+    propertySources.set(name, list);
+    return list;
+  };
+  const nameOfLiteral = (checker, literal, depth) => {
+    const own = kit.propertyOf(literal, 'name');
+    if (own) return kit.stringValue(checker, kit.valueOfProperty(own));
+    for (const property of literal.properties) {
+      if (!ts.isSpreadAssignment(property)) continue;
+      const value = nameOfExpression(checker, property.expression, depth + 1);
+      if (value) return value;
+    }
+    return null;
+  };
+  const nameOfExpression = (checker, expression, depth) => {
+    const node = unparen(expression);
+    if (!node || depth > 5) return null;
+    if (ts.isObjectLiteralExpression(node)) return nameOfLiteral(checker, node, depth);
+    if (ts.isCallExpression(node)) {
+      for (const declaration of kit.declarationsOf(checker, node.expression)) {
+        const body = returned(declaration);
+        const value = body ? nameOfExpression(kit.checkerOf(declaration.getSourceFile()), body, depth + 1) : null;
+        if (value) return value;
+      }
+      return null;
+    }
+    if (ts.isIdentifier(node)) {
+      const declaration = kit.declarationsOf(checker, node)[0];
+      return declaration && ts.isVariableDeclaration(declaration) && declaration.initializer ? nameOfExpression(kit.checkerOf(declaration.getSourceFile()), declaration.initializer, depth + 1) : null;
+    }
+    if (ts.isPropertyAccessExpression(node)) {
+      const target = kit.declarationsOf(checker, node.name)[0];
+      if (!target) return null;
+      const names = new Set(assignmentsOf(node.name.text).filter(item => item.declaration === target).map(item => nameOfExpression(item.checker, item.initializer, depth + 1)).filter(Boolean));
+      return names.size === 1 ? [...names][0] : null;
+    }
+    return null;
+  };
+  /** The capability arrays (`<c>Entities` / `<c>Migrations` of persistence/connection.ts) an expression lists. */
+  const arraysIn = (checker, expression, out, depth) => {
+    const node = unparen(expression);
+    if (!node || depth > 6) return;
+    if (ts.isArrayLiteralExpression(node)) { for (const element of node.elements) arraysIn(checker, ts.isSpreadElement(element) ? element.expression : element, out, depth + 1); return; }
+    if (!ts.isIdentifier(node) && !ts.isPropertyAccessExpression(node)) return;
+    const declaration = kit.declarationsOf(checker, ts.isPropertyAccessExpression(node) ? node.name : node)[0];
+    if (!declaration || !ts.isVariableDeclaration(declaration) || !ts.isIdentifier(declaration.name)) return;
+    const rel = kit.graphPath(declaration);
+    const owner = rel ? persistenceOf(rel) : null;
+    if (owner && owner.below.length === 1 && owner.below[0] === 'connection.ts' && [`${camel(owner.capability)}Entities`, `${camel(owner.capability)}Migrations`].includes(declaration.name.text)) {
+      out.push({ key: path.posix.dirname(owner.root), name: owner.capability });
+    } else if (declaration.initializer) arraysIn(kit.checkerOf(declaration.getSourceFile()), declaration.initializer, out, depth + 1);
+  };
+  const all = []; // every registration literal: {file, node, connection | null when the name cannot be resolved}
+  const registered = new Map(); // capability root -> {name, connections: Map(connection -> first site)}
+  let registrations = 0;
+  for (const file of graph.files.values()) {
+    const checker = kit.checkerOf(file.sourceFile);
+    kit.walk(file.sourceFile, node => {
+      if (!ts.isObjectLiteralExpression(node)) return true;
+      const arrays = [];
+      for (const key of ['entities', 'migrations']) {
+        const property = kit.propertyOf(node, key);
+        if (property) arraysIn(checker, kit.valueOfProperty(property), arrays, 0);
+      }
+      if (!arrays.length) return true;
+      registrations += 1;
+      const connection = nameOfLiteral(checker, node, 0);
+      all.push({ file, node, connection });
+      if (connection === null) return true;
+      for (const { key, name } of new Map(arrays.map(item => [item.key, item])).values()) {
+        if (!registered.has(key)) registered.set(key, { name, connections: new Map() });
+        const sites = registered.get(key).connections;
+        if (!sites.has(connection)) sites.set(connection, { file, node });
+      }
+      return true;
+    });
+  }
+  return { registered, registrations, all };
+}
+
+const PERSISTENCE_SLOT = 'be.persistence';
+/** The slot tiers whose capabilities belong to a bounded context: the domain and the projections (a projection is owned by the context whose connection holds its tables). */
+const CONTEXT_TIERS = new Set(['domain', 'projections']);
+
+/** True for a platform capability the manifest lists as `perConnection` (its tables exist on every connection that uses it); `root` is the capability root. */
+export const isPerConnection = (resolver, root, name) => root.split('/').includes('platform') && (resolver.slot(PERSISTENCE_SLOT)?.perConnection ?? []).includes(name);
+
+/**
+ * `persistenceOf(rel)`: {root, capability, folder, below} of a be.persistence file (`folder` the directory below persistence/, '' at its root),
+ * null for any other file. `root` is the persistence root, its dirname the capability root.
+ */
+export const persistenceOfFactory = resolver => rel => {
+  const classified = resolver.classifyPath(rel);
+  if (classified.slot !== PERSISTENCE_SLOT) return null;
+  const below = rel.slice(classified.root.length + 1).split('/');
+  return { root: classified.root, capability: path.posix.basename(path.posix.dirname(classified.root)), folder: below.length > 1 ? below[0] : '', below };
+};
+
+/**
+ * The bounded-context model of a program: which context (declared connection) each capability belongs to, and which connection an expression's
+ * entity manager is. A context is a connection; a capability belongs to the one declared connection its persistence arrays are registered on
+ * (collectRegistrations), a platform capability named by the manifest's `perConnection` list to none (it is infrastructure on every connection).
+ * Everything is decided by declarations and origins: the registration literal, the `Inject<Conn>EntityManager` decorator's home file, the
+ * transaction callback parameter's receiver. Nothing is matched by a variable name.
+ */
+const MODELS = new WeakMap();
+
+export function contextModelOf(kit, graph) {
+  if (MODELS.has(graph)) return MODELS.get(graph);
+  const { ts, resolver } = kit;
+  const persistenceOf = persistenceOfFactory(resolver);
+  const declared = new Map(resolver.repo.connections.map(connection => [connection.name, connection]));
+  const { registered, all } = collectRegistrations({ kit, graph, persistenceOf });
+  const perConnection = new Set();
+  const contextOfRoot = new Map(); // capability root -> declared connection name (single registration only)
+  for (const [root, { name, connections }] of registered) {
+    if (isPerConnection(resolver, root, name)) { perConnection.add(root); continue; }
+    const names = [...connections.keys()].filter(connection => declared.has(connection));
+    if (names.length === 1) contextOfRoot.set(root, names[0]);
+  }
+  /** The declared connection a capability root belongs to, or null (no registration, several, or a per-connection platform capability). */
+  const contextOfCapability = root => contextOfRoot.get(root) ?? null;
+  /** The context of the capability owning `rel` when that capability is of a context tier (domain, projections), else null: only these are bounded contexts. */
+  const contextOfFile = rel => {
+    const file = graph.files.get(rel);
+    if (!file?.owner || !CONTEXT_TIERS.has(file.tier)) return null;
+    return contextOfCapability(file.owner.root);
+  };
+  const unparen = node => { let current = node; while (current && (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isNonNullExpression(current))) current = current.expression; return current; };
+  /** The declared connection named by a decorator whose callee is declared in src/modules/platform/database/<conn>.decorators.ts, else null. */
+  const connectionOfDecorators = (checker, declaration) => {
+    for (const decorator of kit.decorators(declaration)) {
+      const callee = ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
+      for (const target of kit.declarationsOf(checker, callee)) {
+        const rel = kit.graphPath(target);
+        const name = rel ? [...declared.keys()].find(connection => rel === `${DATABASE_DIR}/${connection}.decorators.ts`) : null;
+        if (name) return name;
+      }
+    }
+    return null;
+  };
+  /**
+   * The declared connection whose entity manager `expression` is: a property or parameter injected with `Inject<Conn>EntityManager`, or the
+   * manager parameter of the callback of a `.transaction(...)` on such a manager. Null when the origin cannot be proven (never guessed).
+   */
+  const connectionOfManager = (checker, expression, depth = 0) => {
+    const node = unparen(expression);
+    if (!node || depth > 4) return null;
+    const target = ts.isPropertyAccessExpression(node) ? node.name : (ts.isIdentifier(node) ? node : null);
+    if (!target) return null;
+    const declaration = kit.declarationsOf(checker, target)[0];
+    if (!declaration) return null;
+    if (ts.isPropertyDeclaration(declaration) || ts.isParameter(declaration)) {
+      const direct = connectionOfDecorators(checker, declaration);
+      if (direct) return direct;
+    }
+    if (ts.isParameter(declaration) && (ts.isArrowFunction(declaration.parent) || ts.isFunctionExpression(declaration.parent)) && declaration.parent.parameters[0] === declaration) {
+      const call = declaration.parent.parent;
+      if (ts.isCallExpression(call) && call.arguments.includes(declaration.parent) && ts.isPropertyAccessExpression(call.expression) && call.expression.name.text === 'transaction') {
+        return connectionOfManager(checker, call.expression.expression, depth + 1);
+      }
+    }
+    return null;
+  };
+  const model = { declared, registered, registrations: all, perConnection, contextOfCapability, contextOfFile, connectionOfManager, unparen };
+  MODELS.set(graph, model);
+  return model;
+}
+
+/** The declared connection names the composition root of `app` passes to the database module registration, as [{connection, node}] in source order. */
+export function connectionsComposedBy(kit, app) {
+  const { ts } = kit;
+  const root = kit.appRoot(app);
+  if (!root) return { root: null, items: [] };
+  const declared = new Set(kit.resolver.repo.connections.map(connection => connection.name));
+  const checker = kit.checkerOf(root.sourceFile);
+  const items = [];
+  kit.walk(root.sourceFile, node => {
+    if (!(ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'register')) return true;
+    const owner = kit.declarationsOf(checker, node.expression.expression).map(kit.ownerOfDeclaration).find(Boolean);
+    if (!owner || owner.tier !== 'platform' || owner.name !== 'database') return true;
+    for (const argument of node.arguments) {
+      kit.walk(argument, inner => {
+        if (ts.isPropertyAssignment(inner.parent ?? {}) && inner.parent.name === inner) return true;
+        if (ts.isPropertyAccessExpression(inner.parent ?? {}) && inner.parent.name === inner) return true;
+        if (!(ts.isIdentifier(inner) || ts.isStringLiteralLike(inner) || ts.isPropertyAccessExpression(inner))) return true;
+        const value = kit.stringValue(checker, inner);
+        if (value === null || !declared.has(value)) return true;
+        items.push({ connection: value, node: inner });
+        return false;
+      });
+    }
+    return true;
+  });
+  return { root, items };
+}

package/runtime/scripts/hfs/architecture/context-owner.mjs

@@ -0,0 +1,82 @@
+import { contextModelOf, connectionsComposedBy } from './context-map.mjs';
+import { machineKit } from './machine-ast.mjs';
+
+/**
+ * R174 `context-owner` (BE_CONTEXT_OWNER). A connection of hfs.json IS a bounded context, and its `owner` is the one service app that composes it:
+ *   - an api or worker app passes to the database module registration (or lists in its options) only the connections it owns (a monolith's one
+ *     app owns them all);
+ *   - an api or worker app imports no domain or projection capability of a context it does not own: it composes only its own contexts;
+ *   - the cli app is the migration runner and composes every declared connection
+ *     that holds registered tables (migrations run only through it, once per connection).
+ * Which connection an app composes is read from two typed origins in its own files: the connection passed to the database module registration
+ * and the connection literal that lists a capability's `<c>Entities` / `<c>Migrations`. Which context a capability belongs to is the connection
+ * its arrays are registered on (context-map.mjs); an import is judged by the owner graph edge and the target's slot tier, never by a path or
+ * name pattern. A runner app with a registration whose connection name cannot be resolved is not judged for missing connections.
+ */
+export const CONTEXT_OWNER_RULE_IDS = ['BE_CONTEXT_OWNER'];
+
+const RULE = 'BE_CONTEXT_OWNER';
+const SERVICE_KINDS = new Set(['api', 'worker']);
+const RUNNER_KINDS = new Set(['migrate', 'cli']);
+
+export function checkContextOwner(input) {
+  const { graph } = input;
+  const kit = machineKit(input);
+  const { resolver } = kit;
+  const model = contextModelOf(kit, graph);
+  const violations = [];
+  const owners = new Map(resolver.repo.connections.map(connection => [connection.name, connection.owner]));
+  let compositions = 0;
+  let imports = 0;
+  const seen = new Set();
+  const once = (key, violation) => { if (!seen.has(key)) { seen.add(key); violations.push({ ruleId: RULE, ...violation }); } };
+  const appOf = rel => { const classified = resolver.classifyPath(rel); return classified.slot?.startsWith('be.app.') ? classified.bindings?.app ?? null : null; };
+
+  // What each app composes: [{connection, file, node}] from the database module registration and from the registration literals under its files.
+  const composed = new Map(resolver.repo.apps.map(app => [app.name, { items: [], unresolved: false }]));
+  for (const app of resolver.repo.apps) {
+    const { root, items } = connectionsComposedBy(kit, app.name);
+    for (const item of items) composed.get(app.name).items.push({ ...item, file: root });
+  }
+  for (const site of model.registrations) {
+    const app = appOf(site.file.rel);
+    if (!app || !composed.has(app)) continue;
+    if (site.connection === null) composed.get(app).unresolved = true;
+    else composed.get(app).items.push({ connection: site.connection, file: site.file, node: site.node });
+  }
+
+  for (const app of resolver.repo.apps) {
+    const { items, unresolved } = composed.get(app.name);
+    compositions += items.length;
+    if (SERVICE_KINDS.has(app.kind)) {
+      for (const { connection, file, node } of items) {
+        const owner = owners.get(connection);
+        if (owner && owner !== app.name) {
+          once(`${app.name}|${connection}`, { ...kit.at(file.rel, file.sourceFile, node), message: `App ${app.name} composes connection ${connection}, the context owned by app ${owner}; an app composes only the contexts it owns. Reach that context through the API or the events of ${owner}.`, connection, app: app.name, owner });
+        }
+      }
+    } else if (RUNNER_KINDS.has(app.kind) && !unresolved) {
+      const root = kit.appRoot(app.name);
+      const present = new Set(items.map(item => item.connection));
+      const held = new Set([...model.registered.values()].flatMap(entry => [...entry.connections.keys()]));
+      for (const connection of owners.keys()) {
+        if (!root || present.has(connection) || !held.has(connection) || !items.length) continue;
+        once(`${app.name}|missing|${connection}`, { ...kit.at(root.rel, root.sourceFile, root.sourceFile), message: `The ${app.kind} app ${app.name} does not compose connection ${connection}; migrations run only through it, once per connection, so it registers every declared connection that holds tables.`, connection, app: app.name });
+      }
+    }
+  }
+
+  const kinds = new Map(resolver.repo.apps.map(app => [app.name, app.kind]));
+  for (const edge of graph.edges) {
+    const app = appOf(edge.from);
+    if (!app || !SERVICE_KINDS.has(kinds.get(app))) continue;
+    const context = model.contextOfFile(edge.to);
+    if (!context) continue;
+    imports += 1;
+    const owner = owners.get(context);
+    if (owner && owner !== app) {
+      once(`${edge.from}|${edge.to}`, { path: edge.from, line: edge.line, column: edge.column, message: `App ${app} imports ${graph.files.get(edge.to).owner.root}, a capability of context ${context} owned by app ${owner}; an app composes only the contexts it owns, so use the API or the events of ${owner} instead.`, connection: context, app, owner });
+    }
+  }
+  return { violations, coverage: { status: 'checked', apps: resolver.repo.apps.length, compositions, contextImports: imports } };
+}

package/runtime/scripts/hfs/architecture/context-platform-tables.mjs

@@ -0,0 +1,47 @@
+import { contextModelOf } from './context-map.mjs';
+import { machineKit } from './machine-ast.mjs';
+
+/**
+ * R178 `context-platform-tables` (BE_CONTEXT_PLATFORM_TABLES). A platform capability the manifest lists as `perConnection` (the event-bus outbox,
+ * the job table) keeps its tables on EVERY connection that uses it: when a call into the capability passes the entity manager of connection C
+ * (an `Inject<C>EntityManager` property, or the manager of a transaction on one), the capability's `<c>Entities` and `<c>Migrations` must be
+ * registered on C, or the row the call writes has no table in C's database. The caller's connection is proven by the manager's origin; a call
+ * whose manager origin cannot be proven is not judged.
+ */
+export const CONTEXT_PLATFORM_TABLES_RULE_IDS = ['BE_CONTEXT_PLATFORM_TABLES'];
+
+const RULE = 'BE_CONTEXT_PLATFORM_TABLES';
+
+export function checkContextPlatformTables(input) {
+  const { graph } = input;
+  const kit = machineKit(input);
+  const { ts } = kit;
+  const model = contextModelOf(kit, graph);
+  const violations = [];
+  let calls = 0;
+  let unproven = 0;
+  if (!model.perConnection.size) return { violations, coverage: { status: 'checked', perConnectionCapabilities: 0, calls, unproven } };
+  const seen = new Set();
+  for (const file of graph.files.values()) {
+    const checker = kit.checkerOf(file.sourceFile);
+    kit.walk(file.sourceFile, node => {
+      if (!ts.isCallExpression(node)) return true;
+      const callee = ts.isPropertyAccessExpression(node.expression) ? node.expression.name : node.expression;
+      const home = kit.declarationsOf(checker, callee).map(kit.ownerOfDeclaration).find(Boolean);
+      if (!home || !model.perConnection.has(home.root) || file.owner?.root === home.root) return true;
+      calls += 1;
+      const connections = new Set(node.arguments.map(argument => model.connectionOfManager(checker, argument)).filter(Boolean));
+      if (!connections.size) { unproven += 1; return true; }
+      const registeredOn = model.registered.get(home.root)?.connections ?? new Map();
+      for (const connection of connections) {
+        if (registeredOn.has(connection)) continue;
+        const key = `${file.rel}|${node.getStart()}|${connection}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        violations.push({ ruleId: RULE, ...kit.at(file.rel, file.sourceFile, node), message: `${file.rel} passes the entity manager of connection ${connection} to ${home.name}, but the tables of ${home.name} are not registered on ${connection} (registered: ${[...registeredOn.keys()].sort().join(', ') || 'none'}); register its entities and migrations on ${connection} too, so the table exists in the database of that context.`, connection, capability: home.name });
+      }
+      return true;
+    });
+  }
+  return { violations, coverage: { status: 'checked', perConnectionCapabilities: model.perConnection.size, calls, unproven } };
+}