@starci/eslint-canon-fe 7.1.2 → 8.0.1

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 } };

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

@@ -5,6 +5,7 @@ import { canonical, isInside, slash } from './config.mjs';
 import { sameOrUnder } from '../../lib/path-key.mjs';
 import { createTypeScriptProgram, readTypeScriptProject, resolveTypeScriptModule, sharedInProgramRun, typeScriptProjectReferencePath } from '../typescript-programs.mjs';
 import { readJsonFile } from '../../lib/json.mjs';
+import { locateDeclaration } from '../../lib/hfs-slots.mjs';
 
 const CODE_EXTENSIONS = /\.(?:[cm]?[jt]sx?)$/i;
 const TEST_FILE = /(?:^|[.-])(?:spec|test)\.[cm]?[jt]sx?$/i;
@@ -16,14 +17,14 @@ export const GENERATED_SEGMENTS = new Set(['.next', '.turbo', '.vercel', '.outpu
 export function isGeneratedPath(root, fileName) {
   return slash(path.relative(root, fileName)).split('/').slice(0, -1).some(segment => GENERATED_SEGMENTS.has(segment));
 }
-// A `<tool>.config.*` or `<tool>.setup.*` module beside a package manifest (next.config.ts,
-// postcss.config.mjs) is build tooling a broad `**/*.ts` include pulls in; a `*.config.ts` inside a source tree
-// (src/config/database.config.ts) has no manifest beside it and stays source. The architecture program still
-// reads tooling modules (a profile may declare one as source); check-scoped-lint does not make one a canon
-// lint subject unless the profile's sourceGlobs name it.
+// A `<tool>.config.*` or `<tool>.setup.*` module at the root of a project (beside a package manifest or a tsconfig.json:
+// next.config.ts and postcss.config.mjs of an app, which has no package.json of its own) is build tooling a broad `**/*.ts`
+// include pulls in; a `*.config.ts` inside a source tree (src/config/database.config.ts) has neither beside it and stays source.
+// The architecture program still reads tooling modules (a profile may declare one as source); the lint (hfs lint) judges one only
+// through the repository's own eslint.config.
 const TOOLING_MODULE = /^[^/]+\.(?:config|setup)\.[cm]?[jt]sx?$/i;
 export function isToolingModule(fileName) {
-  return TOOLING_MODULE.test(path.basename(fileName)) && fs.existsSync(path.join(path.dirname(fileName), 'package.json'));
+  return TOOLING_MODULE.test(path.basename(fileName)) && ['package.json', 'tsconfig.json'].some((manifest) => fs.existsSync(path.join(path.dirname(fileName), manifest)));
 }
 
 function diagnosticMessage(ts, diagnostic) {
@@ -48,9 +49,12 @@ function compilerError(ts, root, diagnostic, project, ruleId = 'ARCH_TSCONFIG_IN
   };
 }
 
-/** Load TypeScript through the target package boundary, never through StarCi's own dependency graph. */
+/**
+ * Load TypeScript through the target package boundary, never through StarCi's own dependency graph. A side folder of an app has no
+ * package.json of its own: the app root's one manifest is the boundary its TypeScript is installed under.
+ */
 export function loadTargetTypeScript(repositoryRoot) {
-  const packageFile = path.join(repositoryRoot, 'package.json');
+  const packageFile = path.join(locateDeclaration(repositoryRoot).appRoot, 'package.json');
   if (!fs.existsSync(packageFile)) throw Error('ARCH_TYPESCRIPT_MISSING: target package.json is required to resolve target-installed TypeScript.');
   const targetRequire = createRequire(packageFile);
   let resolved;
@@ -189,7 +193,8 @@ function workspaceMetadata(config) {
         || backendAppRoots.some(appRoot => isInside(appRoot, root) || isInside(root, appRoot)) };
   };
   const roots = config.workspaces.map(create);
-  const rootPackage = readJson(path.join(config.root, 'package.json'));
+  // A side of an app has no package.json: the app root's one manifest names the package the side's root files belong to.
+  const rootPackage = readJson(path.join(config.packageRoot ?? config.root, 'package.json')) ?? {};
   roots.push({ root: canonical(config.root), relative: '.', name: typeof rootPackage.name === 'string' ? rootPackage.name : null, exports: rootPackage.exports,
     app: config.frontend.routes.some(item => isInside(config.root, path.join(config.root, ...item.split('/')))) || config.kinds.includes('backend') });
   return roots.sort((a, b) => b.root.length - a.root.length);
@@ -415,20 +420,29 @@ function typeScriptContext(config, loaded, paths) {
       .map(item => compilerError(ts, config.root, item, relative, 'ARCH_SYNTAX_INVALID')));
     projects.push({ relative, program, options: parsed.options });
   }
-  const fileMap = new Map();
-  const checkerByFile = new Map();
   const occurrences = new Map();
+  const sourceIn = new Map();
   for (const project of projects) {
     for (const sourceFile of project.program.getSourceFiles().filter(file => isProductionSource(config.root, file))) {
       const name = canonical(sourceFile.fileName);
-      if (!fileMap.has(name)) {
-        fileMap.set(name, sourceFile);
-        checkerByFile.set(name, project.program.getTypeChecker());
-      }
       if (!occurrences.has(name)) occurrences.set(name, []);
       occurrences.get(name).push(project);
+      sourceIn.set(`${project.relative}|${name}`, sourceFile);
     }
   }
+  // The deepest project directory holding a file owns it: its source file, its checker and its resolution. A side or repository
+  // root tsconfig without paths must not shadow the app project whose aliases (`@/*`) the file actually uses.
+  const owningProject = (candidates, file) => candidates.filter(item => isInside(path.dirname(path.join(config.root, ...item.relative.split('/'))), file))
+    .sort((x, y) => y.relative.split('/').length - x.relative.split('/').length)[0] ?? candidates[0];
+  const fileMap = new Map();
+  const checkerByFile = new Map();
+  const ownerByFile = new Map();
+  for (const [name, candidates] of occurrences) {
+    const owner = owningProject(candidates, name);
+    ownerByFile.set(name, owner);
+    fileMap.set(name, sourceIn.get(`${owner.relative}|${name}`));
+    checkerByFile.set(name, owner.program.getTypeChecker());
+  }
   const files = [...fileMap.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, file]) => file);
   const edges = new Map([...fileMap.keys()].map(file => [file, []]));
   for (const [file, sourceFile] of fileMap) {
@@ -441,11 +455,7 @@ function typeScriptContext(config, loaded, paths) {
   const workspaceNames = new Set(workspaces.map(item => item.name).filter(Boolean));
   for (const [from, sourceFile] of fileMap) {
     const owningWorkspace = workspaceOf(workspaces, from);
-    const candidates = occurrences.get(from) ?? [];
-    // The deepest project directory holding the file owns its resolution: a root tsconfig without paths must not
-    // shadow the app project whose aliases the file actually uses.
-    const project = candidates.filter(item => isInside(path.dirname(path.join(config.root, ...item.relative.split('/'))), from))
-      .sort((x, y) => y.relative.split('/').length - x.relative.split('/').length)[0] ?? candidates[0];
+    const project = ownerByFile.get(from);
     if (!project) continue;
     const references = moduleReferences(ts, sourceFile, project.program.getTypeChecker());
     for (const item of references.unproven) errors.push({
@@ -485,6 +495,21 @@ function typeScriptContext(config, loaded, paths) {
       // project is then the boundary it always was.
       const reviewable = isInside(config.root, actualTarget)
         || (config.repository && isInside(config.repository, actualTarget) && !slash(actualTarget).includes('/node_modules/'));
+      // A side of an app (config.root is be/ or fe/) imports nothing of the app outside itself: the root holds no source, the other
+      // side is another program, and a declared read (sides.fe.reads, be/contracts/) is codegen input, never an import.
+      const crossesSide = config.packageRoot !== undefined && config.packageRoot !== config.root
+        && isInside(config.packageRoot, actualTarget) && !isInside(config.root, actualTarget) && !slash(actualTarget).includes('/node_modules/');
+      if (internal && crossesSide) {
+        errors.push({
+          ruleId: 'ARCH_INTERNAL_IMPORT_OUTSIDE',
+          project: project.relative,
+          path: relativePath(config.root, sourceFile.fileName),
+          ...sourceLocation(sourceFile, reference.node),
+          specifier: reference.specifier,
+          message: `Internal import ${reference.specifier} leaves the ${path.basename(config.root)} side for ${slash(path.relative(config.packageRoot, actualTarget))}; nothing crosses the sides of an app.`,
+        });
+        continue;
+      }
       if (internal && !reviewable) {
         errors.push({
           ruleId: 'ARCH_INTERNAL_IMPORT_OUTSIDE',

package/runtime/scripts/checks/typescript-programs.mjs

@@ -4,8 +4,8 @@ import path from 'node:path';
 
 // One TypeScript program per (compiler, root names, compiler options, project references) inside a program run, and
 // one value per (kind, compiler, input) for what callers derive from those programs (the architecture context).
-// check-scoped-lint opens one run around its architecture check and its script checkers and releases it before
-// ESLint and the base measurement, so nothing built here outlives the run that built it. Outside a run every call
+// A caller (canon-scan's architecture machine, a script checker) opens one run around its work and releases it after,
+// so nothing built here outlives the run that built it. Outside a run every call
 // builds afresh.
 const runs = new AsyncLocalStorage();
 

package/runtime/scripts/lib/hfs-path-findings.mjs

@@ -8,11 +8,18 @@ import { allowsFile } from './hfs-allows.mjs';
 import { isFeTestPath } from './hfs-rules/fe-no-tests.mjs';
 import { slotOwnsSecrets } from './hfs-rules/secrets.mjs';
 import { specPlacementFindings } from './hfs-rules/spec-placement.mjs';
+import { APP_SCOPE } from './hfs-slots.mjs';
 
 const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const SOURCE_ROOT = /^(?:src|apps)\//;
 const FREE_NAMES = new Set(['index.ts', 'main.ts']);
 const PLAIN_ENTRY = /^<[a-z][a-z0-9-]*>.ts$/;
+/**
+ * Where the work of a banned data-access suffix goes. The suffix is banned by the manifest (ruleParams.be.bannedSuffixes);
+ * this only adds the convention's home to the finding, so a file that is a repository or a store is told what replaces it.
+ */
+const DATA_ACCESS_HOME = 'SQL text is a constant in <name>.sql.ts of the capability persistence/ folder, and data access is the capability *.service.ts (or the application *.handler.ts) calling the shared EntityManager through its Inject<Conn>EntityManager()';
+const BANNED_SUFFIX_HOME = Object.freeze({ repository: DATA_ACCESS_HOME, store: DATA_ACCESS_HOME });
 
 /**
  * BE_SOURCE_FORM (R89): every tracked src/ or apps/ TypeScript file of a back end is index.ts, main.ts, a migration of
@@ -39,14 +46,16 @@ function sourceFormFindings({ files, resolver }) {
     // A literal file name the owning slot itself requires or allows (persistence/connection.ts, world/global-setup.ts) is its role.
     const slot = resolver.slot(c.slot);
     if ([...(slot?.requires ?? []), ...(slot?.allows ?? [])].some((entry) => entry === base)) continue;
-    // A slot whose `allows` holds a bare <name>.ts entry (be.tests.world.kit) names its files plainly, as platform/primitives does: kebab-case is the whole form.
+    // So is an allows entry below the slot root whose last segment is that literal name (be.tests.world fakes/<provider>/server.ts).
     const admitted = allowsFile(resolver, file);
+    if (admitted?.allowed && admitted.entry?.includes('/') && path.posix.basename(admitted.entry) === base) continue;
+    // A slot whose `allows` holds a bare <name>.ts entry (be.tests.world.kit) names its files plainly, as platform/primitives does: kebab-case is the whole form.
     if (admitted?.allowed && PLAIN_ENTRY.test(admitted.entry ?? '') && KEBAB.test(base.slice(0, -'.ts'.length))) continue;
     if (c.slot === 'be.persistence' && path.posix.basename(path.posix.dirname(file)) === 'migrations') continue;
     const parts = base.slice(0, -'.ts'.length).split('.');
     const banned = parts.slice(1).find((part) => bannedSuffixes.includes(part));
     if (banned) {
-      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, suffix: banned, message: `${file}: the suffix .${banned} is banned; use a role from the closed suffix list (${suffixes.join(', ')})` });
+      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, suffix: banned, message: `${file}: the suffix .${banned} is banned; use a role from the closed suffix list (${suffixes.join(', ')})${BANNED_SUFFIX_HOME[banned] ? `. ${BANNED_SUFFIX_HOME[banned]}` : ''}` });
     } else if (boundSuffixes.has(parts.at(-1)) && parts.length >= 2 && boundSuffixes.get(parts.at(-1)).id !== c.slot) {
       findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, suffix: parts.at(-1), message: `${file}: the suffix .${parts.at(-1)}.ts belongs to ${boundSuffixes.get(parts.at(-1)).path} only; move the file there` });
     } else if (parts.length < 2 || !parts.every((part) => KEBAB.test(part)) || !suffixes.includes(parts.at(-1))) {
@@ -79,6 +88,8 @@ export function pathFindings({ files, resolver, profile }) {
   }
 
   if (profile === 'be') findings.push(...sourceFormFindings({ files, resolver }), ...specPlacementFindings({ files, resolver }));
+  // The app root (scripts/, CI, hooks) holds no test layer: a spec there is the same finding as a spec of an operational script.
+  else if (profile === APP_SCOPE) findings.push(...specPlacementFindings({ files, resolver }));
   // The lint canon's project graph serves these findings on a TypeScript file; the origin keeps them apart from the machine's.
   return findings.map((finding) => ({ ...finding, origin: 'repo' }));
 }