@starci/hfs 4.0.10 → 4.2.0

package/runtime/scripts/hfs/architecture/register-once.mjs

@@ -1,6 +1,8 @@
 import path from 'node:path';
 import { machineKit } from './machine-ast.mjs';
+import { callName } from './supabase-ast.mjs';
 import { isTestWorldSlot } from '../test-world-slot.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 /**
  * R45 `register-once` (BE_MODULE_SHAPE), the module graph read from the app roots (owner rule of 2026-09-30, the
@@ -21,19 +23,7 @@ export const REGISTER_ONCE_RULE_IDS = ['BE_MODULE_SHAPE'];
 const RULE = 'BE_MODULE_SHAPE';
 const CAPABILITY_TIERS = new Set(['domain', 'platform', 'integrations']);
 
-export function checkRegisterOnce(input) {
-  const { config, graph } = input;
-  const kit = machineKit(input);
-  const { ts } = kit;
-  const violations = [];
-  const report = (file, node, message, extra = {}) => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message, ...extra });
-  const isAppRoot = file => Boolean(file.slot?.startsWith('be.app.')) && path.posix.basename(file.rel) === 'app.module.ts';
-  // The test world (slot be.tests.world) is the test composition root: useTestWorld registers capability modules with
-  // `isGlobal: true` the way an app root does. A spec (integration, contract, e2e) is not a composition root.
-  const isWorld = file => isTestWorldSlot(file.slot);
-  const appOf = file => config.apps.find(app => file.rel === `apps/${app.name}/src/app.module.ts`)?.name ?? null;
-
-  // Every @Module class of the program.
+function moduleDeclarations(graph, kit, ts) {
   const modules = new Map(); // declaration -> {name, file, capability}
   for (const file of graph.files.values()) {
     const checker = kit.checkerOf(file.sourceFile);
@@ -47,57 +37,81 @@ export function checkRegisterOnce(input) {
       if (isModule) modules.set(statement, { name: statement.name.text, file, capability: CAPABILITY_TIERS.has(file.tier) });
     }
   }
-  const targetOf = (checker, node) => {
-    for (const declaration of kit.declarationsOf(checker, node)) if (modules.has(declaration)) return { declaration, ...modules.get(declaration) };
-    return null;
-  };
-  const enclosingModule = node => {
-    for (let current = node.parent; current; current = current.parent) if (ts.isClassDeclaration(current) && modules.has(current)) return current;
-    return null;
-  };
+  return modules;
+}
+
+function targetOf(kit, modules, checker, node) {
+  for (const declaration of kit.declarationsOf(checker, node)) {
+    if (modules.has(declaration)) return { declaration, ...modules.get(declaration) };
+  }
+  return null;
+}
+
+function enclosingModule(ts, modules, node) {
+  for (let current = node.parent; current; current = current.parent) {
+    if (ts.isClassDeclaration(current) && modules.has(current)) return current;
+  }
+  return null;
+}
+
+/** Records the reference an element of an imports list, or a register call, makes to a module. */
+function noteReference(scan, element, viaImports) {
+  const { ts, kit, modules, checker, file, seen, references, isAppRoot } = scan;
+  const call = callName(ts, element) === 'register';
+  if (ts.isCallExpression(element) && !call) return;
+  const target = targetOf(kit, modules, checker, call ? element.expression.expression : element);
+  if (!target) return;
+  seen.add(element);
+  const owner = enclosingModule(ts, modules, element);
+  references.push({ file, node: element, target, register: call, viaImports, importer: owner ?? file.rel, importerOwner: file.owner?.root ?? null,
+    options: call ? element.arguments[0] : null, root: isAppRoot(file) });
+}
+
+const isImportsList = (scan, node) => scan.ts.isPropertyAssignment(node) && scan.kit.propertyNameText(node.name) === 'imports' && scan.ts.isArrayLiteralExpression(node.initializer);
+
+const isStrayGlobal = (scan, node) => scan.ts.isPropertyAssignment(node) && scan.kit.propertyNameText(node.name) === 'isGlobal'
+  && node.initializer.kind === scan.ts.SyntaxKind.TrueKeyword && !scan.isAppRoot(scan.file) && !scan.isWorld(scan.file);
 
+function visitReferenceNode(scan, node) {
+  if (isImportsList(scan, node)) {
+    for (const element of node.initializer.elements) noteReference(scan, element, true);
+  } else if (callName(scan.ts, node) === 'register' && !scan.seen.has(node)) {
+    noteReference(scan, node, false);
+  }
+  if (isStrayGlobal(scan, node)) {
+    scan.report(scan.file, node, '`isGlobal: true` appears only in the app root (apps/<app>/src/app.module.ts), where the representative module of a capability is registered; a module never decides its own globality.');
+  }
+  return true;
+}
+
+function moduleReferences(graph, kit, ts, modules, isWorld, isAppRoot, report) {
   // The references to modules: importer (the enclosing module class, else the file), target, node, whether it is a register call.
   const references = [];
   for (const file of graph.files.values()) {
     if (isWorld(file)) continue; // the test composition root assembles modules; it is not a module importer
-    const checker = kit.checkerOf(file.sourceFile);
-    const seen = new Set();
-    const note = (element, viaImports) => {
-      const call = ts.isCallExpression(element) && ts.isPropertyAccessExpression(element.expression) && element.expression.name.text === 'register';
-      if (ts.isCallExpression(element) && !call) return;
-      const target = targetOf(checker, call ? element.expression.expression : element);
-      if (!target) return;
-      seen.add(element);
-      const owner = enclosingModule(element);
-      references.push({ file, node: element, target, register: call, viaImports, importer: owner ?? file.rel, importerOwner: file.owner?.root ?? null,
-        options: call ? element.arguments[0] : null, root: isAppRoot(file) });
-    };
-    kit.walk(file.sourceFile, node => {
-      if (ts.isPropertyAssignment(node) && kit.propertyNameText(node.name) === 'imports' && ts.isArrayLiteralExpression(node.initializer)) {
-        for (const element of node.initializer.elements) note(element, true);
-      } else if (ts.isCallExpression(node) && !seen.has(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'register') {
-        note(node, false);
-      }
-      if (ts.isPropertyAssignment(node) && kit.propertyNameText(node.name) === 'isGlobal' && node.initializer.kind === ts.SyntaxKind.TrueKeyword && !isAppRoot(file) && !isWorld(file)) {
-        report(file, node, '`isGlobal: true` appears only in the app root (apps/<app>/src/app.module.ts), where the representative module of a capability is registered; a module never decides its own globality.');
-      }
-      return true;
-    });
+    const scan = { ts, kit, modules, file, isWorld, isAppRoot, report, references, checker: kit.checkerOf(file.sourceFile), seen: new Set() };
+    kit.walk(file.sourceFile, node => visitReferenceNode(scan, node));
   }
+  return references;
+}
 
-  const trueGlobal = options => Boolean(options) && ts.isObjectLiteralExpression(options) && (() => {
-    const property = kit.propertyOf(options, 'isGlobal');
-    return Boolean(property) && ts.isPropertyAssignment(property) && property.initializer.kind === ts.SyntaxKind.TrueKeyword;
-  })();
+function isTrueGlobal(kit, ts, options) {
+  if (!options || !ts.isObjectLiteralExpression(options)) return false;
+  const property = kit.propertyOf(options, 'isGlobal');
+  return Boolean(property) && ts.isPropertyAssignment(property) && property.initializer.kind === ts.SyntaxKind.TrueKeyword;
+}
 
-  // App roots: each module is listed once, capability modules are registered with isGlobal true.
-  const rootReferences = references.filter(item => item.root);
+function appRegistrations(rootReferences, appOf) {
   const inApps = new Map(); // module declaration -> Set(app names)
   for (const item of rootReferences) {
     const app = appOf(item.file) ?? item.file.rel;
     if (!inApps.has(item.target.declaration)) inApps.set(item.target.declaration, new Set());
     inApps.get(item.target.declaration).add(app);
   }
+  return inApps;
+}
+
+function reportDuplicateAppModules(config, rootReferences, appOf, report) {
   for (const app of config.apps) {
     const seenInApp = new Map();
     for (const item of rootReferences.filter(entry => appOf(entry.file) === app.name)) {
@@ -106,35 +120,70 @@ export function checkRegisterOnce(input) {
       } else seenInApp.set(item.target.declaration, item.node);
     }
   }
+}
+
+function reportCapabilityRegistrations(rootReferences, kit, ts, report) {
   for (const item of rootReferences) {
     if (!item.target.capability || !item.viaImports && !item.register) continue;
     if (!item.register) report(item.file, item.node, `${item.target.name} is listed in imports as a bare class; the representative module of a capability is registered in the app root as ${item.target.name}.register({ isGlobal: true, ...options }).`, { module: item.target.name });
-    else if (!trueGlobal(item.options)) report(item.file, item.node, `${item.target.name} is registered in the app root without the literal \`isGlobal: true\`; write ${item.target.name}.register({ isGlobal: true, ...options }).`, { module: item.target.name });
+    else if (!isTrueGlobal(kit, ts, item.options)) report(item.file, item.node, `${item.target.name} is registered in the app root without the literal \`isGlobal: true\`; write ${item.target.name}.register({ isGlobal: true, ...options }).`, { module: item.target.name });
   }
+}
 
-  // Non-app importers: no importer of an app-registered module, exactly one importer otherwise (the feature case excepted).
+/** The references that import a module from a non-app module, grouped by the imported module declaration. */
+function importersByModule(references) {
   const importersOf = new Map(); // module declaration -> [reference]
   for (const item of references.filter(entry => !entry.root && entry.viaImports)) {
     if (!importersOf.has(item.target.declaration)) importersOf.set(item.target.declaration, []);
     importersOf.get(item.target.declaration).push(item);
   }
-  for (const [declaration, list] of importersOf) {
+  return importersOf;
+}
+
+function reportSharedSubModule(target, list, report) {
+  const distinct = [...new Set(list.map(item => item.importer))];
+  const featureCase = target.file.tier === 'feature' && target.file.owner && list.every(item => item.importerOwner === target.file.owner.root);
+  if (distinct.length <= 1 || featureCase) return;
+  for (const item of list.filter(entry => entry.importer !== list[0].importer)) {
+    report(item.file, item.node, `${target.name} is imported by ${distinct.length} modules; a sub-module has exactly one importer, its parent. Another capability's module is consumed through its Inject*() decorators, never imported.`, { module: target.name });
+  }
+}
+
+function reportNonAppImporters(references, modules, inApps, report) {
+  // Non-app importers: no importer of an app-registered module, exactly one importer otherwise (the feature case excepted).
+  for (const [declaration, list] of importersByModule(references)) {
     const target = modules.get(declaration);
     const apps = inApps.get(declaration);
-    if (apps) {
-      for (const item of list) {
-        report(item.file, item.node, `${target.name} is registered in the root of app ${[...apps].sort().join(', ')}, so no other module imports it; consume it through its Inject*() decorators.`, { module: target.name });
-      }
+    if (!apps) {
+      reportSharedSubModule(target, list, report);
       continue;
     }
-    const distinct = [...new Set(list.map(item => item.importer))];
-    const featureCase = target.file.tier === 'feature' && target.file.owner && list.every(item => item.importerOwner === target.file.owner.root);
-    if (distinct.length > 1 && !featureCase) {
-      for (const item of list.filter(entry => entry.importer !== list[0].importer)) {
-        report(item.file, item.node, `${target.name} is imported by ${distinct.length} modules; a sub-module has exactly one importer, its parent. Another capability's module is consumed through its Inject*() decorators, never imported.`, { module: target.name });
-      }
+    for (const item of list) {
+      report(item.file, item.node, `${target.name} is registered in the root of app ${[...apps].sort(byCodeUnit).join(', ')}, so no other module imports it; consume it through its Inject*() decorators.`, { module: target.name });
     }
   }
+}
+
+export function checkRegisterOnce(input) {
+  const { config, graph } = input;
+  const kit = machineKit(input);
+  const { ts } = kit;
+  const violations = [];
+  const report = (file, node, message, extra = {}) => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message, ...extra });
+  const isAppRoot = file => Boolean(file.slot?.startsWith('be.app.')) && path.posix.basename(file.rel) === 'app.module.ts';
+  // The test world (slot be.tests.world) is the test composition root: useTestWorld registers capability modules with
+  // `isGlobal: true` the way an app root does. A spec (integration, contract, e2e) is not a composition root.
+  const isWorld = file => isTestWorldSlot(file.slot);
+  const appOf = file => config.apps.find(app => file.rel === `apps/${app.name}/src/app.module.ts`)?.name ?? null;
+  const modules = moduleDeclarations(graph, kit, ts);
+  const references = moduleReferences(graph, kit, ts, modules, isWorld, isAppRoot, report);
+  const rootReferences = references.filter(item => item.root);
+  const inApps = appRegistrations(rootReferences, appOf);
+
+  // App roots: each module is listed once, capability modules are registered with isGlobal true.
+  reportDuplicateAppModules(config, rootReferences, appOf, report);
+  reportCapabilityRegistrations(rootReferences, kit, ts, report);
+  reportNonAppImporters(references, modules, inApps, report);
 
   return { violations, coverage: { status: 'checked', apps: config.apps.filter(app => kit.appRoot(app.name)).length, modules: modules.size,
     capabilityModules: [...modules.values()].filter(item => item.capability).length, registrations: references.filter(item => item.register).length,

package/runtime/scripts/hfs/architecture/registration.mjs

@@ -1,8 +1,9 @@
 import path from 'node:path';
 import { canonical } from './config.mjs';
 import { referencedExports, relativePath, unwrapExpression } from './typescript.mjs';
-import { commonJsRequireReasons, decoratorCallee, moduleExportsOf, mutableDecoratorKind, normalizedSymbol, normalizedSymbolValue, programSourcesOf, selectedNode, valueSymbol } from './ast-walks.mjs';
+import { commonJsRequireReasons, decoratorCallee, moduleExportsOf, mutableDecoratorKind, programSourcesOf, selectedNode, valueSymbol } from './ast-walks.mjs';
 import { sourceLocation } from '../../lib/ts-ast.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 const REGISTRATION_RULE_IDS = ['BE_MODULE_HANDLER_REGISTRATION', 'BE_MODULE_PROVIDER_REREGISTRATION'];
 const FRAMEWORK = new Map([
@@ -27,28 +28,33 @@ const mutableFrameworkAlias = (ts, checker, decorator, targets) => {
   return mutableDecoratorKind(ts, checker, decorator, bySymbol);
 };
 
+function collectFrameworkStatement(config, context, checker, sourceFile, statement, targets, reasons) {
+  const bound = moduleExportsOf(context.ts, checker, statement);
+  if (!bound || ![...FRAMEWORK.values()].includes(bound.specifier)) return;
+  const expected = new Set([...FRAMEWORK].filter(([, packageName]) => packageName === bound.specifier).map(([name]) => name));
+  const selected = referencedExports(context.ts, statement, expected);
+  if (!selected.length) return;
+  if (!bound.symbol) {
+    reasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot resolve ${bound.specifier}`);
+    return;
+  }
+  for (const name of selected) {
+    const target = bound.exports.get(name);
+    if (!target) {
+      reasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot resolve ${name} from ${bound.specifier}`);
+      continue;
+    }
+    targets.set(name, target);
+  }
+}
+
 function frameworkTargets(config, context, checker, localFiles) {
   const targets = new Map();
   const reasons = [];
   const files = programSourcesOf(context, checker, localFiles);
   if (!files) return { targets, reasons: ['a TypeScript program checker could not be associated with its source'] };
   for (const sourceFile of files) {
-    for (const statement of sourceFile.statements) {
-      const bound = moduleExportsOf(context.ts, checker, statement);
-      if (!bound || ![...FRAMEWORK.values()].includes(bound.specifier)) continue;
-      const expected = new Set([...FRAMEWORK].filter(([, packageName]) => packageName === bound.specifier).map(([name]) => name));
-      const selected = referencedExports(context.ts, statement, expected);
-      if (!selected.length) continue;
-      if (!bound.symbol) {
-        reasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot resolve ${bound.specifier}`);
-        continue;
-      }
-      for (const name of selected) {
-        const target = bound.exports.get(name);
-        if (target) targets.set(name, target);
-        else reasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot resolve ${name} from ${bound.specifier}`);
-      }
-    }
+    for (const statement of sourceFile.statements) collectFrameworkStatement(config, context, checker, sourceFile, statement, targets, reasons);
     commonJsRequireReasons(context.ts, checker, sourceFile, (specifier) => [...FRAMEWORK.values()].includes(specifier),
       reasons, relativePath(config.root, sourceFile.fileName), 'whose decorator identity cannot be proved', 'Nest framework binding');
   }
@@ -73,28 +79,35 @@ function propertyName(ts, property) {
   return null;
 }
 
+function inspectTokenElement(ts, checker, element, localFiles, field, tokens) {
+  if (ts.isSpreadElement(element)) return true;
+  let key;
+  let node = element;
+  if (ts.isObjectLiteralExpression(element)) {
+    if (element.properties.some(property => ts.isSpreadAssignment(property))) return true;
+    const providers = element.properties.filter(property => propertyName(ts, property) === 'provide');
+    if (providers.length !== 1 || !ts.isPropertyAssignment(providers[0])) return true;
+    node = providers[0].initializer;
+    key = localClassKey(ts, checker, node, localFiles);
+  } else {
+    const token = classToken(ts, checker, element, localFiles);
+    key = token.key;
+    if (!key) return field === 'providers' && !token.external;
+  }
+  if (key) {
+    if (!tokens.has(key)) tokens.set(key, []);
+    tokens.get(key).push(node);
+  }
+  return false;
+}
+
 function tokenEntries(ts, checker, initializer, localFiles, field) {
   initializer = unwrapExpression(ts, initializer);
   if (!ts.isArrayLiteralExpression(initializer)) return { tokens: new Map(), unknown: true };
   const tokens = new Map();
   let unknown = false;
-  const add = (key, node) => {
-    if (!tokens.has(key)) tokens.set(key, []);
-    tokens.get(key).push(node);
-  };
   for (const element of initializer.elements) {
-    if (ts.isSpreadElement(element)) { unknown = true; continue; }
-    if (ts.isObjectLiteralExpression(element)) {
-      if (element.properties.some(property => ts.isSpreadAssignment(property))) { unknown = true; continue; }
-      const providers = element.properties.filter(property => propertyName(ts, property) === 'provide');
-      if (providers.length !== 1 || !ts.isPropertyAssignment(providers[0])) { unknown = true; continue; }
-      const key = localClassKey(ts, checker, providers[0].initializer, localFiles);
-      if (key) add(key, providers[0].initializer);
-      continue;
-    }
-    const token = classToken(ts, checker, element, localFiles);
-    if (token.key) add(token.key, element);
-    else if (field === 'providers' && !token.external) unknown = true;
+    if (inspectTokenElement(ts, checker, element, localFiles, field, tokens)) unknown = true;
   }
   return { tokens, unknown };
 }
@@ -131,114 +144,161 @@ function registrationFinding(module, node, ruleId, message, extra = {}) {
   return { ruleId, path: module.path, ...sourceLocation(node.getSourceFile(), node), module: module.name, message, ...extra };
 }
 
-/** A module belongs to an app only when its runtime source is reachable from that app's composition root. */
-function applicationGraphs(config, context, modules) {
-  const roots = modules.filter(module => /^apps\/[^/]+\/src\/app\.module\.ts$/.test(module.path))
-    .sort((a, b) => a.path.localeCompare(b.path));
-  // Small architecture fixtures without app composition retain the original single-graph relation.
-  if (!roots.length) return [modules];
+const modulesByFileOf = (config, modules) => {
   const byFile = new Map();
   for (const module of modules) {
     const file = canonical(path.resolve(config.root, ...module.path.split('/')));
     if (!byFile.has(file)) byFile.set(file, []);
     byFile.get(file).push(module);
   }
-  const bound = new Set();
-  const graphs = roots.map(root => {
-    const queue = [canonical(path.resolve(config.root, ...root.path.split('/')))];
-    const seen = new Set();
-    const reachable = [];
-    for (let index = 0; index < queue.length; index += 1) {
-      const file = queue[index];
-      if (seen.has(file)) continue;
-      seen.add(file);
-      for (const module of byFile.get(file) ?? []) {
-        reachable.push(module);
-        bound.add(module);
-      }
-      for (const edge of context.edges.get(file) ?? []) if (edge.runtime && !seen.has(edge.to)) queue.push(edge.to);
+  return byFile;
+};
+
+/** The modules whose file the runtime import edges reach from `rootFile`, in first-visit order; each is added to `bound`. */
+const reachableModules = (context, byFile, rootFile, bound) => {
+  const queue = [rootFile];
+  const seen = new Set();
+  const reachable = [];
+  for (const file of queue) {
+    if (seen.has(file)) continue;
+    seen.add(file);
+    for (const module of byFile.get(file) ?? []) {
+      reachable.push(module);
+      bound.add(module);
     }
-    return reachable;
-  });
+    for (const edge of context.edges.get(file) ?? []) if (edge.runtime && !seen.has(edge.to)) queue.push(edge.to);
+  }
+  return reachable;
+};
+
+/** A module belongs to an app only when its runtime source is reachable from that app's composition root. */
+function applicationGraphs(config, context, modules) {
+  const roots = modules.filter(module => /^apps\/[^/]+\/src\/app\.module\.ts$/.test(module.path))
+    .sort((a, b) => a.path.localeCompare(b.path));
+  // Small architecture fixtures without app composition retain the original single-graph relation.
+  if (!roots.length) return [modules];
+  const byFile = modulesByFileOf(config, modules);
+  const bound = new Set();
+  const graphs = roots.map(root => reachableModules(context, byFile, canonical(path.resolve(config.root, ...root.path.split('/'))), bound));
   // A module outside every proven app graph can still contain a duplicate in its own metadata.
   return [...graphs, ...modules.filter(module => !bound.has(module)).map(module => [module])];
 }
 
-/** Prove only static exported class-token identity and selected CQRS handler registration. */
-export function checkModuleRegistration(config, context) {
-  const selected = config.backend.moduleRegistration;
-  if (!selected) return { violations: [], coverage: { status: 'unavailable', reason: 'architecture.json does not select Nest module-registration identity checks' } };
-  const ts = context.ts;
-  const localFiles = new Set(context.files.map(file => canonical(file.fileName)));
+function decoratorKinds(ts, checker, node, framework) {
+  const decorators = ts.canHaveDecorators(node) ? ts.getDecorators(node) ?? [] : node.decorators ?? [];
+  return decorators.map(decorator => ({ decorator, kind: frameworkDecorator(ts, checker, decorator, framework.targets) }));
+}
+
+function recordMutableDecoratorReasons(config, ts, checker, sourceFile, kinds, framework, reasons) {
+  for (const { decorator, kind } of kinds) {
+    const dynamic = kind ? null : mutableFrameworkAlias(ts, checker, decorator, framework.targets);
+    if (dynamic) reasons.push(`${relativePath(config.root, sourceFile.fileName)} uses mutable ${dynamic} decorator identity`);
+  }
+}
+
+function recordModuleDecorator(site, node, kinds, found) {
+  const { config, context, sourceFile, checker, localFiles } = site;
+  const { modules, reasons } = found;
+  const moduleDecorators = kinds.filter(item => item.kind === 'Module');
+  if (moduleDecorators.length === 1) modules.push(moduleRecord(config, context, sourceFile, node, moduleDecorators[0].decorator, checker, localFiles));
+  else if (moduleDecorators.length > 1) reasons.push(`${relativePath(config.root, sourceFile.fileName)} has multiple resolved @Module decorators`);
+}
+
+function recordHandlerDecorator(site, node, kinds, found) {
+  const { config, context, sourceFile, checker, localFiles } = site;
+  const { handlers, reasons } = found;
+  const { ts } = context;
+  const handlerDecorators = kinds.filter(item => item.kind === 'CommandHandler' || item.kind === 'QueryHandler');
+  if (handlerDecorators.length === 1) handlers.push({
+    key: node.name ? localClassKey(ts, checker, node.name, localFiles) : null,
+    name: node.name?.text ?? '(anonymous)',
+    kind: handlerDecorators[0].kind,
+    path: relativePath(config.root, sourceFile.fileName),
+    ...sourceLocation(sourceFile, node.name ?? node),
+  });
+  else if (handlerDecorators.length > 1) reasons.push(`${relativePath(config.root, sourceFile.fileName)} has multiple resolved CQRS handler decorators`);
+}
+
+function inspectRegistrationClass(site, node, found) {
+  const { config, context, sourceFile, checker, framework } = site;
+  const { ts } = context;
+  if (!ts.isClassDeclaration(node)) return;
+  const kinds = decoratorKinds(ts, checker, node, framework);
+  recordMutableDecoratorReasons(config, ts, checker, sourceFile, kinds, framework, found.reasons);
+  recordModuleDecorator(site, node, kinds, found);
+  recordHandlerDecorator(site, node, kinds, found);
+}
+
+function discoverRegistrations(config, context, localFiles) {
   const modules = [];
   const handlers = [];
   const reasons = [];
+  const found = { modules, handlers, reasons };
   const frameworkByChecker = new Map();
   for (const sourceFile of context.files) {
     const checker = context.checkerFor(sourceFile.fileName);
     if (!frameworkByChecker.has(checker)) frameworkByChecker.set(checker, frameworkTargets(config, context, checker, localFiles));
     const framework = frameworkByChecker.get(checker);
     reasons.push(...framework.reasons);
+    const site = { config, context, sourceFile, checker, localFiles, framework };
     const visit = node => {
-      if (ts.isClassDeclaration(node)) {
-        const decorators = ts.canHaveDecorators(node) ? ts.getDecorators(node) ?? [] : node.decorators ?? [];
-        const kinds = decorators.map(decorator => ({ decorator, kind: frameworkDecorator(ts, checker, decorator, framework.targets) }));
-        const recognized = kinds.filter(item => item.kind);
-        for (const { decorator, kind } of kinds) {
-          const dynamic = kind ? null : mutableFrameworkAlias(ts, checker, decorator, framework.targets);
-          if (dynamic) reasons.push(`${relativePath(config.root, sourceFile.fileName)} uses mutable ${dynamic} decorator identity`);
-        }
-        const moduleDecorators = recognized.filter(item => item.kind === 'Module');
-        if (moduleDecorators.length === 1) modules.push(moduleRecord(config, context, sourceFile, node, moduleDecorators[0].decorator, checker, localFiles));
-        else if (moduleDecorators.length > 1) reasons.push(`${relativePath(config.root, sourceFile.fileName)} has multiple resolved @Module decorators`);
-        const handlerDecorators = recognized.filter(item => item.kind === 'CommandHandler' || item.kind === 'QueryHandler');
-        if (handlerDecorators.length === 1) handlers.push({
-          key: node.name ? localClassKey(ts, checker, node.name, localFiles) : null,
-          name: node.name?.text ?? '(anonymous)',
-          kind: handlerDecorators[0].kind,
-          path: relativePath(config.root, sourceFile.fileName),
-          ...sourceLocation(sourceFile, node.name ?? node),
-        });
-        else if (handlerDecorators.length > 1) reasons.push(`${relativePath(config.root, sourceFile.fileName)} has multiple resolved CQRS handler decorators`);
-      }
-      ts.forEachChild(node, visit);
+      inspectRegistrationClass(site, node, found);
+      context.ts.forEachChild(node, visit);
     };
     visit(sourceFile);
   }
-  for (const module of modules) if (module.unknown) reasons.push(`${module.path} has dynamic or unresolvable @Module providers/exports metadata`);
-  for (const handler of handlers) {
-    if (!handler.key) reasons.push(`${handler.path} handler class identity is not resolvable`);
-    if (!selected.handlerDecorators.includes(handler.kind)) reasons.push(`${handler.path} uses unselected ${handler.kind}`);
-  }
-  const violations = [];
+  return { modules, handlers, reasons };
+}
+
+function providerOwnersOf(modules) {
   const providerOwners = new Map();
-  for (const module of modules) for (const key of module.providers.keys()) if (module.exports.has(key)) {
-    if (!providerOwners.has(key)) providerOwners.set(key, []);
-    providerOwners.get(key).push(module);
+  for (const module of modules) {
+    for (const key of module.providers.keys()) {
+      if (!module.exports.has(key)) continue;
+      if (!providerOwners.has(key)) providerOwners.set(key, []);
+      providerOwners.get(key).push(module);
+    }
   }
+  return providerOwners;
+}
+
+const byModulePath = (a, b) => a.module.path.localeCompare(b.module.path) || a.node.getStart() - b.node.getStart();
+
+/** The registrations of `key` in a graph that follow the first one of its owner module: the owner registers it once, every other is a duplicate. */
+const duplicateRegistrations = (graph, key, owner) => {
+  const registrations = graph.flatMap(module => (module.providers.get(key) ?? []).map(node => ({ module, node })))
+    .sort(byModulePath);
+  let keptOwnerRegistration = false;
+  return registrations.filter(registration => {
+    if (registration.module !== owner || keptOwnerRegistration) return true;
+    keptOwnerRegistration = true;
+    return false;
+  });
+};
+
+function reregistrationViolations(config, context, modules, providerOwners) {
+  const violations = [];
   const reportedRegistrations = new Set();
+  const report = (key, owner, duplicate) => {
+    const identity = `${key}\0${duplicate.module.path}\0${duplicate.node.getStart()}`;
+    if (reportedRegistrations.has(identity)) return;
+    reportedRegistrations.add(identity);
+    violations.push(registrationFinding(duplicate.module, duplicate.node,
+      'BE_MODULE_PROVIDER_REREGISTRATION',
+      `Class-token provider exported by ${owner.name} is registered again by ${duplicate.module.name} in one application graph; import the owning module and preserve one class-token registration.`,
+      { ownerModule: owner.name, ownerPath: owner.path }));
+  };
   for (const graph of applicationGraphs(config, context, modules)) for (const [key] of providerOwners) {
     const owners = graph.filter(module => module.providers.has(key) && module.exports.has(key))
       .sort((a, b) => a.path.localeCompare(b.path));
     if (!owners.length) continue;
-    const owner = owners[0];
-    const registrations = graph.flatMap(module => (module.providers.get(key) ?? []).map(node => ({ module, node })))
-      .sort((a, b) => a.module.path.localeCompare(b.module.path) || a.node.getStart() - b.node.getStart());
-    let keptOwnerRegistration = false;
-    for (const duplicate of registrations.filter(registration => {
-      if (registration.module !== owner || keptOwnerRegistration) return true;
-      keptOwnerRegistration = true;
-      return false;
-    })) {
-      const identity = `${key}\0${duplicate.module.path}\0${duplicate.node.getStart()}`;
-      if (reportedRegistrations.has(identity)) continue;
-      reportedRegistrations.add(identity);
-      violations.push(registrationFinding(duplicate.module, duplicate.node,
-        'BE_MODULE_PROVIDER_REREGISTRATION',
-        `Class-token provider exported by ${owner.name} is registered again by ${duplicate.module.name} in one application graph; import the owning module and preserve one class-token registration.`,
-        { ownerModule: owner.name, ownerPath: owner.path }));
-    }
+    for (const duplicate of duplicateRegistrations(graph, key, owners[0])) report(key, owners[0], duplicate);
   }
+  return violations;
+}
+
+function handlerRegistrationViolations(modules, handlers, selected) {
+  const violations = [];
   for (const handler of handlers.filter(item => item.key && selected.handlerDecorators.includes(item.kind))) {
     const registrations = modules.flatMap(module => (module.providers.get(handler.key) ?? []).map(node => ({ module, node })));
     if (registrations.length !== 1) violations.push({
@@ -251,8 +311,25 @@ export function checkModuleRegistration(config, context) {
         ...sourceLocation(registration.node.getSourceFile(), registration.node) })),
     });
   }
+  return violations;
+}
+
+/** Prove only static exported class-token identity and selected CQRS handler registration. */
+export function checkModuleRegistration(config, context) {
+  const selected = config.backend.moduleRegistration;
+  if (!selected) return { violations: [], coverage: { status: 'unavailable', reason: 'hfs.json does not select Nest module-registration identity checks' } };
+  const localFiles = new Set(context.files.map(file => canonical(file.fileName)));
+  const { modules, handlers, reasons } = discoverRegistrations(config, context, localFiles);
+  for (const module of modules) if (module.unknown) reasons.push(`${module.path} has dynamic or unresolvable @Module providers/exports metadata`);
+  for (const handler of handlers) {
+    if (!handler.key) reasons.push(`${handler.path} handler class identity is not resolvable`);
+    if (!selected.handlerDecorators.includes(handler.kind)) reasons.push(`${handler.path} uses unselected ${handler.kind}`);
+  }
+  const providerOwners = providerOwnersOf(modules);
+  const violations = reregistrationViolations(config, context, modules, providerOwners);
+  violations.push(...handlerRegistrationViolations(modules, handlers, selected));
   const coverage = reasons.length
-    ? { status: 'unavailable', reason: 'one or more Nest module-registration relations are not statically provable', details: [...new Set(reasons)].sort() }
+    ? { status: 'unavailable', reason: 'one or more Nest module-registration relations are not statically provable', details: [...new Set(reasons)].sort(byCodeUnit) }
     : { status: 'checked', modules: modules.length, exportedClassTokenProviders: providerOwners.size, handlers: handlers.length,
       selectedHandlerDecorators: selected.handlerDecorators };
   return { violations, coverage };