@starci/hfs 4.11.22 → 4.12.2

package/runtime/scripts/hfs/architecture/constructor-deps.d.mts

@@ -0,0 +1,57 @@
+import type { BindingElement, CallExpression, ClassDeclaration, Declaration, Identifier, Node, ParameterDeclaration, SourceFile, VariableDeclaration } from 'typescript';
+import type { GraphFile, HfsGraph } from './hfs-graph.mjs';
+import type { MachineKit } from './machine-ast.mjs';
+/** A token the decorator names: the exported name it is declared under, and where it is declared. */
+export interface ResolvedToken {
+    kind: 'token';
+    name: string;
+    declaration: VariableDeclaration | BindingElement | null;
+    argument: Identifier;
+    external: boolean;
+    node?: undefined;
+}
+/** A dependency (or token) the reader cannot follow, with why and the node to report at. */
+export interface UnresolvedToken {
+    kind: 'unresolved';
+    reason: string;
+    node: Node | null;
+}
+export type TokenOfArgument = ResolvedToken | UnresolvedToken;
+/** What a custom `Inject<Thing>()` or raw `@Inject(TOKEN)` decorator resolves to, with the decorator's own facts. */
+export type InjectToken = TokenOfArgument & TokenFacts;
+/** The decorator's own facts a resolved inject decorator carries. */
+interface TokenFacts {
+    decorator: string;
+    decoratorDeclaration?: Declaration | null;
+    decoratorFile?: null;
+    injectorCall?: CallExpression;
+}
+/** A parameter and the node a finding about it is reported at. */
+interface Located {
+    parameter: ParameterDeclaration;
+    node: Node;
+}
+/** One constructor parameter's dependency. */
+export type ClassDependency = (Omit<ResolvedToken, 'node'> & TokenFacts & Located) | (Omit<UnresolvedToken, 'node'> & TokenFacts & Located) | {
+    kind: 'class';
+    name: string;
+    parameter: ParameterDeclaration;
+    node: Node;
+} | {
+    kind: 'unresolved';
+    reason: string;
+    parameter: ParameterDeclaration;
+    node: Node;
+};
+/** A service class of the program with the file declaring it. */
+export interface ServiceClass {
+    file: GraphFile;
+    declaration: ClassDeclaration;
+}
+/** The dependencies of one class, in constructor order: [{kind, name?, node, parameter, ...}]. */
+export declare function constructorDependencies(kit: MachineKit, file: {
+    sourceFile: SourceFile;
+}, classDeclaration: ClassDeclaration): ClassDependency[];
+/** Every service class of the program: [{file, declaration}] for each class of a `*.service.ts` file. */
+export declare function serviceClasses(kit: MachineKit, graph: HfsGraph): ServiceClass[];
+export {};

package/runtime/scripts/hfs/architecture/constructor-deps.mjs

@@ -1,5 +1,4 @@
 import path from 'node:path';
-
 /**
  * The constructor dependencies of a service, read the way the injection law (R85) writes them, shared by the unit-spec
  * provider check (R48 `unit-spec-providers`) and the token export check (R85 `injection-token-exported`).
@@ -13,94 +12,104 @@ import path from 'node:path';
  *     a type that is not a class).
  */
 const INJECT_NAME = /^Inject(?:[A-Z][A-Za-z0-9]*)?$/u;
-
 /** The identifier a decorator names: `@InjectFoo()` -> InjectFoo, `@Inject(TOKEN)` -> Inject; null for a non-identifier decorator. */
 function decoratorCallee(ts, decorator) {
-  const expression = decorator.expression;
-  const callee = ts.isCallExpression(expression) ? expression.expression : expression;
-  return ts.isIdentifier(callee) ? { callee, call: ts.isCallExpression(expression) ? expression : null } : null;
+    const expression = decorator.expression;
+    const callee = ts.isCallExpression(expression) ? expression.expression : expression;
+    return ts.isIdentifier(callee) ? { callee, call: ts.isCallExpression(expression) ? expression : null } : null;
 }
-
 /** The token a `injector(<arg>)` call names, judged where the argument is declared. */
 function tokenOfArgument(kit, checker, argument) {
-  const { ts } = kit;
-  if (!argument || !ts.isIdentifier(argument)) return { kind: 'unresolved', reason: 'its token is not a plain identifier of an exported const', node: argument ?? null };
-  const declaration = kit.declarationsOf(checker, argument).find(item => ts.isVariableDeclaration(item) || ts.isBindingElement(item));
-  if (declaration) {
-    const name = ts.isIdentifier(declaration.name) ? declaration.name.text : argument.text;
-    return { kind: 'token', name, declaration, argument, external: false };
-  }
-  const binding = kit.importBinding(checker, argument);
-  if (binding && !binding.module.startsWith('.')) return { kind: 'token', name: binding.name, declaration: null, argument, external: true };
-  return { kind: 'unresolved', reason: `the token ${argument.text} does not resolve to a declaration`, node: argument };
+    const { ts } = kit;
+    if (!argument || !ts.isIdentifier(argument))
+        return { kind: 'unresolved', reason: 'its token is not a plain identifier of an exported const', node: argument ?? null };
+    const declaration = kit.declarationsOf(checker, argument).find((item) => ts.isVariableDeclaration(item) || ts.isBindingElement(item));
+    if (declaration) {
+        const name = ts.isIdentifier(declaration.name) ? declaration.name.text : argument.text;
+        return { kind: 'token', name, declaration, argument, external: false };
+    }
+    const binding = kit.importBinding(checker, argument);
+    if (binding && !binding.module.startsWith('.'))
+        return { kind: 'token', name: binding.name, declaration: null, argument, external: true };
+    return { kind: 'unresolved', reason: `the token ${argument.text} does not resolve to a declaration`, node: argument };
 }
-
 /** The first `injector(...)` call under a decorator declaration, or null. */
 function injectorCallOf(kit, declaration) {
-  const { ts } = kit;
-  let injectorCall = null;
-  kit.walk(declaration, node => {
-    if (injectorCall) return false;
-    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
-      const binding = kit.importBinding(kit.checkerOf(declaration.getSourceFile()), node.expression);
-      if ((binding?.name ?? node.expression.text) === 'injector') injectorCall = node;
-    }
-    return true;
-  });
-  return injectorCall;
+    const { ts } = kit;
+    let injectorCall = null;
+    kit.walk(declaration, node => {
+        if (injectorCall)
+            return false;
+        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+            const binding = kit.importBinding(kit.checkerOf(declaration.getSourceFile()), node.expression);
+            if ((binding?.name ?? node.expression.text) === 'injector')
+                injectorCall = node;
+        }
+        return true;
+    });
+    return injectorCall;
 }
-
 /** The injector token of a custom `Inject<Thing>()` decorator, or an unresolved reason. */
 function tokenOfInjectDecorator(kit, checker, parameter, decorator) {
-  const { ts } = kit;
-  const head = decoratorCallee(ts, decorator);
-  if (!head || !INJECT_NAME.test(head.callee.text)) return null;
-  if (head.callee.text === 'Inject' && head.call?.arguments.length) return { ...tokenOfArgument(kit, checker, head.call.arguments[0]), decorator: head.callee.text, decoratorDeclaration: null, decoratorFile: null };
-  const declaration = kit.declarationsOf(checker, head.callee).find(item => ts.isVariableDeclaration(item) || ts.isFunctionDeclaration(item));
-  if (!declaration) return { kind: 'unresolved', reason: `${head.callee.text}() does not resolve to a declaration`, node: parameter, decorator: head.callee.text };
-  const injectorCall = injectorCallOf(kit, declaration);
-  if (!injectorCall) return { kind: 'unresolved', reason: `${head.callee.text}() is not built with injector<T>(TOKEN)`, node: parameter, decorator: head.callee.text };
-  const declarationChecker = kit.checkerOf(declaration.getSourceFile());
-  return { ...tokenOfArgument(kit, declarationChecker, injectorCall.arguments[0]), decorator: head.callee.text, decoratorDeclaration: declaration, injectorCall };
+    const { ts } = kit;
+    const head = decoratorCallee(ts, decorator);
+    if (!head || !INJECT_NAME.test(head.callee.text))
+        return null;
+    if (head.callee.text === 'Inject' && head.call?.arguments.length)
+        return { ...tokenOfArgument(kit, checker, head.call.arguments[0]), decorator: head.callee.text, decoratorDeclaration: null, decoratorFile: null };
+    const declaration = kit.declarationsOf(checker, head.callee).find((item) => ts.isVariableDeclaration(item) || ts.isFunctionDeclaration(item));
+    if (!declaration)
+        return { kind: 'unresolved', reason: `${head.callee.text}() does not resolve to a declaration`, node: parameter, decorator: head.callee.text };
+    const injectorCall = injectorCallOf(kit, declaration);
+    if (!injectorCall)
+        return { kind: 'unresolved', reason: `${head.callee.text}() is not built with injector<T>(TOKEN)`, node: parameter, decorator: head.callee.text };
+    const declarationChecker = kit.checkerOf(declaration.getSourceFile());
+    return { ...tokenOfArgument(kit, declarationChecker, injectorCall.arguments[0]), decorator: head.callee.text, decoratorDeclaration: declaration, injectorCall };
 }
-
 /** The class a parameter type names, judged where the type is declared; null when it is not a class type. */
 function classOfType(kit, checker, type) {
-  const { ts } = kit;
-  if (!type || !ts.isTypeReferenceNode(type) || !ts.isIdentifier(type.typeName)) return null;
-  const declarations = kit.declarationsOf(checker, type.typeName);
-  const declared = declarations.find(item => ts.isClassDeclaration(item) && item.name);
-  if (declared) return declared.name.text;
-  if (declarations.length) return null;
-  const binding = kit.importBinding(checker, type.typeName);
-  return binding && binding.name !== 'default' && binding.name !== '*' ? binding.name : null;
+    const { ts } = kit;
+    if (!type || !ts.isTypeReferenceNode(type) || !ts.isIdentifier(type.typeName))
+        return null;
+    const declarations = kit.declarationsOf(checker, type.typeName);
+    const declared = declarations.find((item) => ts.isClassDeclaration(item) && Boolean(item.name));
+    if (declared)
+        return declared.name.text;
+    if (declarations.length)
+        return null;
+    const binding = kit.importBinding(checker, type.typeName);
+    return binding && binding.name !== 'default' && binding.name !== '*' ? binding.name : null;
 }
-
 /** The dependencies of one class, in constructor order: [{kind, name?, node, parameter, ...}]. */
 export function constructorDependencies(kit, file, classDeclaration) {
-  const { ts } = kit;
-  const checker = kit.checkerOf(file.sourceFile);
-  const constructor = classDeclaration.members.find(member => ts.isConstructorDeclaration(member) && member.body !== undefined)
-    ?? classDeclaration.members.find(member => ts.isConstructorDeclaration(member));
-  if (!constructor) return [];
-  return constructor.parameters.map(parameter => {
-    for (const decorator of kit.decorators(parameter)) {
-      const token = tokenOfInjectDecorator(kit, checker, parameter, decorator);
-      if (token) return { ...token, parameter, node: token.node ?? parameter };
-    }
-    const name = classOfType(kit, checker, parameter.type);
-    if (name) return { kind: 'class', name, parameter, node: parameter };
-    return { kind: 'unresolved', reason: 'it has no Inject<Thing>() decorator and its type is not a class', parameter, node: parameter };
-  });
+    const { ts } = kit;
+    const checker = kit.checkerOf(file.sourceFile);
+    const constructor = classDeclaration.members.find((member) => ts.isConstructorDeclaration(member) && member.body !== undefined)
+        ?? classDeclaration.members.find((member) => ts.isConstructorDeclaration(member));
+    if (!constructor)
+        return [];
+    return constructor.parameters.map((parameter) => {
+        for (const decorator of kit.decorators(parameter)) {
+            const token = tokenOfInjectDecorator(kit, checker, parameter, decorator);
+            if (token)
+                return { ...token, parameter, node: token.node ?? parameter };
+        }
+        const name = classOfType(kit, checker, parameter.type);
+        if (name)
+            return { kind: 'class', name, parameter, node: parameter };
+        return { kind: 'unresolved', reason: 'it has no Inject<Thing>() decorator and its type is not a class', parameter, node: parameter };
+    });
 }
-
 /** Every service class of the program: [{file, declaration}] for each class of a `*.service.ts` file. */
 export function serviceClasses(kit, graph) {
-  const { ts } = kit;
-  const found = [];
-  for (const file of graph.files.values()) {
-    if (!path.posix.basename(file.rel).endsWith('.service.ts')) continue;
-    for (const statement of file.sourceFile.statements) if (ts.isClassDeclaration(statement) && statement.name) found.push({ file, declaration: statement });
-  }
-  return found;
+    const { ts } = kit;
+    const found = [];
+    for (const file of graph.files.values()) {
+        if (!path.posix.basename(file.rel).endsWith('.service.ts'))
+            continue;
+        for (const statement of file.sourceFile.statements)
+            if (ts.isClassDeclaration(statement) && statement.name)
+                found.push({ file, declaration: statement });
+    }
+    return found;
 }

package/runtime/scripts/hfs/architecture/context-coupling.d.mts

@@ -0,0 +1,21 @@
+import type { ArchitectureViolation, CheckInput } from './hfs-graph.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 declare const CONTEXT_COUPLING_RULE_IDS: string[];
+export declare function checkContextCoupling(input: CheckInput): {
+    violations: ArchitectureViolation[];
+    coverage: {
+        relations: number;
+        foreignKeys: number;
+        imports: number;
+        status: string;
+    };
+};

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

@@ -2,7 +2,6 @@ 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
@@ -14,99 +13,105 @@ import { entitiesOf } from './sql-owner.mjs';
  * 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+(?:"?\w+"?\s*\.\s*)?"?(\w+)"?/giu;
-
 const checkCrossContextImports = (graph, model, covered, counts, once) => {
-  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 });
-  }
+    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 });
+    }
 };
-
 const relationTarget = (kit, model, argument) => {
-  const { ts } = kit;
-  const isFunction = argument && (ts.isArrowFunction(argument) || ts.isFunctionExpression(argument));
-  const target = isFunction && !ts.isBlock(argument.body) ? model.unparen(argument.body) : null;
-  return target && (ts.isIdentifier(target) || ts.isPropertyAccessExpression(target)) ? target : null;
+    const { ts } = kit;
+    const isFunction = argument && (ts.isArrowFunction(argument) || ts.isFunctionExpression(argument));
+    const target = isFunction && !ts.isBlock(argument.body) ? model.unparen(argument.body) : null;
+    return target && (ts.isIdentifier(target) || ts.isPropertyAccessExpression(target)) ? target : null;
 };
-
 // The relation decorator (`@ManyToOne(() => Target)` imported from typeorm) a node is, with the checker that resolves it, else null.
 const relationBinding = (kit, checker, node) => {
-  const { ts } = kit;
-  if (!ts.isDecorator(node) || !ts.isCallExpression(node.expression)) return null;
-  const binding = kit.importBinding(checker, node.expression.expression);
-  return binding?.module === TYPEORM && RELATIONS.has(binding.name) ? binding : null;
+    const { ts } = kit;
+    if (!ts.isDecorator(node) || !ts.isCallExpression(node.expression))
+        return null;
+    const binding = kit.importBinding(checker, node.expression.expression);
+    return binding?.module === TYPEORM && RELATIONS.has(binding.name) ? binding : null;
 };
-
 const checkRelations = (scan, file, ownContext) => {
-  const { kit, model, counts, covered, once } = scan;
-  const { ts } = kit;
-  const checker = kit.checkerOf(file.sourceFile);
-  kit.walk(file.sourceFile, node => {
-    const binding = relationBinding(kit, checker, node);
-    if (!binding) return;
-    counts.relations += 1;
-    const target = relationTarget(kit, model, node.expression.arguments[0]);
-    if (!target) return;
-    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;
-    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 });
-  });
+    const { kit, model, counts, covered, once } = scan;
+    const { ts } = kit;
+    const checker = kit.checkerOf(file.sourceFile);
+    kit.walk(file.sourceFile, (node) => {
+        const binding = relationBinding(kit, checker, node);
+        if (!binding)
+            return;
+        counts.relations += 1;
+        const target = relationTarget(kit, model, node.expression.arguments[0]);
+        if (!target)
+            return;
+        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;
+        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 });
+    });
 };
-
-const stringText = (ts, node) => (ts.isTemplateExpression(node) ? node.head.text + node.templateSpans.map(span => ` ${span.literal.text}`).join('') : node.text);
-
+const stringText = (ts, node) => (ts.isTemplateExpression(node) ? node.head.text + node.templateSpans.map((span) => ` ${span.literal.text}`).join('') : node.text);
 const checkForeignKeys = (scan, file, ownContext) => {
-  const { kit, model, tables, counts, once } = scan;
-  const { ts } = kit;
-  kit.walk(file.sourceFile, node => {
-    if (!(ts.isStringLiteralLike(node) || ts.isTemplateExpression(node))) return;
-    for (const match of stringText(ts, node).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 });
-    }
-  });
+    const { kit, model, tables, counts, once } = scan;
+    const { ts } = kit;
+    kit.walk(file.sourceFile, (node) => {
+        if (!(ts.isStringLiteralLike(node) || ts.isTemplateExpression(node)))
+            return;
+        for (const match of stringText(ts, node).matchAll(REFERENCES)) {
+            counts.foreignKeys += 1;
+            const entity = tables.get(match[1].toLowerCase());
+            const targetContext = entity?.owner ? 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 });
+        }
+    });
 };
-
 const checkPersistenceFile = (scan, file) => {
-  if (file.slot !== 'be.persistence' || !file.owner) return;
-  const ownContext = scan.model.contextOfCapability(file.owner.root);
-  if (!ownContext) return;
-  if (path.posix.basename(file.rel).endsWith('.entity.ts')) checkRelations(scan, file, ownContext);
-  if (file.rel.slice(file.owner.root.length + 1).startsWith('persistence/migrations/')) checkForeignKeys(scan, file, ownContext);
+    if (file.slot !== 'be.persistence' || !file.owner)
+        return;
+    const ownContext = scan.model.contextOfCapability(file.owner.root);
+    if (!ownContext)
+        return;
+    if (path.posix.basename(file.rel).endsWith('.entity.ts'))
+        checkRelations(scan, file, ownContext);
+    if (file.rel.slice(file.owner.root.length + 1).startsWith('persistence/migrations/'))
+        checkForeignKeys(scan, file, ownContext);
 };
-
 export function checkContextCoupling(input) {
-  const { graph } = input;
-  const kit = machineKit(input);
-  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
-  const scan = { kit, model, tables, counts, covered, once };
-
-  for (const file of graph.files.values()) checkPersistenceFile(scan, file);
-
-  checkCrossContextImports(graph, model, covered, counts, once);
-  return { violations, coverage: { status: 'checked', ...counts } };
+    const { graph } = input;
+    const kit = machineKit(input);
+    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
+    const scan = { kit, model, tables, counts, covered, once };
+    for (const file of graph.files.values())
+        checkPersistenceFile(scan, file);
+    checkCrossContextImports(graph, model, covered, counts, once);
+    return { violations, coverage: { status: 'checked', ...counts } };
 }

package/runtime/scripts/hfs/architecture/context-map.d.mts

@@ -0,0 +1,102 @@
+import type { Node, TypeChecker } from 'typescript';
+import type { ArchitectureConfig } from './config.mjs';
+import type { ArchitectureViolation, CheckInput, GraphFile, HfsGraph } from './hfs-graph.mjs';
+import type { MachineKit } from './machine-ast.mjs';
+import type { TypeContext } from './type-context.mjs';
+/** The TypeScript reading kit `machineKit` builds for the machine checks. */
+export type { MachineKit };
+/** The slot resolver (config.hfs). */
+export type SlotResolver = ArchitectureConfig['hfs'];
+/** The TypeScript context (programs, source files, import edges) the checks read. */
+export type TypeScriptContext = TypeContext;
+/** What every HFS graph check receives: the layout config, the TypeScript context and the file and owner graph. */
+export type HfsCheckInput = CheckInput;
+/** What a check returns: its findings and how much of the program it could judge. */
+export interface CheckResult {
+    violations: ArchitectureViolation[];
+    coverage: {
+        status: string;
+        [detail: string]: unknown;
+    };
+}
+/** A source file of the program that a persistence array or a registration literal sits in, and the node there. */
+export interface RegistrationSite {
+    file: GraphFile;
+    node: Node;
+}
+/** A capability's persistence arrays as registered: its name and the connections it is registered on (first site each). */
+export interface RegisteredCapability {
+    name: string;
+    connections: Map<string, RegistrationSite>;
+}
+/** One registration literal of the program; `connection` is null when its name cannot be resolved. */
+export interface RegistrationLiteral extends RegistrationSite {
+    connection: string | null;
+}
+/** The persistence location of a be.persistence file: the persistence root, its capability, the folder below it and the path below the root. */
+export interface PersistenceInfo {
+    root: string;
+    capability: string;
+    folder: string;
+    below: string[];
+}
+/** What `collectRegistrations` reads: the kit, the graph and the persistence classifier. */
+export interface RegistrationInput {
+    kit: MachineKit;
+    graph: HfsGraph;
+    persistenceOf: (rel: string) => PersistenceInfo | null;
+}
+/** What `collectRegistrations` returns. */
+export interface RegistrationMap {
+    registered: Map<string, RegisteredCapability>;
+    registrations: number;
+    all: RegistrationLiteral[];
+}
+/** A declared connection of hfs.json. */
+export interface DeclaredConnection {
+    name: string;
+    owner: string;
+}
+/** The bounded-context model of a program. */
+export interface ContextModel {
+    declared: Map<string, DeclaredConnection>;
+    registered: Map<string, RegisteredCapability>;
+    registrations: RegistrationLiteral[];
+    perConnection: Set<string>;
+    contextOfCapability: (root: string) => string | null;
+    contextOfFile: (rel: string) => string | null;
+    connectionOfManager: (checker: TypeChecker, expression: Node) => string | null;
+    unparen: (node: Node) => Node | undefined;
+}
+/** A declared connection passed to the database module registration by an app's composition. */
+export interface ComposedConnection {
+    connection: string;
+    node: Node;
+    file: GraphFile;
+}
+/**
+ * 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 declare function collectRegistrations({ kit, graph, persistenceOf }: RegistrationInput): RegistrationMap;
+/** 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 declare const isPerConnection: (resolver: SlotResolver, root: string, name: string) => boolean;
+/**
+ * `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 declare const persistenceOfFactory: (resolver: SlotResolver) => (rel: string) => PersistenceInfo | null;
+export declare function contextModelOf(kit: MachineKit, graph: HfsGraph): ContextModel;
+/**
+ * The declared connection names the composition of `app` (its root app.module.ts and the composition groups of compose/) passes to
+ * the database module registration, as [{connection, node, file}] in path then source order.
+ */
+export declare function connectionsComposedBy(kit: MachineKit, app: string): {
+    root: GraphFile | null;
+    items: ComposedConnection[];
+};