@starci/hfs 4.0.8 → 4.0.10

package/runtime/scripts/hfs/architecture/next-data.mjs

@@ -1,7 +1,9 @@
 import path from 'node:path';
 import { canonical, isInside } from './config.mjs';
 import { parseContract, installedSWR } from './next-data-contract.mjs';
-import { relativePath, sourceLocation, unwrapExpression } from './typescript.mjs';
+import { relativePath, unwrapExpression } from './typescript.mjs';
+import { anyDescendant, normalizedSymbol, normalizedSymbolValue, selectedNode, valueSymbol as sharedValueSymbol } from './ast-walks.mjs';
+import { sourceLocation } from '../../lib/ts-ast.mjs';
 
 export const SWR_KEY_RULE_ID = 'FE_SWR_KEY_IDENTITY';
 export const SWR_MUTATION_RULE_ID = 'FE_SWR_MUTATION_RESOURCE_IDENTITY';
@@ -9,41 +11,9 @@ export const SWR_DATA_RULE_IDS = [SWR_KEY_RULE_ID, SWR_MUTATION_RULE_ID];
 
 const SWR_SPECIFIERS = new Set(['swr', 'swr/immutable', 'swr/mutation']);
 
-function normalizedSymbol(ts, checker, value) {
-  let symbol = value ?? null;
-  const seen = new Set();
-  while (symbol && (symbol.flags & ts.SymbolFlags.Alias) && !seen.has(symbol)) {
-    seen.add(symbol);
-    const target = checker.getAliasedSymbol(symbol);
-    if (!target || target === symbol) break;
-    symbol = target;
-  }
-  return symbol;
-}
-
-function selectedNode(ts, expression) {
-  expression = unwrapExpression(ts, expression);
-  if (ts.isIdentifier(expression)) return expression;
-  if (ts.isPropertyAccessExpression(expression)) return expression.name;
-  if (ts.isElementAccessExpression(expression) && ts.isStringLiteralLike(expression.argumentExpression)) return expression.argumentExpression;
-  return null;
-}
-
-function symbolAt(ts, checker, node) {
-  return normalizedSymbol(ts, checker, checker.getSymbolAtLocation(node));
-}
-
-function valueSymbol(ts, checker, expression, seen = new Set()) {
-  const selected = selectedNode(ts, expression);
-  const symbol = selected ? symbolAt(ts, checker, selected) : null;
-  if (!symbol || seen.has(symbol)) return symbol;
-  const declarations = symbol.getDeclarations?.() ?? [];
-  if (declarations.length === 1 && ts.isVariableDeclaration(declarations[0]) && declarations[0].initializer
-    && (ts.getCombinedNodeFlags(declarations[0].parent) & ts.NodeFlags.Const)) {
-    return valueSymbol(ts, checker, declarations[0].initializer, new Set(seen).add(symbol));
-  }
-  return symbol;
-}
+/* null when the expression selects no name at all (the shared default traces the unselected node itself). */
+const valueSymbol = (ts, checker, expression, seen = new Set()) =>
+  sharedValueSymbol(ts, checker, expression, seen, { unselected: 'null' });
 
 function declarationsInside(symbol, root) {
   const declarations = symbol?.getDeclarations?.() ?? [];
@@ -70,7 +40,7 @@ function officialTargets(config, context, installed, reasons) {
         reasons.push(`${relativePath(config.root, source.fileName)} cannot resolve ${statement.moduleSpecifier.text} through the target TypeScript program`);
         continue;
       }
-      const exports = new Map(checker.getExportsOfModule(moduleSymbol).map(symbol => [symbol.getName(), normalizedSymbol(context.ts, checker, symbol)]));
+      const exports = new Map(checker.getExportsOfModule(moduleSymbol).map(symbol => [symbol.getName(), normalizedSymbolValue(context.ts, checker, symbol)]));
       for (const [name, kind] of selected) {
         const target = exports.get(name);
         if (!target) continue;
@@ -136,7 +106,7 @@ function configMutateSymbols(config, context, targets) {
         for (const element of node.name.elements) {
           const property = element.propertyName && context.ts.isIdentifier(element.propertyName) ? element.propertyName.text
             : context.ts.isIdentifier(element.name) ? element.name.text : null;
-          if (property === 'mutate' && context.ts.isIdentifier(element.name)) symbols.add(symbolAt(context.ts, checker, element.name));
+          if (property === 'mutate' && context.ts.isIdentifier(element.name)) symbols.add(normalizedSymbol(context.ts, checker, element.name));
         }
       }
       context.ts.forEachChild(node, visit);
@@ -181,7 +151,7 @@ function exportedHook(config, context, entry, reasons) {
   const checker = context.checkerFor(source.fileName);
   const moduleSymbol = checker.getSymbolAtLocation(source);
   const exported = moduleSymbol ? checker.getExportsOfModule(moduleSymbol).find(symbol => symbol.getName() === entry.export) : null;
-  const symbol = normalizedSymbol(context.ts, checker, exported);
+  const symbol = normalizedSymbolValue(context.ts, checker, exported);
   const declarations = (symbol?.getDeclarations?.() ?? []).filter(declaration => canonical(declaration.getSourceFile().fileName) === canonical(source.fileName));
   const functions = declarations.map(declaration => functionNode(context.ts, declaration)).filter(Boolean);
   if (functions.length !== 1) {
@@ -195,7 +165,7 @@ function bindingSymbols(ts, checker, fn) {
   const found = new Map();
   const addName = name => {
     if (ts.isIdentifier(name)) {
-      const symbol = symbolAt(ts, checker, name);
+      const symbol = normalizedSymbol(ts, checker, name);
       if (symbol) {
         if (!found.has(name.text)) found.set(name.text, new Set());
         found.get(name.text).add(symbol);
@@ -233,7 +203,7 @@ function resolvedIdentities(ts, checker, fn, entry, reasons) {
 
 function accessPath(ts, checker, node) {
   node = unwrapExpression(ts, node);
-  if (ts.isIdentifier(node)) return { symbol: symbolAt(ts, checker, node), parts: [node.text] };
+  if (ts.isIdentifier(node)) return { symbol: normalizedSymbol(ts, checker, node), parts: [node.text] };
   if (ts.isPropertyAccessExpression(node)) {
     const base = accessPath(ts, checker, node.expression);
     return base ? { symbol: base.symbol, parts: [...base.parts, node.name.text] } : null;
@@ -249,7 +219,7 @@ function expandedAccessPath(ts, checker, node, seen = new Set(), depth = 0) {
   if (!node || depth > 10) return null;
   node = unwrapExpression(ts, node);
   if (ts.isIdentifier(node)) {
-    const symbol = symbolAt(ts, checker, node);
+    const symbol = normalizedSymbol(ts, checker, node);
     if (!symbol || seen.has(symbol)) return symbol ? { symbol, parts: [node.text] } : null;
     const initializer = constInitializer(ts, symbol);
     return initializer ? expandedAccessPath(ts, checker, initializer, new Set(seen).add(symbol), depth + 1)
@@ -272,19 +242,8 @@ function matchesIdentityAccess(ts, checker, node, identity) {
   return matches(accessPath(ts, checker, node)) || matches(expandedAccessPath(ts, checker, node));
 }
 
-function expressionReferences(ts, checker, expression, identity) {
-  let found = false;
-  const visit = node => {
-    if (found) return;
-    if (matchesIdentityAccess(ts, checker, node, identity)) {
-      found = true;
-      return;
-    }
-    ts.forEachChild(node, visit);
-  };
-  visit(expression);
-  return found;
-}
+const expressionReferences = (ts, checker, expression, identity) =>
+  anyDescendant(ts, expression, (node) => matchesIdentityAccess(ts, checker, node, identity));
 
 function constInitializer(ts, symbol) {
   const declarations = symbol?.getDeclarations?.() ?? [];
@@ -316,7 +275,7 @@ function identityContribution(ts, checker, expression, identity, seen = new Set(
   expression = unwrapExpression(ts, expression);
   if (matchesIdentityAccess(ts, checker, expression, identity)) return 'yes';
   if (ts.isIdentifier(expression)) {
-    const symbol = symbolAt(ts, checker, expression);
+    const symbol = normalizedSymbol(ts, checker, expression);
     if (!symbol || seen.has(symbol)) return 'no';
     const initializer = constInitializer(ts, symbol);
     return initializer ? identityContribution(ts, checker, initializer, identity, new Set(seen).add(symbol), depth + 1) : 'no';
@@ -378,8 +337,8 @@ function rootKeyExpression(ts, checker, expression, identities, seen = new Set()
     const returned = returnedExpression(ts, expression);
     return returned ? rootKeyExpression(ts, checker, returned, identities, seen, depth + 1) : null;
   }
-  if (ts.isIdentifier(expression) && !identities.some(identity => identity.symbol === symbolAt(ts, checker, expression))) {
-    const symbol = symbolAt(ts, checker, expression);
+  if (ts.isIdentifier(expression) && !identities.some(identity => identity.symbol === normalizedSymbol(ts, checker, expression))) {
+    const symbol = normalizedSymbol(ts, checker, expression);
     if (symbol && !seen.has(symbol)) {
       const declarations = symbol.getDeclarations?.() ?? [];
       if (declarations.length === 1 && ts.isVariableDeclaration(declarations[0]) && declarations[0].initializer
@@ -417,8 +376,8 @@ function staticKeyExpression(ts, checker, expression, identities, seen = new Set
     return false;
   }
   if (ts.isIdentifier(expression)) {
-    if (expression.text === 'undefined' || identities.some(identity => identity.symbol === symbolAt(ts, checker, expression))) return true;
-    const symbol = symbolAt(ts, checker, expression);
+    if (expression.text === 'undefined' || identities.some(identity => identity.symbol === normalizedSymbol(ts, checker, expression))) return true;
+    const symbol = normalizedSymbol(ts, checker, expression);
     if (!symbol || seen.has(symbol)) return false;
     const declarations = symbol.getDeclarations?.() ?? [];
     if (declarations.length !== 1 || !ts.isVariableDeclaration(declarations[0]) || !declarations[0].initializer
@@ -494,7 +453,7 @@ function isUnshadowedCommonJsRequire(ts, checker, expression, seen = new Set(),
 
 function symbolOfRequireAlias(ts, checker, expression) {
   const symbol = checker.getSymbolAtLocation(expression);
-  return normalizedSymbol(ts, checker, symbol);
+  return normalizedSymbolValue(ts, checker, symbol);
 }
 
 function swrReferences(config, context) {
@@ -535,7 +494,7 @@ function containerSymbolsFromKey(ts, checker, expression, found = new Set(), see
   if (!expression || depth > 12) return found;
   expression = unwrapExpression(ts, expression);
   if (ts.isIdentifier(expression)) {
-    const symbol = symbolAt(ts, checker, expression);
+    const symbol = normalizedSymbol(ts, checker, expression);
     if (!symbol || seen.has(symbol)) return found;
     const initializer = constInitializer(ts, symbol);
     if (!initializer) return found;
@@ -555,7 +514,7 @@ function keyContainerRisks(ts, checker, key, owner) {
     .filter(ts.isVariableDeclaration).map(declaration => declaration.name)));
   const risks = [];
   const visit = node => {
-    if (ts.isIdentifier(node) && symbols.has(symbolAt(ts, checker, node)) && !declarationNames.has(node)
+    if (ts.isIdentifier(node) && symbols.has(normalizedSymbol(ts, checker, node)) && !declarationNames.has(node)
       && !(node.pos >= key.pos && node.end <= key.end)) risks.push(node);
     ts.forEachChild(node, visit);
   };

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

@@ -1,19 +1,29 @@
 import path from 'node:path';
 import { canonical, isInside } from './config.mjs';
-import { relativePath, sourceLocation, workspaceExportSources } from './typescript.mjs';
+import { relativePath, workspaceExportSources } from './typescript.mjs';
+import { sourceLocation } from '../../lib/ts-ast.mjs';
+import { isServerActionModule } from './server-action.mjs';
 
 function absolute(root, relative) {
   return canonical(path.resolve(root, ...relative.split('/')));
 }
 
-/** The owner's public entries: its declared entry, plus every source file its package.json `exports` maps when the owner is a workspace package. */
+/** The extra public entries the slot manifest declares for the owner (slot field `entries`, on the slot that holds its entry file), as absolute paths. */
+function slotEntries(config, owner) {
+  const found = config.hfs?.classifyPath?.(owner.entry);
+  const names = found?.slot ? config.hfs.slot(found.slot)?.entries ?? [] : [];
+  return names.map(name => absolute(config.root, `${found.root}/${name}`));
+}
+
+/** The owner's public entries: its declared entry, the `entries` its slot declares, plus every source file its package.json `exports` maps when the owner is a workspace package. */
 function ownerDeclarations(config, context) {
   return config.owners.map(owner => {
     const root = absolute(config.root, owner.root);
     const entry = absolute(config.root, owner.entry);
     const workspace = context.workspaces?.find(item => item.root === root);
-    const entries = new Set([entry, ...(workspace ? workspaceExportSources(context.ts, workspace) : [])]);
-    return { ...owner, root, entry, entries };
+    const declared = slotEntries(config, owner);
+    const entries = new Set([entry, ...declared, ...(workspace ? workspaceExportSources(context.ts, workspace) : [])]);
+    return { ...owner, root, entry, entries, declared };
   }).sort((a, b) => b.root.length - a.root.length);
 }
 
@@ -21,7 +31,7 @@ function ownerOf(owners, file) {
   return owners.find(owner => isInside(owner.root, file)) ?? null;
 }
 
-function privateOwnerChain(context, owners, edge) {
+function privateOwnerChain(context, owners, actionEntries, edge) {
   const sourceOwner = ownerOf(owners, edge.from);
   const queue = [{ file: edge.to, chain: [edge.from, edge.to] }];
   const visited = new Set();
@@ -30,7 +40,7 @@ function privateOwnerChain(context, owners, edge) {
     if (visited.has(current.file)) continue;
     visited.add(current.file);
     const owner = ownerOf(owners, current.file);
-    if (owner && sourceOwner?.id !== owner.id) return owner.entries.has(current.file) ? null : { owner, chain: current.chain };
+    if (owner && sourceOwner?.id !== owner.id) return owner.entries.has(current.file) || actionEntries.has(current.file) ? null : { owner, chain: current.chain };
     for (const candidate of context.edges.get(current.file) ?? []) if (candidate.reexport) {
       queue.push({ file: candidate.to, chain: [...current.chain, candidate.to] });
     }
@@ -55,6 +65,9 @@ export function checkOwners(config, context) {
   const owners = ownerDeclarations(config, context);
   const violations = [];
   const sourceFiles = new Map(context.files.map(file => [canonical(file.fileName), file]));
+  const actionEntries = new Set(config.kinds.includes('frontend')
+    ? [...sourceFiles].filter(([, file]) => isServerActionModule(context.ts, file)).map(([name]) => name)
+    : []);
   for (const owner of owners) {
     const sourceFile = sourceFiles.get(owner.entry);
     if (!sourceFile) {
@@ -62,20 +75,27 @@ export function checkOwners(config, context) {
         message: `Owner ${owner.id} public entry is outside the configured TypeScript programs, so its boundary cannot be checked.` });
       continue;
     }
-    for (const statement of sourceFile.statements) if (context.ts.isExportDeclaration(statement) && !statement.exportClause) {
-      violations.push({
-        ruleId: 'ARCH_OWNER_EXPORT_STAR',
-        path: relativePath(config.root, owner.entry),
-        ...sourceLocation(sourceFile, statement),
-        owner: owner.id,
-        message: `Owner ${owner.id} public entry must use explicit named exports rather than export *.`
-      });
+    const publicFiles = new Set([
+      sourceFile,
+      ...owner.declared.map(file => sourceFiles.get(file)).filter(Boolean),
+      ...[...actionEntries].filter(file => isInside(owner.root, file)).map(file => sourceFiles.get(file)).filter(Boolean),
+    ]);
+    for (const entryFile of publicFiles) {
+      for (const statement of entryFile.statements) if (context.ts.isExportDeclaration(statement) && !statement.exportClause) {
+        violations.push({
+          ruleId: 'ARCH_OWNER_EXPORT_STAR',
+          path: relativePath(config.root, canonical(entryFile.fileName)),
+          ...sourceLocation(entryFile, statement),
+          owner: owner.id,
+          message: `Owner ${owner.id} public entry must use explicit named exports rather than export *.`
+        });
+      }
     }
   }
   for (const sourceFile of context.files) {
     const from = canonical(sourceFile.fileName);
     for (const edge of context.edges.get(from) ?? []) {
-      const bypass = privateOwnerChain(context, owners, edge);
+      const bypass = privateOwnerChain(context, owners, actionEntries, edge);
       if (!bypass) continue;
       if (arrangesSchema(config, from, bypass.chain.at(-1))) continue;
       violations.push({

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

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { machineKit } from './machine-ast.mjs';
+import { isTestWorldSlot } from '../test-world-slot.mjs';
 
 /**
  * R45 `register-once` (BE_MODULE_SHAPE), the module graph read from the app roots (owner rule of 2026-09-30, the
@@ -29,7 +30,7 @@ export function checkRegisterOnce(input) {
   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 => file.slot === 'be.tests.world';
+  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.

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

@@ -1,6 +1,8 @@
 import path from 'node:path';
 import { canonical } from './config.mjs';
-import { isUnshadowedCommonJsRequire, referencedExports, relativePath, sourceLocation, unwrapExpression } from './typescript.mjs';
+import { referencedExports, relativePath, unwrapExpression } from './typescript.mjs';
+import { commonJsRequireReasons, decoratorCallee, moduleExportsOf, mutableDecoratorKind, normalizedSymbol, normalizedSymbolValue, programSourcesOf, selectedNode, valueSymbol } from './ast-walks.mjs';
+import { sourceLocation } from '../../lib/ts-ast.mjs';
 
 const REGISTRATION_RULE_IDS = ['BE_MODULE_HANDLER_REGISTRATION', 'BE_MODULE_PROVIDER_REREGISTRATION'];
 const FRAMEWORK = new Map([
@@ -9,106 +11,46 @@ const FRAMEWORK = new Map([
   ['QueryHandler', '@nestjs/cqrs'],
 ]);
 
-function normalizedSymbolValue(ts, checker, value) {
-  let symbol = value ?? null;
-  const seen = new Set();
-  while (symbol && (symbol.flags & ts.SymbolFlags.Alias) && !seen.has(symbol)) {
-    seen.add(symbol);
-    const target = checker.getAliasedSymbol(symbol);
-    if (!target || target === symbol) break;
-    symbol = target;
-  }
-  return symbol;
-}
-
-function normalizedSymbol(ts, checker, node) {
-  return normalizedSymbolValue(ts, checker, checker?.getSymbolAtLocation(node) ?? null);
-}
-
-function valueSymbol(ts, checker, node, seen = new Set()) {
-  const selected = selectedNode(ts, node) ?? node;
-  const symbol = normalizedSymbol(ts, checker, selected);
-  if (!symbol || seen.has(symbol)) return symbol;
-  seen.add(symbol);
-  const declarations = symbol.getDeclarations?.() ?? [];
-  if (declarations.length === 1 && ts.isVariableDeclaration(declarations[0]) && declarations[0].initializer
-    && (ts.getCombinedNodeFlags(declarations[0].parent) & ts.NodeFlags.Const)) {
-    return valueSymbol(ts, checker, declarations[0].initializer, seen);
-  }
-  return symbol;
-}
-
-function calledExpression(ts, decorator) {
-  const expression = decorator.expression;
-  return ts.isCallExpression(expression) ? expression.expression : expression;
-}
-
-function selectedNode(ts, expression) {
-  expression = unwrapExpression(ts, expression);
-  if (ts.isIdentifier(expression)) return expression;
-  if (ts.isPropertyAccessExpression(expression)) return expression.name;
-  if (ts.isElementAccessExpression(expression) && ts.isStringLiteralLike(expression.argumentExpression)) return expression.argumentExpression;
-  return null;
-}
-
 function frameworkDecorator(ts, checker, decorator, targets) {
-  const selected = selectedNode(ts, calledExpression(ts, decorator));
+  const selected = selectedNode(ts, decoratorCallee(ts, decorator));
   if (!selected) return null;
   const symbol = valueSymbol(ts, checker, selected);
   for (const [name, target] of targets) if (symbol === target) return name;
   return null;
 }
 
-function mutableFrameworkAlias(ts, checker, decorator, targets) {
-  const selected = selectedNode(ts, calledExpression(ts, decorator));
-  const symbol = selected ? normalizedSymbol(ts, checker, selected) : null;
-  const declarations = symbol?.getDeclarations?.() ?? [];
-  if (declarations.length !== 1 || !ts.isVariableDeclaration(declarations[0]) || !declarations[0].initializer
-    || (ts.getCombinedNodeFlags(declarations[0].parent) & ts.NodeFlags.Const)) return null;
-  const target = valueSymbol(ts, checker, declarations[0].initializer);
-  for (const [name, expected] of targets) if (target === expected) return name;
-  return null;
-}
+/* This module's framework map keys decorator names, not symbols - invert it (first name wins, as the old
+ * `for...of` scan did) for the shared symbol-keyed lookup. */
+const mutableFrameworkAlias = (ts, checker, decorator, targets) => {
+  const bySymbol = new Map();
+  for (const [name, symbol] of targets) if (!bySymbol.has(symbol)) bySymbol.set(symbol, name);
+  return mutableDecoratorKind(ts, checker, decorator, bySymbol);
+};
 
 function frameworkTargets(config, context, checker, localFiles) {
   const targets = new Map();
   const reasons = [];
-  const program = context.programs.find(candidate => candidate.getTypeChecker() === checker);
-  if (!program) return { targets, reasons: ['a TypeScript program checker could not be associated with its source'] };
-  for (const sourceFile of program.getSourceFiles()) {
-    if (!localFiles.has(canonical(sourceFile.fileName))) continue;
+  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 moduleSpecifier = (context.ts.isImportDeclaration(statement) || context.ts.isExportDeclaration(statement))
-        && statement.moduleSpecifier && context.ts.isStringLiteralLike(statement.moduleSpecifier) ? statement.moduleSpecifier : null;
-      const importEquals = context.ts.isImportEqualsDeclaration(statement) && context.ts.isExternalModuleReference(statement.moduleReference)
-        && statement.moduleReference.expression && context.ts.isStringLiteralLike(statement.moduleReference.expression)
-        ? statement.moduleReference.expression : null;
-      const specifier = (moduleSpecifier ?? importEquals)?.text;
-      if (!specifier || ![...FRAMEWORK.values()].includes(specifier)) continue;
-      const expected = new Set([...FRAMEWORK].filter(([, packageName]) => packageName === specifier).map(([name]) => name));
+      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;
-      const moduleSymbol = checker.getSymbolAtLocation(moduleSpecifier ?? importEquals);
-      if (!moduleSymbol) {
-        reasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot resolve ${specifier}`);
+      if (!bound.symbol) {
+        reasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot resolve ${bound.specifier}`);
         continue;
       }
-      const exports = new Map(checker.getExportsOfModule(moduleSymbol).map(symbol => [symbol.getName(), normalizedSymbolValue(context.ts, checker, symbol)]));
       for (const name of selected) {
-        const target = exports.get(name);
+        const target = bound.exports.get(name);
         if (target) targets.set(name, target);
-        else reasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot resolve ${name} from ${specifier}`);
+        else reasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot resolve ${name} from ${bound.specifier}`);
       }
     }
-    const visitRequire = node => {
-      if (context.ts.isCallExpression(node) && isUnshadowedCommonJsRequire(context.ts, checker, node.expression)
-        && node.arguments.length === 1 && context.ts.isStringLiteralLike(node.arguments[0])
-        && [...FRAMEWORK.values()].includes(node.arguments[0].text)) {
-        reasons.push(`${relativePath(config.root, sourceFile.fileName)} uses a CommonJS Nest framework binding whose decorator identity cannot be proved`);
-      }
-      context.ts.forEachChild(node, visitRequire);
-    };
-    visitRequire(sourceFile);
+    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');
   }
   return { targets, reasons };
 }

package/runtime/scripts/hfs/architecture/required-files.mjs

@@ -1,35 +1,35 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { gitOutput } from '../../api/git/lib.mjs';
+import { lsFiles } from '../../api/git/ls-files.mjs';
+import { revParseQuery } from '../../api/git/rev-parse-query.mjs';
+import { gitOutputOf } from '../../lib/git.mjs';
 
 /**
  * HFS check 5: the files and directories the slot manifest requires (knowledge/hfs/slots.yaml `requires`,
  * `requiredInstances`, `minInstances`, required app kinds) must exist in the repository tree. Everything is read through the
  * resolver of scripts/hfs/slots.mjs; nothing here names a path.
  *
- *   BE_REQUIRED_MODULE_MISSING   a backend app, feature, domain, integrations or platform instance lacks a required file or
- *                                directory, or a required platform instance (config, logging, errors, primitives) is absent
  *   FE_ERROR_BOUNDARY_MISSING    a fe.app.next app lacks global-error, error, not-found or loading under src/app
- *   HFS_REQUIRED_FILE_MISSING    any other required file or directory (packages, fe modules, i18n, api ...), and a minimum
- *                                (no api app, no feature, no next app) which is reported once at hfs.json
+ *   HFS_REQUIRED_FILE_MISSING    any other required file or directory of any slot (backend app, feature, domain, integrations and
+ *                                platform instances, a required platform instance such as config or logging, packages, fe modules,
+ *                                i18n, api ...), and a minimum (no api app, no feature, no next app) which is reported once at hfs.json
  *
  * Slots of tier none (README, root config, .starciwork, .starcistacks) belong to the slot check; fe.app.next is the one
  * tier-none slot judged here. The tree is the tracked one (`git ls-files` from the repository root, minus files deleted
  * on disk), else the filesystem without node_modules, .git, dist and .next.
  */
-export const REQUIRED_FILE_RULE_IDS = ['BE_REQUIRED_MODULE_MISSING', 'FE_ERROR_BOUNDARY_MISSING', 'HFS_REQUIRED_FILE_MISSING'];
+export const REQUIRED_FILE_RULE_IDS = ['FE_ERROR_BOUNDARY_MISSING', 'HFS_REQUIRED_FILE_MISSING'];
 
 const SKIPPED_DIRECTORIES = new Set(['node_modules', '.git', 'dist', '.next']);
 const ERROR_BOUNDARY_FILE = /^(?:global-error|error|not-found|loading)\.tsx$/u;
-const BACKEND_MODULE_SLOT = /^be\.(?:app|feature|transport|domain|integrations|platform)(?:\.|$)/u;
 const ALSO_JUDGED_TIER_NONE = new Set(['fe.app.next']);
 
 function gitFiles(root) {
   try {
-    const run = args => gitOutput(args, { cwd: root, maxBuffer: 256 * 1024 * 1024 });
-    run(['rev-parse', '--is-inside-work-tree']);
-    const deleted = new Set(run(['ls-files', '--deleted', '-z', '--', '.']).split('\0').filter(Boolean));
-    return run(['ls-files', '--cached', '-z', '--', '.']).split('\0').filter(file => file && !deleted.has(file));
+    const run = (call, args) => gitOutputOf(call(args, { cwd: root, maxBuffer: 256 * 1024 * 1024 }));
+    run(revParseQuery, ['--is-inside-work-tree']);
+    const deleted = new Set(run(lsFiles, ['--deleted', '-z', '--', '.']).split('\0').filter(Boolean));
+    return run(lsFiles, ['--cached', '-z', '--', '.']).split('\0').filter(file => file && !deleted.has(file));
   } catch {
     return null;
   }
@@ -60,12 +60,20 @@ export function treeOf(root) {
   return { files, directories };
 }
 
+/**
+ * The prelude every tree-walking architecture checker shares: the input's config/graph/context, the compiler,
+ * the slot resolver and the tracked repository tree.
+ */
+export function checkerScope({ config, graph, context }) {
+  return { config, graph, context, ts: context.ts, resolver: graph.resolver, tree: treeOf(config.root) };
+}
+
 const strip = entry => entry.replace(/\/+$/u, '');
 const rootOfTarget = target => (target.endsWith('/') ? strip(target) : (path.posix.dirname(target) === '.' ? '' : path.posix.dirname(target)));
 
 function ruleFor(slotId, target, rootExists) {
   if (slotId === 'fe.app.next' && rootExists && ERROR_BOUNDARY_FILE.test(path.posix.basename(strip(target)))) return 'FE_ERROR_BOUNDARY_MISSING';
-  return BACKEND_MODULE_SLOT.test(slotId) ? 'BE_REQUIRED_MODULE_MISSING' : 'HFS_REQUIRED_FILE_MISSING';
+  return 'HFS_REQUIRED_FILE_MISSING';
 }
 
 export function checkRequiredFiles({ config, graph }) {