@starci/hfs 4.0.10 → 4.2.0

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

@@ -4,6 +4,140 @@ import { DATABASE_DIR } from './connection-map.mjs';
 
 const camel = name => { const text = pascal(name); return text[0].toLowerCase() + text.slice(1); };
 
+const unparenWhile = (node, isWrapper) => {
+  let current = node;
+  while (current && isWrapper(current)) current = current.expression;
+  return current;
+};
+
+const isExpressionWrapper = (ts, node) => ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression(node);
+
+const unparenRegistration = (ts, node) => unparenWhile(node, current => isExpressionWrapper(ts, current) || ts.isSatisfiesExpression?.(current));
+
+const returnedExpression = (ts, declaration) => {
+  const fn = ts.isVariableDeclaration(declaration) && declaration.initializer ? unparenRegistration(ts, 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;
+};
+
+/** Every `name:` property assignment of an object literal over the program: [{declaration, initializer, checker}], memoised per name. */
+const assignmentsOf = (ctx, name) => {
+  if (ctx.propertySources.has(name)) return ctx.propertySources.get(name);
+  const { kit } = ctx;
+  const { ts } = kit;
+  const list = [];
+  for (const file of ctx.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;
+    });
+  }
+  ctx.propertySources.set(name, list);
+  return list;
+};
+
+const nameOfLiteral = (ctx, checker, literal, depth) => {
+  const { kit } = ctx;
+  const own = kit.propertyOf(literal, 'name');
+  if (own) return kit.stringValue(checker, kit.valueOfProperty(own));
+  for (const property of literal.properties) {
+    if (!kit.ts.isSpreadAssignment(property)) continue;
+    const value = nameOfExpression(ctx, checker, property.expression, depth + 1);
+    if (value) return value;
+  }
+  return null;
+};
+
+const nameFromCall = (ctx, checker, node, depth) => {
+  const { kit } = ctx;
+  for (const declaration of kit.declarationsOf(checker, node.expression)) {
+    const body = returnedExpression(kit.ts, declaration);
+    const value = body ? nameOfExpression(ctx, kit.checkerOf(declaration.getSourceFile()), body, depth + 1) : null;
+    if (value) return value;
+  }
+  return null;
+};
+
+const nameFromIdentifier = (ctx, checker, node, depth) => {
+  const { kit } = ctx;
+  const declaration = kit.declarationsOf(checker, node)[0];
+  return declaration && kit.ts.isVariableDeclaration(declaration) && declaration.initializer
+    ? nameOfExpression(ctx, kit.checkerOf(declaration.getSourceFile()), declaration.initializer, depth + 1) : null;
+};
+
+const nameFromProperty = (ctx, checker, node, depth) => {
+  const target = ctx.kit.declarationsOf(checker, node.name)[0];
+  if (!target) return null;
+  const names = new Set(assignmentsOf(ctx, node.name.text).filter(item => item.declaration === target)
+    .map(item => nameOfExpression(ctx, item.checker, item.initializer, depth + 1)).filter(Boolean));
+  return names.size === 1 ? [...names][0] : null;
+};
+
+function nameOfExpression(ctx, checker, expression, depth) {
+  const { ts } = ctx.kit;
+  const node = unparenRegistration(ts, expression);
+  if (!node || depth > 5) return null;
+  if (ts.isObjectLiteralExpression(node)) return nameOfLiteral(ctx, checker, node, depth);
+  if (ts.isCallExpression(node)) return nameFromCall(ctx, checker, node, depth);
+  if (ts.isIdentifier(node)) return nameFromIdentifier(ctx, checker, node, depth);
+  if (ts.isPropertyAccessExpression(node)) return nameFromProperty(ctx, checker, node, depth);
+  return null;
+}
+
+const isCapabilityArray = (owner, name) => owner?.below.length === 1 && owner.below[0] === 'connection.ts' && [`${camel(owner.capability)}Entities`, `${camel(owner.capability)}Migrations`].includes(name);
+
+const arrayDeclarationOf = (kit, checker, node) => {
+  const { ts } = kit;
+  const declaration = kit.declarationsOf(checker, ts.isPropertyAccessExpression(node) ? node.name : node)[0];
+  return declaration && ts.isVariableDeclaration(declaration) && ts.isIdentifier(declaration.name) ? declaration : null;
+};
+
+/** The capability arrays (`<c>Entities` / `<c>Migrations` of persistence/connection.ts) an expression lists. */
+function arraysIn(ctx, checker, expression, out, depth) {
+  const { kit } = ctx;
+  const { ts } = kit;
+  const node = unparenRegistration(ts, expression);
+  if (!node || depth > 6) return;
+  if (ts.isArrayLiteralExpression(node)) {
+    for (const element of node.elements) { arraysIn(ctx, checker, ts.isSpreadElement(element) ? element.expression : element, out, depth + 1); }
+    return;
+  }
+  if (!ts.isIdentifier(node) && !ts.isPropertyAccessExpression(node)) return;
+  const declaration = arrayDeclarationOf(kit, checker, node);
+  if (!declaration) return;
+  const rel = kit.graphPath(declaration);
+  const owner = rel ? ctx.persistenceOf(rel) : null;
+  if (isCapabilityArray(owner, declaration.name.text)) {
+    out.push({ key: path.posix.dirname(owner.root), name: owner.capability });
+  } else if (declaration.initializer) arraysIn(ctx, kit.checkerOf(declaration.getSourceFile()), declaration.initializer, out, depth + 1);
+}
+
+const registrationArrays = (ctx, checker, literal) => {
+  const arrays = [];
+  for (const key of ['entities', 'migrations']) {
+    const property = ctx.kit.propertyOf(literal, key);
+    if (property) arraysIn(ctx, checker, ctx.kit.valueOfProperty(property), arrays, 0);
+  }
+  return arrays;
+};
+
+const recordRegistration = (registered, arrays, connection, site) => {
+  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, site);
+  }
+};
+
 /**
  * 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`.
@@ -15,105 +149,20 @@ const camel = name => { const text = pascal(name); return text[0].toLowerCase()
  */
 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 ctx = { kit, graph, persistenceOf, propertySources: new Map() }; // property name -> [{declaration, initializer, checker}] over the program
   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;
+      if (!ts.isObjectLiteralExpression(node)) return;
+      const arrays = registrationArrays(ctx, checker, node);
+      if (!arrays.length) return;
       registrations += 1;
-      const connection = nameOfLiteral(checker, node, 0);
+      const connection = nameOfLiteral(ctx, 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;
+      if (connection !== null) recordRegistration(registered, arrays, connection, { file, node });
     });
   }
   return { registered, registrations, all };
@@ -137,6 +186,54 @@ export const persistenceOfFactory = resolver => rel => {
   return { root: classified.root, capability: path.posix.basename(path.posix.dirname(classified.root)), folder: below.length > 1 ? below[0] : '', below };
 };
 
+/** The declared connection named by a decorator whose callee is declared in src/modules/platform/database/<conn>.decorators.ts, else null. */
+const connectionOfDecorators = (kit, declared, checker, declaration) => {
+  const { ts } = kit;
+  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;
+};
+
+const managerTarget = (ts, node) => {
+  if (ts.isPropertyAccessExpression(node)) return node.name;
+  return ts.isIdentifier(node) ? node : null;
+};
+
+/** The receiver expression of the `.transaction(callback)` call whose first callback parameter is `declaration`, else null. */
+const transactionReceiver = (ts, declaration) => {
+  const callback = declaration.parent;
+  if (!ts.isParameter(declaration) || !(ts.isArrowFunction(callback) || ts.isFunctionExpression(callback)) || callback.parameters[0] !== declaration) return null;
+  const call = callback.parent;
+  if (!ts.isCallExpression(call) || !call.arguments.includes(callback) || !ts.isPropertyAccessExpression(call.expression) || call.expression.name.text !== 'transaction') return null;
+  return call.expression.expression;
+};
+
+/**
+ * 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).
+ */
+function connectionOfManagerIn(kit, declared, checker, expression, depth = 0) {
+  const { ts } = kit;
+  const node = unparenWhile(expression, current => isExpressionWrapper(ts, current));
+  if (!node || depth > 4) return null;
+  const target = managerTarget(ts, node);
+  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(kit, declared, checker, declaration);
+    if (direct) return direct;
+  }
+  const receiver = transactionReceiver(ts, declaration);
+  return receiver ? connectionOfManagerIn(kit, declared, checker, receiver, depth + 1) : null;
+}
+
 /**
  * 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
@@ -167,47 +264,35 @@ export function contextModelOf(kit, graph) {
     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;
+  const model = {
+    declared, registered, registrations: all, perConnection, contextOfCapability, contextOfFile,
+    connectionOfManager: (checker, expression) => connectionOfManagerIn(kit, declared, checker, expression),
+    unparen: node => unparenWhile(node, current => isExpressionWrapper(ts, current)),
   };
-  /**
-   * 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;
 }
 
+const composedConnection = (kit, declared, checker, inner) => {
+  const { ts } = kit;
+  const parent = inner.parent;
+  if (parent?.name === inner && (ts.isPropertyAssignment(parent) || ts.isPropertyAccessExpression(parent))) return null;
+  if (!(ts.isIdentifier(inner) || ts.isStringLiteralLike(inner) || ts.isPropertyAccessExpression(inner))) return null;
+  const value = kit.stringValue(checker, inner);
+  return value !== null && declared.has(value) ? value : null;
+};
+
+const collectComposedConnections = (kit, declared, checker, call, items) => {
+  for (const argument of call.arguments) {
+    kit.walk(argument, inner => {
+      const value = composedConnection(kit, declared, checker, inner);
+      if (value === null) return true;
+      items.push({ connection: value, node: inner });
+      return false;
+    });
+  }
+};
+
 /** 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;
@@ -217,21 +302,10 @@ export function connectionsComposedBy(kit, app) {
   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;
+    if (!(ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'register')) return;
     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;
+    if (owner?.tier !== 'platform' || owner.name !== 'database') return;
+    collectComposedConnections(kit, declared, checker, node, items);
   });
   return { root, items };
 }

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

@@ -19,6 +19,43 @@ const RULE = 'BE_CONTEXT_OWNER';
 const SERVICE_KINDS = new Set(['api', 'worker']);
 const RUNNER_KINDS = new Set(['migrate', 'cli']);
 
+// What each app composes: [{connection, file, node}] from the database module registration and from the registration literals under its files.
+const compositionsOf = (kit, resolver, model, appOf) => {
+  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 });
+  }
+  return composed;
+};
+
+// A service app composes only the connections it owns; a runner app composes every declared connection with tables.
+const judgeComposition = (app, { items, unresolved }, { owners, model, kit, once }) => {
+  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 });
+    }
+  }
+  return items.length;
+};
+
 export function checkContextOwner(input) {
   const { graph } = input;
   const kit = machineKit(input);
@@ -32,38 +69,10 @@ export function checkContextOwner(input) {
   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 });
-  }
+  const composed = compositionsOf(kit, resolver, model, appOf);
 
   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 });
-      }
-    }
+    compositions += judgeComposition(app, composed.get(app.name), { owners, model, kit, once });
   }
 
   const kinds = new Map(resolver.repo.apps.map(app => [app.name, app.kind]));

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

@@ -1,5 +1,6 @@
 import { contextModelOf } from './context-map.mjs';
 import { machineKit } from './machine-ast.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 /**
  * R178 `context-platform-tables` (BE_CONTEXT_PLATFORM_TABLES). A platform capability the manifest lists as `perConnection` (the event-bus outbox,
@@ -12,36 +13,49 @@ export const CONTEXT_PLATFORM_TABLES_RULE_IDS = ['BE_CONTEXT_PLATFORM_TABLES'];
 
 const RULE = 'BE_CONTEXT_PLATFORM_TABLES';
 
+function perConnectionHome(kit, model, checker, file, node) {
+  const { ts } = kit;
+  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 undefined;
+  return home;
+}
+
+function unregisteredViolations(kit, model, scope, home, connections, seen) {
+  const { file, node } = scope;
+  const registeredOn = model.registered.get(home.root)?.connections ?? new Map();
+  const violations = [];
+  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(byCodeUnit).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 violations;
+}
+
 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 counts = { calls: 0, unproven: 0 };
+  if (!model.perConnection.size) return { violations, coverage: { status: 'checked', perConnectionCapabilities: 0, ...counts } };
   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 home = perConnectionHome(kit, model, checker, file, node);
+      if (!home) return true;
+      counts.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 });
-      }
+      if (!connections.size) { counts.unproven += 1; return true; }
+      violations.push(...unregisteredViolations(kit, model, { file, node }, home, connections, seen));
       return true;
     });
   }
-  return { violations, coverage: { status: 'checked', perConnectionCapabilities: model.perConnection.size, calls, unproven } };
+  return { violations, coverage: { status: 'checked', perConnectionCapabilities: model.perConnection.size, ...counts } };
 }

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

@@ -13,14 +13,47 @@ export const CONTEXT_TRANSACTION_RULE_IDS = ['BE_CONTEXT_TRANSACTION'];
 
 const RULE = 'BE_CONTEXT_TRANSACTION';
 
+const SPAN_ADVICE = "one transaction touches one context's connection. Span contexts with a saga: one transaction per context, linked by events.";
+
+/** Reports an entity manager of another connection, or a call into another context's capability, found inside a transaction callback. */
+function inspectInner(scope, file, checker, connection, inner) {
+  const { ts, kit, model, graph, report } = scope;
+  if (ts.isPropertyAccessExpression(inner)) {
+    const other = model.connectionOfManager(checker, inner);
+    if (other && other !== connection) report(file, inner, `A transaction on connection ${connection} uses the entity manager of connection ${other}; ${SPAN_ADVICE}`, { connection, other });
+  }
+  if (!ts.isCallExpression(inner)) return;
+  const callee = ts.isPropertyAccessExpression(inner.expression) ? inner.expression.name : inner.expression;
+  const declaration = kit.declarationsOf(checker, callee)[0];
+  const rel = declaration ? kit.graphPath(declaration) : null;
+  const context = rel ? model.contextOfFile(rel) : null;
+  if (context && context !== connection) {
+    report(file, inner, `A transaction on connection ${connection} calls ${graph.files.get(rel).owner.root} of context ${context}; ${SPAN_ADVICE}`, { connection, other: context });
+  }
+}
+
+/** Judges a `.transaction(...)` call: counts it as proven or unproven and inspects its callback body; any other node is skipped. */
+function inspectTransaction(scope, file, checker, node) {
+  const { ts, kit, model, counts } = scope;
+  if (!(ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'transaction')) return;
+  const callback = node.arguments.find(argument => ts.isArrowFunction(argument) || ts.isFunctionExpression(argument));
+  if (!callback) return;
+  const connection = model.connectionOfManager(checker, node.expression.expression);
+  if (!connection) { counts.unproven += 1; return; }
+  counts.transactions += 1;
+  kit.walk(callback.body, inner => {
+    inspectInner(scope, file, checker, connection, inner);
+    return true;
+  });
+}
+
 export function checkContextTransaction(input) {
   const { graph } = input;
   const kit = machineKit(input);
   const { ts } = kit;
   const model = contextModelOf(kit, graph);
   const violations = [];
-  let transactions = 0;
-  let unproven = 0;
+  const counts = { transactions: 0, unproven: 0 };
   const seen = new Set();
   const report = (file, node, message, extra) => {
     const key = `${file.rel}|${node.getStart()}|${message}`;
@@ -28,33 +61,13 @@ export function checkContextTransaction(input) {
     seen.add(key);
     violations.push({ ruleId: RULE, ...kit.at(file.rel, file.sourceFile, node), message, ...extra });
   };
+  const scope = { ts, kit, model, graph, report, counts };
   for (const file of graph.files.values()) {
     const checker = kit.checkerOf(file.sourceFile);
     kit.walk(file.sourceFile, node => {
-      if (!(ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'transaction')) return true;
-      const callback = node.arguments.find(argument => ts.isArrowFunction(argument) || ts.isFunctionExpression(argument));
-      if (!callback) return true;
-      const connection = model.connectionOfManager(checker, node.expression.expression);
-      if (!connection) { unproven += 1; return true; }
-      transactions += 1;
-      kit.walk(callback.body, inner => {
-        if (ts.isPropertyAccessExpression(inner)) {
-          const other = model.connectionOfManager(checker, inner);
-          if (other && other !== connection) report(file, inner, `A transaction on connection ${connection} uses the entity manager of connection ${other}; one transaction touches one context's connection. Span contexts with a saga: one transaction per context, linked by events.`, { connection, other });
-        }
-        if (ts.isCallExpression(inner)) {
-          const callee = ts.isPropertyAccessExpression(inner.expression) ? inner.expression.name : inner.expression;
-          const declaration = kit.declarationsOf(checker, callee)[0];
-          const rel = declaration ? kit.graphPath(declaration) : null;
-          const context = rel ? model.contextOfFile(rel) : null;
-          if (context && context !== connection) {
-            report(file, inner, `A transaction on connection ${connection} calls ${graph.files.get(rel).owner.root} of context ${context}; one transaction touches one context's connection. Span contexts with a saga: one transaction per context, linked by events.`, { connection, other: context });
-          }
-        }
-        return true;
-      });
+      inspectTransaction(scope, file, checker, node);
       return true;
     });
   }
-  return { violations, coverage: { status: 'checked', transactions, unproven } };
+  return { violations, coverage: { status: 'checked', transactions: counts.transactions, unproven: counts.unproven } };
 }