@starci/hfs 1.0.1 → 2.0.0

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

@@ -0,0 +1,89 @@
+import path from 'node:path';
+import { canonical, isInside } from './config.mjs';
+import { relativePath, sourceLocation } from './typescript.mjs';
+
+function absolute(root, relative) {
+  return canonical(path.resolve(root, ...relative.split('/')));
+}
+
+function ownerDeclarations(config) {
+  return config.owners.map(owner => ({ ...owner, root: absolute(config.root, owner.root), entry: absolute(config.root, owner.entry) }))
+    .sort((a, b) => b.root.length - a.root.length);
+}
+
+function ownerOf(owners, file) {
+  return owners.find(owner => isInside(owner.root, file)) ?? null;
+}
+
+function privateOwnerChain(context, owners, edge) {
+  const sourceOwner = ownerOf(owners, edge.from);
+  const queue = [{ file: edge.to, chain: [edge.from, edge.to] }];
+  const visited = new Set();
+  while (queue.length) {
+    const current = queue.shift();
+    if (visited.has(current.file)) continue;
+    visited.add(current.file);
+    const owner = ownerOf(owners, current.file);
+    if (owner && sourceOwner?.id !== owner.id) return current.file === owner.entry ? null : { owner, chain: current.chain };
+    for (const candidate of context.edges.get(current.file) ?? []) if (candidate.reexport) {
+      queue.push({ file: candidate.to, chain: [...current.chain, candidate.to] });
+    }
+  }
+  return null;
+}
+
+/**
+ * A `*.builder.ts` of slot be.tests.fixtures.builders arranges data at the schema level: it may deep-import the persistence
+ * entity classes and connection entity lists (slot be.persistence) of any capability. No other file may.
+ */
+function arrangesSchema(config, from, to) {
+  const resolver = config.hfs;
+  if (!resolver?.classifyPath) return false;
+  return resolver.classifyPath(relativePath(config.root, from)).slot === 'be.tests.fixtures.builders'
+    && resolver.classifyPath(relativePath(config.root, to)).slot === 'be.persistence';
+}
+
+/** Enforce explicit same-source owner entries without constraining imports inside one owner. */
+export function checkOwners(config, context) {
+  if (!config.owners?.length) return [];
+  const owners = ownerDeclarations(config);
+  const violations = [];
+  const sourceFiles = new Map(context.files.map(file => [canonical(file.fileName), file]));
+  for (const owner of owners) {
+    const sourceFile = sourceFiles.get(owner.entry);
+    if (!sourceFile) {
+      violations.push({ ruleId: 'ARCH_OWNER_EXPORT_BYPASS', path: relativePath(config.root, owner.entry), line: 1, column: 1, owner: owner.id,
+        message: `Owner ${owner.id} public entry is outside the configured TypeScript programs, so its boundary cannot be checked.` });
+      continue;
+    }
+    for (const statement of sourceFile.statements) if (context.ts.isExportDeclaration(statement) && !statement.exportClause) {
+      violations.push({
+        ruleId: 'ARCH_OWNER_EXPORT_STAR',
+        path: relativePath(config.root, owner.entry),
+        ...sourceLocation(sourceFile, statement),
+        owner: owner.id,
+        message: `Owner ${owner.id} public entry must use explicit named exports rather than export *.`
+      });
+    }
+  }
+  for (const sourceFile of context.files) {
+    const from = canonical(sourceFile.fileName);
+    for (const edge of context.edges.get(from) ?? []) {
+      const bypass = privateOwnerChain(context, owners, edge);
+      if (!bypass) continue;
+      if (arrangesSchema(config, from, bypass.chain.at(-1))) continue;
+      violations.push({
+        ruleId: 'ARCH_OWNER_EXPORT_BYPASS',
+        path: relativePath(config.root, from),
+        line: edge.line,
+        column: edge.column,
+        owner: bypass.owner.id,
+        specifier: edge.specifier,
+        resolvedPath: relativePath(config.root, bypass.chain.at(-1)),
+        dependencyChain: bypass.chain.map(file => relativePath(config.root, file)),
+        message: `Cross-owner dependency must enter ${bypass.owner.id} through ${relativePath(config.root, bypass.owner.entry)}.`
+      });
+    }
+  }
+  return violations;
+}

package/runtime/scripts/checks/architecture/package-shape.mjs

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { treeOf } from './required-files.mjs';
+
+/**
+ * R63 `package-shape` (FE_PACKAGE_SHAPE, knowledge/hfs/README.md 6.2). A shared package is built to `dist` and says what it
+ * exports. The package manifest of every package owner (slots repo.packages and fe.package.ui, packages/<pkg>/package.json)
+ * must have:
+ *
+ *   - a `scripts.build`;
+ *   - an explicit `exports` map: present, no `*` pattern in a subpath, no folder mapping;
+ *   - every export target, and `main`, `module`, `types` and `typings` when present, inside `./dist/`: a target into `src/`
+ *     ships source that was never built.
+ *
+ * `export *` in the package entry is ARCH_OWNER_EXPORT_STAR, a dead unit is HFS_UNUSED_EXPORT and the package tiers are the
+ * eslint rule `monorepo-tier-belongs-to-its-side`; none is judged a second time here.
+ */
+export const PACKAGE_SHAPE_RULE_IDS = ['FE_PACKAGE_SHAPE'];
+
+const RULE = 'FE_PACKAGE_SHAPE';
+
+/** Every string target of an exports value (a string, a condition map, an array of either), with the condition path. */
+function targetsOf(value, trail = []) {
+  if (typeof value === 'string') return [{ target: value, trail }];
+  if (Array.isArray(value)) return value.flatMap((item, index) => targetsOf(item, [...trail, String(index)]));
+  if (value && typeof value === 'object') return Object.entries(value).flatMap(([key, item]) => targetsOf(item, [...trail, key]));
+  return [];
+}
+
+const insideDist = target => path.posix.normalize(target).replace(/^\.\//u, '').startsWith('dist/');
+
+export function checkPackageShape({ config, graph }) {
+  const resolver = graph.resolver;
+  const violations = [];
+  let packages = 0;
+  const roots = new Set();
+  for (const rel of treeOf(config.root).files) {
+    const owner = resolver.ownerOf(rel);
+    if (owner && resolver.slot(owner.slot)?.tier === 'package') roots.add(owner.root);
+  }
+  for (const root of [...roots].sort()) {
+    const manifestRel = `${root}/package.json`;
+    const report = (message, extra = {}) => violations.push({ ruleId: RULE, path: manifestRel, line: 1, column: 1, package: root, message, ...extra });
+    let manifest;
+    try { manifest = JSON.parse(fs.readFileSync(path.join(config.root, ...manifestRel.split('/')), 'utf8')); } catch { continue; }
+    packages += 1;
+    if (typeof manifest.scripts?.build !== 'string' || !manifest.scripts.build.trim()) report(`${manifestRel} has no scripts.build; a shared package is built to dist before an app consumes it.`);
+    if (manifest.exports === undefined) {
+      report(`${manifestRel} declares no exports map; a package lists what it exports, subpath by subpath, each pointing into ./dist/.`);
+    } else {
+      if (typeof manifest.exports === 'object' && !Array.isArray(manifest.exports)) {
+        for (const key of Object.keys(manifest.exports)) if (key.includes('*') || key.endsWith('/')) report(`exports key "${key}" of ${manifestRel} is a pattern or folder mapping; list each exported subpath explicitly.`, { export: key });
+      }
+      for (const { target, trail } of targetsOf(manifest.exports)) {
+        if (!insideDist(target)) report(`exports target "${target}" (${trail.join(' > ') || '.'}) of ${manifestRel} is not inside ./dist/; a package exports what it built, never its source.`, { export: target });
+      }
+    }
+    for (const field of ['main', 'module', 'types', 'typings']) {
+      if (typeof manifest[field] === 'string' && !insideDist(manifest[field])) report(`${field} "${manifest[field]}" of ${manifestRel} is not inside ./dist/; a package points at what it built.`, { field });
+    }
+  }
+  return { violations, coverage: { status: 'checked', packages } };
+}

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

@@ -0,0 +1,233 @@
+/**
+ * HFS check 3, reachability (knowledge/hfs/slots.yaml rules BE_FEATURE_NOT_COMPOSED, FE_OWNER_REACHABLE):
+ *   BE  every feature owner (be.feature) and every capability owner (be.domain, be.integrations, be.platform) must be
+ *       composed into an app root: reachable from an app entry file (apps/<app>/src, the be.app.* owners) through runtime
+ *       imports and re-exports. A type-only import composes nothing. A module reached only through a reached module
+ *       is reached. An owner no root reaches is dead code: no process ever serves it.
+ *   FE  every page/layout/overlay feature (fe.feature) must be mounted: reachable by runtime imports from a file of
+ *       its app's route tree (apps/<app>/src/app, slot fe.route); and every string-literal href/redirect/router target
+ *       must resolve to a route of that app (page.tsx / route.ts under src/app, route groups and [locale] transparent).
+ * Only literals are judged: a computed href is counted as skipped, never guessed at.
+ */
+export const REACHABILITY_RULE_IDS = ['BE_FEATURE_NOT_COMPOSED', 'FE_OWNER_REACHABLE', 'FE_HREF_RESOLVES'];
+
+const BE_CAPABILITY_SLOTS = new Set(['be.domain', 'be.integrations', 'be.platform']);
+const TEST_FILE = /(?:\.(?:spec|test|stories|e2e-spec)\.[cm]?[jt]sx?$)|(?:(?:^|\/)__tests__\/)/;
+const ROUTE_FILE = /^(?:page|route)\.(?:tsx|ts|jsx|js)$/;
+const PLACEHOLDER = '\u0000';
+
+/** Breadth-first reach over runtime, non-type-only edges (re-exports included) from `roots`. */
+function reachFrom(graph, roots) {
+  const forward = new Map();
+  for (const edge of graph.edges) {
+    if (!edge.runtime) continue;
+    if (!forward.has(edge.from)) forward.set(edge.from, []);
+    forward.get(edge.from).push(edge.to);
+  }
+  const reached = new Set(roots);
+  const queue = [...roots];
+  while (queue.length) {
+    for (const next of forward.get(queue.shift()) ?? []) {
+      if (reached.has(next)) continue;
+      reached.add(next);
+      queue.push(next);
+    }
+  }
+  return reached;
+}
+
+function ownerFiles(graph) {
+  const byUnit = new Map();
+  for (const [rel, node] of graph.files) {
+    if (!node.owner) continue;
+    const key = `${node.owner.slot}:${node.owner.root}`;
+    if (!byUnit.has(key)) byUnit.set(key, []);
+    byUnit.get(key).push(rel);
+  }
+  return byUnit;
+}
+
+/** The file that stands for an owner in a finding: its public entry when the graph holds one, else its first file. */
+function entryOf(root, files) {
+  const base = root.replace(/\/$/, '');
+  return files.find(rel => new RegExp(`^${base.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/index\\.[tj]sx?$`).test(rel)) ?? [...files].sort()[0];
+}
+
+function checkBackend(graph) {
+  const byUnit = ownerFiles(graph);
+  const rootFiles = [];
+  const appRoots = new Set();
+  for (const [key, files] of byUnit) {
+    const slot = key.slice(0, key.indexOf(':'));
+    if (!slot.startsWith('be.app.')) continue;
+    appRoots.add(key.slice(key.indexOf(':') + 1));
+    for (const rel of files) if (!TEST_FILE.test(rel)) rootFiles.push(rel);
+  }
+  const roots = [...appRoots].sort();
+  const counts = { features: 0, modules: 0, appRoots: roots.length, notComposed: 0 };
+  if (!roots.length) return { violations: [], coverage: { status: 'unavailable', reason: 'no be.app.* owner instance holds a source file, so there is no app root to compose into', ...counts } };
+  const reached = reachFrom(graph, rootFiles);
+  const violations = [];
+  for (const [key, files] of [...byUnit].sort(([a], [b]) => a.localeCompare(b))) {
+    const slot = key.slice(0, key.indexOf(':'));
+    const root = key.slice(key.indexOf(':') + 1);
+    const feature = slot === 'be.feature';
+    if (!feature && !BE_CAPABILITY_SLOTS.has(slot)) continue;
+    counts[feature ? 'features' : 'modules'] += 1;
+    if (files.some(rel => reached.has(rel))) continue;
+    counts.notComposed += 1;
+    const label = root.replace(/\/$/, '');
+    violations.push({
+      ruleId: 'BE_FEATURE_NOT_COMPOSED',
+      path: entryOf(root, files), owner: label, slot, appRoots: roots,
+      message: `${feature ? 'Feature' : 'Module'} ${label} is not composed into any app: no runtime import path leads from ${roots.join(', ')} to it (a type-only import composes nothing), so it is dead code that no process serves.`,
+    });
+  }
+  return { violations, coverage: { status: 'checked', ...counts } };
+}
+
+/** Route table of one app: arrays of segments, each {kind:'static'|'dyn'|'catch'|'optcatch', text}. */
+function routeTable(graph, app) {
+  const prefix = `apps/${app}/src/app/`;
+  const routes = [];
+  for (const rel of graph.files.keys()) {
+    if (!rel.startsWith(prefix)) continue;
+    const parts = rel.slice(prefix.length).split('/');
+    if (!ROUTE_FILE.test(parts.at(-1))) continue;
+    const segments = [];
+    let usable = true;
+    for (const part of parts.slice(0, -1)) {
+      if (/^\([^.)][^)]*\)$/.test(part)) continue;            // route group
+      if (part.startsWith('@')) continue;                      // parallel slot: no URL segment
+      if (part.startsWith('_') || /^\(\.+\)/.test(part)) { usable = false; break; } // private folder, intercepting route
+      segments.push(part);
+    }
+    if (!usable) continue;
+    if (segments[0] === '[locale]') segments.shift();
+    routes.push(segments.map(part => {
+      if (/^\[\[\.\.\..+\]\]$/.test(part)) return { kind: 'optcatch', text: part };
+      if (/^\[\.\.\..+\]$/.test(part)) return { kind: 'catch', text: part };
+      if (/^\[.+\]$/.test(part)) return { kind: 'dyn', text: part };
+      return { kind: 'static', text: part };
+    }));
+  }
+  return routes;
+}
+
+/** One href segment (may contain PLACEHOLDER for a template expression) against one route segment. */
+function segmentMatches(hrefSegment, routeSegment) {
+  if (!hrefSegment.includes(PLACEHOLDER)) return routeSegment.kind === 'dyn' || routeSegment.text === hrefSegment;
+  if (routeSegment.kind === 'dyn' || routeSegment.kind === 'catch' || routeSegment.kind === 'optcatch') return true;
+  const parts = hrefSegment.split(PLACEHOLDER).map(part => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  return new RegExp(`^${parts.join('.*')}$`).test(routeSegment.text);
+}
+
+function matchRoute(hrefSegments, route, at = 0, from = 0) {
+  if (from === route.length) return at === hrefSegments.length;
+  const routeSegment = route[from];
+  if (routeSegment.kind === 'optcatch' && matchRoute(hrefSegments, route, at, from + 1)) return true;
+  if (routeSegment.kind === 'catch' || routeSegment.kind === 'optcatch') {
+    for (let take = 1; at + take <= hrefSegments.length; take += 1) if (matchRoute(hrefSegments, route, at + take, from + 1)) return true;
+    return false;
+  }
+  if (at >= hrefSegments.length || !segmentMatches(hrefSegments[at], routeSegment)) return false;
+  return matchRoute(hrefSegments, route, at + 1, from + 1);
+}
+
+function hrefResolves(href, routes) {
+  const cut = href.search(/[?#]/);
+  const pathOnly = cut === -1 ? href : href.slice(0, cut);
+  const segments = pathOnly.split('/').slice(1).filter(segment => segment !== '');
+  const candidates = [segments];
+  // A leading locale (a literal `en`/`vi-VN` or a bare template expression) is what [locale] carries: try without it too.
+  if (segments.length && (/^[a-z]{2}(?:-[a-zA-Z]{2})?$/.test(segments[0]) || segments[0] === PLACEHOLDER)) candidates.push(segments.slice(1));
+  return candidates.some(candidate => routes.some(route => matchRoute(candidate, route)));
+}
+
+/** The text of a string-ish expression with PLACEHOLDER for each ${...}; null when it is not a literal we can read. */
+function literalText(ts, node) {
+  if (!node) return null;
+  while (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || (ts.isNonNullExpression && ts.isNonNullExpression(node))) node = node.expression;
+  if (ts.isStringLiteralLike(node)) return node.text;                 // includes NoSubstitutionTemplateLiteral
+  if (ts.isTemplateExpression(node)) return node.head.text + node.templateSpans.map(span => PLACEHOLDER + span.literal.text).join('');
+  return null;
+}
+
+const NAVIGATION_CALLS = new Set(['redirect', 'permanentRedirect']);
+const ROUTER_METHODS = new Set(['push', 'replace', 'prefetch']);
+
+/** Every href-like target in a source file: {node, text|null (null = computed)}. */
+function hrefTargets(ts, sourceFile) {
+  const found = [];
+  const visit = node => {
+    if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === 'href' && node.initializer) {
+      const value = ts.isJsxExpression(node.initializer) ? node.initializer.expression : node.initializer;
+      found.push({ node: value ?? node, text: value ? literalText(ts, value) : null });
+    } else if (ts.isCallExpression(node) && node.arguments.length) {
+      const callee = node.expression;
+      const navigates = (ts.isIdentifier(callee) && NAVIGATION_CALLS.has(callee.text))
+        || (ts.isPropertyAccessExpression(callee) && ROUTER_METHODS.has(callee.name.text)
+          && /router$/i.test(ts.isIdentifier(callee.expression) ? callee.expression.text : ts.isPropertyAccessExpression(callee.expression) ? callee.expression.name.text : ''));
+      if (navigates) found.push({ node: node.arguments[0], text: literalText(ts, node.arguments[0]) });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return found;
+}
+
+function checkFrontend(config, context, graph) {
+  const ts = context.ts ?? context.loaded.ts;
+  const byUnit = ownerFiles(graph);
+  const apps = new Map();
+  for (const [rel, node] of graph.files) {
+    if (node.slot !== 'fe.route') continue;
+    const app = /^apps\/([^/]+)\/src\/app\//.exec(rel)?.[1];
+    if (!app) continue;
+    if (!apps.has(app)) apps.set(app, []);
+    apps.get(app).push(rel);
+  }
+  const counts = { pages: 0, mounted: 0, hrefs: 0, hrefsResolved: 0, hrefsSkipped: 0, routes: 0 };
+  const violations = [];
+  const reachedByApp = new Map([...apps].map(([app, roots]) => [app, reachFrom(graph, roots)]));
+  for (const [key, files] of [...byUnit].sort(([a], [b]) => a.localeCompare(b))) {
+    if (!key.startsWith('fe.feature:')) continue;
+    const root = key.slice('fe.feature:'.length);
+    const app = /^apps\/([^/]+)\//.exec(root)?.[1];
+    counts.pages += 1;
+    const reached = reachedByApp.get(app);
+    if (reached && files.some(rel => reached.has(rel))) { counts.mounted += 1; continue; }
+    const label = root.replace(/\/$/, '');
+    violations.push({
+      ruleId: 'FE_OWNER_REACHABLE', path: entryOf(root, files), owner: label, app,
+      message: `${label} is not mounted: no runtime import path leads from a route file under apps/${app}/src/app to it (a type-only import mounts nothing), so the page is never shown.`,
+    });
+  }
+  for (const app of [...new Set([...apps.keys(), ...[...graph.files.keys()].map(rel => /^apps\/([^/]+)\/src\//.exec(rel)?.[1]).filter(Boolean)])].sort()) {
+    const routes = routeTable(graph, app);
+    counts.routes += routes.length;
+    const prefix = `apps/${app}/src/`;
+    for (const [rel, node] of graph.files) {
+      if (!rel.startsWith(prefix) || TEST_FILE.test(rel)) continue;
+      for (const target of hrefTargets(ts, node.sourceFile)) {
+        counts.hrefs += 1;
+        const text = target.text;
+        if (text === null || !text.startsWith('/') || text.startsWith('//') || !routes.length) { counts.hrefsSkipped += 1; continue; }
+        const hrefPath = text.split(/[?#]/)[0];
+        if (/\.[A-Za-z0-9]{1,6}$/.test(hrefPath.split('/').at(-1))) { counts.hrefsSkipped += 1; continue; } // static asset
+        if (hrefResolves(text, routes)) { counts.hrefsResolved += 1; continue; }
+        const point = node.sourceFile.getLineAndCharacterOfPosition(target.node.getStart(node.sourceFile));
+        const shown = text.split(PLACEHOLDER).join('${…}');
+        violations.push({
+          ruleId: 'FE_HREF_RESOLVES', path: rel, line: point.line + 1, column: point.character + 1, app, href: shown,
+          message: `href "${shown}" matches no route of app ${app}: no page.tsx or route.ts under ${prefix}app serves that path.`,
+        });
+      }
+    }
+  }
+  return { violations, coverage: { status: 'checked', ...counts } };
+}
+
+export function checkReachability({ config, context, graph } = {}) {
+  return graph.profile === 'be' ? checkBackend(graph) : checkFrontend(config, context, graph);
+}

package/runtime/scripts/checks/architecture/register-once.mjs

@@ -0,0 +1,141 @@
+import path from 'node:path';
+import { machineKit } from './machine-ast.mjs';
+
+/**
+ * R45 `register-once` (BE_MODULE_SHAPE), the module graph read from the app roots (owner rule of 2026-09-30, the
+ * reference's `CodingModule imports DeviceModule` shape). Each capability has one representative module: the only module
+ * of the capability an app registers, once, in `apps/<app>/src/app.module.ts` as `X.register({ isGlobal: true, ... })`.
+ * It may split itself into sub-modules imported as plain `imports: [Sub]`; a sub-module is never in an app and has one
+ * importer, its parent. Over every `@Module` class of the program:
+ *
+ *   - a module in an app root's imports (a `X.register(...)` call or a listed class, helpers of the root included) is
+ *     listed once there, is imported by no other module, and, when it is a capability module of src/modules, is registered
+ *     with the literal `isGlobal: true` (a bare capability class is not a registration);
+ *   - a module imported by a non-app module has exactly one importer and appears in no app root; the one exception is
+ *     the feature case: a feature's application module is imported by each protocol module of the same feature;
+ *   - `isGlobal: true` appears only in an app root.
+ */
+export const REGISTER_ONCE_RULE_IDS = ['BE_MODULE_SHAPE'];
+
+const RULE = 'BE_MODULE_SHAPE';
+const CAPABILITY_TIERS = new Set(['domain', 'platform', 'integrations']);
+
+export function checkRegisterOnce(input) {
+  const { config, graph } = input;
+  const kit = machineKit(input);
+  const { ts } = kit;
+  const violations = [];
+  const report = (file, node, message, extra = {}) => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message, ...extra });
+  const isAppRoot = file => Boolean(file.slot?.startsWith('be.app.')) && path.posix.basename(file.rel) === 'app.module.ts';
+  // The test world (slot be.tests.world) is the test composition root: useTestWorld registers capability modules with
+  // `isGlobal: true` the way an app root does. A spec (integration, contract, e2e) is not a composition root.
+  const isWorld = file => file.slot === 'be.tests.world';
+  const appOf = file => config.apps.find(app => file.rel === `apps/${app.name}/src/app.module.ts`)?.name ?? null;
+
+  // Every @Module class of the program.
+  const modules = new Map(); // declaration -> {name, file, capability}
+  for (const file of graph.files.values()) {
+    const checker = kit.checkerOf(file.sourceFile);
+    for (const statement of file.sourceFile.statements) {
+      if (!ts.isClassDeclaration(statement) || !statement.name) continue;
+      const isModule = kit.decorators(statement).some(decorator => {
+        const call = ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
+        const binding = kit.importBinding(checker, call);
+        return binding?.module === '@nestjs/common' && binding.name === 'Module';
+      });
+      if (isModule) modules.set(statement, { name: statement.name.text, file, capability: CAPABILITY_TIERS.has(file.tier) });
+    }
+  }
+  const targetOf = (checker, node) => {
+    for (const declaration of kit.declarationsOf(checker, node)) if (modules.has(declaration)) return { declaration, ...modules.get(declaration) };
+    return null;
+  };
+  const enclosingModule = node => {
+    for (let current = node.parent; current; current = current.parent) if (ts.isClassDeclaration(current) && modules.has(current)) return current;
+    return null;
+  };
+
+  // The references to modules: importer (the enclosing module class, else the file), target, node, whether it is a register call.
+  const references = [];
+  for (const file of graph.files.values()) {
+    if (isWorld(file)) continue; // the test composition root assembles modules; it is not a module importer
+    const checker = kit.checkerOf(file.sourceFile);
+    const seen = new Set();
+    const note = (element, viaImports) => {
+      const call = ts.isCallExpression(element) && ts.isPropertyAccessExpression(element.expression) && element.expression.name.text === 'register';
+      if (ts.isCallExpression(element) && !call) return;
+      const target = targetOf(checker, call ? element.expression.expression : element);
+      if (!target) return;
+      seen.add(element);
+      const owner = enclosingModule(element);
+      references.push({ file, node: element, target, register: call, viaImports, importer: owner ?? file.rel, importerOwner: file.owner?.root ?? null,
+        options: call ? element.arguments[0] : null, root: isAppRoot(file) });
+    };
+    kit.walk(file.sourceFile, node => {
+      if (ts.isPropertyAssignment(node) && kit.propertyNameText(node.name) === 'imports' && ts.isArrayLiteralExpression(node.initializer)) {
+        for (const element of node.initializer.elements) note(element, true);
+      } else if (ts.isCallExpression(node) && !seen.has(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'register') {
+        note(node, false);
+      }
+      if (ts.isPropertyAssignment(node) && kit.propertyNameText(node.name) === 'isGlobal' && node.initializer.kind === ts.SyntaxKind.TrueKeyword && !isAppRoot(file) && !isWorld(file)) {
+        report(file, node, '`isGlobal: true` appears only in the app root (apps/<app>/src/app.module.ts), where the representative module of a capability is registered; a module never decides its own globality.');
+      }
+      return true;
+    });
+  }
+
+  const trueGlobal = options => Boolean(options) && ts.isObjectLiteralExpression(options) && (() => {
+    const property = kit.propertyOf(options, 'isGlobal');
+    return Boolean(property) && ts.isPropertyAssignment(property) && property.initializer.kind === ts.SyntaxKind.TrueKeyword;
+  })();
+
+  // App roots: each module is listed once, capability modules are registered with isGlobal true.
+  const rootReferences = references.filter(item => item.root);
+  const inApps = new Map(); // module declaration -> Set(app names)
+  for (const item of rootReferences) {
+    const app = appOf(item.file) ?? item.file.rel;
+    if (!inApps.has(item.target.declaration)) inApps.set(item.target.declaration, new Set());
+    inApps.get(item.target.declaration).add(app);
+  }
+  for (const app of config.apps) {
+    const seenInApp = new Map();
+    for (const item of rootReferences.filter(entry => appOf(entry.file) === app.name)) {
+      if (seenInApp.has(item.target.declaration)) {
+        report(item.file, item.node, `${item.target.name} is registered more than once in the root of app ${app.name}; a module is listed once per app.`, { module: item.target.name, app: app.name });
+      } else seenInApp.set(item.target.declaration, item.node);
+    }
+  }
+  for (const item of rootReferences) {
+    if (!item.target.capability || !item.viaImports && !item.register) continue;
+    if (!item.register) report(item.file, item.node, `${item.target.name} is listed in imports as a bare class; the representative module of a capability is registered in the app root as ${item.target.name}.register({ isGlobal: true, ...options }).`, { module: item.target.name });
+    else if (!trueGlobal(item.options)) report(item.file, item.node, `${item.target.name} is registered in the app root without the literal \`isGlobal: true\`; write ${item.target.name}.register({ isGlobal: true, ...options }).`, { module: item.target.name });
+  }
+
+  // Non-app importers: no importer of an app-registered module, exactly one importer otherwise (the feature case excepted).
+  const importersOf = new Map(); // module declaration -> [reference]
+  for (const item of references.filter(entry => !entry.root && entry.viaImports)) {
+    if (!importersOf.has(item.target.declaration)) importersOf.set(item.target.declaration, []);
+    importersOf.get(item.target.declaration).push(item);
+  }
+  for (const [declaration, list] of importersOf) {
+    const target = modules.get(declaration);
+    const apps = inApps.get(declaration);
+    if (apps) {
+      for (const item of list) {
+        report(item.file, item.node, `${target.name} is registered in the root of app ${[...apps].sort().join(', ')}, so no other module imports it; consume it through its Inject*() decorators.`, { module: target.name });
+      }
+      continue;
+    }
+    const distinct = [...new Set(list.map(item => item.importer))];
+    const featureCase = target.file.tier === 'feature' && target.file.owner && list.every(item => item.importerOwner === target.file.owner.root);
+    if (distinct.length > 1 && !featureCase) {
+      for (const item of list.filter(entry => entry.importer !== list[0].importer)) {
+        report(item.file, item.node, `${target.name} is imported by ${distinct.length} modules; a sub-module has exactly one importer, its parent. Another capability's module is consumed through its Inject*() decorators, never imported.`, { module: target.name });
+      }
+    }
+  }
+
+  return { violations, coverage: { status: 'checked', apps: config.apps.filter(app => kit.appRoot(app.name)).length, modules: modules.size,
+    capabilityModules: [...modules.values()].filter(item => item.capability).length, registrations: references.filter(item => item.register).length,
+    rootImports: rootReferences.length } };
+}