@starci/hfs 1.0.0 → 2.0.0

package/runtime/scripts/checks/architecture/cross-app-duplicate.mjs

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+
+/**
+ * R21 `cross-app-duplicate` (FE_CROSS_APP_DUPLICATE): the slot manifest's `crossApp` law says apps never import each other and
+ * shared code is a `packages/<pkg>` slot. `HFS_DUPLICATE_CODE` sees blocks of a size inside the owner graph; this sees whole
+ * files of any size, route-tree files included: two TypeScript files under different apps whose token-normalised content is
+ * equal (comments and whitespace do not exist in the token sequence; identifiers and literals are kept) are one file copied
+ * instead of moved to a package.
+ *
+ * Exempt: a file made only of import and export statements. It is the sanctioned shape of a Next route file that must exist
+ * per app and re-exports one package symbol (`export { default } from "@family/ui/global-error"`), and it holds nothing to move.
+ * Not source, so not judged: declaration files and everything that is not .ts/.tsx (JSON catalogs, CSS).
+ */
+export const CROSS_APP_DUPLICATE_RULE_IDS = ['FE_CROSS_APP_DUPLICATE'];
+
+const RULE = 'FE_CROSS_APP_DUPLICATE';
+const SOURCE = /\.[cm]?tsx?$/u;
+
+export function checkCrossAppDuplicate({ graph, context }) {
+  const ts = context.ts;
+  const { SyntaxKind } = ts;
+  const resolver = graph.resolver;
+  const declaredApps = resolver.repo.apps.map(app => app.name);
+  /** The app a file belongs to: the slot binding when a slot owns it, else the declared app whose directory holds it. */
+  const appOf = rel => resolver.classifyPath(rel).bindings?.app ?? declaredApps.find(name => rel.startsWith(`apps/${name}/`)) ?? null;
+  const onlyModuleEdges = file => file.sourceFile.statements.every(statement => ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)
+    || (ts.isExportAssignment(statement) && ts.isIdentifier(statement.expression)));
+
+  const tokens = sourceFile => {
+    const parts = [];
+    const visit = node => {
+      if (node.kind >= SyntaxKind.FirstJSDocNode && node.kind <= SyntaxKind.LastJSDocNode) return;
+      if (node.kind === SyntaxKind.JsxText && node.containsOnlyTriviaWhiteSpaces) return;
+      const children = node.getChildren(sourceFile);
+      if (!children.length) {
+        if (node.kind !== SyntaxKind.EndOfFileToken) parts.push(node.kind === SyntaxKind.JsxText ? node.getText(sourceFile).replace(/\s+/gu, ' ').trim() : node.getText(sourceFile));
+        return;
+      }
+      for (const child of children) visit(child);
+    };
+    visit(sourceFile);
+    return parts.join('\u0000');
+  };
+
+  const groups = new Map();
+  let files = 0;
+  for (const file of graph.files.values()) {
+    if (!SOURCE.test(file.rel) || /\.d\.[cm]?tsx?$/u.test(file.rel)) continue;
+    const app = appOf(file.rel);
+    if (!app || onlyModuleEdges(file) || !file.sourceFile.statements.length) continue;
+    files += 1;
+    const key = createHash('sha256').update(tokens(file.sourceFile)).digest('hex');
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push({ rel: file.rel, app });
+  }
+
+  const violations = [];
+  let duplicated = 0;
+  for (const group of groups.values()) {
+    if (new Set(group.map(item => item.app)).size < 2) continue;
+    duplicated += 1;
+    group.sort((a, b) => a.rel.localeCompare(b.rel));
+    for (const item of group) {
+      const twins = group.filter(other => other.app !== item.app).map(other => other.rel);
+      violations.push({
+        ruleId: RULE, path: item.rel, line: 1, column: 1, twins,
+        message: `${item.rel} is token-for-token the same file as ${twins.join(', ')} in another app (comments and whitespace ignored); shared code is a packages/<pkg> slot. Move it to a package (packages/<pkg>) and let each app re-export it (${path.posix.basename(item.rel)} keeps only an import or export statement).`,
+      });
+    }
+  }
+  return { violations, coverage: { status: 'checked', files, duplicatedGroups: duplicated } };
+}

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

@@ -0,0 +1,265 @@
+/**
+ * HFS check 4, dead code (knowledge/hfs/rules.yaml R25, both profiles, errors in every gate):
+ *   HFS_UNUSED_EXPORT  an export of an owner's public entry that no production file outside the owner imports is dead.
+ *   HFS_UNUSED_FILE    a production source file that no root reaches is dead. Roots: the files an app slot requires
+ *                      (main.ts, app.module.ts), every route file (slot tier `route`), the public entry of every package,
+ *                      and a source file a framework config of the app names by a relative string literal
+ *                      (next.config.ts pointing next-intl at its request config). Specs and tests are not in the graph,
+ *                      so a file only a spec imports is dead, on purpose. Type-only imports reach a file.
+ *
+ * Owner = every graph.ownerRoots unit whose tier is not `app` and whose public entry file is in the graph (index.ts or
+ * index.tsx, a package's src/index.ts). The exported names of the entry are its named exports, `export { a as b }`,
+ * `export { x } from`, declarations with `export`, and `default` for `export default`. `export *` is refused by owners.mjs
+ * and contributes no name here.
+ *
+ * A name is used when a production file outside the owner imports it from the entry (type-only imports count). A
+ * namespace import, `import x = require`, a dynamic import()/require(), an `export *` or `export * as` of the entry make
+ * every name used. A file outside the owner that re-exports the name (`export { n as m } from`) uses it when `m` is itself
+ * used by the importers of that file; a re-exporting file nobody imports is a framework entry (a route file) and uses it.
+ * Specs and tests are not in the graph, so an export used only by a spec is dead, on purpose, with one exception (unit test
+ * standard): a `<name>.service.spec.ts` (the only unit spec kind) and a `*.builder.ts` under src/tests/fixtures/builders read from
+ * disk count as consumers, because a spec can only provide an Inject*() token or a param type the entry exports. Specs of any
+ * other kind, e2e specs and world files still do not count. A consumer inside the owner is skipped like any inside consumer.
+ */
+import fs from 'node:fs';
+import { canonical } from './config.mjs';
+import path from 'node:path';
+import { treeOf } from './required-files.mjs';
+
+export const DEAD_EXPORT_RULE_IDS = ['HFS_UNUSED_EXPORT', 'HFS_UNUSED_FILE'];
+
+const PACKAGE_ENTRIES = ['src/index.ts', 'src/index.tsx', 'index.ts', 'index.tsx'];
+const OWNER_ENTRIES = ['index.ts', 'index.tsx'];
+const CHAIN_DEPTH = 6;
+/** Tiers whose files are not production source that an app serves: judged by no dead-file rule. */
+const UNJUDGED_TIERS = new Set(['none', 'e2e', 'fixtures']);
+const CONFIG_EXTENSIONS = ['', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '/index.ts', '/index.tsx', '/index.js'];
+const CONFIG_STRING = /['"`](\.{1,2}\/[^'"`\s]+)['"`]/g;
+
+/** The public entry file (repository-relative) of an owner unit, or null when the owner has none in the graph. */
+export function entryOf(graph, config, key, owner) {
+  const declared = config.owners?.find(item => item.id === key)?.entry;
+  if (declared && graph.files.has(declared)) return declared;
+  for (const candidate of owner.tier === 'package' ? PACKAGE_ENTRIES : OWNER_ENTRIES) {
+    const rel = owner.root ? `${owner.root}/${candidate}` : candidate;
+    if (graph.files.has(rel)) return rel;
+  }
+  return null;
+}
+
+/** Names an import/export declaration takes from its target: {all} or {pairs: [{imported, exported}]}. */
+function bindingsOf(ts, declaration) {
+  const kind = ts.SyntaxKind;
+  if (!declaration) return { all: true, pairs: [] };
+  if (declaration.kind === kind.ImportDeclaration) {
+    const clause = declaration.importClause;
+    if (!clause) return { all: false, pairs: [] }; // side-effect import: uses nothing
+    const pairs = [];
+    if (clause.name) pairs.push({ imported: 'default', exported: null });
+    const named = clause.namedBindings;
+    if (named && named.kind === kind.NamespaceImport) return { all: true, pairs: [] };
+    if (named) for (const element of named.elements) pairs.push({ imported: (element.propertyName ?? element.name).text, exported: null });
+    return { all: false, pairs };
+  }
+  if (declaration.kind === kind.ExportDeclaration) {
+    const clause = declaration.exportClause;
+    if (!clause || clause.kind === kind.NamespaceExport) return { all: true, pairs: [] };
+    return { all: false, pairs: clause.elements.map(element => ({ imported: (element.propertyName ?? element.name).text, exported: element.name.text })) };
+  }
+  if (declaration.kind === kind.ImportTypeNode) {
+    let qualifier = declaration.qualifier;
+    if (!qualifier) return { all: true, pairs: [] };
+    while (qualifier.kind === kind.QualifiedName) qualifier = qualifier.left;
+    return { all: false, pairs: [{ imported: qualifier.text, exported: null }] };
+  }
+  // ImportEqualsDeclaration, dynamic import(), require(): the whole module is taken.
+  return { all: true, pairs: [] };
+}
+
+/** The exported names of an entry source file, each with the line of its declaration. */
+export function exportedNames(ts, sourceFile) {
+  const kind = ts.SyntaxKind;
+  const found = new Map();
+  const add = (name, node) => {
+    if (found.has(name)) return;
+    found.set(name, sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1);
+  };
+  const bindingNames = (name, node) => {
+    if (name.kind === kind.Identifier) add(name.text, node);
+    else for (const element of name.elements) if (element.kind === kind.BindingElement) bindingNames(element.name, node);
+  };
+  for (const statement of sourceFile.statements) {
+    if (statement.kind === kind.ExportDeclaration) {
+      if (statement.exportClause?.kind === kind.NamedExports) for (const element of statement.exportClause.elements) add(element.name.text, element);
+      else if (statement.exportClause?.kind === kind.NamespaceExport) add(statement.exportClause.name.text, statement);
+      continue;
+    }
+    if (statement.kind === kind.ExportAssignment) { add('default', statement); continue; }
+    const modifiers = statement.modifiers ?? [];
+    if (!modifiers.some(modifier => modifier.kind === kind.ExportKeyword)) continue;
+    if (modifiers.some(modifier => modifier.kind === kind.DefaultKeyword)) { add('default', statement); continue; }
+    if (statement.kind === kind.VariableStatement) for (const declaration of statement.declarationList.declarations) bindingNames(declaration.name, declaration);
+    else if (statement.name && statement.name.kind === kind.Identifier) add(statement.name.text, statement);
+  }
+  return found;
+}
+
+const withoutSlash = value => value.replace(/\/$/, '');
+
+/** The files the graph serves from: what an app slot requires, every route file, every package entry, every config-named file. */
+function rootFiles(graph, config) {
+  const roots = new Set();
+  for (const [rel, node] of graph.files) {
+    if (node.tier === 'route') { roots.add(rel); continue; }
+    if (!node.owner || node.tier !== 'app') continue;
+    const slot = graph.resolver.slot(node.owner.slot);
+    const inside = rel.slice(withoutSlash(node.owner.root).length + 1);
+    if ((slot?.requires ?? []).some(name => name === inside)) roots.add(rel);
+  }
+  for (const [key, owner] of graph.ownerRoots) {
+    if (owner.tier !== 'package') continue;
+    const entry = entryOf(graph, config, key, owner);
+    if (entry) roots.add(entry);
+  }
+  // A framework config of an app (slot fe.app.next) names sources by string, never by import.
+  for (const app of config.apps ?? []) {
+    const directory = `apps/${app.name}`;
+    let names = [];
+    try { names = fs.readdirSync(path.join(config.root, ...directory.split('/'))); } catch { continue; }
+    for (const name of names) {
+      if (graph.resolver.classifyPath(`${directory}/${name}`).slot !== 'fe.app.next' || !/\.[cm]?[jt]sx?$/.test(name)) continue;
+      let text = '';
+      try { text = fs.readFileSync(path.join(config.root, ...directory.split('/'), name), 'utf8'); } catch { continue; }
+      for (const match of text.matchAll(CONFIG_STRING)) {
+        const target = path.posix.join(directory, match[1]);
+        const hit = CONFIG_EXTENSIONS.map(extension => `${target}${extension}`).find(candidate => graph.files.has(candidate));
+        if (hit) roots.add(hit);
+      }
+    }
+  }
+  return roots;
+}
+
+/** HFS_UNUSED_FILE: production files no root reaches through runtime or type-only imports and re-exports. */
+function deadFiles(graph, config) {
+  const roots = rootFiles(graph, config);
+  const forward = new Map();
+  for (const edge of graph.edges) {
+    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)) { reached.add(next); queue.push(next); }
+  const violations = [];
+  let judged = 0;
+  for (const [rel, node] of [...graph.files].sort(([a], [b]) => a.localeCompare(b))) {
+    if (node.tier === null || UNJUDGED_TIERS.has(node.tier) || node.tier === 'route') continue;
+    judged += 1;
+    if (reached.has(rel)) continue;
+    violations.push({
+      ruleId: 'HFS_UNUSED_FILE',
+      path: rel, line: 1, column: 1,
+      slot: node.slot, owner: node.owner?.root ?? null,
+      message: `${rel} is not reached from any root (an app main.ts or app.module.ts, a route file, a package entry): nothing imports it, so no process runs it. Delete the file, or import it where it is used (a spec alone does not count).`,
+    });
+  }
+  return { violations, judged, roots: roots.size };
+}
+
+const TEST_CONSUMER = /^(?:(?:src|apps)\/.+\.service\.spec\.ts|src\/tests\/fixtures\/builders\/.+\.builder\.ts)$/u;
+
+/** Pseudo edges from the unit specs of services and the fixture builders (read from disk, outside the production program) to graph files. */
+function testConsumerEdges({ context, graph, config }) {
+  const { ts } = context;
+  const options = context.projects?.[0]?.options ?? {};
+  const edges = [];
+  for (const rel of [...treeOf(config.root).files].filter(file => TEST_CONSUMER.test(file)).sort()) {
+    const abs = path.join(config.root, ...rel.split('/'));
+    let text;
+    try { text = fs.readFileSync(abs, 'utf8'); } catch { continue; }
+    const sourceFile = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true);
+    for (const statement of sourceFile.statements) {
+      if (!(ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) || !statement.moduleSpecifier || !ts.isStringLiteralLike(statement.moduleSpecifier)) continue;
+      const resolved = ts.resolveModuleName(statement.moduleSpecifier.text, abs, options, ts.sys).resolvedModule?.resolvedFileName;
+      const to = resolved ? graph.abs(canonical(resolved)) : null;
+      if (to) edges.push({ from: rel, to, edge: { declaration: statement }, reexport: false });
+    }
+  }
+  return edges;
+}
+
+export function checkDeadExports({ context, graph, config }) {
+  const { ts } = context;
+  const violations = [];
+  const edgesTo = new Map();
+  const unitOf = rel => {
+    const known = graph.unit(rel);
+    if (known) return known;
+    const classified = graph.resolver.classifyPath(rel);
+    const owner = classified.slot ? graph.resolver.ownerOf(rel) : null;
+    return owner ? `${owner.slot}:${owner.root}` : null;
+  };
+  for (const edge of [...graph.edges, ...testConsumerEdges({ context, graph, config })]) {
+    if (!edgesTo.has(edge.to)) edgesTo.set(edge.to, []);
+    edgesTo.get(edge.to).push(edge);
+  }
+
+  /** What the importers of `file` take from it; edges from inside `ownerKey` are skipped when given. */
+  const consumed = (file, ownerKey, depth, visiting) => {
+    const result = { all: false, names: new Set() };
+    for (const edge of edgesTo.get(file) ?? []) {
+      if (ownerKey && unitOf(edge.from) === ownerKey) continue;
+      const bindings = bindingsOf(ts, edge.edge.declaration);
+      if (bindings.all) { result.all = true; continue; }
+      for (const pair of bindings.pairs) {
+        if (pair.exported === null) { result.names.add(pair.imported); continue; }
+        // A re-export by name: the name is used when the re-exporting file's own export is used further on.
+        const reexporter = edge.from;
+        if (visiting.has(reexporter) || depth >= CHAIN_DEPTH) { result.names.add(pair.imported); continue; }
+        if (!(edgesTo.get(reexporter)?.length)) {
+          // nobody imports the re-exporting file: a framework entry (route file) uses it, an unused owner entry does not
+          const holder = graph.files.get(reexporter);
+          if (!holder?.owner || graph.resolver.slot(holder.owner.slot)?.tier === 'app') result.names.add(pair.imported);
+          continue;
+        }
+        const next = consumed(reexporter, null, depth + 1, new Set([...visiting, reexporter]));
+        if (next.all || next.names.has(pair.exported)) result.names.add(pair.imported);
+      }
+    }
+    return result;
+  };
+
+  let owners = 0;
+  let exports = 0;
+  for (const [key, owner] of graph.ownerRoots) {
+    if (owner.tier === 'app') continue;
+    const entry = entryOf(graph, config, key, owner);
+    if (!entry) continue;
+    owners += 1;
+    const names = exportedNames(ts, graph.files.get(entry).sourceFile);
+    const used = consumed(entry, key, 0, new Set([entry]));
+    // A consumer outside the owner that imports a file the entry re-exports by name reaches the entry's export of that name.
+    for (const edge of graph.edges) {
+      if (edge.from !== entry || !edge.reexport || graph.unit(edge.to) !== key) continue;
+      const reexport = bindingsOf(ts, edge.edge.declaration);
+      const inner = consumed(edge.to, key, 0, new Set([entry, edge.to]));
+      if (reexport.all) continue;
+      for (const pair of reexport.pairs) if (inner.all || inner.names.has(pair.imported)) used.names.add(pair.exported);
+    }
+    for (const [name, line] of names) {
+      exports += 1;
+      if (used.all || used.names.has(name)) continue;
+      violations.push({
+        ruleId: 'HFS_UNUSED_EXPORT',
+        path: entry, line, column: 1,
+        name, owner: owner.root, slot: owner.slot,
+        message: `${entry} exports ${name}, but no production file outside ${owner.root || 'the repository root'} imports it; remove the export (only a service unit spec or a fixture builder counts besides production files).`,
+      });
+    }
+  }
+  const files = deadFiles(graph, config);
+  const deadExports = violations.length;
+  violations.push(...files.violations);
+  return { violations, coverage: { status: 'checked', owners, exports, dead: deadExports, files: files.judged, roots: files.roots, unusedFiles: files.violations.length } };
+}

package/runtime/scripts/checks/architecture/default-deny.mjs

@@ -0,0 +1,129 @@
+import { machineKit } from './machine-ast.mjs';
+
+/**
+ * R41 `default-deny-app-guard` (BE_DEFAULT_DENY). Every api app root provides its `APP_GUARD` entries in the order
+ * throttler -> CSRF origin guard -> AuthGuard, each exactly once, so no request reaches a handler before it was
+ * rate-limited, origin-checked and authenticated. A guard is classified by structure, never by name or folder alone
+ * (BE-CONVENTION 1.7 names the roles, not a library):
+ *   - throttler: a class of @nestjs/throttler or one that extends it, or a guard that reads through a Reflector the
+ *     per-door metadata (the `@RateLimit(tier)` decorator) that a SetMetadata call of its own capability writes;
+ *   - CSRF origin guard: a guard declared in platform/http-security that reads the request origin or referer header;
+ *   - AuthGuard: the `AuthGuard` class declared in domain/identity.
+ * Other guards are permitted between them; a missing, repeated or reordered one of the three is a finding.
+ */
+export const DEFAULT_DENY_RULE_IDS = ['BE_DEFAULT_DENY'];
+
+const RULE = 'BE_DEFAULT_DENY';
+const ORDER = ['throttler', 'csrf', 'auth'];
+const ORIGIN_HEADERS = new Set(['origin', 'referer', 'referrer']);
+const METADATA_READERS = new Set(['get', 'getAll', 'getAllAndMerge', 'getAllAndOverride']);
+const LABEL = { throttler: 'the throttler guard', csrf: 'the CSRF origin guard of platform/http-security', auth: 'AuthGuard of domain/identity' };
+
+export function checkDefaultDeny(input) {
+  const { config } = input;
+  const kit = machineKit(input);
+  const { ts } = kit;
+  const violations = [];
+  let apps = 0;
+
+  const extendsThrottler = (declaration, depth = 0) => {
+    if (!ts.isClassDeclaration(declaration) || depth > 8) return false;
+    const checker = kit.checkerOf(declaration.getSourceFile());
+    if (!checker) return false;
+    for (const clause of declaration.heritageClauses ?? []) {
+      for (const type of clause.types) {
+        if (kit.isImportOf(checker, type.expression, 'ThrottlerGuard', '@nestjs/throttler')) return true;
+        if (kit.declarationsOf(checker, type.expression).some(parent => parent !== declaration && extendsThrottler(parent, depth + 1))) return true;
+      }
+    }
+    return false;
+  };
+
+  const keySymbol = (checker, node) => (node ? kit.aliased(checker, kit.symbolAt(checker, node)) ?? null : null);
+
+  /** The symbols a SetMetadata call of the owner writes as metadata keys: what its door decorators (`@RateLimit(tier)`) attach. */
+  const writtenKeys = (owner, cache = new Map()) => {
+    if (cache.has(owner.root)) return cache.get(owner.root);
+    const keys = new Set();
+    for (const file of input.graph.files.values()) {
+      if (file.owner?.root !== owner.root) continue;
+      const checker = kit.checkerOf(file.sourceFile);
+      if (!checker) continue;
+      kit.walk(file.sourceFile, node => {
+        if (ts.isCallExpression(node) && kit.isImportOf(checker, node.expression, 'SetMetadata', '@nestjs/common')) {
+          const key = keySymbol(checker, node.arguments[0]);
+          if (key) keys.add(key);
+        }
+        return true;
+      });
+    }
+    cache.set(owner.root, keys);
+    return keys;
+  };
+  const keyCache = new Map();
+
+  /** True when the class reads a request origin or referer header (the origin/referer allowlist of the CSRF guard). */
+  const readsOrigin = declaration => {
+    let found = false;
+    kit.walk(declaration, node => {
+      if (ts.isPropertyAccessExpression(node) && ORIGIN_HEADERS.has(node.name.text.toLowerCase())) found = true;
+      else if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression) && ORIGIN_HEADERS.has(node.argumentExpression.text.toLowerCase())) found = true;
+      return !found;
+    });
+    return found;
+  };
+
+  /** True when the class reads, through a metadata getter, a key its own capability's SetMetadata decorators write. */
+  const readsDoorMetadata = (declaration, owner) => {
+    const checker = kit.checkerOf(declaration.getSourceFile());
+    if (!checker) return false;
+    const keys = writtenKeys(owner, keyCache);
+    let found = false;
+    kit.walk(declaration, node => {
+      if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && METADATA_READERS.has(node.expression.name.text)) {
+        const key = keySymbol(checker, node.arguments[0]);
+        if (key && keys.has(key)) found = true;
+      }
+      return !found;
+    });
+    return found;
+  };
+
+  const classify = (checker, node) => {
+    if (!node) return null;
+    if (kit.importBinding(checker, node)?.module === '@nestjs/throttler') return 'throttler';
+    const declarations = kit.declarationsOf(checker, node);
+    if (declarations.some(declaration => extendsThrottler(declaration))) return 'throttler';
+    for (const declaration of declarations) {
+      const owner = kit.ownerOfDeclaration(declaration);
+      if (owner?.tier === 'platform' && owner.name === 'http-security' && ts.isClassDeclaration(declaration)) {
+        if (readsOrigin(declaration)) return 'csrf';
+        if (readsDoorMetadata(declaration, owner)) return 'throttler';
+      }
+      if (owner?.tier === 'domain' && owner.name === 'identity' && ts.isClassDeclaration(declaration) && declaration.name?.text === 'AuthGuard') return 'auth';
+    }
+    return null;
+  };
+
+  for (const app of config.apps.filter(item => item.kind === 'api')) {
+    const root = kit.appRoot(app.name);
+    if (!root) continue;
+    apps += 1;
+    const guards = kit.providersOf(root, 'APP_GUARD', '@nestjs/core');
+    const roles = guards.map(guard => ({ guard, role: classify(guard.checker, guard.useClass) }));
+    const anchor = guards[0]?.node ?? root.sourceFile.statements[0] ?? root.sourceFile;
+    const finding = (node, message) => violations.push({ ruleId: RULE, path: root.rel, ...kit.at(root.rel, root.sourceFile, node), app: app.name, message });
+    for (const role of ORDER) {
+      const entries = roles.filter(item => item.role === role);
+      if (entries.length === 0) finding(anchor, `App ${app.name} does not provide ${LABEL[role]} as an APP_GUARD; an api app is denied by default: throttler, then CSRF origin guard, then AuthGuard.`);
+      else if (entries.length > 1) finding(entries[1].guard.node, `App ${app.name} provides ${LABEL[role]} more than once as an APP_GUARD.`);
+    }
+    const indexes = ORDER.map(role => roles.findIndex(item => item.role === role));
+    if (indexes.every(index => index >= 0)) {
+      for (let i = 1; i < indexes.length; i += 1) {
+        if (indexes[i] < indexes[i - 1]) finding(roles[indexes[i]].guard.node, `App ${app.name} provides ${LABEL[ORDER[i]]} before ${LABEL[ORDER[i - 1]]}; the APP_GUARD order is throttler, CSRF origin guard, AuthGuard.`);
+      }
+    }
+  }
+  return { violations, coverage: { status: 'checked', apps } };
+}

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

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { treeOf } from './required-files.mjs';
+import { documentLanguageHits, isDocument, isLocalizedDataFile } from '../../lib/language.mjs';
+
+/**
+ * R96 `doc-language` (HFS_DOC_NOT_ENGLISH). Every Markdown and YAML document under knowledge/, docs/, src/ and apps/ is English:
+ * prose, patterns and examples alike, and a code fence inside Markdown counts because an example is read exactly like the
+ * prose around it. Detection is structural on characters (scripts/lib/language.mjs), never a word list.
+ *
+ * The one exception is data, decided by placement: a YAML file that sits in a slot carrying localized text (a message
+ * catalog slot or an i18n fixtures slot, listed in scripts/lib/language.mjs) may hold another language. Markdown is never data, so a README
+ * inside a catalog slot is judged like any other document. No comment pragma, no path pattern.
+ */
+export const DOC_LANGUAGE_RULE_IDS = ['HFS_DOC_NOT_ENGLISH'];
+
+const RULE = 'HFS_DOC_NOT_ENGLISH';
+/** The top-level folders whose documents this check reads. */
+export const DOCUMENT_ROOTS = Object.freeze(['knowledge', 'docs', 'src', 'apps']);
+
+export function checkDocLanguage({ config, graph }) {
+  const resolver = graph.resolver;
+  const tree = treeOf(config.root);
+  const violations = [];
+  let files = 0;
+  for (const file of [...tree.files].sort()) {
+    if (!DOCUMENT_ROOTS.includes(file.split('/')[0]) || !isDocument(file) || file.split('/').includes('node_modules')) continue;
+    const classified = resolver.classifyPath(file);
+    if (isLocalizedDataFile(file, classified.status === 'owned' ? classified.slot : null)) continue;
+    let text;
+    try { text = fs.readFileSync(path.join(config.root, ...file.split('/')), 'utf8'); } catch { continue; }
+    files += 1;
+    for (const hit of documentLanguageHits(file, text)) {
+      violations.push({ ruleId: RULE, path: file, line: hit.line, column: hit.column,
+        message: `${file}:${hit.line} carries a Vietnamese letter. Documents are English (prose, patterns, examples and code fences); only YAML data in a message-catalog or i18n-fixtures slot may hold another language. Write the line in English.` });
+    }
+  }
+  return { violations, coverage: { status: 'checked', files } };
+}

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

@@ -0,0 +1,57 @@
+import path from 'node:path';
+import { machineKit } from './machine-ast.mjs';
+
+/**
+ * R33 `entrypoint-only-in-apps` (BE_ENTRYPOINT_ONLY_IN_APPS). A process starts in `apps/<app>/src/main.ts` only:
+ * `NestFactory.create*` (from @nestjs/core) and a top-level `bootstrap()` call anywhere else are entrypoints hiding in a
+ * library, a feature, a spec helper or another file of an app.
+ *
+ * The test world (slot be.tests.world) is the test COMPOSITION ROOT, like an app's main.ts: use-test-world.ts boots the
+ * real apps with NestFactory the way main.ts does in production, so it is an entrypoint owner too. A spec
+ * (*.integration-spec.ts, *.contract-spec.ts, *.e2e-spec.ts) does not compose: it calls useTestWorld(...) only, and the
+ * other test slots stay refused.
+ */
+export const ENTRYPOINT_RULE_IDS = ['BE_ENTRYPOINT_ONLY_IN_APPS'];
+
+const RULE = 'BE_ENTRYPOINT_ONLY_IN_APPS';
+
+export function checkEntrypoints(input) {
+  const { graph } = input;
+  const kit = machineKit(input);
+  const { ts } = kit;
+  const violations = [];
+  let entrypoints = 0;
+  /** The identifier a top-level statement calls: `bootstrap()`, `void bootstrap()`, `bootstrap().catch(...)`. */
+  const calledIdentifier = expression => {
+    let current = expression;
+    for (;;) {
+      if (ts.isVoidExpression(current) || ts.isAwaitExpression(current) || ts.isParenthesizedExpression(current) || ts.isNonNullExpression(current)) current = current.expression;
+      else if (ts.isCallExpression(current)) {
+        if (ts.isIdentifier(current.expression)) return current.expression;
+        current = current.expression;
+      } else if (ts.isPropertyAccessExpression(current)) current = current.expression;
+      else return null;
+    }
+  };
+  for (const file of graph.files.values()) {
+    const isMain = (Boolean(file.slot?.startsWith('be.app.')) && path.posix.basename(file.rel) === 'main.ts') || file.slot === 'be.tests.world';
+    const checker = kit.checkerOf(file.sourceFile);
+    const report = (node, message) => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message });
+    kit.walk(file.sourceFile, node => {
+      if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text.startsWith('create')
+        && kit.isImportOf(checker, node.expression.expression, 'NestFactory', '@nestjs/core')) {
+        if (isMain) entrypoints += 1;
+        else report(node, `NestFactory.${node.expression.name.text}() starts a process outside apps/<app>/src/main.ts; entrypoints live in an app's main.ts only.`);
+      }
+      return true;
+    });
+    if (isMain) continue;
+    for (const statement of file.sourceFile.statements) {
+      if (!ts.isExpressionStatement(statement)) continue;
+      if (calledIdentifier(statement.expression)?.text === 'bootstrap') {
+        report(statement, "A top-level bootstrap() call starts a process outside apps/<app>/src/main.ts; entrypoints live in an app's main.ts only.");
+      }
+    }
+  }
+  return { violations, coverage: { status: 'checked', entrypoints } };
+}

package/runtime/scripts/checks/architecture/error-codes.mjs

@@ -0,0 +1,45 @@
+import path from 'node:path';
+import { machineKit, upperSnake } from './machine-ast.mjs';
+
+/**
+ * R38 error codes (BE_ERROR_HOME, machine half; the eslint half judges the error classes). The string value of every
+ * member of a `<C>ErrorCode` enum in a capability's `errors/<c>.error.ts` is a string literal shaped
+ * `<CAPABILITY>_<WHAT>` (UPPER_SNAKE of the owning capability, no `_ERROR` or `_EXCEPTION` suffix) and unique across the
+ * whole repository, so a code names one refusal and one capability for the client and the log.
+ */
+export const ERROR_CODE_RULE_IDS = ['BE_ERROR_HOME'];
+
+const RULE = 'BE_ERROR_HOME';
+
+export function checkErrorCodes(input) {
+  const { graph } = input;
+  const kit = machineKit(input);
+  const { ts } = kit;
+  const violations = [];
+  const seen = new Map();
+  let enums = 0;
+  let codes = 0;
+  const files = [...graph.files.values()].filter(file => file.slot === 'be.errors' && file.owner && path.posix.basename(file.rel).endsWith('.error.ts'))
+    .sort((a, b) => a.rel.localeCompare(b.rel));
+  for (const file of files) {
+    const capability = upperSnake(path.posix.basename(file.owner.root));
+    const shape = new RegExp(`^${capability}_[A-Z0-9]+(?:_[A-Z0-9]+)*$`, 'u');
+    for (const statement of file.sourceFile.statements) {
+      if (!ts.isEnumDeclaration(statement) || !statement.name.text.endsWith('ErrorCode')) continue;
+      enums += 1;
+      for (const member of statement.members) {
+        const report = message => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, member), message });
+        const name = kit.propertyNameText(member.name) ?? '?';
+        const value = member.initializer && ts.isStringLiteralLike(member.initializer) ? member.initializer.text : null;
+        if (value === null) { report(`${statement.name.text}.${name} must be a string literal code (\`${capability}_<WHAT>\`); a computed or numeric code cannot be checked or told apart in a log.`); continue; }
+        codes += 1;
+        if (!shape.test(value) || /_(?:ERROR|EXCEPTION)$/u.test(value)) {
+          report(`${statement.name.text}.${name} = "${value}" must match ${capability}_<WHAT> in UPPER_SNAKE with the capability prefix and no _ERROR or _EXCEPTION suffix.`);
+        }
+        if (seen.has(value)) report(`Error code "${value}" is already declared in ${seen.get(value)}; a code is unique across the repository.`);
+        else seen.set(value, file.rel);
+      }
+    }
+  }
+  return { violations, coverage: { status: 'checked', enums, codes } };
+}