@starci/hfs 4.3.0 → 4.4.0

package/runtime/scripts/hfs/architecture/client-reaches-server.mjs

@@ -4,7 +4,7 @@ import { sourceLocation } from '../../lib/ts-ast.mjs';
 /**
  * R55 `client-reaches-server` (FE_CLIENT_REACHES_SERVER), the repository half of the eslint rule `client-no-server-import`,
  * which sees one hop from a file that carries the directive. The machine walks the resolved import graph from every module
- * whose first statement is the `"use client"` directive, over runtime edges only (a type-only import vanishes at build), and
+ * whose directive prologue contains `"use client"`, over runtime edges only (a type-only import vanishes at build), and
  * reports any reachable module (the entry itself included) that imports a server-only surface:
  *
  *   - `server-only`, `next/headers`, `next/server`, `next-intl/server`;
@@ -22,8 +22,11 @@ const NODE_BUILTINS = new Set(builtinModules.map(name => name.replace(/^node:/u,
 
 const isServerSpecifier = specifier => SERVER_MODULES.has(specifier) || specifier.startsWith('node:') || NODE_BUILTINS.has(specifier.split('/')[0]);
 const isClientEntry = (ts, file) => {
-  const first = file.sourceFile.statements[0];
-  return Boolean(first) && ts.isExpressionStatement(first) && ts.isStringLiteral(first.expression) && first.expression.text === 'use client';
+  for (const statement of file.sourceFile.statements) {
+    if (!ts.isExpressionStatement(statement) || !ts.isStringLiteral(statement.expression)) return false;
+    if (statement.expression.text === 'use client') return true;
+  }
+  return false;
 };
 
 const reachesBundle = (ts, declaration) => {

package/runtime/scripts/hfs/architecture/dead-exports-bindings.mjs

@@ -0,0 +1,149 @@
+// Import and namespace consumption analysis shared by dead-export edges.
+import path from 'node:path';
+
+/** Disk/staged test consumers have no production checker; bind their local names without resolving dependencies. */
+const namespaceChecker = (context, sourceFile, namespace) => {
+  if (context.namespaceCheckers.has(sourceFile)) return context.namespaceCheckers.get(sourceFile);
+  const { ts } = context;
+  let checker = context.checkerFor?.(sourceFile.fileName);
+  if (!checker?.getSymbolAtLocation(namespace.name)) {
+    const options = { noResolve: true, noLib: true, types: [], allowJs: true, target: ts.ScriptTarget.Latest };
+    const host = ts.createCompilerHost(options);
+    const filename = path.resolve(sourceFile.fileName);
+    host.getSourceFile = file => path.resolve(file) === filename ? sourceFile : undefined;
+    host.fileExists = file => path.resolve(file) === filename;
+    host.readFile = file => path.resolve(file) === filename ? sourceFile.text : undefined;
+    checker = ts.createProgram([filename], options, host).getTypeChecker();
+  }
+  context.namespaceCheckers.set(sourceFile, checker);
+  return checker;
+};
+
+const transparentExpression = (ts, node) => node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node)
+  || ts.isTypeAssertionExpression(node) || ts.isNonNullExpression(node) || ts.isSatisfiesExpression(node));
+
+const literalMember = (ts, node) => {
+  while (transparentExpression(ts, node)) node = node.expression;
+  return node && (ts.isStringLiteralLike(node) || ts.isNumericLiteral(node)) ? node.text : null;
+};
+
+const destructuredMember = (ts, name) => {
+  if (ts.isIdentifier(name)) return name.text;
+  if (ts.isComputedPropertyName(name)) return literalMember(ts, name.expression);
+  return literalMember(ts, name);
+};
+
+/** A destructuring alias consumes the property's name, while a rest/computed binding may consume every export. */
+const destructuredBindings = (ts, pattern) => {
+  const names = [];
+  const elements = ts.isObjectBindingPattern(pattern) ? pattern.elements : pattern.properties;
+  for (const element of elements) {
+    if (element.dotDotDotToken || ts.isSpreadAssignment(element)) return { all: true, pairs: [] };
+    const name = destructuredMember(ts, element.propertyName ?? element.name);
+    if (name === null) return { all: true, pairs: [] };
+    names.push(name);
+  }
+  return { all: false, pairs: names.map(imported => ({ imported, exported: null })) };
+};
+
+const namespaceReference = (ts, checker, symbol, node) => {
+  if (checker.getSymbolAtLocation(node) === symbol) return true;
+  const parent = node.parent;
+  if (ts.isShorthandPropertyAssignment(parent) && parent.name === node) return checker.getShorthandAssignmentValueSymbol(parent) === symbol;
+  return ts.isExportSpecifier(parent) && node === (parent.propertyName ?? parent.name)
+    && checker.getExportSpecifierLocalTargetSymbol(parent) === symbol;
+};
+
+const unwrappedNamespace = (ts, node) => {
+  while (transparentExpression(ts, node.parent)) node = node.parent;
+  return node;
+};
+
+const indexedNamespaceMember = (ts, node) => {
+  if (!ts.isTypeQueryNode(node.parent) || node.parent.exprName !== node) return null;
+  let query = node.parent;
+  while (ts.isParenthesizedTypeNode(query.parent)) query = query.parent;
+  const indexed = query.parent;
+  return ts.isIndexedAccessTypeNode(indexed) && indexed.objectType === query && ts.isLiteralTypeNode(indexed.indexType)
+    ? literalMember(ts, indexed.indexType.literal) : null;
+};
+
+/** The first member is the entry export even in a chain such as namespace.Enum.Member or namespace.Type.Inner. */
+const namespaceUse = (ts, reference) => {
+  const node = unwrappedNamespace(ts, reference);
+  const parent = node.parent;
+  let name = null;
+  if (ts.isPropertyAccessExpression(parent) && parent.expression === node) name = parent.name.text;
+  else if (ts.isQualifiedName(parent) && parent.left === node) name = parent.right.text;
+  else if (ts.isElementAccessExpression(parent) && parent.expression === node) name = literalMember(ts, parent.argumentExpression);
+  else if (ts.isVariableDeclaration(parent) && parent.initializer === node && ts.isObjectBindingPattern(parent.name)) return destructuredBindings(ts, parent.name);
+  else if (ts.isBinaryExpression(parent) && parent.right === node && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken
+    && ts.isObjectLiteralExpression(parent.left)) return destructuredBindings(ts, parent.left);
+  else name = indexedNamespaceMember(ts, node);
+  return name === null ? { all: true, pairs: [] } : { all: false, pairs: [{ imported: name, exported: null }] };
+};
+
+const namespaceBindings = (context, declaration, namespace) => {
+  if (context.namespaceUses.has(namespace)) return context.namespaceUses.get(namespace);
+  const { ts } = context;
+  const sourceFile = declaration.getSourceFile();
+  const checker = namespaceChecker(context, sourceFile, namespace);
+  const symbol = checker.getSymbolAtLocation(namespace.name);
+  const result = { all: false, pairs: [] };
+  const visit = node => {
+    if (ts.isJSDocSeeTag(node) || ts.isJSDocLink(node) || ts.isJSDocLinkCode(node) || ts.isJSDocLinkPlain(node)) return;
+    if (ts.isIdentifier(node) && node !== namespace.name && namespaceReference(ts, checker, symbol, node)) {
+      const used = namespaceUse(ts, node);
+      result.all ||= used.all;
+      result.pairs.push(...used.pairs);
+    }
+    if (!result.all) {
+      ts.forEachChild(node, visit);
+      for (const doc of node.jsDoc ?? []) visit(doc);
+    }
+  };
+  // An unavailable binding must never turn an unknown consumer into a false unused-export finding.
+  if (symbol) visit(sourceFile);
+  else result.all = true;
+  context.namespaceUses.set(namespace, result);
+  return result;
+};
+
+const importBindings = (context, declaration) => {
+  const { ts } = context;
+  const clause = declaration.importClause;
+  if (!clause) return { all: false, pairs: [] }; // side-effect import: uses nothing
+  const pairs = [];
+  if (clause.name) pairs.push({ imported: 'default', exported: null });
+  const named = clause.namedBindings;
+  if (named && named.kind === ts.SyntaxKind.NamespaceImport) {
+    const namespace = namespaceBindings(context, declaration, named);
+    return { all: namespace.all, pairs: [...pairs, ...namespace.pairs] };
+  }
+  if (named) for (const element of named.elements) pairs.push({ imported: (element.propertyName ?? element.name).text, exported: null });
+  return { all: false, pairs };
+};
+
+const exportBindings = (ts, declaration) => {
+  const clause = declaration.exportClause;
+  if (!clause || clause.kind === ts.SyntaxKind.NamespaceExport) return { all: true, pairs: [] };
+  return { all: false, pairs: clause.elements.map(element => ({ imported: (element.propertyName ?? element.name).text, exported: element.name.text })) };
+};
+
+const importTypeBindings = (ts, declaration) => {
+  let qualifier = declaration.qualifier;
+  if (!qualifier) return { all: true, pairs: [] };
+  while (qualifier.kind === ts.SyntaxKind.QualifiedName) qualifier = qualifier.left;
+  return { all: false, pairs: [{ imported: qualifier.text, exported: null }] };
+};
+
+/** Names an import/export declaration takes from its target: {all} or {pairs: [{imported, exported}]}. */
+export function bindingsOf(context, declaration) {
+  const { ts } = context;
+  if (!declaration) return { all: true, pairs: [] };
+  if (declaration.kind === ts.SyntaxKind.ImportDeclaration) return importBindings(context, declaration);
+  if (declaration.kind === ts.SyntaxKind.ExportDeclaration) return exportBindings(ts, declaration);
+  if (declaration.kind === ts.SyntaxKind.ImportTypeNode) return importTypeBindings(ts, declaration);
+  // ImportEqualsDeclaration, dynamic import(), require(): the whole module is taken.
+  return { all: true, pairs: [] };
+}

package/runtime/scripts/hfs/architecture/dead-exports.mjs

@@ -17,8 +17,9 @@
  * and contributes no name here.
  *
  * A name is used when a production file outside the owner imports it from the entry (type-only imports count). A
- * namespace import, `import x = require`, a dynamic import()/require(), an `export *` or `export * as` of the entry make
- * every name used. A file outside the owner that re-exports the name (`export { n as m } from`) uses it when `m` is itself
+ * namespace import uses its statically accessed members; a computed read or an escape of the namespace uses every name.
+ * `import x = require`, a dynamic import()/require(), an `export *` or `export * as` of the entry make every name used.
+ * A file outside the owner that re-exports the name (`export { n as m } from`) uses it when `m` is itself
  * used by the importers of that file; a re-exporting file nobody imports is a framework entry (a route file) and uses it.
  * Specs and tests are not in the graph, so an export used only by a spec is dead, on purpose, with these exceptions (unit test
  * standard): the unit spec of every unit role (ruleParams.be.unitRoles: `<name>.service.spec.ts`, `<name>.cli.spec.ts`) and of every logic role
@@ -39,6 +40,7 @@ import path from 'node:path';
 import { treeOf } from './required-files.mjs';
 import { globExpression } from '../../lib/glob.mjs';
 import { stagedConsumerSources } from './staged-consumers.mjs';
+import { bindingsOf } from './dead-exports-bindings.mjs';
 
 export const DEAD_EXPORT_RULE_IDS = ['HFS_UNUSED_EXPORT', 'HFS_UNUSED_FILE'];
 
@@ -70,40 +72,6 @@ function extraEntries(graph, entry) {
   return names.flatMap(name => (name.includes('*') ? matches(name) : [`${found.root}/${name}`].filter(rel => graph.files.has(rel))));
 }
 
-const importBindings = (ts, declaration) => {
-  const clause = declaration.importClause;
-  if (!clause) return { all: false, pairs: [] }; // side-effect import: uses nothing
-  const pairs = [];
-  if (clause.name) pairs.push({ imported: 'default', exported: null });
-  const named = clause.namedBindings;
-  if (named && named.kind === ts.SyntaxKind.NamespaceImport) return { all: true, pairs: [] };
-  if (named) for (const element of named.elements) pairs.push({ imported: (element.propertyName ?? element.name).text, exported: null });
-  return { all: false, pairs };
-};
-
-const exportBindings = (ts, declaration) => {
-  const clause = declaration.exportClause;
-  if (!clause || clause.kind === ts.SyntaxKind.NamespaceExport) return { all: true, pairs: [] };
-  return { all: false, pairs: clause.elements.map(element => ({ imported: (element.propertyName ?? element.name).text, exported: element.name.text })) };
-};
-
-const importTypeBindings = (ts, declaration) => {
-  let qualifier = declaration.qualifier;
-  if (!qualifier) return { all: true, pairs: [] };
-  while (qualifier.kind === ts.SyntaxKind.QualifiedName) qualifier = qualifier.left;
-  return { all: false, pairs: [{ imported: qualifier.text, exported: null }] };
-};
-
-/** Names an import/export declaration takes from its target: {all} or {pairs: [{imported, exported}]}. */
-function bindingsOf(ts, declaration) {
-  if (!declaration) return { all: true, pairs: [] };
-  if (declaration.kind === ts.SyntaxKind.ImportDeclaration) return importBindings(ts, declaration);
-  if (declaration.kind === ts.SyntaxKind.ExportDeclaration) return exportBindings(ts, declaration);
-  if (declaration.kind === ts.SyntaxKind.ImportTypeNode) return importTypeBindings(ts, declaration);
-  // ImportEqualsDeclaration, dynamic import(), require(): the whole module is taken.
-  return { all: true, pairs: [] };
-}
-
 const addExportName = (found, sourceFile, name, node) => {
   if (found.has(name)) return;
   found.set(name, sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1);
@@ -312,7 +280,7 @@ const consumedNames = (context, file, ownerKey, depth, visiting) => {
   const result = { all: false, names: new Set() };
   for (const edge of context.edgesTo.get(file) ?? []) {
     if (ownerKey && unitOfFile(context.graph, edge.from) === ownerKey) continue;
-    const bindings = bindingsOf(context.ts, edge.edge.declaration);
+    const bindings = bindingsOf(context, edge.edge.declaration);
     if (bindings.all) { result.all = true; continue; }
     for (const pair of bindings.pairs) consumeReexportedName(context, result, edge, pair, depth, visiting);
   }
@@ -321,10 +289,10 @@ const consumedNames = (context, file, ownerKey, depth, visiting) => {
 
 /** Adds to `used` the entry exports reached by a consumer outside the owner that imports a file the entry re-exports by name. */
 const addReexportedUses = (context, key, publicEntry, used) => {
-  const { ts, graph } = context;
+  const { graph } = context;
   for (const edge of graph.edges) {
     if (edge.from !== publicEntry || !edge.reexport || graph.unit(edge.to) !== key) continue;
-    const reexport = bindingsOf(ts, edge.edge.declaration);
+    const reexport = bindingsOf(context, edge.edge.declaration);
     const inner = consumedNames(context, edge.to, key, 0, new Set([publicEntry, edge.to]));
     if (reexport.all) continue;
     for (const pair of reexport.pairs) if (inner.all || inner.names.has(pair.imported)) used.names.add(pair.exported);
@@ -342,7 +310,7 @@ const unusedExportViolation = (publicEntry, name, line, owner) => ({
 const addSiblingEntryUses = (context, publicEntry, declared, used) => {
   for (const edge of context.edgesTo.get(publicEntry) ?? []) {
     if (edge.reexport || edge.from === publicEntry || !declared.has(edge.from)) continue;
-    const bindings = bindingsOf(context.ts, edge.edge.declaration);
+    const bindings = bindingsOf(context, edge.edge.declaration);
     if (bindings.all) used.all = true;
     for (const pair of bindings.pairs) used.names.add(pair.imported);
   }
@@ -382,7 +350,7 @@ const ownerExportFindings = (context, config) => {
 
 export function checkDeadExports({ context, graph, config }) {
   const edgesTo = edgeIndex([...graph.edges, ...testConsumerEdges({ context, graph, config })]);
-  const analysis = { ...context, graph, edgesTo };
+  const analysis = { ...context, graph, edgesTo, namespaceCheckers: new WeakMap(), namespaceUses: new WeakMap() };
   const exports = ownerExportFindings(analysis, config);
   const files = deadFiles(graph, config);
   const dead = exports.violations.length;

package/runtime/scripts/hfs/architecture/default-deny.mjs

@@ -2,22 +2,23 @@ import { machineKit } from './machine-ast.mjs';
 
 /**
  * R41 `default-deny-app-guard` (BE_DEFAULT_DENY). Every api app root provides its `APP_GUARD` entries in the order
- * throttler -> CSRF origin guard -> AuthGuard, each exactly once, so no request reaches a handler before it was
- * rate-limited, origin-checked and authenticated. A guard is classified by structure, never by name or folder alone
+ * throttler -> CSRF origin guard -> CredentialGuard -> AuthGuard, each exactly once, so no request reaches a handler before it was
+ * rate-limited, origin-checked, credential-authenticated and admitted. A guard is classified by structure, never by name or folder alone
  * (BE-CONVENTION 1.7 names the roles, not a library):
  *   - throttler: a class of @nestjs/throttler or one that extends it, or a guard that reads through a Reflector the
  *     per-door metadata (the `@RateLimit(tier)` decorator) that a SetMetadata call of its own capability writes;
  *   - CSRF origin guard: a guard declared in platform/http-security that reads the request origin or referer header;
+ *   - CredentialGuard: the `CredentialGuard` class declared in domain/identity;
  *   - AuthGuard: the `AuthGuard` class declared in domain/identity.
  * Other guards are permitted between them; a missing, repeated or reordered one of the three is a finding.
  */
 export const DEFAULT_DENY_RULE_IDS = ['BE_DEFAULT_DENY'];
 
 const RULE = 'BE_DEFAULT_DENY';
-const ORDER = ['throttler', 'csrf', 'auth'];
+const ORDER = ['throttler', 'csrf', 'credential', 'auth'];
 const ORIGIN_HEADERS = new Set(['origin', 'referer', 'referrer']);
 const METADATA_READERS = new Set(['get', 'getAll', 'getAllAndMerge', 'getAllAndOverride']);
-const LABEL = { throttler: 'the throttler guard', csrf: 'the CSRF origin guard of platform/http-security', auth: 'AuthGuard of domain/identity' };
+const LABEL = { throttler: 'the throttler guard', csrf: 'the CSRF origin guard of platform/http-security', credential: 'CredentialGuard of domain/identity', auth: 'AuthGuard of domain/identity' };
 
 const keySymbol = (kit, checker, node) => (node ? kit.aliased(checker, kit.symbolAt(checker, node)) ?? null : null);
 
@@ -98,6 +99,7 @@ const classifyDeclaration = (kit, graph, keyCache, declaration) => {
     if (readsDoorMetadata(kit, graph, keyCache, declaration, owner)) return 'throttler';
   }
   if (owner?.tier === 'domain' && owner.name === 'identity' && ts.isClassDeclaration(declaration) && declaration.name?.text === 'AuthGuard') return 'auth';
+  if (owner?.tier === 'domain' && owner.name === 'identity' && ts.isClassDeclaration(declaration) && declaration.name?.text === 'CredentialGuard') return 'credential';
   return null;
 };
 
@@ -117,7 +119,7 @@ const roleMessages = (app, roles, anchor) => {
   const out = [];
   for (const role of ORDER) {
     const entries = roles.filter(item => item.role === role);
-    if (entries.length === 0) out.push({ node: anchor, message: `App ${app.name} does not provide ${LABEL[role]} as an APP_GUARD; an api app is denied by default: throttler, then CSRF origin guard, then AuthGuard.` });
+    if (entries.length === 0) out.push({ node: anchor, message: `App ${app.name} does not provide ${LABEL[role]} as an APP_GUARD; an api app is denied by default: throttler, then CSRF origin guard, then CredentialGuard, then AuthGuard.` });
     else if (entries.length > 1) out.push({ node: entries[1].guard.node, message: `App ${app.name} provides ${LABEL[role]} more than once as an APP_GUARD.` });
   }
   return out;
@@ -128,7 +130,7 @@ const orderMessages = (app, roles) => {
   if (!indexes.every(index => index >= 0)) return [];
   const out = [];
   for (let i = 1; i < indexes.length; i += 1) {
-    if (indexes[i] < indexes[i - 1]) out.push({ node: roles[indexes[i]].guard.node, message: `App ${app.name} provides ${LABEL[ORDER[i]]} before ${LABEL[ORDER[i - 1]]}; the APP_GUARD order is throttler, CSRF origin guard, AuthGuard.` });
+    if (indexes[i] < indexes[i - 1]) out.push({ node: roles[indexes[i]].guard.node, message: `App ${app.name} provides ${LABEL[ORDER[i]]} before ${LABEL[ORDER[i - 1]]}; the APP_GUARD order is throttler, CSRF origin guard, CredentialGuard, AuthGuard.` });
   }
   return out;
 };

package/runtime/scripts/hfs/architecture/frontend-world.mjs

@@ -74,7 +74,7 @@ class WorldAnalysis {
     let found = false;
     const visit = node => {
       if (!found && this.ts.isCallExpression(node) && this.ts.isIdentifier(node.expression) && node.expression.text === 'fetch'
-        && !checker.getSymbolAtLocation(node.expression)) found = true;
+        && (checker.getSymbolAtLocation(node.expression)?.getDeclarations() ?? []).every(declaration => declaration.getSourceFile().isDeclarationFile)) found = true;
       if (!found) this.ts.forEachChild(node, visit);
     };
     visit(sourceFile);

package/runtime/scripts/hfs/architecture/function-spec-providers.mjs

@@ -0,0 +1,153 @@
+import path from 'node:path';
+
+export const keyOf = (ts, property) => (ts.isPropertyAssignment(property) || ts.isShorthandPropertyAssignment(property)) && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) ? property.name.text : null;
+const exported = (ts, statement) => statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+
+/** The directly defined functions among the declarations of an exported variable statement; other values are not callable. */
+function callableVariables(ts, statement) {
+  const names = [];
+  for (const declaration of statement.declarationList.declarations) {
+    const initializer = declaration.initializer;
+    if (ts.isIdentifier(declaration.name) && initializer && (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer))) names.push(declaration.name.text);
+  }
+  return names;
+}
+
+/** The callable exports of one statement: an overload signature has no body and collapses into its implementation. */
+function callableExports(ts, statement) {
+  if (!exported(ts, statement)) return [];
+  if (ts.isFunctionDeclaration(statement)) return statement.name && statement.body ? [statement.name.text] : [];
+  return ts.isVariableStatement(statement) ? callableVariables(ts, statement) : [];
+}
+
+/**
+ * The callable subset of a function subject's exports. Constants, enums, objects, types, `export ... from` re-exports and overload
+ * signatures do not change which functions the spec must provide; a class or a default-export assignment keeps the class-provider
+ * check (null), as does a module with no callable export.
+ */
+export function functionSubjectExports(ts, sourceFile) {
+  const names = [];
+  for (const statement of sourceFile.statements) {
+    if (ts.isClassDeclaration(statement) || ts.isExportAssignment(statement)) return null;
+    for (const name of callableExports(ts, statement)) if (!names.includes(name)) names.push(name);
+  }
+  return names.length ? names : null;
+}
+
+const decoratorsOf = (ts, node) => (ts.canHaveDecorators(node) ? ts.getDecorators(node) ?? [] : []);
+
+/** A value object: an undecorated class whose constructor parameters carry no injection token, so Nest never builds it. */
+function isValueObjectClass(ts, declaration) {
+  if (decoratorsOf(ts, declaration).length > 0) return false;
+  const constructors = declaration.members.filter(member => ts.isConstructorDeclaration(member));
+  return constructors.every(constructor => constructor.parameters.every(parameter => decoratorsOf(ts, parameter).length === 0));
+}
+
+/** The names of the value-object classes a module exports, or null when it exports a class that is not one (or none). */
+export function valueObjectSubjects(ts, sourceFile) {
+  const classes = sourceFile.statements.filter(statement => ts.isClassDeclaration(statement) && statement.name && exported(ts, statement));
+  if (!classes.length || !classes.every(declaration => isValueObjectClass(ts, declaration))) return null;
+  return classes.map(declaration => declaration.name.text);
+}
+
+/** The value of one literal object property. */
+const propertyValue = (ts, object, key) => {
+  const property = object.properties.find(item => keyOf(ts, item) === key);
+  return property && ts.isPropertyAssignment(property) ? property.initializer : null;
+};
+
+/** A literal value object maps every exported function to its real sibling import. */
+function realFunctions(ts, value, names, imports, rel, serviceRel) {
+  if (!value || !ts.isObjectLiteralExpression(value) || value.properties.length !== names.length) return false;
+  const remaining = new Set(names);
+  for (const property of value.properties) {
+    const key = keyOf(ts, property);
+    const identifier = ts.isShorthandPropertyAssignment(property) ? property.name : property.initializer;
+    if (!remaining.delete(key) || !identifier || !ts.isIdentifier(identifier)) return false;
+    const binding = imports.get(identifier.text);
+    if (!binding || binding.name !== key || !binding.module.startsWith('.')) return false;
+    const target = path.posix.normalize(path.posix.join(path.posix.dirname(rel), binding.module)).replace(/\.[cm]?[jt]s$/u, '');
+    if (target !== serviceRel.replace(/\.ts$/u, '')) return false;
+  }
+  return remaining.size === 0;
+}
+
+/** Every node satisfying a predicate, within one spec. */
+function matchingNodes(ts, root, predicate) {
+  const found = [];
+  const visit = node => {
+    if (predicate(node)) found.push(node);
+    ts.forEachChild(node, visit);
+  };
+  visit(root);
+  return found;
+}
+
+/** The declared variable initialized by an expression, including its await and call chain. */
+function initializedVariable(ts, expression) {
+  let cursor = expression;
+  let compiled = false;
+  let awaited = false;
+  while (cursor.parent && (ts.isAwaitExpression(cursor.parent) || ts.isPropertyAccessExpression(cursor.parent) || ts.isCallExpression(cursor.parent))) {
+    cursor = cursor.parent;
+    if (ts.isAwaitExpression(cursor)) awaited = true;
+    if (ts.isCallExpression(cursor) && ts.isPropertyAccessExpression(cursor.expression) && cursor.expression.name.text === 'compile') compiled = true;
+  }
+  if (!compiled || !awaited) return null;
+  const declaration = cursor.parent;
+  return declaration && ts.isVariableDeclaration(declaration) && ts.isIdentifier(declaration.name) ? declaration.name.text : null;
+}
+
+/** The subject variable receiving module.get, whether declared there or assigned in beforeEach. */
+function retrievedVariable(ts, call) {
+  let cursor = call;
+  while (cursor.parent && (ts.isAwaitExpression(cursor.parent) || ts.isParenthesizedExpression(cursor.parent))) cursor = cursor.parent;
+  const parent = cursor.parent;
+  if (parent && ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) return parent.name.text;
+  if (parent && ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isIdentifier(parent.left)) return parent.left.text;
+  return null;
+}
+
+/** A helper returning the retrieved subject is followed to the variable receiving its result. */
+function retrievedSubjects(ts, read, sourceFile) {
+  const direct = retrievedVariable(ts, read);
+  if (direct) return [direct];
+  if (!read.parent || !ts.isReturnStatement(read.parent)) return [];
+  let helper = read.parent;
+  while (helper.parent && !ts.isFunctionLike(helper)) helper = helper.parent;
+  const name = helper.name?.text ?? helper.parent?.name?.text;
+  if (!name) return [];
+  return matchingNodes(ts, sourceFile, node => ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === name)
+    .map(node => retrievedVariable(ts, node)).filter(Boolean);
+}
+
+/** The same compiled module retrieves the matching token and its result actually calls a subject function. */
+function retrievedSubjectUsed(ts, call, token, names) {
+  const moduleName = initializedVariable(ts, call);
+  if (!moduleName) return false;
+  const sourceFile = call.getSourceFile();
+  const reads = matchingNodes(ts, sourceFile, node => {
+    if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) return false;
+    const member = node.expression;
+    return ts.isIdentifier(member.expression) && member.expression.text === moduleName && member.name.text === 'get'
+      && node.arguments.length === 1 && ts.isIdentifier(node.arguments[0]) && node.arguments[0].text === token.text;
+  });
+  return reads.some(read => {
+    const subjects = retrievedSubjects(ts, read, sourceFile);
+    return matchingNodes(ts, sourceFile, node => ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)
+      && ts.isIdentifier(node.expression.expression) && subjects.includes(node.expression.expression.text) && names.includes(node.expression.name.text)).length > 0;
+  });
+}
+
+/** A pure function service has exactly one real subject value provider, retrieved and exercised through Nest. */
+export function checkFunctionSubject({ ts, rel, serviceRel, imports, call, list, names, report }) {
+  const provider = list.elements[0];
+  const shape = provider && ts.isObjectLiteralExpression(provider) && provider.properties.length === 2;
+  const token = shape ? propertyValue(ts, provider, 'provide') : null;
+  const value = shape ? propertyValue(ts, provider, 'useValue') : null;
+  if (list.elements.length !== 1 || !token || !ts.isIdentifier(token) || !realFunctions(ts, value, names, imports, rel, serviceRel)) {
+    report(provider ?? list, `${rel}: a function-only subject needs exactly one { provide: TOKEN, useValue: { ...realFunctions } } provider containing every callable export imported from ./${path.posix.basename(serviceRel, '.ts')}.`);
+    return;
+  }
+  if (!retrievedSubjectUsed(ts, call, token, names)) report(list, `${rel}: retrieve the function subject with moduleRef.get(TOKEN) from this compiled testing module and exercise a function on the returned subject.`);
+}

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

@@ -297,11 +297,11 @@ function checkTestTopology(state) {
   // Test kinds and folders that do not exist: int-spec, harness-spec, src/tests/harness and live/;
   // a backend spec sits by its kind (beside its subject, or under src/tests/{integration,e2e,contract}/).
   for (const file of state.tree.files()) {
-    if (UNSUPPORTED_TEST_SUFFIX.test(file))
+    if (state.backend && state.profile === 'be' && UNSUPPORTED_TEST_SUFFIX.test(file))
       state.finding('BE_TEST_TOPOLOGY', file, `${file} uses an unsupported test kind. Only unit *.spec.ts, *.integration-spec.ts, *.e2e-spec.ts and *.contract-spec.ts exist, each in its own folder under src/tests/.`);
-    else if (state.backend && UNSUPPORTED_TEST_FOLDER.test(file))
+    else if (state.backend && state.profile === 'be' && UNSUPPORTED_TEST_FOLDER.test(file))
       state.finding('BE_TEST_TOPOLOGY', file, `${file} sits in an unsupported test folder. Unit specs sit beside their subject, flows go under src/tests/e2e/<area>/ and test infrastructure under src/tests/world/.`);
-    else if (state.backend && file.startsWith('src/tests/') && isExtraTestConfig(file))
+    else if (state.backend && state.profile === 'be' && file.startsWith('src/tests/') && isExtraTestConfig(file))
       state.finding('BE_TEST_TOPOLOGY', file, `${file} is a per-lane test config. One root jest.config.js declares exactly the unit, integration, e2e and contract projects.`);
   }
 }

package/runtime/scripts/hfs/architecture/module-per-transport.mjs

@@ -7,11 +7,13 @@ import { trimTrailingSlashes } from '../trailing-slashes.mjs';
 /**
  * R45 `module-per-transport` (BE_MODULE_SHAPE, BE-CONVENTION 1.2 and 1.6). A feature has one Nest module for its
  * application (`<f>.module.ts` at the feature root) and exactly one module per transport folder
- * (`transport/<protocol>/<f>-<protocol>.module.ts`). Never one module per operation, never a module-definition in a feature:
+ * (`transport/<protocol>/<f>-<protocol>.module.ts`). Never one module per operation. Every one of these modules has its own
+ * module-definition beside it (owner ruling module-definition-everywhere, R295):
  *
- *   - a `*.module.ts` file below a transport folder other than `<f>-<protocol>.module.ts`, a `*.module-definition.ts`
- *     anywhere in a feature, and an `@Module` class (or a `ConfigurableModuleBuilder`/`ConfigurableModuleClass` use) in a
- *     feature file that is neither the application module nor the transport module of its own folder are refused;
+ *   - a `*.module.ts` file below a transport folder other than `<f>-<protocol>.module.ts`, a `*.module-definition.ts` that is
+ *     not the sibling of the application module or of the transport module of its own folder, and an `@Module` class (or a
+ *     `ConfigurableModuleBuilder`/`ConfigurableModuleClass` use) in a feature file that is neither the application module, the
+ *     transport module of its own folder nor that module's definition are refused;
  *   - apps import only transport modules, of the kinds their app kind allows: the `composedBy` list of each transport slot
  *     in knowledge/hfs/slots.yaml (api: graphql, http, websocket; worker: schedule, message). An app root (app.module.ts
  *     or a composition group of its compose/ folder) that lists a feature's application module, or the transport module
@@ -53,13 +55,24 @@ function composedByProtocol(resolver) {
   return composedBy;
 }
 
-function reportTransportFileShapes(tree, placeOf, plain) {
+/** The module a feature file may declare: the application module, the transport module of its folder, or a cli folder's module. */
+function ownModuleOf(place, rel, composedModuleOf) {
+  if (place.composed) return composedModuleOf(rel);
+  return place.protocol === null
+    ? `${place.root}/${place.feature}.module.ts`
+    : `${place.root}/transport/${place.protocol}/${place.feature}-${place.protocol}.module.ts`;
+}
+
+const DEFINITION_FILE = /\.module-definition\.[cm]?tsx?$/u;
+const definitionOf = modulePath => modulePath.replace(/\.module\.([cm]?tsx?)$/u, '.module-definition.$1');
+
+function reportTransportFileShapes(tree, placeOf, plain, composedModuleOf) {
   let transportModules = 0;
   for (const rel of [...tree.files].sort(byCodeUnit)) {
     const place = placeOf(rel);
     if (!place) continue;
     const base = path.posix.basename(rel);
-    if (/\.module-definition\.[cm]?tsx?$/u.test(base)) plain(rel, `${rel} is a module-definition inside feature ${place.feature}; a feature module is a static \`@Module\`, and only capabilities under src/modules build their module from a definition. Delete it and list the providers in the module.`, { feature: place.feature });
+    if (DEFINITION_FILE.test(base) && rel !== definitionOf(ownModuleOf(place, rel, composedModuleOf))) plain(rel, `${rel} is a module-definition that is not beside a module of feature ${place.feature}; the definition of a module is its sibling ${path.posix.basename(definitionOf(ownModuleOf(place, rel, composedModuleOf)))}, one per application module, transport module or cli folder.`, { feature: place.feature });
     if (place.protocol && /\.module\.[cm]?tsx?$/u.test(base)) {
       const expected = `${place.feature}-${place.protocol}.module.ts`;
       if (place.below.length !== 3 || base !== expected) plain(rel, `${rel} is a second module of the ${place.protocol} transport of ${place.feature}; a transport folder has exactly one module, transport/${place.protocol}/${expected}, never one module per operation. List the operation's providers in that module and delete this file.`, { feature: place.feature, protocol: place.protocol });
@@ -88,13 +101,15 @@ function reportModuleClassLocation(file, statement, place, composedModuleOf, rep
   if (file.rel !== own) report(file, statement.name, `${statement.name.text} is a Nest module declared in ${file.rel}; a feature declares exactly its application module (${place.feature}.module.ts) and one module per transport folder (${place.feature}-<protocol>.module.ts), never a module per operation.`, { feature: place.feature });
 }
 
-function reportConfigurableModuleUses(file, checker, kit, ts, place, report) {
+function reportConfigurableModuleUses(file, checker, kit, ts, place, env) {
+  const own = ownModuleOf(place, file.rel, env.composedModuleOf);
+  const isDefinition = file.rel === definitionOf(own);
   kit.walk(file.sourceFile, node => {
-    if (ts.isNewExpression(node) && kit.isImportOf(checker, node.expression, 'ConfigurableModuleBuilder', '@nestjs/common')) {
-      report(file, node, `ConfigurableModuleBuilder builds a capability's module definition; feature ${place.feature} has static modules only, so declare the providers in its @Module.`, { feature: place.feature });
-    } else if (ts.isHeritageClause(node)) {
+    if (ts.isNewExpression(node) && kit.isImportOf(checker, node.expression, 'ConfigurableModuleBuilder', '@nestjs/common') && !isDefinition) {
+      env.report(file, node, `ConfigurableModuleBuilder builds the module definition of one module; in feature ${place.feature} it is written only in ${path.posix.basename(definitionOf(own))}, beside ${path.posix.basename(own)}.`, { feature: place.feature });
+    } else if (ts.isHeritageClause(node) && file.rel !== own) {
       for (const type of node.types) if (kit.isImportOf(checker, type.expression, 'ConfigurableModuleClass', '@nestjs/common')) {
-        report(file, type, `A feature module never extends ConfigurableModuleClass; feature ${place.feature} has static modules only.`, { feature: place.feature });
+        env.report(file, type, `ConfigurableModuleClass is extended by the module of its own definition only (${path.posix.basename(own)}); feature ${place.feature} declares no other configurable module.`, { feature: place.feature });
       }
     }
     return true;
@@ -118,7 +133,7 @@ function collectFeatureModules(graph, kit, ts, placeOf, composedModuleOf, report
     const checker = kit.checkerOf(file.sourceFile);
     const place = placeOf(file.rel);
     moduleClassesInFile(file, checker, place, modules, env);
-    if (place) reportConfigurableModuleUses(file, checker, kit, ts, place, report);
+    if (place) reportConfigurableModuleUses(file, checker, kit, ts, place, env);
   }
   return modules;
 }
@@ -203,7 +218,7 @@ export function checkModulePerTransport(input) {
   const composedBy = composedByProtocol(resolver);
 
   const tree = treeOf(config.root);
-  const transportModules = reportTransportFileShapes(tree, placeOf, plain);
+  const transportModules = reportTransportFileShapes(tree, placeOf, plain, composedModuleOf);
 
   const modules = collectFeatureModules(graph, kit, ts, placeOf, composedModuleOf, report);