@starci/hfs 3.0.0 → 4.0.1

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

@@ -41,10 +41,6 @@ export const HFS_RULE_IDS = [
   'HFS_WORK_IN_FE',
 ];
 
-const REQUIRED_COMMON = ['.gitattributes', '.github', '.gitignore', '.husky', 'hfs.json',
-  'eslint.config.mjs', 'package-lock.json', 'package.json', 'README.md',
-  'sonar-project.properties', 'tsconfig.json'];
-const REQUIRED_BACKEND = ['.sops.yaml', '.starcistacks', '.starciwork', 'jest.config.js', 'nest-cli.json', 'src'];
 const NON_NPM_ENTRIES = new Set(['pnpm-lock.yaml', 'pnpm-workspace.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb']);
 const RUNTIME_ROOT_MARKDOWN = new Set(['README.md', 'CONTEXT.md', 'CONTRIBUTING.md', 'CHANGELOG.md', 'THIRD_PARTY_NOTICES.md']);
 const PRODUCT_ROOT_MARKDOWN = new Set(['README.md']);
@@ -57,18 +53,21 @@ const RETIRED_TEST_FOLDER = /^src\/tests\/(?:harness|live|e2e\/live)(?:\/|$)/u;
 const EXTRA_TEST_CONFIG = /(?:^|\/)(?:jest[.-][^/]*(?:config\.[cm]?[jt]s|\.json)|jest-(?:e2e|int|integration|harness)[^/]*)$/u;
 const NODE_ENTRIES_SKIPPED = new Set(['node_modules', '.git']);
 
-/** The slot resolver of a repository: the caller's, else the one its hfs.json declares, else the profile's slots with no app declared. */
+/** The slot resolver of a side folder: the caller's, else the side view its app's hfs.json declares, else the profile's slots with no app declared. */
 function resolverOf(root, profile, given) {
   if (given) return given;
   try { return openHfs({ repoRoot: root }); } catch { /* an invalid hfs.json is HFS_DECLARATION_INVALID's finding, judged elsewhere */ }
-  return createSlotResolver(loadSlotManifest(), { profile, apps: [], optionalSlots: [], connections: [] });
+  return createSlotResolver(loadSlotManifest(), { profile, side: profile, apps: [], optionalSlots: [], connections: [], reads: [] });
 }
 
-/** The first path segment of every slot of the profile that may exist: the repository root entries (contracts/, docs/, src/ ...). */
-function slotRootEntries(resolver) {
-  const roots = new Set(['apps']);
+/**
+ * The first path segment of every slot of the scope that may exist: the root entries of a side (contracts/, docs/, src/ ...) or of
+ * the app (be/, fe/, .github/ ...). `scope` is the profile whose slots count (the app resolver answers for the sides too).
+ */
+function slotRootEntries(resolver, scope) {
+  const roots = new Set(scope === 'app' ? [] : ['apps']);
   for (const slot of resolver.slots()) {
-    if (slot.presence === 'forbidden') continue;
+    if (slot.presence === 'forbidden' || !slot.profiles.includes(scope)) continue;
     for (const variant of braceVariants(slot.path)) {
       const first = variant.split('/')[0];
       if (first && !/[*?<%]/u.test(first)) roots.add(first);
@@ -77,6 +76,11 @@ function slotRootEntries(resolver) {
   return roots;
 }
 
+/** The root entries the scope's required slots name (the first segment of every required path of the scope): hfs.json, be/, .starcistacks/ ... */
+function requiredRootEntries(resolver) {
+  return new Set(resolver.requiredPaths().paths.filter((entry) => !entry.side).map((entry) => entry.path.split('/')[0]));
+}
+
 /** The folders directly below src/tests/ that the be.tests.* slots declare (world, fixtures, integration, e2e, contract). */
 function slotTestChildren(resolver) {
   const children = new Set();
@@ -145,25 +149,28 @@ function fsFiles(root, relative = '') {
   return out;
 }
 
+/** The tree view of a list of tracked paths (posix, root-relative): what the git view answers, for a list already in hand. */
+export function trackedTreeView(tracked) {
+  const files = new Set(tracked);
+  return {
+    source: 'git',
+    top: [...new Set(tracked.map(file => file.split('/')[0]))],
+    children: dir => {
+      const prefix = `${dir}/`;
+      const names = new Set();
+      for (const file of tracked) if (file.startsWith(prefix)) names.add(file.slice(prefix.length).split('/')[0]);
+      return [...names];
+    },
+    hasDir: dir => tracked.some(file => file.startsWith(`${dir}/`)),
+    hasFile: file => files.has(file),
+    files: () => tracked,
+  };
+}
+
 /** Uniform tree view: top entries plus children(dir)/hasDir/hasFile answers over posix relatives. */
 function treeView(root) {
   const tracked = gitPaths(root);
-  if (tracked !== null) {
-    const files = new Set(tracked);
-    return {
-      source: 'git',
-      top: [...new Set(tracked.map(file => file.split('/')[0]))],
-      children: dir => {
-        const prefix = `${dir}/`;
-        const names = new Set();
-        for (const file of tracked) if (file.startsWith(prefix)) names.add(file.slice(prefix.length).split('/')[0]);
-        return [...names];
-      },
-      hasDir: dir => tracked.some(file => file.startsWith(`${dir}/`)),
-      hasFile: file => files.has(file),
-      files: () => tracked,
-    };
-  }
+  if (tracked !== null) return trackedTreeView(tracked);
   return {
     source: 'fs',
     top: fsChildren(root, '.'),
@@ -211,7 +218,7 @@ function scriptCommand(name) {
 }
 
 /** Presentation checks shared by the product HFS gate and this runtime's own standalone gate. */
-export function checkRepoPresentation({ root, runtime = false, tree = treeView(root), profile = 'be' }) {
+export function checkRepoPresentation({ root, runtime = false, tree = treeView(root), profile = 'app' }) {
   const violations = [];
   const finding = (ruleId, entry, message, line = 1) => violations.push({ ruleId, path: entry, line, column: 1, message });
   for (const entry of tree.top) {
@@ -333,7 +340,11 @@ function hooksPathNotRedirected({ root, finding }) {
   return { status: 'checked' };
 }
 
-function e2eInAutomaticGate({ root, tree, backend, finding }) {
+/**
+ * The app root's automatic gates never run integration, e2e or contract: the husky hooks and the root scripts they call, the unit
+ * scripts over the be side's jest configuration (`jestConfig`, app-relative), and the workflows that start on push or pull_request.
+ */
+function e2eInAutomaticGate({ root, tree, jestConfig, finding }) {
   const rule = 'HFS_E2E_IN_AUTOMATIC_GATE';
   let pkg = null;
   try { pkg = JSON.parse(readText(root, 'package.json') ?? ''); } catch { /* the package checks own invalid JSON */ }
@@ -358,18 +369,31 @@ function e2eInAutomaticGate({ root, tree, backend, finding }) {
     if (runsE2e(command)) finding(rule, 'package.json', `Script ${name} is run by a husky hook and touches integration, e2e or contract. They are manual only.`);
     for (const match of command.matchAll(/npm\s+run\s+([\w:.-]+)/gu)) pending.push(match[1]);
   }
-  // 2. Unit and coverage scripts on a jest repository select the unit project only and exclude src/tests.
-  if (backend && tree.hasFile('jest.config.js')) {
+  // 2. Unit and coverage scripts over the be side's jest configuration select the unit project only and exclude src/tests.
+  if (tree.hasFile(jestConfig)) {
     for (const name of UNIT_RUN_SCRIPTS) {
       const command = scripts[name];
       if (typeof command === 'string' && /\bjest\b/u.test(command) && !/--selectProjects\s+unit\b/u.test(command))
         finding(rule, 'package.json', `Script ${name} runs jest without --selectProjects unit and would run the integration, e2e or contract project.`);
     }
-    const jestConfig = readText(root, 'jest.config.js') ?? '';
-    if (/collectCoverageFrom/u.test(jestConfig) && !/!src\/tests\/(?:\*\*|e2e)/u.test(jestConfig))
-      finding(rule, 'jest.config.js', 'collectCoverageFrom must exclude src/tests/** so no integration, e2e or contract file counts toward coverage.');
+    const jestText = readText(root, jestConfig) ?? '';
+    if (/collectCoverageFrom/u.test(jestText) && !/!src\/tests\/(?:\*\*|e2e)/u.test(jestText))
+      finding(rule, jestConfig, 'collectCoverageFrom must exclude src/tests/** so no integration, e2e or contract file counts toward coverage.');
+  }
+  // 3. A workflow that starts on push or pull_request never runs e2e.
+  for (const file of tree.files().filter(entry => /^\.github\/workflows\/[^/]+\.ya?ml$/u.test(entry))) {
+    const text = readText(root, file);
+    if (text === null) continue;
+    const trigger = /^on:.*(?:\n(?:[ \t]+.*|)$)*/mu.exec(text)?.[0] ?? '';
+    if (!/\b(?:push|pull_request)\b/u.test(trigger)) continue;
+    if (runsE2e(withoutComments(text)))
+      finding(rule, file, `${file} runs e2e on push or pull_request. Move the e2e job to its own workflow with on: workflow_dispatch only.`);
   }
-  // 3. A back end's default tsconfig excludes the world, integration, e2e and contract trees.
+}
+
+/** The be side's default tsconfig excludes the world, integration, e2e and contract trees (they are checked by src/tests/tsconfig.json). */
+function testTreesOutOfDefaultProgram({ root, tree, finding }) {
+  const rule = 'HFS_E2E_IN_AUTOMATIC_GATE';
   const tsconfigText = readText(root, 'tsconfig.json');
   let tsconfig = null;
   try { tsconfig = tsconfigText === null ? null : JSON.parse(tsconfigText); } catch { /* the typecheck itself owns parsing */ }
@@ -378,19 +402,10 @@ function e2eInAutomaticGate({ root, tree, backend, finding }) {
     const excludesTestTrees = ['world', 'integration', 'e2e', 'contract'].every(tree => excludedText.includes(`src/tests/${tree}`));
     const defaultAll = tsconfig.include === undefined && tsconfig.files === undefined;
     const files = tree.files();
-    if (backend && files.some(file => /^src\/tests\/(?:world|integration|e2e|contract)\/.+\.[cm]?tsx?$/u.test(file)) && !excludesTestTrees &&
+    if (files.some(file => /^src\/tests\/(?:world|integration|e2e|contract)\/.+\.[cm]?tsx?$/u.test(file)) && !excludesTestTrees &&
         (defaultAll || JSON.stringify(tsconfig.include ?? []).includes('src')))
       finding(rule, 'tsconfig.json', 'The default tsconfig includes src/tests/{world,integration,e2e,contract}/**. Exclude those trees and check them with src/tests/tsconfig.json (typecheck:tests).');
   }
-  // 4. A workflow that starts on push or pull_request never runs e2e.
-  for (const file of tree.files().filter(entry => /^\.github\/workflows\/[^/]+\.ya?ml$/u.test(entry))) {
-    const text = readText(root, file);
-    if (text === null) continue;
-    const trigger = /^on:.*(?:\n(?:[ \t]+.*|)$)*/mu.exec(text)?.[0] ?? '';
-    if (!/\b(?:push|pull_request)\b/u.test(trigger)) continue;
-    if (runsE2e(withoutComments(text)))
-      finding(rule, file, `${file} runs e2e on push or pull_request. Move the e2e job to its own workflow with on: workflow_dispatch only.`);
-  }
 }
 
 export function checkHfs(config) {
@@ -401,29 +416,27 @@ export function checkHfs(config) {
   const tree = treeView(config.root);
   const violations = [];
   const finding = (ruleId, entry, message) => violations.push({ ruleId, path: entry, line: 1, column: 1, message });
-  const resolver = resolverOf(config.root, backend ? 'be' : 'fe', config.hfs);
-  const presentation = checkRepoPresentation({ root: config.root, tree, profile: backend ? 'be' : 'fe' });
-  violations.push(...presentation.violations);
-
-  const allowed = slotRootEntries(resolver);
+  const profile = backend ? 'be' : 'fe';
+  const resolver = resolverOf(config.root, profile, config.hfs);
+  // The README, the hooks, the workflows and the scripts are the app root's (checkAppRoot); a side folder is judged as the old
+  // repository root it stands for, less those.
+  const allowed = slotRootEntries(resolver, profile);
   for (const entry of [...tree.top].sort()) {
     if (NON_NPM_ENTRIES.has(entry) || /\.md$/iu.test(entry)) continue;
     if (frontend && !backend) {
-      if (entry === '.starciwork') { finding('HFS_WORK_IN_FE', entry, 'A frontend repository must not hold a .starciwork tree; Work records live in the backend repository.'); continue; }
-      if (entry === '.starcistacks') { finding('HFS_STACKS_IN_FE', entry, 'A frontend repository must not hold .starcistacks; stack declarations live in the backend repository.'); continue; }
-      if (entry === 'src') { finding('HFS_ROOT_SRC_FORBIDDEN_FE', entry, 'A frontend repository keeps source only under apps/<app>/src; the root src/ tree must move.'); continue; }
+      if (entry === '.starciwork') { finding('HFS_WORK_IN_FE', entry, 'The fe side must not hold a .starciwork tree; Work records live in the app root .starciwork.'); continue; }
+      if (entry === '.starcistacks') { finding('HFS_STACKS_IN_FE', entry, 'The fe side must not hold .starcistacks; stack declarations live in be/.starcistacks.'); continue; }
+      if (entry === 'src') { finding('HFS_ROOT_SRC_FORBIDDEN_FE', entry, 'The fe side keeps source only under apps/<app>/src; the fe/src/ tree must move.'); continue; }
     }
     if (frontend && !backend && (isFeTestPath(entry) || isFeTestPath(`${entry}/x`))) continue;   // a test entry of a front end is FE_NO_TESTS's, the one finding of that path
     if (!allowed.has(entry)) {
-      finding('HFS_ROOT_ENTRY_FORBIDDEN', entry, `Root entry ${entry} is not in the HFS ${backend ? 'backend' : 'frontend'} allowlist.`);
+      finding('HFS_ROOT_ENTRY_FORBIDDEN', entry, `Root entry ${entry} of the ${profile} side is not in the slots of the ${profile} side.`);
     }
   }
 
-  const required = new Set(REQUIRED_COMMON);
-  if (backend) for (const entry of REQUIRED_BACKEND) required.add(entry);
-  for (const entry of [...required].sort()) {
-    if (entry === 'apps' || entry === 'README.md' || entry === '.gitattributes') continue;
-    if (!tree.top.includes(entry)) finding('HFS_ROOT_ENTRY_MISSING', entry, `The ${backend ? 'backend' : 'frontend'} HFS tree requires root entry ${entry}.`);
+  for (const entry of [...requiredRootEntries(resolver)].sort()) {
+    if (entry === 'apps') continue;
+    if (!tree.top.includes(entry)) finding('HFS_ROOT_ENTRY_MISSING', entry, `The ${profile} side requires root entry ${entry}.`);
   }
 
   const apps = tree.children('apps').sort();
@@ -444,8 +457,9 @@ export function checkHfs(config) {
     }
     // next-env.d.ts is generated by Next and commonly ignored by Git; it is not
     // a reliable tracked-tree input.
-    if (frontend) for (const entry of ['package.json', 'next.config.ts', 'tsconfig.json', 'postcss.config.mjs']) {
-      if (!tree.hasFile(`apps/${app}/${entry}`)) missing.push(entry);
+    // A front-end app holds the files its slot requires at its own root (next.config.ts, tsconfig.json, ...; it has no package.json).
+    if (frontend) for (const required of resolver.requiredFiles(`apps/${app}/next.config.ts`).filter(entry => !entry.slice(`apps/${app}/`.length).includes('/'))) {
+      if (!tree.hasFile(required)) missing.push(required.slice(`apps/${app}/`.length));
     }
     if (missing.length) finding('HFS_APP_LAYOUT_INVALID', `apps/${app}`, `Application apps/${app} lacks ${missing.join(', ')} required by the HFS app layout.`);
   }
@@ -481,15 +495,13 @@ export function checkHfs(config) {
       finding('HFS_TEST_KIND_RETIRED', file, `${file} is a per-lane test config. One root jest.config.js declares exactly the unit, integration, e2e and contract projects.`);
   }
 
-  e2eInAutomaticGate({ root: config.root, tree, backend, finding });
-  const hooksPath = hooksPathNotRedirected({ root: config.root, finding });
+  if (backend) testTreesOutOfDefaultProgram({ root: config.root, tree, finding });
 
   return {
     violations,
     coverage: {
       status: 'checked',
       source: tree.source,
-      hooksPath,
       rootEntries: tree.top.length,
       apps,
       ruleIds: [...HFS_RULE_IDS],
@@ -497,6 +509,30 @@ export function checkHfs(config) {
   };
 }
 
+/**
+ * The HFS tree check of the app root (`resolver` is the app's): the README, the root entries the app-root slots allow and require,
+ * the automatic gates (hooks, the root scripts they call, the workflows) and the hooks path. `hfs check` runs it once per app; the
+ * machine runs checkHfs once per side folder.
+ */
+export function checkAppRoot({ root, resolver, tree = treeView(root) }) {
+  const violations = [];
+  const finding = (ruleId, entry, message) => violations.push({ ruleId, path: entry, line: 1, column: 1, message });
+  violations.push(...checkRepoPresentation({ root, tree, profile: 'app' }).violations);
+  const allowed = slotRootEntries(resolver, 'app');
+  for (const entry of [...tree.top].sort()) {
+    if (NON_NPM_ENTRIES.has(entry) || /\.md$/iu.test(entry)) continue;
+    if (!allowed.has(entry)) finding('HFS_ROOT_ENTRY_FORBIDDEN', entry, `Root entry ${entry} is not in the slots of the app root.`);
+  }
+  for (const entry of [...requiredRootEntries(resolver)].sort()) {
+    if (entry === 'README.md' || entry === '.gitattributes') continue;   // checkRepoPresentation reports these two
+    if (!tree.top.includes(entry)) finding('HFS_ROOT_ENTRY_MISSING', entry, `The app root requires root entry ${entry}.`);
+  }
+  const jestConfig = resolver.sides ? `be/${[...braceVariants(resolver.slot('be.tool-config').path)].find(file => file.startsWith('jest.config.'))}` : null;
+  e2eInAutomaticGate({ root, tree, jestConfig, finding });
+  const hooksPath = hooksPathNotRedirected({ root, finding });
+  return { violations, coverage: { status: 'checked', source: tree.source, hooksPath, rootEntries: tree.top.length } };
+}
+
 /** Keep tree findings visible even when the TypeScript architecture config is invalid. */
 export function checkHfsWithoutConfig(repositoryRoot) {
   let root;
@@ -505,9 +541,11 @@ export function checkHfsWithoutConfig(repositoryRoot) {
   }
   let kinds = [];
   try {
-    const authored = JSON.parse(fs.readFileSync(path.resolve(root, 'hfs.json'), 'utf8'));
-    if (authored.profile === 'be') kinds = ['backend'];
-    else if (authored.profile === 'fe') kinds = ['frontend'];
+    const opened = openHfs({ repoRoot: root });
+    // The app root is judged by checkAppRoot; a side folder by its side's tree check.
+    if (opened.repo.profile === 'app') return checkAppRoot({ root, resolver: opened });
+    if (opened.repo.profile === 'be') kinds = ['backend'];
+    else if (opened.repo.profile === 'fe') kinds = ['frontend'];
   } catch { /* A malformed hfs.json remains an HFS_DECLARATION_INVALID error. */ }
   if (!kinds.length) {
     try {

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

@@ -37,7 +37,8 @@ function relativeSource(repository, value, label) {
 }
 
 function parseContract(config) {
-  const manifest = JSON.parse(fs.readFileSync(path.join(config.root, 'package.json'), 'utf8'));
+  // The contract is declared in the app's one package.json (the app root; config.root is the fe side folder).
+  const manifest = JSON.parse(fs.readFileSync(path.join(config.packageRoot ?? config.root, 'package.json'), 'utf8'));
   const next = manifest?.starci?.codePatterns?.next;
   const value = next?.dataLifecycle;
   if (value === undefined) return null;
@@ -711,7 +712,7 @@ export function checkFrontendDataLifecycle(config, context) {
     details: ['package.json#starci.codePatterns.next.dataLifecycle is required when production source selects SWR', ...references.unsupported] } };
   reasons.push(...references.unsupported);
   let installed;
-  try { installed = installedSWR(config.root); } catch (error) {
+  try { installed = installedSWR(config.packageRoot ?? config.root); } catch (error) {
     return { violations, coverage: { status: 'unavailable', ruleIds, details: [String(error.message ?? error)] } };
   }
   if (installed.major !== contract.swr.major) reasons.push(`installed swr ${installed.version} does not match declared major ${contract.swr.major}`);

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

@@ -115,7 +115,7 @@ function frameworkTargets(config, context, checker, localFiles) {
 
 function classToken(ts, checker, node, localFiles) {
   const symbol = valueSymbol(ts, checker, node);
-  const declarations = symbol?.getDeclarations?.().filter(declaration => ts.isClassDeclaration(declaration)) ?? [];
+  const declarations = (symbol?.getDeclarations?.() ?? []).filter(declaration => ts.isClassDeclaration(declaration)) ?? [];
   const local = declarations.filter(declaration => localFiles.has(canonical(declaration.getSourceFile().fileName)));
   const keys = [...new Set(local.map(declaration => `${canonical(declaration.getSourceFile().fileName)}#${declaration.getStart(declaration.getSourceFile())}`))];
   return { key: keys.length === 1 ? keys[0] : null, external: declarations.length > 0 && local.length === 0 };

package/runtime/scripts/checks/architecture/symbols.mjs

@@ -8,7 +8,9 @@
  *                         exported `const Y = X` / `const Y = X.y` (a bare identifier or member that resolves to a function,
  *                         class, const or enum of the repository), `type Y = X` and `interface Y extends X {}` (no body, no
  *                         type arguments, no type parameters): a second name for one declaration. Rename the declaration,
- *                         or import it by its name.
+ *                         or import it by its name. A route file (slot fe.route) binding a declaration to a name Next.js
+ *                         requires of a route segment (generateMetadata, generateStaticParams, ...) is not a second name: the
+ *                         framework fixes that name, so no rename can remove it.
  * Specs and tests are not in the graph. The public entry of an owner is found the way dead-exports.mjs finds it.
  */
 import { canonical } from './config.mjs';
@@ -145,14 +147,23 @@ function declarationAliases(ts, checker, graph, statement) {
   return found;
 }
 
+/** The names Next.js reads from a route segment file (layout, page, route, ...): the framework fixes them. */
+const NEXT_SEGMENT_EXPORTS = new Set([
+  'generateMetadata', 'metadata', 'generateViewport', 'viewport', 'generateStaticParams', 'generateImageMetadata', 'generateSitemaps',
+  'dynamic', 'dynamicParams', 'revalidate', 'fetchCache', 'runtime', 'preferredRegion', 'maxDuration',
+]);
+const ROUTE_SLOT = 'fe.route';
+
 function aliasReexports({ context, graph }) {
   const kind = context.ts.SyntaxKind;
   const violations = [];
   for (const [rel, node] of graph.files) {
+    const frameworkName = name => node.slot === ROUTE_SLOT && NEXT_SEGMENT_EXPORTS.has(name);
     const point = target => node.sourceFile.getLineAndCharacterOfPosition(target.getStart(node.sourceFile));
     const checker = context.checkerFor(node.abs);
     for (const statement of node.sourceFile.statements) {
       for (const alias of declarationAliases(context.ts, checker, graph, statement)) {
+        if (frameworkName(alias.name)) continue;
         const at = point(alias.node);
         violations.push({
           ruleId: 'HFS_ALIAS_REEXPORT', path: rel, line: at.line + 1, column: at.character + 1, name: alias.name, aliasOf: alias.of,
@@ -170,7 +181,7 @@ function aliasReexports({ context, graph }) {
         continue;
       }
       for (const element of clause.elements) {
-        if (!element.propertyName || element.propertyName.text === element.name.text) continue;
+        if (!element.propertyName || element.propertyName.text === element.name.text || frameworkName(element.name.text)) continue;
         const at = point(element);
         violations.push({
           ruleId: 'HFS_ALIAS_REEXPORT', path: rel, line: at.line + 1, column: at.character + 1,

package/runtime/scripts/checks/architecture/test-world-files.mjs

@@ -3,25 +3,30 @@ import { allowsFile } from '../../lib/hfs-allows.mjs';
 import { DEFAULT_ENVIRONMENT, STACKS_DIRECTORY, STATEFUL_KINDS, namesOfService, readStack } from '../../lib/stack-services.mjs';
 
 /**
- * R47 `test-world-files` (BE_TEST_TOPOLOGY). Two judgements over the test world, read through slots, the repository's own
+ * R47 `test-world-files` (BE_TEST_TOPOLOGY). Judgements over the test world, read through slots, the repository's own
  * stack definition (`.starcistacks/<env>`, scripts/lib/stack-services.mjs) and the world's declaration
- * (`test-world.config.ts` of the test-world library), never through a path or a name list:
+ * (`test-world.config.ts`, read in the shape @starci/test-world defines), never through a path or a name list:
  *
  * 1. Files. `src/tests/world/` is the only test infrastructure location, and it holds only what its slot `allows`
  *    (knowledge/hfs/slots.yaml be.tests.world: global-setup.ts, global-teardown.ts, use-test-world.ts, and fakes/; kit/ is
  *    its own slot, be.tests.world.kit) plus files at its root whose role suffix is in ruleParams.be.suffixes
  *    (`stripe.client.ts`, `checkout.contracts.ts`, `test-world.config.ts`, ...). Every tracked file below the world root is
  *    matched by the slot's own entries through `allowsFile`.
- * 2. Fakes against the stack (owner refinement 2026-09-30). Every service the stack declares runs real in the world;
- *    `fakes/<provider>/` holds a network-edge fake of an external SaaS the team does not operate. A `fakes/<provider>/` that
- *    fakes a stack service (its own name, its image repository or a well-known alias of the image) is refused, except the one
- *    owner-approved exception: a stack service that is stateless compute needing special hardware or an external model
- *    (GPU inference, a self-hosted embedding model) and that the config declares in `fakedBy`:
- *    `fakedBy: { "<stack service>": { fake: "<fakes/ folder>", reason: "<non-empty>" } }`. A stack service of a stateful
- *    kind (database, cache, identity, storage, mail, queue, search) or with a persistent volume is never accepted, and a
- *    `fakedBy` entry that names a stack service or a fake folder that does not exist, or has no reason, is refused as stale
- *    or empty. The config's `stacks` names the stack environments the world runs (default `dev`); the machine reads the
- *    literal object of the config through the TypeScript AST and nothing else of it.
+ * 2. The declaration. `test-world.config.ts` declares the world in ONE form, the named export R89 allows:
+ *    `export const { useTestWorld, useSandbox } = defineTestWorld({ ... })` (an exported `const` initialized by a
+ *    `defineTestWorld(<object literal>)` call). A config without it (a default export, or a declaration the machine cannot
+ *    read) is refused: the world it declares could not be judged.
+ * 3. Fakes against the stack (owner refinement 2026-09-30). Every service the stack declares runs real in the world; a fake
+ *    (a `fakes/<provider>/` folder, or a `fakes` entry of the declaration such as `smtp: smtpFake()`) is a network-edge fake
+ *    of an external SaaS the team does not operate. A fake of a stack service (its own name, its image repository or a
+ *    well-known alias of the image) is refused, except the one owner-approved exception: a stack service that is stateless
+ *    compute needing special hardware or an external model (GPU inference, a self-hosted embedding model) whose `stacks` entry
+ *    declares it faked: `stacks: { "<stack service>": { fakedBy: "<fake>", reason: "<non-empty>" } }`. A stack service of a
+ *    stateful kind (database, cache, identity, storage, mail, queue, search) or with a persistent volume is never accepted, and
+ *    an entry that names a stack service or a fake (a `fakes` entry or a `fakes/` folder) that does not exist, or has no
+ *    reason, is refused as stale or empty. The declaration's `stack` (`".starcistacks/<env>"`) names the stack environment the
+ *    world runs (default `dev`); the machine reads the literal object of the declaration through the TypeScript AST and
+ *    nothing else of it.
  */
 export const TEST_WORLD_FILES_RULE_IDS = ['BE_TEST_TOPOLOGY'];
 
@@ -29,6 +34,8 @@ const RULE = 'BE_TEST_TOPOLOGY';
 const WORLD_SLOT = 'be.tests.world';
 const FAKES_DIRECTORY = 'fakes/';
 const CONFIG_FILE = 'test-world.config.ts';
+const DEFINE = 'defineTestWorld';
+const NAMED_FORM = `export const { useTestWorld, useSandbox } = ${DEFINE}({ ... })`;
 const defaultEnvironment = DEFAULT_ENVIRONMENT;
 const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 
@@ -39,51 +46,70 @@ const unwrap = (ts, node) => {
   return current;
 };
 const propertyOf = (ts, literal, key) => literal.properties.find(property => ts.isPropertyAssignment(property) && nameOf(ts, property.name) === key)?.initializer ?? null;
+const isExported = (ts, statement) => (statement.modifiers ?? []).some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword);
+const positionOf = (sourceFile, node) => {
+  const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+  return { line: position.line + 1, column: position.character + 1 };
+};
+
+/** The object literal of `defineTestWorld(<object literal>)`, or null. */
+function defineLiteral(ts, expression) {
+  const call = unwrap(ts, expression);
+  if (!call || !ts.isCallExpression(call) || !ts.isIdentifier(call.expression) || call.expression.text !== DEFINE) return null;
+  const [first] = call.arguments;
+  const literal = first ? unwrap(ts, first) : null;
+  return literal && ts.isObjectLiteralExpression(literal) ? literal : null;
+}
 
-/** The object literal a config file declares: `export default { ... }` or `export default defineTestWorld({ ... })`. */
+/** The declaration of the world: the object literal of an exported `const` initialized by `defineTestWorld({ ... })`, or null. */
 function configLiteral(ts, sourceFile) {
   for (const statement of sourceFile.statements) {
-    if (!ts.isExportAssignment(statement)) continue;
-    const expression = unwrap(ts, statement.expression);
-    if (ts.isObjectLiteralExpression(expression)) return expression;
-    if (ts.isCallExpression(expression)) {
-      const [first] = expression.arguments;
-      const literal = first ? unwrap(ts, first) : null;
-      if (literal && ts.isObjectLiteralExpression(literal)) return literal;
+    if (!ts.isVariableStatement(statement) || !isExported(ts, statement)) continue;
+    if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      const literal = declaration.initializer ? defineLiteral(ts, declaration.initializer) : null;
+      if (literal) return literal;
     }
   }
   return null;
 }
 
-/** `stacks` as a list of environment names: an array of strings, or the keys of an object literal. */
-function stacksOf(ts, literal) {
-  const node = literal ? propertyOf(ts, literal, 'stacks') : null;
+/** `stack` as the environment it names: the last segment of `".starcistacks/<env>"`; null when absent or not a literal. */
+function environmentOf(ts, literal) {
+  const node = literal ? propertyOf(ts, literal, 'stack') : null;
   const value = node ? unwrap(ts, node) : null;
-  if (!value) return null;
-  if (ts.isArrayLiteralExpression(value)) return value.elements.filter(element => ts.isStringLiteralLike(element)).map(element => element.text);
-  if (ts.isObjectLiteralExpression(value)) return value.properties.map(property => nameOf(ts, property.name)).filter(Boolean);
-  return null;
+  if (!value || !ts.isStringLiteralLike(value)) return null;
+  return value.text.split(/[\\/]+/u).filter(Boolean).at(-1) ?? null;
 }
 
-/** `fakedBy` entries: [{service, fake, reason, line, column}]; a value the reader cannot read statically has an empty fake and reason. */
+/** The keys of the declaration's `fakes` object literal, with their positions. */
+function fakeEntriesOf(ts, sourceFile, literal) {
+  const node = literal ? propertyOf(ts, literal, 'fakes') : null;
+  const value = node ? unwrap(ts, node) : null;
+  if (!value || !ts.isObjectLiteralExpression(value)) return [];
+  return value.properties
+    .map(property => ({ name: nameOf(ts, property.name), ...positionOf(sourceFile, property) }))
+    .filter(entry => entry.name);
+}
+
+/** The `stacks` entries that declare `fakedBy`: [{service, fake, reason, line, column}]; a value the reader cannot read statically has an empty fake and reason. */
 function fakedByOf(ts, sourceFile, literal) {
-  const node = literal ? propertyOf(ts, literal, 'fakedBy') : null;
+  const node = literal ? propertyOf(ts, literal, 'stacks') : null;
   const value = node ? unwrap(ts, node) : null;
   if (!value || !ts.isObjectLiteralExpression(value)) return [];
   const entries = [];
   for (const property of value.properties) {
     if (!ts.isPropertyAssignment(property)) continue;
-    const service = nameOf(ts, property.name);
     const body = unwrap(ts, property.initializer);
-    const fake = ts.isObjectLiteralExpression(body) ? propertyOf(ts, body, 'fake') : null;
-    const reason = ts.isObjectLiteralExpression(body) ? propertyOf(ts, body, 'reason') : null;
-    const position = sourceFile.getLineAndCharacterOfPosition(property.getStart(sourceFile));
+    if (!body || !ts.isObjectLiteralExpression(body)) continue;
+    const fake = propertyOf(ts, body, 'fakedBy');
+    if (!fake) continue;
+    const reason = propertyOf(ts, body, 'reason');
     entries.push({
-      service,
-      fake: fake && ts.isStringLiteralLike(fake) ? fake.text : '',
+      service: nameOf(ts, property.name),
+      fake: ts.isStringLiteralLike(fake) ? fake.text : '',
       reason: reason && ts.isStringLiteralLike(reason) ? reason.text.trim() : '',
-      line: position.line + 1,
-      column: position.character + 1,
+      ...positionOf(sourceFile, property),
     });
   }
   return entries;
@@ -123,7 +149,13 @@ export function checkTestWorldFiles(input) {
   const configPath = worldRoot === null ? null : `${worldRoot}${CONFIG_FILE}`;
   const configFile = configPath === null ? null : graph.files.get(configPath) ?? null;
   const literal = configFile ? configLiteral(ts, configFile.sourceFile) : null;
-  const environments = (literal ? stacksOf(ts, literal) : null) ?? [defaultEnvironment];
+  if (configFile && !literal) {
+    violations.push({
+      ruleId: RULE, path: configPath, line: 1, column: 1, slot: WORLD_SLOT,
+      message: `${configPath} declares no world the machine can read. Declare it in the one named form \`${NAMED_FORM}\` (an exported const of a ${DEFINE} call with an object literal, imported from @starci/test-world); a default export is refused by R89 and is not read.`,
+    });
+  }
+  const environments = [(literal ? environmentOf(ts, literal) : null) ?? defaultEnvironment];
   const services = [];
   for (const environment of environments) {
     let stack = null;
@@ -132,14 +164,15 @@ export function checkTestWorldFiles(input) {
   }
   const stackHint = `${STACKS_DIRECTORY}/${environments.join(', ')}`;
   const statefulWhy = service => (STATEFUL_KINDS.has(service.kind) ? `a ${service.kind} holds data the app reads back` : service.persistent ? 'the stack gives it a persistent volume' : null);
-  const declared = configFile ? fakedByOf(ts, configFile.sourceFile, literal) : [];
+  const declared = literal ? fakedByOf(ts, configFile.sourceFile, literal) : [];
+  const fakeEntries = literal ? fakeEntriesOf(ts, configFile.sourceFile, literal) : [];
 
   for (const entry of declared) {
     const service = services.find(candidate => candidate.name === entry.service);
     const problems = [];
     if (!service) problems.push(`${stackHint} declares no service ${entry.service}`);
     else if (statefulWhy(service)) problems.push(`${service.name} is stateful (${statefulWhy(service)}) and always runs real`);
-    if (!fakeProviders.has(entry.fake)) problems.push(`there is no fakes/${entry.fake || '<fake>'}/ folder`);
+    if (!fakeProviders.has(entry.fake) && !fakeEntries.some(fake => fake.name === entry.fake)) problems.push(`there is no fakes entry and no fakes/${entry.fake || '<fake>'}/ folder of that name`);
     if (entry.reason === '') problems.push('the reason is empty');
     if (problems.length > 0) {
       violations.push({
@@ -149,14 +182,19 @@ export function checkTestWorldFiles(input) {
     }
   }
 
-  for (const [provider, file] of [...fakeProviders].sort(([a], [b]) => a.localeCompare(b))) {
-    const service = services.find(candidate => namesOfService(candidate).includes(provider));
+  // Every fake the world runs: the repository's fakes/<provider>/ folders and the fakes entries of the declaration.
+  const fakes = [
+    ...[...fakeProviders].map(([provider, file]) => ({ name: provider, path: file, line: 1, column: 1, what: `fakes/${provider}/` })),
+    ...fakeEntries.filter(entry => !fakeProviders.has(entry.name)).map(entry => ({ name: entry.name, path: configPath, line: entry.line, column: entry.column, what: `the fakes entry ${entry.name}` })),
+  ].sort((a, b) => a.name.localeCompare(b.name));
+  for (const fake of fakes) {
+    const service = services.find(candidate => namesOfService(candidate).includes(fake.name));
     if (!service) continue;
-    if (declared.some(entry => entry.service === service.name && entry.fake === provider)) continue; // judged on its config entry above
+    if (declared.some(entry => entry.service === service.name && entry.fake === fake.name)) continue; // judged on its stacks entry above
     const why = statefulWhy(service);
     violations.push({
-      ruleId: RULE, path: file, line: 1, column: 1, slot: WORLD_SLOT,
-      message: `fakes/${provider}/ fakes ${service.name} (${service.image}), which ${stackHint} declares: a service of the repository's own stack runs real in the test world. ${why ? `${service.name} is stateful (${why}), so no exception applies. ` : `Only stateless compute that needs special hardware or an external model may be faked, and only when ${configPath ?? `${CONFIG_FILE} in the world`} declares it in fakedBy with a reason. `}Delete the fake and let the world run the real service; fakes/ is otherwise only for external SaaS the team does not operate.`,
+      ruleId: RULE, path: fake.path, line: fake.line, column: fake.column, slot: WORLD_SLOT,
+      message: `${fake.what} fakes ${service.name} (${service.image}), which ${stackHint} declares: a service of the repository's own stack runs real in the test world. ${why ? `${service.name} is stateful (${why}), so no exception applies. ` : `Only stateless compute that needs special hardware or an external model may be faked, and only when ${configPath ?? `${CONFIG_FILE} in the world`} declares it in its stacks entry ({ fakedBy, reason }). `}Delete the fake and let the world run the real service; fakes are otherwise only for external SaaS the team does not operate.`,
     });
   }
   return { violations, coverage: { status: 'checked', files } };