@starci/hfs 4.0.8 → 4.0.10

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

@@ -1,6 +1,8 @@
 import path from 'node:path';
 import { isInside } from './config.mjs';
-import { isUnshadowedCommonJsRequire, referencedExports, relativePath, sourceLocation, UNPROVEN_FRAMEWORK, unwrapExpression } from './typescript.mjs';
+import { referencedExports, relativePath, UNPROVEN_FRAMEWORK, unwrapExpression } from './typescript.mjs';
+import { anyDescendant, commonJsRequireReasons, constructedDecoratorKind as sharedConstructedDecoratorKind, decoratorCallee, moduleExportsOf, nodeDecorators, normalizedSymbol, normalizedSymbolValue, programSourcesOf, returnedExpressions, selectedNode, valueSymbol, violation } from './ast-walks.mjs';
+import { sourceLocation } from '../../lib/ts-ast.mjs';
 
 export const PUBLIC_CONTRACT_RULE_ID = 'BE_PUBLIC_CONTRACT_FORM';
 export const READONLY_BOUNDARY_RULE_ID = 'BE_READONLY_BOUNDARY';
@@ -19,42 +21,7 @@ function canonical(file) {
   return path.resolve(file);
 }
 
-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 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 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 frameworkKindForSymbol(symbol, targets) {
   const selected = targets.get(symbol);
@@ -69,125 +36,42 @@ function frameworkKindForSymbol(symbol, targets) {
   return null;
 }
 
-function returnedExpressions(ts, declaration) {
-  if ((ts.isArrowFunction(declaration) || ts.isFunctionExpression(declaration)) && !ts.isBlock(declaration.body)) return [declaration.body];
-  const body = ts.isFunctionDeclaration(declaration) || ts.isMethodDeclaration(declaration)
-    || ts.isArrowFunction(declaration) || ts.isFunctionExpression(declaration) ? declaration.body : null;
-  if (!body || !ts.isBlock(body)) return [];
-  const returned = [];
-  const visit = node => {
-    if (node !== body && (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node)
-      || ts.isArrowFunction(node) || ts.isMethodDeclaration(node))) return;
-    if (ts.isReturnStatement(node) && node.expression) returned.push(node.expression);
-    else ts.forEachChild(node, visit);
-  };
-  visit(body);
-  return returned;
-}
-
-function tracedFrameworkKinds(ts, checker, expression, targets, seen = new Set(), depth = 0) {
-  if (!expression) return new Set();
-  if (depth > 10) return new Set([UNPROVEN_FRAMEWORK]);
-  expression = unwrapExpression(ts, expression);
-  const selected = selectedNode(ts, expression);
-  const symbol = selected ? normalizedSymbol(ts, checker, selected) : null;
-  const direct = symbol ? frameworkKindForSymbol(valueSymbol(ts, checker, selected), targets) : null;
-  if (direct) return new Set([direct]);
-  if (ts.isArrowFunction(expression) || ts.isFunctionExpression(expression)) {
-    const kinds = new Set();
-    for (const returned of returnedExpressions(ts, expression)) {
-      for (const kind of tracedFrameworkKinds(ts, checker, returned, targets, seen, depth + 1)) kinds.add(kind);
-    }
-    return kinds;
-  }
-  if (ts.isCallExpression(expression)) {
-    const kinds = tracedFrameworkKinds(ts, checker, expression.expression, targets, seen, depth + 1);
-    if (kinds.size) return kinds;
-  }
-  if (!symbol || seen.has(symbol)) return new Set();
-  const nextSeen = new Set(seen).add(symbol);
-  const kinds = new Set();
-  for (const declaration of symbol.getDeclarations?.() ?? []) {
-    if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
-      for (const kind of tracedFrameworkKinds(ts, checker, declaration.initializer, targets, nextSeen, depth + 1)) kinds.add(kind);
-    }
-    if (ts.isShorthandPropertyAssignment(declaration)) {
-      const target = normalizedSymbolValue(ts, checker, checker.getShorthandAssignmentValueSymbol?.(declaration));
-      const kind = frameworkKindForSymbol(target, targets);
-      if (kind) kinds.add(kind);
-    }
-    if (ts.isPropertyAssignment(declaration)) {
-      for (const kind of tracedFrameworkKinds(ts, checker, declaration.initializer, targets, nextSeen, depth + 1)) kinds.add(kind);
-    }
-    for (const returned of returnedExpressions(ts, declaration)) {
-      for (const kind of tracedFrameworkKinds(ts, checker, returned, targets, nextSeen, depth + 1)) kinds.add(kind);
-    }
-  }
-  return kinds;
-}
+/* This module's trace through frameworkKindForSymbol (name lookup and node_modules marker) instead of the
+ * default symbol->kind map, plus the shorthand/property-assignment descent. */
+const FRAMEWORK_TRACE = {
+  directOf: (ts, checker, { selected, targets }) => frameworkKindForSymbol(valueSymbol(ts, checker, selected), targets),
+  shorthandOf: (ts, checker, target, targets) => frameworkKindForSymbol(target, targets),
+};
 
 function frameworkTargets(config, context, checker, localFiles) {
   const bySymbol = new Map();
   const reasons = [];
-  const program = context.programs.find(candidate => candidate.getTypeChecker() === checker);
-  if (!program) return { bySymbol, reasons: ['a TypeScript program checker could not be associated with its source'] };
-  for (const sourceFile of program.getSourceFiles()) {
-    if (!localFiles.has(canonical(sourceFile.fileName))
-      && !(sourceFile.isDeclarationFile && isInside(config.root, sourceFile.fileName)
-        && !sourceFile.fileName.replaceAll('\\', '/').includes('/node_modules/'))) continue;
+  const files = programSourcesOf(context, checker, localFiles, { root: config.root });
+  if (!files) return { bySymbol, 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 specifierNode = moduleSpecifier ?? importEquals;
-      const specifier = specifierNode?.text;
-      if (!specifier || !FRAMEWORK_EXPORTS.has(specifier)) continue;
-      const moduleSymbol = checker.getSymbolAtLocation(specifierNode);
-      if (!moduleSymbol) {
-        reasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot resolve ${specifier}`);
-        continue;
-      }
-      const selected = FRAMEWORK_EXPORTS.get(specifier);
-      const exports = new Map(checker.getExportsOfModule(moduleSymbol).map(symbol => [symbol.getName(), normalizedSymbolValue(context.ts, checker, symbol)]));
-      for (const name of referencedExports(context.ts, statement, selected)) {
-        const target = exports.get(name);
+      const bound = moduleExportsOf(context.ts, checker, statement);
+      if (!bound || !FRAMEWORK_EXPORTS.has(bound.specifier)) continue;
+      if (!bound.symbol) { reasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot resolve ${bound.specifier}`); continue; }
+      for (const name of referencedExports(context.ts, statement, FRAMEWORK_EXPORTS.get(bound.specifier))) {
+        const target = bound.exports.get(name);
         if (target) bySymbol.set(target, name);
-        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_EXPORTS.has(node.arguments[0].text)) {
-        reasons.push(`${relativePath(config.root, sourceFile.fileName)} uses a CommonJS ${node.arguments[0].text} binding whose contract role cannot be proved`);
-      }
-      context.ts.forEachChild(node, visitRequire);
-    };
-    visitRequire(sourceFile);
+    commonJsRequireReasons(context.ts, checker, sourceFile, (specifier) => FRAMEWORK_EXPORTS.has(specifier),
+      reasons, relativePath(config.root, sourceFile.fileName), 'binding whose contract role cannot be proved');
   }
   return { bySymbol, reasons };
 }
 
-function calledExpression(ts, decorator) {
-  return ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
-}
-
 function decoratorKind(ts, checker, decorator, targets) {
-  const selected = selectedNode(ts, calledExpression(ts, decorator));
+  const selected = selectedNode(ts, decoratorCallee(ts, decorator));
   return selected ? frameworkKindForSymbol(valueSymbol(ts, checker, selected), targets) : null;
 }
 
-function constructedDecoratorKind(ts, checker, decorator, targets) {
-  const kinds = tracedFrameworkKinds(ts, checker, calledExpression(ts, decorator), targets);
-  if (kinds.has(UNPROVEN_FRAMEWORK)) return 'unproven framework';
-  return kinds.size === 1 ? [...kinds][0] : kinds.size ? 'multiple framework' : null;
-}
-
-function decorators(ts, node) {
-  return ts.canHaveDecorators(node) ? ts.getDecorators(node) ?? [] : node.decorators ?? [];
-}
+const constructedDecoratorKind = (ts, checker, decorator, targets) =>
+  sharedConstructedDecoratorKind(ts, checker, decorator, targets, FRAMEWORK_TRACE);
 
 function modifiers(ts, node) {
   return ts.canHaveModifiers(node) ? ts.getModifiers(node) ?? [] : node.modifiers ?? [];
@@ -205,9 +89,7 @@ function readonlyMember(ts, node) {
   return hasModifier(ts, node, ts.SyntaxKind.ReadonlyKeyword);
 }
 
-function violation(config, sourceFile, node, ruleId, message, extra = {}) {
-  return { ruleId, path: relativePath(config.root, sourceFile.fileName), ...sourceLocation(sourceFile, node), message, ...extra };
-}
+
 
 function sourceRole(sourceFile) {
   const normalized = sourceFile.fileName.replaceAll('\\', '/');
@@ -221,7 +103,7 @@ function isFrameworkHelper(sourceFile, declaration, framework) {
   const role = sourceRole(sourceFile);
   if (role.transport || NON_API_SOURCE_ROLES.has(role.role) || NON_API_SOURCE_ROLES.has(role.base)) return true;
   if (declaration && declaration.name && /Module$/.test(declaration.name.text ?? '')) {
-    return decorators(framework.ts, declaration).some(decorator => decoratorKind(framework.ts, framework.checker, decorator, framework.targets) === 'Module');
+    return nodeDecorators(framework.ts, declaration).some(decorator => decoratorKind(framework.ts, framework.checker, decorator, framework.targets) === 'Module');
   }
   return false;
 }
@@ -442,19 +324,8 @@ function expressionOrigin(ts, checker, expression, seen = new Set(), depth = 0)
   return symbol;
 }
 
-function expressionReferencesOrigin(ts, checker, expression, expected) {
-  let found = false;
-  const visit = node => {
-    if (found) return;
-    if (expressionOrigin(ts, checker, node) === expected) {
-      found = true;
-      return;
-    }
-    ts.forEachChild(node, visit);
-  };
-  visit(expression);
-  return found;
-}
+const expressionReferencesOrigin = (ts, checker, expression, expected) =>
+  anyDescendant(ts, expression, (node) => expressionOrigin(ts, checker, node) === expected);
 
 function isSafePrimitiveProjection(ts, checker, expression, expected) {
   expression = unwrapExpression(ts, expression);
@@ -626,13 +497,13 @@ function checkInjectedClass(config, context, checker, declaration, classKind, ta
     .map(member => [propertyName(ts, member), member]).filter(([name]) => name));
   for (const member of declaration.members) {
     if (ts.isPropertyDeclaration(member)) {
-      const injected = decorators(ts, member).some(decorator => decoratorKind(ts, checker, decorator, targets) === 'Inject');
+      const injected = nodeDecorators(ts, member).some(decorator => decoratorKind(ts, checker, decorator, targets) === 'Inject');
       if (injected) checkReadonlyProperty(config, context, sourceFile, member, `Injected property ${propertyName(ts, member) ?? '(computed)'}`, violations);
       continue;
     }
     if (!ts.isConstructorDeclaration(member)) continue;
     for (const parameter of member.parameters) {
-      const explicitInject = decorators(ts, parameter).some(decorator => decoratorKind(ts, checker, decorator, targets) === 'Inject');
+      const explicitInject = nodeDecorators(ts, parameter).some(decorator => decoratorKind(ts, checker, decorator, targets) === 'Inject');
       if (!classKind && !explicitInject) continue;
       const parameterProperty = modifiers(ts, parameter).some(modifier => [ts.SyntaxKind.PublicKeyword, ts.SyntaxKind.PrivateKeyword,
         ts.SyntaxKind.ProtectedKeyword, ts.SyntaxKind.ReadonlyKeyword].includes(modifier.kind));
@@ -729,7 +600,7 @@ export function checkBackendContracts(config, context) {
     };
     collectClasses(sourceFile);
     for (const statement of classes) {
-      const classDecorators = decorators(ts, statement);
+      const classDecorators = nodeDecorators(ts, statement);
       const kindsByDecorator = classDecorators.map(decorator => decoratorKind(ts, checker, decorator, framework.targets));
       const directKinds = kindsByDecorator.filter(Boolean);
       for (const [index, decorator] of classDecorators.entries()) if (!kindsByDecorator[index]) {
@@ -740,15 +611,15 @@ export function checkBackendContracts(config, context) {
       }
       const classKind = directKinds.find(kind => NEST_CREATED.has(kind)) ?? null;
       for (const member of statement.members) for (const decorated of [member, ...(ts.isConstructorDeclaration(member) ? member.parameters : [])]) {
-        for (const decorator of decorators(ts, decorated)) if (!decoratorKind(ts, checker, decorator, framework.targets)) {
+        for (const decorator of nodeDecorators(ts, decorated)) if (!decoratorKind(ts, checker, decorator, framework.targets)) {
           const constructed = constructedDecoratorKind(ts, checker, decorator, framework.targets);
           if (constructed === 'Inject' || constructed === 'unproven framework') {
             readonlyReasons.push(`${relativePath(config.root, sourceFile.fileName)} has a constructed ${constructed} injection decorator identity`);
           }
         }
       }
-      const hasInjectedMember = statement.members.some(member => decorators(ts, member).some(decorator => decoratorKind(ts, checker, decorator, framework.targets) === 'Inject')
-        || (ts.isConstructorDeclaration(member) && member.parameters.some(parameter => decorators(ts, parameter)
+      const hasInjectedMember = statement.members.some(member => nodeDecorators(ts, member).some(decorator => decoratorKind(ts, checker, decorator, framework.targets) === 'Inject')
+        || (ts.isConstructorDeclaration(member) && member.parameters.some(parameter => nodeDecorators(ts, parameter)
           .some(decorator => decoratorKind(ts, checker, decorator, framework.targets) === 'Inject'))));
       if (classKind || hasInjectedMember) {
         injectedClasses += 1;

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

@@ -8,7 +8,8 @@
  *                      so a file only a spec imports is dead, on purpose. Type-only imports reach a file.
  *
  * Owner = every graph.ownerRoots unit whose tier is not `app` and whose public entry file is in the graph (index.ts or
- * index.tsx, a package's src/index.ts). The exported names of the entry are its named exports, `export { a as b }`,
+ * index.tsx, a package's src/index.ts). The `entries` its slot declares (slot data, e.g. fe.modules.db browser.ts) are further
+ * public entries of the same owner, judged exactly like the entry. The exported names of an entry are its named exports, `export { a as b }`,
  * `export { x } from`, declarations with `export`, and `default` for `export default`. `export *` is refused by owners.mjs
  * and contributes no name here.
  *
@@ -16,13 +17,17 @@
  * 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
  * 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 one exception (unit test
- * standard): a `<name>.service.spec.ts` (the only unit spec kind) and a `*.builder.ts` under src/tests/fixtures/builders read from
- * disk count as consumers, because a spec can only provide an Inject*() token or a param type the entry exports. An integration
+ * 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
+ * (ruleParams.be.logicRoles: `<name>.policy.spec.ts`, `<name>.client.spec.ts`, ...), a
+ * unit spec of a webhook, gateway or subscription door (`.webhook.spec.ts`, `.gateway.spec.ts`, `.subscription.spec.ts`: a door has no service of its own), a
+ * `*.builder.ts` under src/tests/fixtures/builders, and a file of the test world (slots be.tests.world and be.tests.world.kit, which
+ * open and migrate the real databases of the e2e run) read from disk count as consumers, because a spec can only provide an
+ * Inject*() token or a param type the entry exports, and the world wires the same capabilities the apps do. An integration
  * spec (slot be.tests.integration, `src/tests/integration/<capability>/*.integration-spec.ts`) counts as a consumer of exactly one
  * owner: the integration (slot be.integrations, `src/modules/integrations/<provider>/`) whose provider folder is its capability
  * folder, because R112 makes that spec register the integration module and reference its ErrorCode enum. Specs of any other kind,
- * an integration spec importing another owner, e2e specs and world files still do not count. A consumer inside the owner is
+ * an integration spec importing another owner, and e2e specs still do not count. A consumer inside the owner is
  * skipped like any inside consumer.
  */
 import fs from 'node:fs';
@@ -51,6 +56,12 @@ export function entryOf(graph, config, key, owner) {
   return null;
 }
 
+/** The additional public entry files (repository-relative, in the graph) the slot manifest declares for the owner (slot field `entries`, on the slot that holds its entry file). */
+function extraEntries(graph, entry) {
+  const found = graph.resolver.classifyPath(entry);
+  return (found.slot ? graph.resolver.slot(found.slot)?.entries ?? [] : []).map(name => `${found.root}/${name}`).filter(rel => graph.files.has(rel));
+}
+
 /** Names an import/export declaration takes from its target: {all} or {pairs: [{imported, exported}]}. */
 function bindingsOf(ts, declaration) {
   const kind = ts.SyntaxKind;
@@ -171,7 +182,22 @@ function deadFiles(graph, config) {
   return { violations, judged, roots: roots.size };
 }
 
-const TEST_CONSUMER = /^(?:(?:src|apps)\/.+\.service\.spec\.ts|src\/tests\/fixtures\/builders\/.+\.builder\.ts)$/u;
+/** The unit spec of a webhook, gateway or subscription door: a door has no service of its own, so its spec is the only unit spec of its kind. */
+const DOOR_SPEC = /^src\/features\/(?:webhooks|realtime)\/.+\.(?:webhook|gateway|subscription)\.spec\.ts$/u;
+const BUILDER_CONSUMER = /^src\/tests\/fixtures\/builders\/.+\.builder\.ts$/u;
+/** The test world slots (knowledge/hfs/slots.yaml): their files wire the real capabilities of the e2e run. */
+const WORLD_SLOTS = new Set(['be.tests.world', 'be.tests.world.kit']);
+
+/** Whether `rel` is a test file that counts as a consumer of any owner: a unit role spec, a fixture builder, a world file. */
+function testConsumer(graph, rel) {
+  const params = graph.resolver.ruleParams();
+  const specs = [...(params.unitRoles ?? []).map(role => role.spec), ...(params.logicRoles ?? []).map(role => `${role}.spec`)];
+  if (/^(?:src|apps)\//u.test(rel) && specs.some(spec => rel.endsWith(`.${spec}.ts`))) return true;
+  if (DOOR_SPEC.test(rel)) return true;
+  if (BUILDER_CONSUMER.test(rel)) return true;
+  const classified = graph.resolver.classifyPath(rel);
+  return WORLD_SLOTS.has(classified.slot) && classified.status !== 'forbidden' && /\.tsx?$/u.test(rel);
+}
 /** The slot of integration specs and the slot of the integrations they pair with by folder (knowledge/hfs/slots.yaml). */
 const INTEGRATION_SPEC_SLOT = 'be.tests.integration';
 const INTEGRATION_SLOT = 'be.integrations';
@@ -189,16 +215,17 @@ function inIntegrationOf(graph, to, provider) {
 }
 
 /**
- * Pseudo edges (read from disk, outside the production program) to graph files: from the unit specs of services and the fixture
- * builders to anything, and from an integration spec only to the integration of its own provider folder.
+ * Pseudo edges (read from disk, outside the production program) to graph files: from the unit role specs, the fixture builders and
+ * the test world files to anything, and from an integration spec only to the integration of its own provider folder.
  */
 function testConsumerEdges({ context, graph, config }) {
   const { ts } = context;
   const options = context.projects?.[0]?.options ?? {};
   const edges = [];
   const consumers = [...treeOf(config.root).files]
-    .map(file => ({ file, provider: TEST_CONSUMER.test(file) ? null : integrationSpecProvider(graph, file) }))
-    .filter(({ file, provider }) => provider !== null || TEST_CONSUMER.test(file))
+    .map(file => ({ file, any: testConsumer(graph, file) }))
+    .map(({ file, any }) => ({ file, provider: any ? null : integrationSpecProvider(graph, file), any }))
+    .filter(({ any, provider }) => any || provider !== null)
     .sort((a, b) => a.file.localeCompare(b.file));
   for (const { file: rel, provider } of consumers) {
     const abs = path.join(config.root, ...rel.split('/'));
@@ -263,25 +290,27 @@ export function checkDeadExports({ context, graph, config }) {
     const entry = entryOf(graph, config, key, owner);
     if (!entry) continue;
     owners += 1;
-    const names = exportedNames(ts, graph.files.get(entry).sourceFile);
-    const used = consumed(entry, key, 0, new Set([entry]));
-    // A consumer outside the owner that imports a file the entry re-exports by name reaches the entry's export of that name.
-    for (const edge of graph.edges) {
-      if (edge.from !== entry || !edge.reexport || graph.unit(edge.to) !== key) continue;
-      const reexport = bindingsOf(ts, edge.edge.declaration);
-      const inner = consumed(edge.to, key, 0, new Set([entry, 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);
-    }
-    for (const [name, line] of names) {
-      exports += 1;
-      if (used.all || used.names.has(name)) continue;
-      violations.push({
-        ruleId: 'HFS_UNUSED_EXPORT',
-        path: entry, line, column: 1,
-        name, owner: owner.root, slot: owner.slot,
-        message: `${entry} exports ${name}, but no production file outside ${owner.root || 'the repository root'} imports it; remove the export (only a service unit spec, a fixture builder, or an integration spec of this integration's own provider folder counts besides production files).`,
-      });
+    for (const publicEntry of [entry, ...extraEntries(graph, entry)]) {
+      const names = exportedNames(ts, graph.files.get(publicEntry).sourceFile);
+      const used = consumed(publicEntry, key, 0, new Set([publicEntry]));
+      // A consumer outside the owner that imports a file the entry re-exports by name reaches the entry's export of that name.
+      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 inner = consumed(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);
+      }
+      for (const [name, line] of names) {
+        exports += 1;
+        if (used.all || used.names.has(name)) continue;
+        violations.push({
+          ruleId: 'HFS_UNUSED_EXPORT',
+          path: publicEntry, line, column: 1,
+          name, owner: owner.root, slot: owner.slot,
+          message: `${publicEntry} exports ${name}, but no production file outside ${owner.root || 'the repository root'} imports it; remove the export (only a unit role spec, a fixture builder, a test world file, or an integration spec of this integration's own provider folder counts besides production files).`,
+        });
+      }
     }
   }
   const files = deadFiles(graph, config);

package/runtime/scripts/hfs/architecture/doc-language.mjs

@@ -16,7 +16,7 @@ export const DOC_LANGUAGE_RULE_IDS = ['HFS_DOC_NOT_ENGLISH'];
 
 const RULE = 'HFS_DOC_NOT_ENGLISH';
 /** The top-level folders whose documents this check reads. */
-export const DOCUMENT_ROOTS = Object.freeze(['knowledge', 'docs', 'src', 'apps']);
+const DOCUMENT_ROOTS = Object.freeze(['knowledge', 'docs', 'src', 'apps']);
 
 export function checkDocLanguage({ config, graph }) {
   const resolver = graph.resolver;

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

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { machineKit } from './machine-ast.mjs';
+import { isTestWorldSlot } from '../test-world-slot.mjs';
 
 /**
  * R33 `entrypoint-only-in-apps` (BE_ENTRYPOINT_ONLY_IN_APPS). A process starts in `apps/<app>/src/main.ts` only:
@@ -34,7 +35,7 @@ export function checkEntrypoints(input) {
     }
   };
   for (const file of graph.files.values()) {
-    const isMain = (Boolean(file.slot?.startsWith('be.app.')) && path.posix.basename(file.rel) === 'main.ts') || file.slot === 'be.tests.world';
+    const isMain = (Boolean(file.slot?.startsWith('be.app.')) && path.posix.basename(file.rel) === 'main.ts') || isTestWorldSlot(file.slot);
     const checker = kit.checkerOf(file.sourceFile);
     const report = (node, message) => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message });
     kit.walk(file.sourceFile, node => {

package/runtime/scripts/hfs/architecture/fe-slot-allows.mjs

@@ -8,9 +8,9 @@ import { isFeTestPath } from '../rules/fe-no-tests.mjs';
  * Every tracked file of such a slot is matched against the `requires` and `allows` entries of its slot; a file no entry names is a
  * finding - `page.tsx` in a hooks domain, a `[lang]` segment under `app/`, a stray file beside a component or at a feature
  * root. A file that sits where the slot expects a folder (`hooks/useX.ts`, so the "domain" is a file name) is one too.
- * Files no slot owns are HFS_PATH_NO_SLOT's (`hfs check`), so together every front-end file is placed by exactly one slot and
+ * Files no slot owns are HFS_PATH_NO_SLOT's (`starci app check`), so together every front-end file is placed by exactly one slot and
  * named by it. A test path (a `.spec.tsx` or `.test.tsx` beside a component, a test directory or test tooling) is FE_NO_TESTS's
- * (R97, contract-change fe-no-tests): that rule is the one finding of such a file, so this check leaves it alone, as
+ * (R97 FE_NO_TESTS): that rule is the one finding of such a file, so this check leaves it alone, as
  * HFS_PATH_NO_SLOT does (scripts/hfs/path-findings.mjs).
  */
 export const FE_SLOT_ALLOWS_RULE_IDS = ['FE_SLOT_FILE_ROLE'];

package/runtime/scripts/hfs/architecture/feature-shape.mjs

@@ -5,7 +5,7 @@ import { allowsFile } from '../allows.mjs';
 /**
  * R29 `feature-shape` (BE_FEATURE_SHAPE). A feature root holds `index.ts`, `<feature>.module.ts`, `application/`,
  * `transport/<protocol>/` and `messages/` only, and each of those folders holds only what its slot `allows` (knowledge/hfs/
- * slots.yaml: be.feature, be.feature.application, be.feature.application.support, be.transport.*, be.feature.transport.cli,
+ * slots.yaml: be.feature, be.feature.application, be.feature.application.support, be.transport.*,
  * be.feature.messages). Every tracked file below a feature root is classified by the slot resolver and matched against
  * the `requires` and `allows` entries of the slot that owns it; a directory that no slot owns (an unknown protocol under
  * `transport/`, a `graphql/` folder under `application/`) is refused because its files fall back to the feature root slot.
@@ -31,7 +31,10 @@ export function checkFeatureShape({ config, graph }) {
     const feature = path.posix.basename(owner.root);
     const where = `${verdict.slot} (${verdict.root})`;
     if (verdict.slot === owner.slot) {
-      // The feature root slot owns only the files at the root; anything deeper sits in a directory no slot claims.
+      // A file the feature root slot itself allows is in place (the cli feature root allows its <group>/ folders); any other file
+      // deeper than the root sits in a directory no slot claims.
+      // A directory entry (`transport/`, `application/`) is held by its own slots: below it, only those slots admit a file.
+      if (verdict.allowed && !String(verdict.entry ?? '').endsWith('/')) continue;
       if (verdict.relative.includes('/')) {
         const folder = verdict.relative.split('/')[0];
         report(file, `${file} sits in ${owner.root}/${folder}/, which no slot owns; a feature root holds only ${verdict.allows.join(', ')}, and transport/ holds one folder per protocol a slot names. Move it to application/ or a transport/<protocol>/ folder, or delete it.`,

package/runtime/scripts/hfs/architecture/framework-pinned.mjs

@@ -1,6 +1,6 @@
 // framework-pinned.mjs - the Next.js files that only load from a source root (the directory holding
 // app/). Authored once in knowledge/patterns/fe/folder.yaml FE-FOLDER-1 (frameworkPinnedRootFiles), never
-// hard-coded here (supervisor ruling, nivo wf-nivo-fe-debt-mug06w7h inc-2e42a24b74e4). Read by the architecture
+// hard-coded here (a supervisor ruling). Read by the architecture
 // check (FE_SOURCE_LAYOUT_INVALID).
 //
 // An unreadable or malformed list is a broken install, not "no pinned files": the reader throws