@starci/hfs 4.11.21 → 4.12.0

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

@@ -1,5 +1,4 @@
 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 -> CredentialGuard -> AuthGuard, each exactly once, so no request reaches a handler before it was
@@ -13,144 +12,164 @@ import { machineKit } from './machine-ast.mjs';
  * 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', 'credential', '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', credential: 'CredentialGuard of domain/identity', auth: 'AuthGuard of domain/identity' };
-
 const keySymbol = (kit, checker, node) => (node ? kit.aliased(checker, kit.symbolAt(checker, node)) ?? null : null);
-
 const extendsThrottlerType = (kit, checker, declaration, type, depth) => {
-  if (kit.isImportOf(checker, type.expression, 'ThrottlerGuard', '@nestjs/throttler')) return true;
-  return kit.declarationsOf(checker, type.expression).some(parent => parent !== declaration && extendsThrottler(kit, parent, depth + 1));
+    if (kit.isImportOf(checker, type.expression, 'ThrottlerGuard', '@nestjs/throttler'))
+        return true;
+    return kit.declarationsOf(checker, type.expression).some(parent => parent !== declaration && extendsThrottler(kit, parent, depth + 1));
 };
-
 function extendsThrottler(kit, declaration, depth = 0) {
-  if (!kit.ts.isClassDeclaration(declaration) || depth > 8) return false;
-  const checker = kit.checkerOf(declaration.getSourceFile());
-  if (!checker) return false;
-  const types = (declaration.heritageClauses ?? []).flatMap(clause => [...clause.types]);
-  return types.some(type => extendsThrottlerType(kit, checker, declaration, type, depth));
+    const ts = kit.ts;
+    if (!ts.isClassDeclaration(declaration) || depth > 8)
+        return false;
+    const checker = kit.checkerOf(declaration.getSourceFile());
+    if (!checker)
+        return false;
+    const types = (declaration.heritageClauses ?? []).flatMap(clause => [...clause.types]);
+    return types.some(type => extendsThrottlerType(kit, checker, declaration, type, depth));
 }
-
 const collectSetMetadataKeys = (kit, file, keys) => {
-  const { ts } = kit;
-  const checker = kit.checkerOf(file.sourceFile);
-  if (!checker) return;
-  kit.walk(file.sourceFile, node => {
-    if (ts.isCallExpression(node) && kit.isImportOf(checker, node.expression, 'SetMetadata', '@nestjs/common')) {
-      const key = keySymbol(kit, checker, node.arguments[0]);
-      if (key) keys.add(key);
-    }
-    return true;
-  });
+    const { ts } = kit;
+    const checker = kit.checkerOf(file.sourceFile);
+    if (!checker)
+        return;
+    kit.walk(file.sourceFile, (node) => {
+        if (ts.isCallExpression(node) && kit.isImportOf(checker, node.expression, 'SetMetadata', '@nestjs/common')) {
+            const key = keySymbol(kit, checker, node.arguments[0]);
+            if (key)
+                keys.add(key);
+        }
+        return true;
+    });
 };
-
 /** The symbols a SetMetadata call of the owner writes as metadata keys: what its door decorators (`@RateLimit(tier)`) attach. */
 const writtenKeys = (kit, graph, owner, cache) => {
-  if (cache.has(owner.root)) return cache.get(owner.root);
-  const keys = new Set();
-  for (const file of graph.files.values()) {
-    if (file.owner?.root === owner.root) collectSetMetadataKeys(kit, file, keys);
-  }
-  cache.set(owner.root, keys);
-  return keys;
+    const cached = cache.get(owner.root);
+    if (cached)
+        return cached;
+    const keys = new Set();
+    for (const file of graph.files.values()) {
+        if (file.owner?.root === owner.root)
+            collectSetMetadataKeys(kit, file, keys);
+    }
+    cache.set(owner.root, keys);
+    return keys;
 };
-
 /** True when the class reads a request origin or referer header (the origin/referer allowlist of the CSRF guard). */
 const readsOrigin = (kit, declaration) => {
-  const { ts } = kit;
-  let found = false;
-  kit.walk(declaration, node => {
-    let name = null;
-    if (ts.isPropertyAccessExpression(node)) name = node.name.text;
-    else if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression)) name = node.argumentExpression.text;
-    if (name && ORIGIN_HEADERS.has(name.toLowerCase())) found = true;
-    return !found;
-  });
-  return found;
+    const { ts } = kit;
+    let found = false;
+    kit.walk(declaration, (node) => {
+        let name = null;
+        if (ts.isPropertyAccessExpression(node))
+            name = node.name.text;
+        else if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression))
+            name = node.argumentExpression.text;
+        if (name && ORIGIN_HEADERS.has(name.toLowerCase()))
+            found = true;
+        return !found;
+    });
+    return found;
 };
-
 const isMetadataRead = (ts, node) => ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && METADATA_READERS.has(node.expression.name.text);
-
 /** True when the class reads, through a metadata getter, a key its own capability's SetMetadata decorators write. */
 const readsDoorMetadata = (kit, graph, keyCache, declaration, owner) => {
-  const checker = kit.checkerOf(declaration.getSourceFile());
-  if (!checker) return false;
-  const keys = writtenKeys(kit, graph, owner, keyCache);
-  let found = false;
-  kit.walk(declaration, node => {
-    if (isMetadataRead(kit.ts, node)) {
-      const key = keySymbol(kit, checker, node.arguments[0]);
-      if (key && keys.has(key)) found = true;
-    }
-    return !found;
-  });
-  return found;
+    const checker = kit.checkerOf(declaration.getSourceFile());
+    if (!checker)
+        return false;
+    const keys = writtenKeys(kit, graph, owner, keyCache);
+    let found = false;
+    kit.walk(declaration, (node) => {
+        if (isMetadataRead(kit.ts, node)) {
+            const key = keySymbol(kit, checker, node.arguments[0]);
+            if (key && keys.has(key))
+                found = true;
+        }
+        return !found;
+    });
+    return found;
 };
-
 const classifyDeclaration = (kit, graph, keyCache, declaration) => {
-  const { ts } = kit;
-  const owner = kit.ownerOfDeclaration(declaration);
-  if (owner?.tier === 'platform' && owner.name === 'http-security' && ts.isClassDeclaration(declaration)) {
-    if (readsOrigin(kit, declaration)) return 'csrf';
-    if (readsDoorMetadata(kit, graph, keyCache, declaration, owner)) return 'throttler';
-  }
-  if (owner?.tier === 'domain' && owner.name === 'identity' && ts.isClassDeclaration(declaration) && declaration.name?.text === 'AuthGuard') return 'auth';
-  if (owner?.tier === 'domain' && owner.name === 'identity' && ts.isClassDeclaration(declaration) && declaration.name?.text === 'CredentialGuard') return 'credential';
-  return null;
+    const ts = kit.ts;
+    const owner = kit.ownerOfDeclaration(declaration);
+    if (owner?.tier === 'platform' && owner.name === 'http-security' && ts.isClassDeclaration(declaration)) {
+        if (readsOrigin(kit, declaration))
+            return 'csrf';
+        if (readsDoorMetadata(kit, graph, keyCache, declaration, owner))
+            return 'throttler';
+    }
+    if (owner?.tier === 'domain' && owner.name === 'identity' && ts.isClassDeclaration(declaration) && declaration.name?.text === 'AuthGuard')
+        return 'auth';
+    if (owner?.tier === 'domain' && owner.name === 'identity' && ts.isClassDeclaration(declaration) && declaration.name?.text === 'CredentialGuard')
+        return 'credential';
+    return null;
 };
-
 const classify = (kit, graph, keyCache, 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(kit, declaration))) return 'throttler';
-  for (const declaration of declarations) {
-    const role = classifyDeclaration(kit, graph, keyCache, declaration);
-    if (role) return role;
-  }
-  return null;
+    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(kit, declaration)))
+        return 'throttler';
+    for (const declaration of declarations) {
+        const role = classifyDeclaration(kit, graph, keyCache, declaration);
+        if (role)
+            return role;
+    }
+    return null;
 };
-
 const roleMessages = (app, roles, anchor) => {
-  const out = [];
-  for (const role of ORDER) {
-    const entries = roles.filter(item => item.role === role);
-    if (entries.length === 0) out.push({ node: anchor, message: `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 CredentialGuard, then AuthGuard.` });
-    else if (entries.length > 1) out.push({ node: entries[1].guard.node, message: `App ${app.name} provides ${LABEL[role]} more than once as an APP_GUARD.` });
-  }
-  return out;
+    const out = [];
+    for (const role of ORDER) {
+        const entries = roles.filter(item => item.role === role);
+        if (entries.length === 0)
+            out.push({ node: anchor, message: `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 CredentialGuard, then AuthGuard.` });
+        else if (entries.length > 1 && entries[1])
+            out.push({ node: entries[1].guard.node, message: `App ${app.name} provides ${LABEL[role]} more than once as an APP_GUARD.` });
+    }
+    return out;
 };
-
 const orderMessages = (app, roles) => {
-  const indexes = ORDER.map(role => roles.findIndex(item => item.role === role));
-  if (!indexes.every(index => index >= 0)) return [];
-  const out = [];
-  for (let i = 1; i < indexes.length; i += 1) {
-    if (indexes[i] < indexes[i - 1]) out.push({ node: roles[indexes[i]].guard.node, message: `App ${app.name} provides ${LABEL[ORDER[i]]} before ${LABEL[ORDER[i - 1]]}; the APP_GUARD order is throttler, CSRF origin guard, CredentialGuard, AuthGuard.` });
-  }
-  return out;
+    const indexes = ORDER.map(role => roles.findIndex(item => item.role === role));
+    if (!indexes.every(index => index >= 0))
+        return [];
+    const out = [];
+    for (let i = 1; i < indexes.length; i += 1) {
+        const index = indexes[i];
+        const previous = indexes[i - 1];
+        const role = ORDER[i];
+        const before = ORDER[i - 1];
+        const entry = index === undefined ? undefined : roles[index];
+        if (index === undefined || previous === undefined || role === undefined || before === undefined || entry === undefined)
+            continue;
+        if (index < previous)
+            out.push({ node: entry.guard.node, message: `App ${app.name} provides ${LABEL[role]} before ${LABEL[before]}; the APP_GUARD order is throttler, CSRF origin guard, CredentialGuard, AuthGuard.` });
+    }
+    return out;
 };
-
 export function checkDefaultDeny(input) {
-  const { config } = input;
-  const kit = machineKit(input);
-  const violations = [];
-  const keyCache = new Map();
-  let apps = 0;
-
-  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(kit, input.graph, keyCache, guard.checker, guard.useClass) }));
-    const anchor = guards[0]?.node ?? root.sourceFile.statements[0] ?? root.sourceFile;
-    const messages = [...roleMessages(app, roles, anchor), ...orderMessages(app, roles)];
-    for (const { node, message } of messages) violations.push({ ruleId: RULE, path: root.rel, ...kit.at(root.rel, root.sourceFile, node), app: app.name, message });
-  }
-  return { violations, coverage: { status: 'checked', apps } };
+    const { config } = input;
+    const kit = machineKit(input);
+    const violations = [];
+    const keyCache = new Map();
+    let apps = 0;
+    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(kit, input.graph, keyCache, guard.checker, guard.useClass) }));
+        const anchor = guards[0]?.node ?? root.sourceFile.statements[0] ?? root.sourceFile;
+        const messages = [...roleMessages(app, roles, anchor), ...orderMessages(app, roles)];
+        for (const { node, message } of messages)
+            violations.push({ ruleId: RULE, path: root.rel, ...kit.at(root.rel, root.sourceFile, node), app: app.name, message });
+    }
+    return { violations, coverage: { status: 'checked', apps } };
 }

package/runtime/scripts/hfs/architecture/doc-language.d.mts

@@ -0,0 +1,17 @@
+import type { ArchitectureConfig } from './config.mjs';
+import type { HfsGraph } from './hfs-graph.mjs';
+import type { CheckResult } from './context-map.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 declare const DOC_LANGUAGE_RULE_IDS: string[];
+export declare function checkDocLanguage({ config, graph }: {
+    config: ArchitectureConfig;
+    graph: HfsGraph;
+}): CheckResult;

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

@@ -3,7 +3,6 @@ import path from 'node:path';
 import { treeOf } from './required-files.mjs';
 import { documentLanguageHits, isDocument, isLocalizedDataFile } from '../../lib/language.mjs';
 import { byCodeUnit } from '../../lib/list.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
@@ -14,27 +13,33 @@ import { byCodeUnit } from '../../lib/list.mjs';
  * 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. */
 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(byCodeUnit)) {
-    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.` });
+    const resolver = graph.resolver;
+    const tree = treeOf(config.root);
+    const violations = [];
+    let files = 0;
+    for (const file of [...tree.files].sort(byCodeUnit)) {
+        if (!DOCUMENT_ROOTS.includes(file.split('/')[0] ?? '') || !isDocument(file) || file.split('/').includes('node_modules'))
+            continue;
+        const classified = resolver.classifyPath(file);
+        const dataSlot = classified.status === 'owned' ? classified.slot : null;
+        if (dataSlot !== null && isLocalizedDataFile(file, dataSlot))
+            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 } };
+    return { violations, coverage: { status: 'checked', files } };
 }

package/runtime/scripts/hfs/architecture/entity-registry.d.mts

@@ -0,0 +1,49 @@
+import type { Node } from 'typescript';
+/**
+ * The entity registry (persistence.md BE-PERSISTENCE-3): the one file whose slot plays `role: entity-registry`
+ * (`be.platform.database.entities`, lite's `src/modules/platform/database/entities.ts`). It lists every capability's `<c>Entities`
+ * array as `PRIMARY_ENTITIES`, so it is the one platform file that imports domain and platform capability barrels, and only for
+ * that name; and it is imported by deep path only from the files its slot's `importedBy` names (app composition and the test world).
+ * The tier matrix (tiers.mjs), the public-entry check (owners.mjs) and the lint rule `import-owner-entry` read it here.
+ */
+export declare const ENTITY_REGISTRY_ROLE = "entity-registry";
+/** A slot of the manifest as far as the entity registry reads it. */
+export interface RegistrySlot {
+    role?: string;
+    tier?: string;
+    importedBy?: string[];
+}
+/** The slot resolver as far as the entity registry reads it. */
+export interface RegistryResolver {
+    slotOf?(file: string): RegistrySlot | null | undefined;
+    sideOf?(file: string): string | null | undefined;
+    ownerOf(file: string): {
+        slot: string;
+        root: string;
+    } | null | undefined;
+    slot(id: string): RegistrySlot | null | undefined;
+}
+/** An owner-graph edge: side-relative `from` and `to`, with the TypeScript statement that makes it. */
+export interface RegistryEdge {
+    from: string;
+    to: string;
+    declaration?: Node;
+    edge?: {
+        declaration?: Node;
+    };
+}
+/** The entity list a capability exports: `<c>Entities`, `<c>` its folder name in camelCase. */
+export declare const entityListName: (capability: string) => string;
+/** The slot of `file` (side-relative or absolute) when it plays the entity-registry role, else null. */
+export declare function registrySlot(resolver: RegistryResolver | null | undefined, file: string): RegistrySlot | null;
+/**
+ * Whether `file` is one of the importers the registry slot admits by deep path (`importedBy`, side-relative patterns); an app-wide
+ * resolver answers for a side-prefixed path (`be/apps/...`), which is read without its side folder.
+ */
+export declare function registryImporter(resolver: RegistryResolver | null | undefined, slot: RegistrySlot, file: string): boolean;
+/**
+ * Whether an owner-graph edge (side-relative `from` and `to`, `edge.declaration` the TypeScript statement) is the registry naming a
+ * capability's entity list: it leaves the registry, imports the public entry (`index.ts`) of a domain or platform capability, and
+ * binds that capability's `<c>Entities` and nothing else.
+ */
+export declare function registryListImport(resolver: RegistryResolver, edge: RegistryEdge): boolean;

package/runtime/scripts/hfs/architecture/entity-registry.mjs

@@ -1,5 +1,4 @@
 import { braceVariants, globExpression } from '../../lib/glob.mjs';
-
 /**
  * The entity registry (persistence.md BE-PERSISTENCE-3): the one file whose slot plays `role: entity-registry`
  * (`be.platform.database.entities`, lite's `src/modules/platform/database/entities.ts`). It lists every capability's `<c>Entities`
@@ -8,46 +7,45 @@ import { braceVariants, globExpression } from '../../lib/glob.mjs';
  * The tier matrix (tiers.mjs), the public-entry check (owners.mjs) and the lint rule `import-owner-entry` read it here.
  */
 export const ENTITY_REGISTRY_ROLE = 'entity-registry';
-
 /** The tiers whose capabilities contribute an entity list to the registry. */
 const CONTRIBUTING_TIERS = new Set(['domain', 'platform']);
-
 /** The entity list a capability exports: `<c>Entities`, `<c>` its folder name in camelCase. */
-export const entityListName = capability => `${capability.replace(/-([a-z0-9])/g, (_, next) => next.toUpperCase())}Entities`;
-
+export const entityListName = (capability) => `${capability.replace(/-([a-z0-9])/g, (_, next) => next.toUpperCase())}Entities`;
 /** The slot of `file` (side-relative or absolute) when it plays the entity-registry role, else null. */
 export function registrySlot(resolver, file) {
-  const slot = resolver?.slotOf?.(file);
-  return slot?.role === ENTITY_REGISTRY_ROLE ? slot : null;
+    const slot = resolver?.slotOf?.(file);
+    return slot?.role === ENTITY_REGISTRY_ROLE ? slot : null;
 }
-
 /**
  * Whether `file` is one of the importers the registry slot admits by deep path (`importedBy`, side-relative patterns); an app-wide
  * resolver answers for a side-prefixed path (`be/apps/...`), which is read without its side folder.
  */
 export function registryImporter(resolver, slot, file) {
-  const side = resolver?.sideOf?.(file);
-  const rel = side ? file.slice(side.length + 1) : file;
-  return (slot.importedBy ?? []).some(pattern => braceVariants(pattern).some(variant => globExpression(variant).test(rel)));
+    const side = resolver?.sideOf?.(file);
+    const rel = side ? file.slice(side.length + 1) : file;
+    return (slot.importedBy ?? []).some(pattern => braceVariants(pattern).some((variant) => globExpression(variant).test(rel)));
 }
-
 /** The names an import declaration binds by name; null for a default, namespace or side-effect import and for any re-export. */
 function namedImports(declaration) {
-  const clause = declaration?.importClause;
-  if (!clause || clause.name || !Array.isArray(clause.namedBindings?.elements) || !clause.namedBindings.elements.length) return null;
-  return clause.namedBindings.elements.map(element => (element.propertyName ?? element.name).text);
+    const clause = declaration?.importClause;
+    const bindings = clause?.namedBindings;
+    if (!clause || clause.name || !Array.isArray(bindings?.elements) || !bindings.elements.length)
+        return null;
+    return bindings.elements.map(element => (element.propertyName ?? element.name).text);
 }
-
 /**
  * Whether an owner-graph edge (side-relative `from` and `to`, `edge.declaration` the TypeScript statement) is the registry naming a
  * capability's entity list: it leaves the registry, imports the public entry (`index.ts`) of a domain or platform capability, and
  * binds that capability's `<c>Entities` and nothing else.
  */
 export function registryListImport(resolver, edge) {
-  if (!registrySlot(resolver, edge.from)) return false;
-  const owner = resolver.ownerOf(edge.to);
-  if (!owner || !CONTRIBUTING_TIERS.has(resolver.slot(owner.slot)?.tier) || edge.to !== `${owner.root}/index.ts`) return false;
-  const names = namedImports(edge.edge?.declaration ?? edge.declaration);
-  const listName = entityListName(owner.root.split('/').at(-1));
-  return names !== null && names.every(name => name === listName);
+    if (!registrySlot(resolver, edge.from))
+        return false;
+    const owner = resolver.ownerOf(edge.to);
+    const tier = owner ? resolver.slot(owner.slot)?.tier : undefined;
+    if (!owner || !CONTRIBUTING_TIERS.has(tier ?? '') || edge.to !== `${owner.root}/index.ts`)
+        return false;
+    const names = namedImports(edge.edge?.declaration ?? edge.declaration);
+    const listName = entityListName(owner.root.split('/').at(-1) ?? '');
+    return names !== null && names.every(name => name === listName);
 }

package/runtime/scripts/hfs/architecture/entrypoint.d.mts

@@ -0,0 +1,13 @@
+import type { CheckResult, HfsCheckInput } from './context-map.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 declare const ENTRYPOINT_RULE_IDS: string[];
+export declare function checkEntrypoints(input: HfsCheckInput): CheckResult;

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

@@ -1,7 +1,6 @@
 import path from 'node:path';
 import { machineKit } from './machine-ast.mjs';
 import { isTestWorldSlot } from '../test-world-slot.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
@@ -13,61 +12,64 @@ import { isTestWorldSlot } from '../test-world-slot.mjs';
  * other test slots stay refused.
  */
 export const ENTRYPOINT_RULE_IDS = ['BE_ENTRYPOINT_ONLY_IN_APPS'];
-
 const RULE = 'BE_ENTRYPOINT_ONLY_IN_APPS';
-
 const TRANSPARENT = ['isVoidExpression', 'isAwaitExpression', 'isParenthesizedExpression', 'isNonNullExpression'];
-
+const isTransparent = (ts, node) => TRANSPARENT.some(test => ts[test](node));
 /** The identifier a top-level statement calls: `bootstrap()`, `void bootstrap()`, `bootstrap().catch(...)`. */
 function calledIdentifier(ts, expression) {
-  let current = expression;
-  for (;;) {
-    if (TRANSPARENT.some(test => ts[test](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;
-  }
+    let current = expression;
+    for (;;) {
+        if (isTransparent(ts, 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;
+    }
 }
-
 const isNestFactoryCreate = (kit, ts, checker, node) => ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text.startsWith('create')
-  && kit.isImportOf(checker, node.expression.expression, 'NestFactory', '@nestjs/core');
-
-const isMainFile = file => (Boolean(file.slot?.startsWith('be.app.')) && path.posix.basename(file.rel) === 'main.ts') || isTestWorldSlot(file.slot);
-
+    && kit.isImportOf(checker, node.expression.expression, 'NestFactory', '@nestjs/core');
+const isMainFile = (file) => (Boolean(file.slot?.startsWith('be.app.')) && path.posix.basename(file.rel) === 'main.ts') || isTestWorldSlot(file.slot);
 /** Counts the NestFactory.create* calls of an entrypoint owner and reports them in any other file. */
 function inspectFactoryCalls(kit, file, isMain, report) {
-  const { ts } = kit;
-  const checker = kit.checkerOf(file.sourceFile);
-  let entrypoints = 0;
-  kit.walk(file.sourceFile, node => {
-    if (!isNestFactoryCreate(kit, ts, checker, node)) return;
-    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 entrypoints;
+    const { ts } = kit;
+    const checker = kit.checkerOf(file.sourceFile);
+    let entrypoints = 0;
+    kit.walk(file.sourceFile, (node) => {
+        if (!isNestFactoryCreate(kit, ts, checker, node))
+            return;
+        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 entrypoints;
 }
-
 function inspectBootstrapCalls(ts, file, report) {
-  for (const statement of file.sourceFile.statements) {
-    if (!ts.isExpressionStatement(statement)) continue;
-    if (calledIdentifier(ts, 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.");
+    for (const statement of file.sourceFile.statements) {
+        if (!ts.isExpressionStatement(statement))
+            continue;
+        if (calledIdentifier(ts, 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.");
+        }
     }
-  }
 }
-
 export function checkEntrypoints(input) {
-  const { graph } = input;
-  const kit = machineKit(input);
-  const violations = [];
-  let entrypoints = 0;
-  for (const file of graph.files.values()) {
-    const isMain = isMainFile(file);
-    const report = (node, message) => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message });
-    entrypoints += inspectFactoryCalls(kit, file, isMain, report);
-    if (!isMain) inspectBootstrapCalls(kit.ts, file, report);
-  }
-  return { violations, coverage: { status: 'checked', entrypoints } };
+    const { graph } = input;
+    const kit = machineKit(input);
+    const violations = [];
+    let entrypoints = 0;
+    for (const file of graph.files.values()) {
+        const isMain = isMainFile(file);
+        const report = (node, message) => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message });
+        entrypoints += inspectFactoryCalls(kit, file, isMain, report);
+        if (!isMain)
+            inspectBootstrapCalls(kit.ts, file, report);
+    }
+    return { violations, coverage: { status: 'checked', entrypoints } };
 }

package/runtime/scripts/hfs/architecture/error-codes.d.mts

@@ -0,0 +1,16 @@
+import type { ArchitectureViolation, CheckInput } from './hfs-graph.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 declare const ERROR_CODE_RULE_IDS: string[];
+export declare function checkErrorCodes(input: CheckInput): {
+    violations: ArchitectureViolation[];
+    coverage: {
+        status: string;
+        enums: number;
+        codes: number;
+    };
+};