@starci/hfs 1.0.0 → 2.0.0

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

@@ -0,0 +1,319 @@
+import path from 'node:path';
+import { canonical } from './config.mjs';
+import { isUnshadowedCommonJsRequire, referencedExports, relativePath, sourceLocation, unwrapExpression } from './typescript.mjs';
+
+const REGISTRATION_RULE_IDS = ['BE_MODULE_HANDLER_REGISTRATION', 'BE_MODULE_PROVIDER_REREGISTRATION'];
+const FRAMEWORK = new Map([
+  ['Module', '@nestjs/common'],
+  ['CommandHandler', '@nestjs/cqrs'],
+  ['QueryHandler', '@nestjs/cqrs'],
+]);
+
+function normalizedSymbolValue(ts, checker, value) {
+  let symbol = value ?? null;
+  const seen = new Set();
+  while (symbol && (symbol.flags & ts.SymbolFlags.Alias) && !seen.has(symbol)) {
+    seen.add(symbol);
+    const target = checker.getAliasedSymbol(symbol);
+    if (!target || target === symbol) break;
+    symbol = target;
+  }
+  return symbol;
+}
+
+function normalizedSymbol(ts, checker, node) {
+  return normalizedSymbolValue(ts, checker, checker?.getSymbolAtLocation(node) ?? null);
+}
+
+function valueSymbol(ts, checker, node, seen = new Set()) {
+  const selected = selectedNode(ts, node) ?? node;
+  const symbol = normalizedSymbol(ts, checker, selected);
+  if (!symbol || seen.has(symbol)) return symbol;
+  seen.add(symbol);
+  const declarations = symbol.getDeclarations?.() ?? [];
+  if (declarations.length === 1 && ts.isVariableDeclaration(declarations[0]) && declarations[0].initializer
+    && (ts.getCombinedNodeFlags(declarations[0].parent) & ts.NodeFlags.Const)) {
+    return valueSymbol(ts, checker, declarations[0].initializer, seen);
+  }
+  return symbol;
+}
+
+function calledExpression(ts, decorator) {
+  const expression = decorator.expression;
+  return ts.isCallExpression(expression) ? expression.expression : expression;
+}
+
+function selectedNode(ts, expression) {
+  expression = unwrapExpression(ts, expression);
+  if (ts.isIdentifier(expression)) return expression;
+  if (ts.isPropertyAccessExpression(expression)) return expression.name;
+  if (ts.isElementAccessExpression(expression) && ts.isStringLiteralLike(expression.argumentExpression)) return expression.argumentExpression;
+  return null;
+}
+
+function frameworkDecorator(ts, checker, decorator, targets) {
+  const selected = selectedNode(ts, calledExpression(ts, decorator));
+  if (!selected) return null;
+  const symbol = valueSymbol(ts, checker, selected);
+  for (const [name, target] of targets) if (symbol === target) return name;
+  return null;
+}
+
+function mutableFrameworkAlias(ts, checker, decorator, targets) {
+  const selected = selectedNode(ts, calledExpression(ts, decorator));
+  const symbol = selected ? normalizedSymbol(ts, checker, selected) : null;
+  const declarations = symbol?.getDeclarations?.() ?? [];
+  if (declarations.length !== 1 || !ts.isVariableDeclaration(declarations[0]) || !declarations[0].initializer
+    || (ts.getCombinedNodeFlags(declarations[0].parent) & ts.NodeFlags.Const)) return null;
+  const target = valueSymbol(ts, checker, declarations[0].initializer);
+  for (const [name, expected] of targets) if (target === expected) return name;
+  return null;
+}
+
+function frameworkTargets(config, context, checker, localFiles) {
+  const targets = new Map();
+  const reasons = [];
+  const program = context.programs.find(candidate => candidate.getTypeChecker() === checker);
+  if (!program) return { targets, reasons: ['a TypeScript program checker could not be associated with its source'] };
+  for (const sourceFile of program.getSourceFiles()) {
+    if (!localFiles.has(canonical(sourceFile.fileName))) continue;
+    for (const statement of sourceFile.statements) {
+      const moduleSpecifier = (context.ts.isImportDeclaration(statement) || context.ts.isExportDeclaration(statement))
+        && statement.moduleSpecifier && context.ts.isStringLiteralLike(statement.moduleSpecifier) ? statement.moduleSpecifier : null;
+      const importEquals = context.ts.isImportEqualsDeclaration(statement) && context.ts.isExternalModuleReference(statement.moduleReference)
+        && statement.moduleReference.expression && context.ts.isStringLiteralLike(statement.moduleReference.expression)
+        ? statement.moduleReference.expression : null;
+      const specifier = (moduleSpecifier ?? importEquals)?.text;
+      if (!specifier || ![...FRAMEWORK.values()].includes(specifier)) continue;
+      const expected = new Set([...FRAMEWORK].filter(([, packageName]) => packageName === specifier).map(([name]) => name));
+      const selected = referencedExports(context.ts, statement, expected);
+      if (!selected.length) continue;
+      const moduleSymbol = checker.getSymbolAtLocation(moduleSpecifier ?? importEquals);
+      if (!moduleSymbol) {
+        reasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot resolve ${specifier}`);
+        continue;
+      }
+      const exports = new Map(checker.getExportsOfModule(moduleSymbol).map(symbol => [symbol.getName(), normalizedSymbolValue(context.ts, checker, symbol)]));
+      for (const name of selected) {
+        const target = exports.get(name);
+        if (target) targets.set(name, target);
+        else reasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot resolve ${name} from ${specifier}`);
+      }
+    }
+    const visitRequire = node => {
+      if (context.ts.isCallExpression(node) && isUnshadowedCommonJsRequire(context.ts, checker, node.expression)
+        && node.arguments.length === 1 && context.ts.isStringLiteralLike(node.arguments[0])
+        && [...FRAMEWORK.values()].includes(node.arguments[0].text)) {
+        reasons.push(`${relativePath(config.root, sourceFile.fileName)} uses a CommonJS Nest framework binding whose decorator identity cannot be proved`);
+      }
+      context.ts.forEachChild(node, visitRequire);
+    };
+    visitRequire(sourceFile);
+  }
+  return { targets, reasons };
+}
+
+function classToken(ts, checker, node, localFiles) {
+  const symbol = valueSymbol(ts, checker, node);
+  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 };
+}
+
+function localClassKey(ts, checker, node, localFiles) {
+  return classToken(ts, checker, node, localFiles).key;
+}
+
+function propertyName(ts, property) {
+  if (!property.name) return null;
+  if (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) return property.name.text;
+  return null;
+}
+
+function tokenEntries(ts, checker, initializer, localFiles, field) {
+  initializer = unwrapExpression(ts, initializer);
+  if (!ts.isArrayLiteralExpression(initializer)) return { tokens: new Map(), unknown: true };
+  const tokens = new Map();
+  let unknown = false;
+  const add = (key, node) => {
+    if (!tokens.has(key)) tokens.set(key, []);
+    tokens.get(key).push(node);
+  };
+  for (const element of initializer.elements) {
+    if (ts.isSpreadElement(element)) { unknown = true; continue; }
+    if (ts.isObjectLiteralExpression(element)) {
+      if (element.properties.some(property => ts.isSpreadAssignment(property))) { unknown = true; continue; }
+      const providers = element.properties.filter(property => propertyName(ts, property) === 'provide');
+      if (providers.length !== 1 || !ts.isPropertyAssignment(providers[0])) { unknown = true; continue; }
+      const key = localClassKey(ts, checker, providers[0].initializer, localFiles);
+      if (key) add(key, providers[0].initializer);
+      continue;
+    }
+    const token = classToken(ts, checker, element, localFiles);
+    if (token.key) add(token.key, element);
+    else if (field === 'providers' && !token.external) unknown = true;
+  }
+  return { tokens, unknown };
+}
+
+function metadataTokens(ts, checker, metadata, field, localFiles) {
+  metadata = unwrapExpression(ts, metadata);
+  if (!ts.isObjectLiteralExpression(metadata)) return { tokens: new Map(), unknown: true };
+  if (metadata.properties.some(property => ts.isSpreadAssignment(property))) return { tokens: new Map(), unknown: true };
+  const matches = metadata.properties.filter(property => propertyName(ts, property) === field);
+  if (!matches.length) return { tokens: new Map(), unknown: false };
+  if (matches.length !== 1 || !ts.isPropertyAssignment(matches[0])) return { tokens: new Map(), unknown: true };
+  return tokenEntries(ts, checker, matches[0].initializer, localFiles, field);
+}
+
+function moduleRecord(config, context, sourceFile, declaration, decorator, checker, localFiles) {
+  const call = decorator.expression;
+  const location = declaration.name ?? declaration;
+  const base = {
+    key: declaration.name ? localClassKey(context.ts, checker, declaration.name, localFiles) : null,
+    name: declaration.name?.text ?? '(anonymous)',
+    path: relativePath(config.root, sourceFile.fileName),
+    ...sourceLocation(sourceFile, location),
+    providers: new Map(),
+    exports: new Map(),
+    unknown: false,
+  };
+  if (!context.ts.isCallExpression(call) || call.arguments.length !== 1 || !base.key) return { ...base, unknown: true };
+  const providers = metadataTokens(context.ts, checker, call.arguments[0], 'providers', localFiles);
+  const exports = metadataTokens(context.ts, checker, call.arguments[0], 'exports', localFiles);
+  return { ...base, providers: providers.tokens, exports: exports.tokens, unknown: providers.unknown || exports.unknown };
+}
+
+function registrationFinding(module, node, ruleId, message, extra = {}) {
+  return { ruleId, path: module.path, ...sourceLocation(node.getSourceFile(), node), module: module.name, message, ...extra };
+}
+
+/** A module belongs to an app only when its runtime source is reachable from that app's composition root. */
+function applicationGraphs(config, context, modules) {
+  const roots = modules.filter(module => /^apps\/[^/]+\/src\/app\.module\.ts$/.test(module.path))
+    .sort((a, b) => a.path.localeCompare(b.path));
+  // Small architecture fixtures without app composition retain the original single-graph relation.
+  if (!roots.length) return [modules];
+  const byFile = new Map();
+  for (const module of modules) {
+    const file = canonical(path.resolve(config.root, ...module.path.split('/')));
+    if (!byFile.has(file)) byFile.set(file, []);
+    byFile.get(file).push(module);
+  }
+  const bound = new Set();
+  const graphs = roots.map(root => {
+    const queue = [canonical(path.resolve(config.root, ...root.path.split('/')))];
+    const seen = new Set();
+    const reachable = [];
+    for (let index = 0; index < queue.length; index += 1) {
+      const file = queue[index];
+      if (seen.has(file)) continue;
+      seen.add(file);
+      for (const module of byFile.get(file) ?? []) {
+        reachable.push(module);
+        bound.add(module);
+      }
+      for (const edge of context.edges.get(file) ?? []) if (edge.runtime && !seen.has(edge.to)) queue.push(edge.to);
+    }
+    return reachable;
+  });
+  // A module outside every proven app graph can still contain a duplicate in its own metadata.
+  return [...graphs, ...modules.filter(module => !bound.has(module)).map(module => [module])];
+}
+
+/** Prove only static exported class-token identity and selected CQRS handler registration. */
+export function checkModuleRegistration(config, context) {
+  const selected = config.backend.moduleRegistration;
+  if (!selected) return { violations: [], coverage: { status: 'unavailable', reason: 'architecture.json does not select Nest module-registration identity checks' } };
+  const ts = context.ts;
+  const localFiles = new Set(context.files.map(file => canonical(file.fileName)));
+  const modules = [];
+  const handlers = [];
+  const reasons = [];
+  const frameworkByChecker = new Map();
+  for (const sourceFile of context.files) {
+    const checker = context.checkerFor(sourceFile.fileName);
+    if (!frameworkByChecker.has(checker)) frameworkByChecker.set(checker, frameworkTargets(config, context, checker, localFiles));
+    const framework = frameworkByChecker.get(checker);
+    reasons.push(...framework.reasons);
+    const visit = node => {
+      if (ts.isClassDeclaration(node)) {
+        const decorators = ts.canHaveDecorators(node) ? ts.getDecorators(node) ?? [] : node.decorators ?? [];
+        const kinds = decorators.map(decorator => ({ decorator, kind: frameworkDecorator(ts, checker, decorator, framework.targets) }));
+        const recognized = kinds.filter(item => item.kind);
+        for (const { decorator, kind } of kinds) {
+          const dynamic = kind ? null : mutableFrameworkAlias(ts, checker, decorator, framework.targets);
+          if (dynamic) reasons.push(`${relativePath(config.root, sourceFile.fileName)} uses mutable ${dynamic} decorator identity`);
+        }
+        const moduleDecorators = recognized.filter(item => item.kind === 'Module');
+        if (moduleDecorators.length === 1) modules.push(moduleRecord(config, context, sourceFile, node, moduleDecorators[0].decorator, checker, localFiles));
+        else if (moduleDecorators.length > 1) reasons.push(`${relativePath(config.root, sourceFile.fileName)} has multiple resolved @Module decorators`);
+        const handlerDecorators = recognized.filter(item => item.kind === 'CommandHandler' || item.kind === 'QueryHandler');
+        if (handlerDecorators.length === 1) handlers.push({
+          key: node.name ? localClassKey(ts, checker, node.name, localFiles) : null,
+          name: node.name?.text ?? '(anonymous)',
+          kind: handlerDecorators[0].kind,
+          path: relativePath(config.root, sourceFile.fileName),
+          ...sourceLocation(sourceFile, node.name ?? node),
+        });
+        else if (handlerDecorators.length > 1) reasons.push(`${relativePath(config.root, sourceFile.fileName)} has multiple resolved CQRS handler decorators`);
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+  }
+  for (const module of modules) if (module.unknown) reasons.push(`${module.path} has dynamic or unresolvable @Module providers/exports metadata`);
+  for (const handler of handlers) {
+    if (!handler.key) reasons.push(`${handler.path} handler class identity is not resolvable`);
+    if (!selected.handlerDecorators.includes(handler.kind)) reasons.push(`${handler.path} uses unselected ${handler.kind}`);
+  }
+  const violations = [];
+  const providerOwners = new Map();
+  for (const module of modules) for (const key of module.providers.keys()) if (module.exports.has(key)) {
+    if (!providerOwners.has(key)) providerOwners.set(key, []);
+    providerOwners.get(key).push(module);
+  }
+  const reportedRegistrations = new Set();
+  for (const graph of applicationGraphs(config, context, modules)) for (const [key] of providerOwners) {
+    const owners = graph.filter(module => module.providers.has(key) && module.exports.has(key))
+      .sort((a, b) => a.path.localeCompare(b.path));
+    if (!owners.length) continue;
+    const owner = owners[0];
+    const registrations = graph.flatMap(module => (module.providers.get(key) ?? []).map(node => ({ module, node })))
+      .sort((a, b) => a.module.path.localeCompare(b.module.path) || a.node.getStart() - b.node.getStart());
+    let keptOwnerRegistration = false;
+    for (const duplicate of registrations.filter(registration => {
+      if (registration.module !== owner || keptOwnerRegistration) return true;
+      keptOwnerRegistration = true;
+      return false;
+    })) {
+      const identity = `${key}\0${duplicate.module.path}\0${duplicate.node.getStart()}`;
+      if (reportedRegistrations.has(identity)) continue;
+      reportedRegistrations.add(identity);
+      violations.push(registrationFinding(duplicate.module, duplicate.node,
+        'BE_MODULE_PROVIDER_REREGISTRATION',
+        `Class-token provider exported by ${owner.name} is registered again by ${duplicate.module.name} in one application graph; import the owning module and preserve one class-token registration.`,
+        { ownerModule: owner.name, ownerPath: owner.path }));
+    }
+  }
+  for (const handler of handlers.filter(item => item.key && selected.handlerDecorators.includes(item.kind))) {
+    const registrations = modules.flatMap(module => (module.providers.get(handler.key) ?? []).map(node => ({ module, node })));
+    if (registrations.length !== 1) violations.push({
+      ruleId: 'BE_MODULE_HANDLER_REGISTRATION', path: handler.path, line: handler.line, column: handler.column,
+      handler: handler.name, decorator: handler.kind,
+      message: registrations.length === 0
+        ? `${handler.kind} ${handler.name} is not registered as a direct class-token provider in a resolved Nest module.`
+        : `${handler.kind} ${handler.name} has multiple direct module registrations; one owner must preserve its handler identity.`,
+      modules: registrations.map(registration => ({ name: registration.module.name, path: registration.module.path,
+        ...sourceLocation(registration.node.getSourceFile(), registration.node) })),
+    });
+  }
+  const coverage = reasons.length
+    ? { status: 'unavailable', reason: 'one or more Nest module-registration relations are not statically provable', details: [...new Set(reasons)].sort() }
+    : { status: 'checked', modules: modules.length, exportedClassTokenProviders: providerOwners.size, handlers: handlers.length,
+      selectedHandlerDecorators: selected.handlerDecorators };
+  return { violations, coverage };
+}
+
+export { REGISTRATION_RULE_IDS };

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

@@ -0,0 +1,172 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { gitOutput } from '../../lib/git.mjs';
+
+/**
+ * HFS check 5: the files and directories the slot manifest requires (knowledge/hfs/slots.yaml `requires`,
+ * `requiredInstances`, `minInstances`, required app kinds) must exist in the repository tree. Everything is read through the
+ * resolver of scripts/lib/hfs-slots.mjs; nothing here names a path.
+ *
+ *   BE_REQUIRED_MODULE_MISSING   a backend app, feature, domain, integrations or platform instance lacks a required file or
+ *                                directory, or a required platform instance (config, logging, errors, primitives) is absent
+ *   FE_ERROR_BOUNDARY_MISSING    a fe.app.next app lacks global-error, error, not-found or loading under src/app
+ *   HFS_REQUIRED_FILE_MISSING    any other required file or directory (packages, fe modules, i18n, api ...), and a minimum
+ *                                (no api app, no feature, no next app) which is reported once at hfs.json
+ *
+ * Slots of tier none (README, root config, .starciwork, .starcistacks) belong to the slot check; fe.app.next is the one
+ * tier-none slot judged here. The tree is the tracked one (`git ls-files` from the repository root, minus files deleted
+ * on disk), else the filesystem without node_modules, .git, dist and .next.
+ */
+export const REQUIRED_FILE_RULE_IDS = ['BE_REQUIRED_MODULE_MISSING', 'FE_ERROR_BOUNDARY_MISSING', 'HFS_REQUIRED_FILE_MISSING'];
+
+const SKIPPED_DIRECTORIES = new Set(['node_modules', '.git', 'dist', '.next']);
+const ERROR_BOUNDARY_FILE = /^(?:global-error|error|not-found|loading)\.tsx$/u;
+const BACKEND_MODULE_SLOT = /^be\.(?:app|feature|transport|domain|integrations|platform)(?:\.|$)/u;
+const ALSO_JUDGED_TIER_NONE = new Set(['fe.app.next']);
+
+function gitFiles(root) {
+  try {
+    const run = args => gitOutput(args, { cwd: root, maxBuffer: 256 * 1024 * 1024 });
+    run(['rev-parse', '--is-inside-work-tree']);
+    const deleted = new Set(run(['ls-files', '--deleted', '-z', '--', '.']).split('\0').filter(Boolean));
+    return run(['ls-files', '--cached', '-z', '--', '.']).split('\0').filter(file => file && !deleted.has(file));
+  } catch {
+    return null;
+  }
+}
+
+function diskFiles(root, relative = '') {
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(path.join(root, ...relative.split('/').filter(Boolean)), { withFileTypes: true }); } catch { return out; }
+  for (const entry of entries) {
+    if (SKIPPED_DIRECTORIES.has(entry.name)) continue;
+    const child = relative ? `${relative}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...diskFiles(root, child));
+    else out.push(child);
+  }
+  return out;
+}
+
+/** The repository tree as file and directory sets over posix relatives. */
+export function treeOf(root) {
+  const list = gitFiles(root) ?? diskFiles(root);
+  const files = new Set(list);
+  const directories = new Set();
+  for (const file of list) {
+    const parts = file.split('/');
+    for (let i = 1; i < parts.length; i += 1) directories.add(parts.slice(0, i).join('/'));
+  }
+  return { files, directories };
+}
+
+const strip = entry => entry.replace(/\/+$/u, '');
+const rootOfTarget = target => (target.endsWith('/') ? strip(target) : (path.posix.dirname(target) === '.' ? '' : path.posix.dirname(target)));
+
+function ruleFor(slotId, target, rootExists) {
+  if (slotId === 'fe.app.next' && rootExists && ERROR_BOUNDARY_FILE.test(path.posix.basename(strip(target)))) return 'FE_ERROR_BOUNDARY_MISSING';
+  return BACKEND_MODULE_SLOT.test(slotId) ? 'BE_REQUIRED_MODULE_MISSING' : 'HFS_REQUIRED_FILE_MISSING';
+}
+
+export function checkRequiredFiles({ config, graph }) {
+  const resolver = graph?.resolver ?? config.hfs;
+  const tree = treeOf(config.root);
+  const judged = slotId => {
+    const slot = resolver.slot(slotId);
+    return Boolean(slot) && (slot.tier !== 'none' || ALSO_JUDGED_TIER_NONE.has(slotId));
+  };
+
+  const requirements = new Map(); // repository-relative target (as written, dirs end with /) -> {slot, target, root}
+  const instances = new Set();
+  const addRequirement = (slot, target, root) => { if (!requirements.has(target)) requirements.set(target, { slot, target, root }); };
+
+  // 1. What the repository must hold whatever it contains: fixed instances (requiredInstances, one per declared app).
+  const declared = resolver.requiredPaths();
+  const currentRoot = new Map();
+  for (const item of declared.paths) {
+    if (!judged(item.slot)) continue;
+    if (item.via !== 'requires') {
+      const root = rootOfTarget(item.path);
+      currentRoot.set(item.slot, root);
+      instances.add(`${item.slot}|${root}`);
+      addRequirement(item.slot, item.path, root);
+    } else {
+      addRequirement(item.slot, item.path, currentRoot.get(item.slot) ?? '');
+    }
+  }
+
+  // 2. What each instance found by walking the tree requires (features, domains, integrations, packages, transports, ...).
+  const seenInstances = new Set();
+  const instanceRequires = (slotId, root, representative) => {
+    const key = `${slotId}|${root}`;
+    if (seenInstances.has(key) || !judged(slotId)) return;
+    seenInstances.add(key);
+    instances.add(key);
+    for (const target of resolver.requiredFiles(representative)) addRequirement(slotId, target, root);
+  };
+  const ownerRequires = owner => {
+    const key = `${owner.slot}|${owner.root}`;
+    if (seenInstances.has(key) || !judged(owner.slot) || !resolver.slotEnabled(resolver.slot(owner.slot))) return;
+    seenInstances.add(key);
+    instances.add(key);
+    for (const entry of resolver.slot(owner.slot).requires ?? []) {
+      const rooted = entry.startsWith('/');
+      const filled = (rooted ? entry.slice(1) : entry).replace(/<([A-Za-z][A-Za-z0-9-]*)>/g, (whole, name) => owner.bindings[name] ?? whole);
+      addRequirement(owner.slot, rooted || !owner.root ? filled : `${owner.root}/${filled}`, owner.root);
+    }
+  };
+  const found = new Map(); // slot -> Set(root) of instances seen while walking
+  const note = (slotId, root) => {
+    if (!found.has(slotId)) found.set(slotId, new Set());
+    found.get(slotId).add(root);
+  };
+  for (const file of tree.files) {
+    const classified = resolver.classifyPath(file);
+    if (classified.status === 'owned' && classified.slot) {
+      note(classified.slot, classified.root);
+      instanceRequires(classified.slot, classified.root, file);
+    }
+    const owner = resolver.ownerOf(file);
+    if (owner) {
+      note(owner.slot, owner.root);
+      // an owner root may classify to a more specific slot (modules/i18n) or a nested one, so expand the owner slot's own requires
+      ownerRequires(owner);
+    }
+  }
+
+  const violations = [];
+  const reported = new Set();
+  const report = (ruleId, target, slotId, root, extra, message) => {
+    const key = `${ruleId}|${target}`;
+    if (reported.has(key)) return;
+    reported.add(key);
+    violations.push({ ruleId, path: target, slot: slotId, ...(root ? { root } : {}), ...extra, message });
+  };
+  const exists = target => (target.endsWith('/') ? tree.directories.has(strip(target)) : tree.files.has(target));
+
+  for (const requirement of requirements.values()) {
+    if (exists(requirement.target)) continue;
+    const rootExists = !requirement.root || tree.directories.has(requirement.root);
+    if (!rootExists) {
+      report(ruleFor(requirement.slot, requirement.target, false), requirement.root, requirement.slot, requirement.root, { kind: 'directory' },
+        `Required directory ${requirement.root} (slot ${requirement.slot}) does not exist; the slot manifest requires it, along with what it holds.`);
+      continue;
+    }
+    const kind = requirement.target.endsWith('/') ? 'directory' : 'file';
+    report(ruleFor(requirement.slot, requirement.target, true), strip(requirement.target), requirement.slot, requirement.root, { kind },
+      `Required ${kind} ${strip(requirement.target)} is missing; slot ${requirement.slot} requires it in every instance${requirement.root ? ` (${requirement.root})` : ''}.`);
+  }
+
+  // 3. Minimums: at least minInstances instances of a required slot.
+  for (const minimum of declared.minimums) {
+    if (!judged(minimum.slot)) continue;
+    const count = minimum.appKind !== undefined
+      ? resolver.repo.apps.filter(app => app.kind === minimum.appKind).length
+      : (found.get(minimum.slot)?.size ?? 0);
+    if (count >= minimum.min) continue;
+    report('HFS_REQUIRED_FILE_MISSING', 'hfs.json', minimum.slot, '', { minimum: minimum.min, found: count },
+      `Slot ${minimum.slot} needs at least ${minimum.min} instance${minimum.min === 1 ? '' : 's'}${minimum.appKind ? ` (an app of kind ${minimum.appKind} declared in hfs.json)` : ''}; the repository has ${count}.`);
+  }
+
+  return { violations, coverage: { status: 'checked', instances: instances.size, requirements: requirements.size, missing: violations.length } };
+}

package/runtime/scripts/checks/architecture/route-files-thin.mjs

@@ -0,0 +1,97 @@
+import path from 'node:path';
+import { machineKit } from './machine-ast.mjs';
+
+/**
+ * R54 `route-files-thin` (FE_ROUTE_FILES_THIN, knowledge/hfs/README.md 6.2). A route file only mounts an owner: it holds no
+ * inline component, no drawing and no hook. For every file of the route slot (fe.route, apps/<app>/src/app) named
+ * `layout`, `template`, `loading` or `not-found`:
+ *
+ *   - no host element (`<div>`, `<main>`): drawing belongs to the feature the file mounts;
+ *   - no function other than the default export that returns JSX: an inline component is a feature in the wrong folder;
+ *   - JSX, when present, mounts exactly one feature owner (a component resolved to a file of tier `feature`); a file with no
+ *     JSX re-exports or delegates and needs none. Package components (a locale shell) may wrap the owner.
+ *
+ * and, for every such file and every `page`: no hook call. A hook is an imported `use<Name>` function or any function of
+ * hooks/. The page's own mount, redirect and decision rules are the existing FE_ROUTE_ONE_PAGE, FE_ROUTE_DRAWING_DECISION,
+ * FE_ROUTE_CLIENT_BOUNDARY and FE_ROUTE_CLIENT_HOOK checks of frontend.mjs and are not judged a second time here.
+ */
+export const ROUTE_FILES_THIN_RULE_IDS = ['FE_ROUTE_FILES_THIN'];
+
+const RULE = 'FE_ROUTE_FILES_THIN';
+const ROUTE_SLOT = 'fe.route';
+const MOUNTING_ROUTES = new Set(['layout', 'template', 'loading', 'not-found']);
+const HOOK_ROUTES = new Set([...MOUNTING_ROUTES, 'page']);
+const HOOK_NAME = /^use[A-Z0-9]/u;
+const HOOKS_SLOT = 'fe.hooks';
+
+export function checkRouteFilesThin(input) {
+  const { graph } = input;
+  const kit = machineKit(input);
+  const { ts } = kit;
+  const violations = [];
+  let routes = 0;
+
+  for (const file of graph.files.values()) {
+    if (file.slot !== ROUTE_SLOT) continue;
+    const stem = path.posix.basename(file.rel).replace(/\.[cm]?[jt]sx?$/u, '');
+    if (!HOOK_ROUTES.has(stem)) continue;
+    routes += 1;
+    const mounting = MOUNTING_ROUTES.has(stem);
+    const checker = kit.checkerOf(file.sourceFile);
+    const report = (node, message, extra = {}) => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message, route: stem, ...extra });
+
+    // The default export function: `export default function X`, `export default X` (X a function), `export default () => ...`.
+    const defaults = new Set();
+    for (const statement of file.sourceFile.statements) {
+      if (ts.isFunctionDeclaration(statement) && statement.modifiers?.some(item => item.kind === ts.SyntaxKind.DefaultKeyword)) defaults.add(statement);
+      if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+        const target = statement.expression;
+        if (ts.isIdentifier(target)) for (const declaration of kit.declarationsOf(checker, target)) defaults.add(ts.isVariableDeclaration(declaration) ? declaration.initializer ?? declaration : declaration);
+        else defaults.add(target);
+      }
+    }
+    const isFunction = node => ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node);
+    const jsxOf = node => ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node);
+    const tagOf = node => (ts.isJsxElement(node) ? node.openingElement.tagName : ts.isJsxSelfClosingElement(node) ? node.tagName : null);
+    /** True when the function contains JSX that is not inside a nested function. */
+    const drawsDirectly = fn => {
+      let found = false;
+      const visit = node => {
+        if (found) return;
+        if (node !== fn && isFunction(node)) return;
+        if (jsxOf(node)) { found = true; return; }
+        ts.forEachChild(node, visit);
+      };
+      visit(fn);
+      return found;
+    };
+
+    let hasJsx = false;
+    let owners = 0;
+    kit.walk(file.sourceFile, node => {
+      if (jsxOf(node)) hasJsx = true;
+      const tag = tagOf(node);
+      if (mounting && tag) {
+        if (ts.isIdentifier(tag) && /^[a-z]/u.test(tag.text)) report(tag, `<${tag.text}> is drawing in a ${stem} route file; a route file mounts one feature and draws nothing. Move the markup into the feature.`);
+        else if (kit.declarationsOf(checker, ts.isPropertyAccessExpression(tag) ? tag.name : tag).some(declaration => graph.files.get(kit.graphPath(declaration) ?? '')?.tier === 'feature')) owners += 1;
+      }
+      if (mounting && isFunction(node) && !defaults.has(node) && drawsDirectly(node)) {
+        report(node, `A function other than the default export draws JSX in a ${stem} route file; that is an inline component. Move it into the feature the route mounts.`);
+      }
+      if (ts.isCallExpression(node)) {
+        const callee = ts.isIdentifier(node.expression) ? node.expression : null;
+        if (callee && HOOK_NAME.test(callee.text)) {
+          const binding = kit.importBinding(checker, callee);
+          const inHooks = kit.declarationsOf(checker, callee).some(declaration => graph.files.get(kit.graphPath(declaration) ?? '')?.slot === HOOKS_SLOT);
+          if (binding || inHooks) report(callee, `${callee.text} is a hook called in a ${stem} route file; a route file is a server adapter and holds no hook. Read the data in the feature it mounts.`);
+        }
+      }
+      return true;
+    });
+    if (mounting && hasJsx && owners !== 1) {
+      violations.push({ ruleId: RULE, path: file.rel, line: 1, column: 1, route: stem, owners,
+        message: `${file.rel} mounts ${owners} feature owners; a ${stem} route file mounts exactly one feature (a layouts- or pages-tier component of the app), optionally inside a package shell.` });
+    }
+  }
+  return { violations, coverage: { status: 'checked', routes } };
+}