@starci/hfs 1.0.1 → 2.0.0

package/runtime/scripts/checks/architecture/hooks-are-hooks.mjs

@@ -0,0 +1,88 @@
+import path from 'node:path';
+import { machineKit } from './machine-ast.mjs';
+import { treeOf } from './required-files.mjs';
+
+/**
+ * R56 `hooks-are-hooks` (FE_HOOKS_ARE_HOOKS), the repository half of the eslint rule `hooks-folder-holds-hooks-only`, which
+ * judges one file at a time and leaves to the machine what needs the whole tree. Per domain folder of hooks
+ * (slot fe.hooks, apps/<app>/src/hooks/<domain>):
+ *
+ *   - at most one shared file, named `<domain>.shared.ts`: a second `*.shared.ts`, or one named for another domain, is a
+ *     second dumping ground for non-hook helpers;
+ *   - no helper declared twice: a top-level function or arrow-function constant that is not a hook and whose name is declared
+ *     in two files of the domain is a helper copied instead of shared; it lives once in `<domain>.shared.ts`.
+ */
+export const HOOKS_ARE_HOOKS_RULE_IDS = ['FE_HOOKS_ARE_HOOKS'];
+
+const RULE = 'FE_HOOKS_ARE_HOOKS';
+const HOOKS_SLOT = 'fe.hooks';
+const HOOK_NAME = /^use[A-Z0-9]/u;
+const SHARED = /\.shared\.[cm]?tsx?$/u;
+
+export function checkHooksAreHooks(input) {
+  const { config, graph } = input;
+  const kit = machineKit(input);
+  const { ts, resolver } = kit;
+  const violations = [];
+  const domains = new Set();
+
+  const tree = treeOf(config.root);
+  const shared = new Map(); // domain root -> [file]
+  for (const rel of [...tree.files].sort()) {
+    const classified = resolver.classifyPath(rel);
+    if (classified.slot !== HOOKS_SLOT || !classified.root) continue;
+    domains.add(classified.root);
+    const base = path.posix.basename(rel);
+    if (/\.spec\.[cm]?tsx?$/u.test(base) || !SHARED.test(base)) continue;
+    if (!shared.has(classified.root)) shared.set(classified.root, []);
+    shared.get(classified.root).push({ rel, base });
+  }
+  for (const [root, list] of shared) {
+    const domain = path.posix.basename(root);
+    const at = (item, message) => violations.push({ ruleId: RULE, path: item.rel, line: 1, column: 1, domain, message });
+    for (const item of list) {
+      if (item.base.replace(/\.[cm]?tsx?$/u, '') !== `${domain}.shared` || path.posix.dirname(item.rel) !== root) {
+        at(item, `${item.rel} is a shared file that is not ${root}/${domain}.shared.ts; a hooks domain has one shared file for its non-hook helpers, named after the domain. Move the helpers into it.`);
+      }
+    }
+    for (const item of list.filter(entry => entry.base.replace(/\.[cm]?tsx?$/u, '') === `${domain}.shared` && path.posix.dirname(entry.rel) === root).slice(1)) {
+      at(item, `${item.rel} is a second shared file of hooks domain ${domain}; a domain has exactly one, ${domain}.shared.ts. Merge the helpers into it.`);
+    }
+  }
+
+  // Helpers declared in more than one file of one domain.
+  const declared = new Map(); // domain root -> name -> [{file, node}]
+  for (const file of graph.files.values()) {
+    if (file.slot !== HOOKS_SLOT) continue;
+    const root = resolver.classifyPath(file.rel).root;
+    for (const statement of file.sourceFile.statements) {
+      const found = [];
+      if (ts.isFunctionDeclaration(statement) && statement.name) found.push([statement.name.text, statement.name]);
+      if (ts.isVariableStatement(statement)) {
+        for (const declaration of statement.declarationList.declarations) {
+          const init = declaration.initializer;
+          if (ts.isIdentifier(declaration.name) && init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) found.push([declaration.name.text, declaration.name]);
+        }
+      }
+      for (const [name, node] of found) {
+        if (HOOK_NAME.test(name)) continue;
+        if (!declared.has(root)) declared.set(root, new Map());
+        const byName = declared.get(root);
+        if (!byName.has(name)) byName.set(name, []);
+        byName.get(name).push({ file, node });
+      }
+    }
+  }
+  for (const [root, byName] of declared) {
+    const domain = path.posix.basename(root);
+    for (const [name, list] of byName) {
+      if (list.length < 2) continue;
+      for (const item of list.slice(1)) {
+        const others = list.map(entry => entry.file.rel).filter(rel => rel !== item.file.rel).sort();
+        violations.push({ ruleId: RULE, path: item.file.rel, ...kit.at(item.file.rel, item.file.sourceFile, item.node), domain, helper: name,
+          message: `${name} is declared again in hooks domain ${domain} (also in ${others.join(', ')}); a helper the hooks share is written once, in ${domain}.shared.ts.` });
+      }
+    }
+  }
+  return { violations, coverage: { status: 'checked', domains: domains.size } };
+}

package/runtime/scripts/checks/architecture/i18n-keys.mjs

@@ -0,0 +1,146 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * R106 `i18n-keys` (FE_I18N_KEYS). The catalogs of an app (`apps/<app>/src/modules/i18n/messages/<locale>.json`, slot fe.modules.i18n) and
+ * the source that reads them agree, both ways. The key sets of the locales agree with each other (FE_I18N_CATALOG, `hfs check`); this
+ * rule holds the source to the catalogs:
+ *
+ *   - a key read with a literal is in every locale: `useTranslations("ns")` / `getTranslations("ns")` (also `{ namespace }`, `await`)
+ *     imported from `next-intl` or `next-intl/server`, then `t("key")`, `t.rich("key")`, `t.raw("key")`, `t.markup("key")` inside the app's
+ *     own source (both branches of a conditional key are read). A key no locale's catalog holds is FE_I18N_KEYS, once per call. A computed
+ *     key (a template with an interpolation, a variable) is not judged here; it counts as a read.
+ *   - a key nobody reads is dead: a leaf of the app's catalogs that no string in the app's or the shared packages' source can be reading.
+ *     A leaf counts as read when a string literal or a template pattern (each interpolation a wildcard segment) of that source equals a
+ *     tail of its dotted path (`"title"`, `"card.title"`, `"orders.card.title"` all read `orders.card.title`); the test is deliberately loose
+ *     so a key handed through props or a table of keys is never reported, and only a key that appears nowhere is.
+ *
+ * Reads the source of the program and the JSON catalogs on disk; the wording of a translation is the product owner's.
+ */
+export const I18N_KEYS_RULE_IDS = ['FE_I18N_KEYS'];
+
+const RULE = 'FE_I18N_KEYS';
+const MODULES = new Set(['next-intl', 'next-intl/server']);
+const FACTORIES = new Set(['useTranslations', 'getTranslations']);
+const READERS = new Set(['rich', 'raw', 'markup']);
+const APP_SOURCE = /^apps\/([^/]+)\/src\//u;
+
+const leavesOf = (value, prefix = '') => (value !== null && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length
+  ? Object.entries(value).flatMap(([key, child]) => leavesOf(child, prefix ? `${prefix}.${key}` : key))
+  : [prefix]);
+
+const readCatalog = (root, rel) => {
+  try { return new Set(leavesOf(JSON.parse(fs.readFileSync(path.join(root, rel), 'utf8'))).filter(Boolean)); } catch { return null; }
+};
+
+/** True when the key `full` is a leaf of `leaves` or a namespace above one (an object read by `rich`, `raw` or a nested `t`). */
+const held = (leaves, full) => leaves.has(full) || [...leaves].some(leaf => leaf.startsWith(`${full}.`));
+
+// A pattern that is only wildcards (`${a}`, `${a}.${b}`) names nothing: it would read every key, so it reads none.
+const tailMatches = (pattern, leafSegments) => pattern.some(segment => segment !== '*' && segment !== '') && pattern.length <= leafSegments.length
+  && pattern.every((segment, index) => segment === '*' || segment === leafSegments[leafSegments.length - pattern.length + index]);
+
+export function checkI18nKeys({ config, graph, context }) {
+  const ts = context.ts;
+  const violations = [];
+  const report = (file, node, message, extra = {}) => {
+    const at = file.sourceFile.getLineAndCharacterOfPosition(node.getStart(file.sourceFile));
+    violations.push({ ruleId: RULE, path: file.rel, line: at.line + 1, column: at.character + 1, message, ...extra });
+  };
+
+  const catalogsByApp = new Map();
+  const seen = new Set();
+  for (const file of graph.files.values()) {
+    const app = APP_SOURCE.exec(file.rel)?.[1];
+    if (!app || seen.has(app)) continue;
+    seen.add(app);
+    const dir = `apps/${app}/src/modules/i18n/messages/`;
+    let names = [];
+    try { names = fs.readdirSync(path.join(config.root, dir)).filter(name => name.endsWith('.json')).sort(); } catch { /* the app has no catalog directory: FE_I18N_PLACEMENT's finding */ }
+    if (names.length) catalogsByApp.set(dir, names.map(name => ({ rel: `${dir}${name}`, locale: name.slice(0, -5) })));
+  }
+
+  let apps = 0;
+  for (const [dir, catalogs] of catalogsByApp) {
+    const app = /^apps\/([^/]+)\//u.exec(dir)?.[1];
+    const loaded = catalogs.map(catalog => ({ ...catalog, leaves: readCatalog(config.root, catalog.rel) })).filter(catalog => catalog.leaves);
+    if (!app || !loaded.length) continue;
+    apps += 1;
+    const own = [...graph.files.values()].filter(file => file.rel.startsWith(`apps/${app}/src/`));
+    const shared = [...graph.files.values()].filter(file => /^packages\/[^/]+\/src\//u.test(file.rel));
+    const patterns = [];
+
+    for (const file of [...own, ...shared]) {
+      const visit = node => {
+        if (ts.isStringLiteralLike(node)) patterns.push(node.text.split('.'));
+        else if (ts.isTemplateExpression(node)) patterns.push([node.head.text, ...node.templateSpans.map(span => span.literal.text)].join('\u0000').split('\u0000').join('*').split('.'));
+        ts.forEachChild(node, visit);
+      };
+      visit(file.sourceFile);
+    }
+
+    for (const file of own) {
+      const factories = new Set();
+      for (const statement of file.sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || !MODULES.has(statement.moduleSpecifier.text)) continue;
+        const named = statement.importClause?.namedBindings;
+        if (!named || !ts.isNamedImports(named)) continue;
+        for (const element of named.elements) if (!element.isTypeOnly && FACTORIES.has((element.propertyName ?? element.name).text)) factories.add(element.name.text);
+      }
+      if (!factories.size) continue;
+      const checker = context.checkerFor(file.sourceFile.fileName);
+      const namespaces = new Map();   // translator variable declaration -> namespace ('' = none); a computed namespace is left out
+      const collect = node => {
+        if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+          let init = node.initializer;
+          if (ts.isAwaitExpression(init)) init = init.expression;
+          if (ts.isCallExpression(init) && ts.isIdentifier(init.expression) && factories.has(init.expression.text)) {
+            const [first] = init.arguments;
+            if (first === undefined) namespaces.set(node, '');
+            else if (ts.isStringLiteralLike(first)) namespaces.set(node, first.text);
+            else if (ts.isObjectLiteralExpression(first)) {
+              const property = first.properties.find(candidate => ts.isPropertyAssignment(candidate) && candidate.name.getText(file.sourceFile) === 'namespace');
+              if (!property) namespaces.set(node, '');
+              else if (ts.isStringLiteralLike(property.initializer)) namespaces.set(node, property.initializer.text);
+            }
+          }
+        }
+        ts.forEachChild(node, collect);
+      };
+      collect(file.sourceFile);
+      if (!namespaces.size) continue;
+      const keysOf = argument => {
+        if (ts.isConditionalExpression(argument)) return [...keysOf(argument.whenTrue), ...keysOf(argument.whenFalse)];
+        if (ts.isParenthesizedExpression(argument) || ts.isAsExpression(argument) || ts.isSatisfiesExpression(argument)) return keysOf(argument.expression);
+        return ts.isStringLiteralLike(argument) ? [argument] : [];
+      };
+      const read = node => {
+        if (ts.isCallExpression(node)) {
+          const callee = node.expression;
+          const owner = ts.isIdentifier(callee) ? callee : (ts.isPropertyAccessExpression(callee) && READERS.has(callee.name.text) && ts.isIdentifier(callee.expression) ? callee.expression : null);
+          const [first] = node.arguments;
+          const declaration = owner ? checker.getSymbolAtLocation(owner)?.valueDeclaration : null;
+          if (owner && first !== undefined && namespaces.has(declaration)) {
+            for (const literal of keysOf(first)) {
+              const namespace = namespaces.get(declaration);
+              const full = namespace ? `${namespace}.${literal.text}` : literal.text;
+              const lacking = loaded.filter(catalog => !held(catalog.leaves, full)).map(catalog => catalog.locale);
+              if (lacking.length) report(file, literal, `${file.rel} reads "${full}" and ${lacking.join(', ')} ${lacking.length === 1 ? 'holds' : 'hold'} no such key; add it to every catalog of ${app} or read a key that exists`, { key: full, locales: lacking });
+            }
+          }
+        }
+        ts.forEachChild(node, read);
+      };
+      read(file.sourceFile);
+    }
+
+    const [primary] = [...loaded].sort((a, b) => a.locale.localeCompare(b.locale));
+    const every = new Set(loaded.flatMap(catalog => [...catalog.leaves]));
+    for (const leaf of [...every].sort()) {
+      const segments = leaf.split('.');
+      if (patterns.some(pattern => tailMatches(pattern, segments))) continue;
+      violations.push({ ruleId: RULE, path: primary.rel, line: 1, column: 1, message: `${primary.rel} holds the key "${leaf}" and no source of ${app} or the shared packages reads it; delete the key from every catalog`, key: leaf });
+    }
+  }
+  return { violations, coverage: { status: 'checked', apps } };
+}

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

@@ -0,0 +1,316 @@
+import path from 'node:path';
+import { canonical, loadArchitectureConfig } from './config.mjs';
+import { sameOrUnder } from '../../lib/path-key.mjs';
+import { buildTypeScriptContext, relativePath } from './typescript.mjs';
+import { checkBackend } from './backend.mjs';
+import { checkBackendContracts, PUBLIC_CONTRACT_RULE_ID, READONLY_BOUNDARY_RULE_ID } from './contracts.mjs';
+import { checkFrontend } from './frontend.mjs';
+import { checkOwners } from './owners.mjs';
+import { checkModuleRegistration, REGISTRATION_RULE_IDS } from './registration.mjs';
+import { checkFrontendDataLifecycle, SWR_DATA_RULE_IDS } from './next-data.mjs';
+import { checkBackendSourceShape, SOURCE_LAYOUT_RULE_ID, SOURCE_NAME_RULE_ID } from './source-names.mjs';
+import { checkHfs, checkHfsWithoutConfig, HFS_RULE_IDS } from './hfs.mjs';
+import { buildHfsGraph } from './hfs-graph.mjs';
+import { checkTiers, TIER_RULE_IDS } from './tiers.mjs';
+import { checkReachability, REACHABILITY_RULE_IDS } from './reachability.mjs';
+import { checkDeadExports, DEAD_EXPORT_RULE_IDS } from './dead-exports.mjs';
+import { checkRequiredFiles, REQUIRED_FILE_RULE_IDS } from './required-files.mjs';
+import { checkSizeGrowth, SIZE_GROWTH_RULE_IDS } from './size-growth.mjs';
+import { checkClones, CLONE_RULE_IDS } from './clones.mjs';
+import { checkSymbols, SYMBOL_RULE_IDS } from './symbols.mjs';
+import { checkConnectionMap, CONNECTION_RULE_IDS } from './connection-map.mjs';
+import { checkSqlOwner, SQL_OWNER_RULE_IDS } from './sql-owner.mjs';
+import { checkRegisterOnce, REGISTER_ONCE_RULE_IDS } from './register-once.mjs';
+import { checkErrorMasked, ERROR_MASKED_RULE_IDS } from './error-masked.mjs';
+import { checkDefaultDeny, DEFAULT_DENY_RULE_IDS } from './default-deny.mjs';
+import { checkEntrypoints, ENTRYPOINT_RULE_IDS } from './entrypoint.mjs';
+import { checkErrorCodes, ERROR_CODE_RULE_IDS } from './error-codes.mjs';
+import { checkConfigUnread, CONFIG_UNREAD_RULE_IDS } from './config-unread.mjs';
+import { checkFeatureShape, FEATURE_SHAPE_RULE_IDS } from './feature-shape.mjs';
+import { checkTestWorldFiles, TEST_WORLD_FILES_RULE_IDS } from './test-world-files.mjs';
+import { checkUnitSpecProviders, UNIT_SPEC_PROVIDERS_RULE_IDS } from './unit-spec-providers.mjs';
+import { checkInjectionTokenExported, INJECTION_TOKEN_EXPORTED_RULE_IDS } from './injection-token-exported.mjs';
+import { checkContractFixtureGuard, CONTRACT_FIXTURE_GUARD_RULE_IDS } from './contract-fixture-guard.mjs';
+import { checkSchemaOwner, SCHEMA_OWNER_RULE_IDS } from './schema-owner.mjs';
+import { checkModulePerTransport, MODULE_PER_TRANSPORT_RULE_IDS } from './module-per-transport.mjs';
+import { checkBackgroundUnowned, BACKGROUND_UNOWNED_RULE_IDS } from './background-unowned.mjs';
+import { checkTransportOwner, TRANSPORT_OWNER_RULE_IDS } from './transport-owner.mjs';
+import { checkRouteFilesThin, ROUTE_FILES_THIN_RULE_IDS } from './route-files-thin.mjs';
+import { checkHooksAreHooks, HOOKS_ARE_HOOKS_RULE_IDS } from './hooks-are-hooks.mjs';
+import { checkClientReachesServer, CLIENT_REACHES_SERVER_RULE_IDS } from './client-reaches-server.mjs';
+import { checkCrossAppDuplicate, CROSS_APP_DUPLICATE_RULE_IDS } from './cross-app-duplicate.mjs';
+import { checkPackageShape, PACKAGE_SHAPE_RULE_IDS } from './package-shape.mjs';
+import { checkFeSlotAllows, FE_SLOT_ALLOWS_RULE_IDS } from './fe-slot-allows.mjs';
+import { checkI18nKeys, I18N_KEYS_RULE_IDS } from './i18n-keys.mjs';
+import { checkDocLanguage, DOC_LANGUAGE_RULE_IDS } from './doc-language.mjs';
+
+export { REGISTRATION_RULE_IDS, SWR_DATA_RULE_IDS };
+
+const LIMITATIONS = [
+  'This is a static TypeScript dependency and source-shape check; it does not prove runtime dependency-injection bindings, global/provider scope, state lifetime, server/client behavior, feature-versus-capability ownership, route behavior, or business correctness.',
+  'Dependencies hidden behind constructed aliases, reflection, or calls other than direct import()/require() syntax require separate review.',
+  'Protocol surfaces selected through reflection, nonliteral computed properties, or aliases constructed beyond static import/re-export bindings require separate review.',
+  'Backend source-shape rules classify only resolved roots, declarations, framework symbols, and static decorator arguments; cohesive capability, error, persistence, and migration ownership still require design and runtime evidence.',
+  'Backend contract rules prove selected declaration and readonly field forms only; they do not prove runtime validation, serialization compatibility, provider scope, token identity, or dependency behavior.',
+  'Frontend SWR lifecycle rules prove declared key bindings and installed SWR identity only; domain identity completeness, stale-result behavior and mutation effects require target behavior evidence.',
+];
+
+// The backend composition and data machine (R29, R32, R33, R35, R38, R39, R41, R45, R46, R47, R48, R84, R85, R86): name -> [check, the rule ids it makes truthful].
+const BACKEND_MACHINE = {
+  connectionMap: [checkConnectionMap, CONNECTION_RULE_IDS],
+  sqlOwner: [checkSqlOwner, SQL_OWNER_RULE_IDS],
+  registerOnce: [checkRegisterOnce, REGISTER_ONCE_RULE_IDS],
+  errorMasked: [checkErrorMasked, ERROR_MASKED_RULE_IDS],
+  defaultDeny: [checkDefaultDeny, DEFAULT_DENY_RULE_IDS],
+  entrypoints: [checkEntrypoints, ENTRYPOINT_RULE_IDS],
+  errorCodes: [checkErrorCodes, ERROR_CODE_RULE_IDS],
+  featureShape: [checkFeatureShape, FEATURE_SHAPE_RULE_IDS],
+  unitSpecProviders: [checkUnitSpecProviders, UNIT_SPEC_PROVIDERS_RULE_IDS],
+  injectionTokenExported: [checkInjectionTokenExported, INJECTION_TOKEN_EXPORTED_RULE_IDS],
+  schemaOwner: [checkSchemaOwner, SCHEMA_OWNER_RULE_IDS],
+  modulePerTransport: [checkModulePerTransport, MODULE_PER_TRANSPORT_RULE_IDS],
+  backgroundUnowned: [checkBackgroundUnowned, BACKGROUND_UNOWNED_RULE_IDS],
+  testWorldFiles: [checkTestWorldFiles, TEST_WORLD_FILES_RULE_IDS],
+  contractFixtureGuard: [checkContractFixtureGuard, CONTRACT_FIXTURE_GUARD_RULE_IDS],
+};
+
+// The frontend repository machine (R21, R50, R54, R55, R56, R63, R94, R106): same shape, run for a front-end repository only.
+const FRONTEND_MACHINE = {
+  transportOwner: [checkTransportOwner, TRANSPORT_OWNER_RULE_IDS],
+  routeFilesThin: [checkRouteFilesThin, ROUTE_FILES_THIN_RULE_IDS],
+  hooksAreHooks: [checkHooksAreHooks, HOOKS_ARE_HOOKS_RULE_IDS],
+  packageShape: [checkPackageShape, PACKAGE_SHAPE_RULE_IDS],
+  clientReachesServer: [checkClientReachesServer, CLIENT_REACHES_SERVER_RULE_IDS],
+  crossAppDuplicate: [checkCrossAppDuplicate, CROSS_APP_DUPLICATE_RULE_IDS],
+  feSlotAllows: [checkFeSlotAllows, FE_SLOT_ALLOWS_RULE_IDS],
+  i18nKeys: [checkI18nKeys, I18N_KEYS_RULE_IDS],
+};
+
+/** Errors the machine reports when a program cannot be built or an edge cannot be proven: it cannot judge, so it refuses. */
+const COMMON_REFUSAL_RULE_IDS = [
+  'ARCH_DYNAMIC_DEPENDENCY_UNPROVEN',
+  'ARCH_INTERNAL_IMPORT_OUTSIDE',
+  'ARCH_INTERNAL_IMPORT_UNRESOLVED',
+  'ARCH_NO_SOURCE',
+  'ARCH_SYNTAX_INVALID',
+  'ARCH_TSCONFIG_INVALID',
+  'ARCH_TSCONFIG_MISSING',
+  'ARCH_TSCONFIG_REFERENCE_OUTSIDE',
+];
+const COMMON_RULE_IDS = [
+  ...COMMON_REFUSAL_RULE_IDS,
+  'ARCH_PACKAGE_EXPORT_BYPASS',
+  'ARCH_PACKAGE_IMPORTS_APP',
+];
+const BACKEND_RULE_IDS = [
+  'BE_APP_BUSINESS_ROLE',
+  'BE_APP_COMPOSITION_ONLY',
+  'BE_APPLICATION_IMPORTS_TRANSPORT',
+  'BE_APPLICATION_TRANSPORT_FRAMEWORK',
+];
+const FRONTEND_RULE_IDS = [
+  'FE_BLOCK_PRODUCT_HOOK_DEFINITION',
+  'FE_COMPONENT_WORLD_OWNERSHIP',
+  'FE_COMPONENT_DEEP_HOOK_IMPORT',
+  'FE_CONNECTED_BLOCK_RENDER_PAIR',
+  'FE_CUSTOM_HOOK_LOCATION',
+  'FE_PURE_REACHES_DATA',
+  'FE_PURE_WORLD_HOOK',
+  'FE_PURE_WORLD_IMPORT',
+  'FE_ROUTE_CLIENT_BOUNDARY',
+  'FE_ROUTE_CLIENT_HOOK',
+  'FE_ROUTE_DEFAULT_EXPORT',
+  'FE_ROUTE_DRAWING_DECISION',
+  'FE_ROUTE_ONE_PAGE',
+  'FE_SOURCE_LAYOUT_INVALID',
+  'FE_WORLD_OWNER_RENDER_BOUNDARY',
+];
+export const OWNER_RULE_IDS = ['ARCH_OWNER_EXPORT_BYPASS', 'ARCH_OWNER_EXPORT_STAR'];
+export const GRAMMAR_RULE_IDS = ['ARCH_GRAMMAR_CONTRACT_INVALID', 'ARCH_GRAMMAR_EXPORT_BYPASS'];
+
+/**
+ * Every code the machine reports as an error because it cannot judge (a check that cannot run is an error, never a pass).
+ * These are infrastructure refusals, not obligations, so no rule of knowledge/hfs/rules.yaml owns them.
+ */
+export const ERROR_RULE_IDS = Object.freeze([
+  'ARCH_COMPILER_FAILURE', 'ARCH_CONFIG_INVALID', 'ARCH_EXECUTION_UNAVAILABLE', 'ARCH_KNOWLEDGE_UNAVAILABLE', 'ARCH_TYPESCRIPT_INVALID', 'ARCH_TYPESCRIPT_MISSING',
+  ...COMMON_REFUSAL_RULE_IDS,
+]);
+
+const machineIds = () => [
+  ...TIER_RULE_IDS, ...REACHABILITY_RULE_IDS, ...DEAD_EXPORT_RULE_IDS, ...REQUIRED_FILE_RULE_IDS, ...SIZE_GROWTH_RULE_IDS, ...CLONE_RULE_IDS, ...SYMBOL_RULE_IDS,
+  ...Object.values(BACKEND_MACHINE).flatMap(([, ids]) => ids), ...Object.values(FRONTEND_MACHINE).flatMap(([, ids]) => ids),
+];
+/**
+ * The rules only the HFS machine emits: the tier, reachability, dead-export, required-file, size, clone and symbol checks and the
+ * backend composition and data machine and frontend repository machine. A rule id an ordinary check also emits (the composition
+ * spec and the app-composition check both report BE_APP_COMPOSITION_ONLY) is not here. A spec about another rule judges its own
+ * report without these (they have their own specs); every one of them is in ARCHITECTURE_RULE_IDS.
+ */
+export const HFS_MACHINE_RULE_IDS = Object.freeze((() => {
+  const ordinary = new Set([...COMMON_RULE_IDS, ...BACKEND_RULE_IDS, ...FRONTEND_RULE_IDS, ...OWNER_RULE_IDS, ...GRAMMAR_RULE_IDS, ...REGISTRATION_RULE_IDS,
+    ...SWR_DATA_RULE_IDS, SOURCE_LAYOUT_RULE_ID, SOURCE_NAME_RULE_ID, PUBLIC_CONTRACT_RULE_ID, READONLY_BOUNDARY_RULE_ID]);
+  return [...new Set(machineIds().filter((id) => !ordinary.has(id)))].sort();
+})());
+
+/** Every code the machine can emit, derived from the rule id lists of its checks (`hfs check` ships exactly these why entries). */
+export const ARCHITECTURE_RULE_IDS = Object.freeze([...new Set([
+  ...COMMON_RULE_IDS, ...BACKEND_RULE_IDS, ...FRONTEND_RULE_IDS, ...HFS_RULE_IDS, ...TIER_RULE_IDS, ...REACHABILITY_RULE_IDS,
+  ...DEAD_EXPORT_RULE_IDS, ...DOC_LANGUAGE_RULE_IDS, ...REQUIRED_FILE_RULE_IDS, ...SIZE_GROWTH_RULE_IDS, ...CLONE_RULE_IDS, ...OWNER_RULE_IDS, ...GRAMMAR_RULE_IDS,
+  ...REGISTRATION_RULE_IDS, ...SWR_DATA_RULE_IDS, ...SYMBOL_RULE_IDS, SOURCE_LAYOUT_RULE_ID, SOURCE_NAME_RULE_ID, PUBLIC_CONTRACT_RULE_ID,
+  READONLY_BOUNDARY_RULE_ID, ...ERROR_RULE_IDS, ...CONFIG_UNREAD_RULE_IDS, ...Object.values(BACKEND_MACHINE).flatMap(([, ids]) => ids), ...Object.values(FRONTEND_MACHINE).flatMap(([, ids]) => ids),
+])].sort());
+
+function stable(items) {
+  return items.sort((a, b) => `${a.path ?? ''}:${a.line ?? 0}:${a.column ?? 0}:${a.ruleId}`.localeCompare(`${b.path ?? ''}:${b.line ?? 0}:${b.column ?? 0}:${b.ruleId}`));
+}
+
+/**
+ * Check a target repository. injectedTypeScript exists only for hermetic rule fixtures. `fast` leaves out the checks
+ * that read the whole repository to answer (clones, dead exports, repository-wide symbols); the pre-push check of the changed owners uses it.
+ */
+export function checkArchitecture({ repositoryRoot, injectedTypeScript, paths = [], base, fast = false, hfs: openedHfs } = {}) {
+  let config;
+  try {
+    config = loadArchitectureConfig(repositoryRoot, { hfs: openedHfs });
+  } catch (error) {
+    const hfs = checkHfsWithoutConfig(repositoryRoot);
+    return { schema: 'starci/architecture-check@1', ok: false, repository: String(repositoryRoot ?? ''), kinds: [], files: 0,
+      compiler: null, violations: stable(hfs.violations), coverage: { hfs: hfs.coverage },
+      errors: [{ ruleId: /^(HFS_[A-Z_]+):/.exec(String(error.message))?.[1] ?? 'ARCH_CONFIG_INVALID', message: String(error.message ?? error).replace(/^HFS_[A-Z_]+:\s*/, '') }], limitations: LIMITATIONS };
+  }
+  const hfs = checkHfs(config);
+  let context;
+  try {
+    context = buildTypeScriptContext(config, injectedTypeScript, paths);
+  } catch (error) {
+    const message = String(error.message ?? error);
+    const match = /^(ARCH_[A-Z_]+):\s*/.exec(message);
+    return { schema: 'starci/architecture-check@1', ok: false, repository: config.root, kinds: config.kinds, files: 0,
+      compiler: null, violations: hfs.violations, coverage: { hfs: hfs.coverage },
+      errors: [{ ruleId: match?.[1] ?? 'ARCH_COMPILER_FAILURE', message: message.replace(/^(ARCH_[A-Z_]+):\s*/, '') }], limitations: LIMITATIONS };
+  }
+  const violations = [...hfs.violations];
+  const configUnread = checkConfigUnread({ config, context });
+  violations.push(...configUnread.violations);
+  let moduleRegistration = { status: 'not-applicable' };
+  let backendSourceShape = { status: 'not-applicable' };
+  let backendContractTypeForm = { publicContracts: { status: 'not-applicable' }, readonlyBoundaries: { status: 'not-applicable' } };
+  let frontendDataLifecycle = { status: 'not-applicable' };
+  if (context.program) violations.push(...checkOwners(config, context));
+  if (context.program && config.kinds.includes('backend')) {
+    violations.push(...checkBackend(config, context));
+    // A slice may omit every app root. Registration ownership needs the complete
+    // composition graph even when the caller asks for findings in only one path.
+    const registrationContext = paths.length && config.backend.moduleRegistration
+      ? buildTypeScriptContext(config, injectedTypeScript) : context;
+    const registration = checkModuleRegistration(config, registrationContext);
+    violations.push(...registration.violations);
+    moduleRegistration = registration.coverage;
+    const sourceShape = checkBackendSourceShape(config, context);
+    violations.push(...sourceShape.violations);
+    backendSourceShape = sourceShape.coverage;
+    const contracts = checkBackendContracts(config, context);
+    violations.push(...contracts.violations);
+    backendContractTypeForm = contracts.coverage;
+  }
+  let frontendChecked = config.kinds.includes('frontend');
+  if (context.program && config.kinds.includes('frontend')) {
+    // A broken authored input (the framework-pinned root list in knowledge) is an error, never a
+    // silently different contract: the frontend rules are then not reported as checked.
+    try {
+      violations.push(...checkFrontend(config, context));
+    } catch (error) {
+      const message = String(error.message ?? error);
+      const match = /^(ARCH_[A-Z_]+):\s*/.exec(message);
+      if (!match) throw error;
+      context.errors.push({ ruleId: match[1], message: message.slice(match[0].length) });
+      frontendChecked = false;
+    }
+    const dataLifecycle = checkFrontendDataLifecycle(config, context);
+    violations.push(...dataLifecycle.violations);
+    frontendDataLifecycle = dataLifecycle.coverage;
+  }
+  // HFS machine: the slot-driven graph checks read the whole program, also when the caller asked for one path.
+  const hfsContext = paths.length ? buildTypeScriptContext(config, injectedTypeScript) : context;
+  const hfsChecks = { tiers: null, reachability: null, deadExports: null, requiredFiles: null, sizeGrowth: null, clones: null, symbols: null, docLanguage: null };
+  if (hfsContext.program) {
+    const graph = buildHfsGraph(config, hfsContext);
+    const input = { config, context: hfsContext, graph, base };
+    const runs = { tiers: () => checkTiers(graph), reachability: () => checkReachability(input), deadExports: () => checkDeadExports(input),
+      requiredFiles: () => checkRequiredFiles(input), sizeGrowth: () => checkSizeGrowth(input), clones: () => checkClones(input), symbols: () => checkSymbols(input), docLanguage: () => checkDocLanguage(input) };
+    if (graph.profile === 'be') for (const [name, [check]] of Object.entries(BACKEND_MACHINE)) runs[name] = () => check(input);
+    if (graph.profile === 'fe') for (const [name, [check]] of Object.entries(FRONTEND_MACHINE)) runs[name] = () => check(input);
+    if (fast) { delete runs.deadExports; delete runs.clones; delete runs.symbols; }
+    for (const [name, run] of Object.entries(runs)) {
+      const result = run();
+      violations.push(...result.violations);
+      hfsChecks[name] = result.coverage;
+    }
+  }
+  const inScope = item => !paths.length || (item.path && paths.some(prefix => sameOrUnder(item.path, prefix.replace(/\/$/, ''))));
+  const errors = stable(context.errors.filter(item => item.ruleId.startsWith('ARCH_TSCONFIG_') || !item.path || inScope(item)));
+  const scopedViolations = stable(violations.filter(inScope));
+  const sourceFiles = new Set(context.files.map(file => canonical(file.fileName)));
+  const missingOwnerEntries = config.owners?.filter(owner => !sourceFiles.has(canonical(path.resolve(config.root, ...owner.entry.split('/'))))) ?? [];
+  const coverage = {
+    sourceFiles: context.files.map(file => relativePath(config.root, canonical(file.fileName))).sort(),
+    hfs: hfs.coverage,
+    configUnread: configUnread.coverage,
+    backendContractTypeForm,
+    backendSourceShape,
+    frontendDataLifecycle,
+    moduleRegistration,
+    hfsMachine: hfsChecks,
+    ownerPublicApi: !config.owners.length
+      ? { status: 'unavailable', reason: 'no slot owner instance with an entry file exists in the repository' }
+      : missingOwnerEntries.length
+        ? { status: 'unavailable', reason: 'one or more declared owner entries are outside the checked production TypeScript or JavaScript program',
+          missingEntries: missingOwnerEntries.map(owner => owner.entry).sort() }
+      : { status: 'checked', declarations: config.owners.length },
+    grammarContract: !config.kinds.includes('frontend')
+      ? { status: 'not-applicable' }
+      : config.frontend.grammar
+        ? { status: 'checked', package: config.frontend.grammar.package }
+        : { status: 'unavailable', reason: 'no app has a src/app/globals.css to judge against the Grammar style entry' },
+  };
+  coverage.checkedRuleIds = [...new Set([
+    ...COMMON_RULE_IDS,
+    ...(hfs.coverage.status === 'checked' ? HFS_RULE_IDS : []),
+    ...(config.kinds.includes('backend') ? BACKEND_RULE_IDS : []),
+    ...(hfsChecks.tiers ? TIER_RULE_IDS : []),
+    ...(hfsChecks.reachability?.status === 'checked' ? REACHABILITY_RULE_IDS : []),
+    ...(hfsChecks.deadExports?.status === 'checked' ? DEAD_EXPORT_RULE_IDS : []),
+    ...(hfsChecks.requiredFiles?.status === 'checked' ? REQUIRED_FILE_RULE_IDS : []),
+    ...(hfsChecks.sizeGrowth?.status === 'checked' ? SIZE_GROWTH_RULE_IDS : []),
+    ...(hfsChecks.clones?.status === 'checked' ? CLONE_RULE_IDS : []),
+    ...(hfsChecks.symbols?.status === 'checked' ? SYMBOL_RULE_IDS : []),
+    ...(hfsChecks.docLanguage?.status === 'checked' ? DOC_LANGUAGE_RULE_IDS : []),
+    ...CONFIG_UNREAD_RULE_IDS,
+    ...Object.entries({ ...BACKEND_MACHINE, ...FRONTEND_MACHINE }).flatMap(([name, [, ids]]) => (hfsChecks[name]?.status === 'checked' ? ids : [])),
+    ...(frontendChecked ? FRONTEND_RULE_IDS : []),
+    ...(coverage.ownerPublicApi.status === 'checked' ? OWNER_RULE_IDS : []),
+    ...(coverage.grammarContract.status === 'checked' ? GRAMMAR_RULE_IDS : []),
+    ...(coverage.moduleRegistration.status === 'checked' ? REGISTRATION_RULE_IDS : []),
+    ...(coverage.backendSourceShape.layout?.status === 'checked' ? [SOURCE_LAYOUT_RULE_ID] : []),
+    ...(coverage.backendSourceShape.naming?.status === 'checked' ? [SOURCE_NAME_RULE_ID] : []),
+    ...(coverage.backendContractTypeForm.publicContracts?.status === 'checked' ? [PUBLIC_CONTRACT_RULE_ID] : []),
+    ...(coverage.backendContractTypeForm.readonlyBoundaries?.status === 'checked' ? [READONLY_BOUNDARY_RULE_ID] : []),
+    ...(config.kinds.includes('frontend') && ['checked', 'not-applicable'].includes(coverage.frontendDataLifecycle.status) ? SWR_DATA_RULE_IDS : []),
+  ])]
+    // A back-end repository checked no FE_ rule and a front-end one no BE_ rule, whatever list a shared check (tiers, required files) carries.
+    .filter(id => !(id.startsWith('FE_') && !config.kinds.includes('frontend')) && !(id.startsWith('BE_') && !config.kinds.includes('backend')))
+    .sort();
+  return {
+    schema: 'starci/architecture-check@1',
+    ok: errors.length === 0 && scopedViolations.length === 0,
+    repository: config.root,
+    kinds: config.kinds,
+    files: context.files.length,
+    compiler: { version: context.loaded.version, resolved: context.loaded.resolved, projects: context.projects.map(item => item.relative) },
+    coverage,
+    violations: scopedViolations,
+    errors,
+    limitations: LIMITATIONS,
+  };
+}

package/runtime/scripts/checks/architecture/injection-token-exported.mjs

@@ -0,0 +1,62 @@
+import path from 'node:path';
+import { machineKit } from './machine-ast.mjs';
+import { constructorDependencies, serviceClasses } from './constructor-deps.mjs';
+
+/**
+ * R85 `injection-token-exported` (BE_RAW_INJECT), the injection law's last obligation: a spec can only provide a token it
+ * can import. Every `Inject<Thing>()` decorator that a service constructor uses resolves to a token (the argument of its
+ * `injector<T>(TOKEN)`), and that token must be EXPORTED, by name, from the file of the decorator (`<cap>.decorators.ts`),
+ * from the `<cap>.decorators.ts` that declares it, or from the index.ts of the capability that owns either file. A token
+ * that is a private (non-exported) const, or one only a sibling file of the capability can reach, cannot be provided by a
+ * unit spec and is a finding. A token that a package declares (a Nest options token, say) is the package's export.
+ * The finding sits on the decorator's `injector(...)` call, once per decorator, however many services use it.
+ */
+export const INJECTION_TOKEN_EXPORTED_RULE_IDS = ['BE_RAW_INJECT'];
+
+const RULE = 'BE_RAW_INJECT';
+
+export function checkInjectionTokenExported(input) {
+  const { graph } = input;
+  const kit = machineKit(input);
+  const { ts } = kit;
+  const violations = [];
+  const seen = new Set();
+  let decorators = 0;
+
+  const exportsName = (file, name) => {
+    if (!file) return false;
+    for (const statement of file.sourceFile.statements) {
+      if (ts.isVariableStatement(statement) && kit.isExported(statement)) {
+        for (const declaration of statement.declarationList.declarations) {
+          if (ts.isIdentifier(declaration.name) && declaration.name.text === name) return true;
+          if (ts.isObjectBindingPattern(declaration.name) && declaration.name.elements.some(element => ts.isIdentifier(element.name) && element.name.text === name)) return true;
+        }
+      }
+      if (ts.isExportDeclaration(statement) && statement.exportClause && ts.isNamedExports(statement.exportClause)
+        && statement.exportClause.elements.some(element => element.name.text === name)) return true;
+    }
+    return false;
+  };
+  const indexOf = file => (file?.owner ? graph.files.get(`${file.owner.root}/index.ts`) : null);
+
+  for (const { file, declaration } of serviceClasses(kit, graph)) {
+    for (const dependency of constructorDependencies(kit, file, declaration)) {
+      if (dependency.external || !dependency.decoratorDeclaration || !dependency.injectorCall || seen.has(dependency.injectorCall)) continue;
+      seen.add(dependency.injectorCall);
+      decorators += 1;
+      const decoratorFile = graph.files.get(kit.graphPath(dependency.decoratorDeclaration));
+      if (dependency.kind === 'unresolved') {
+        if (decoratorFile) violations.push({ ruleId: RULE, path: decoratorFile.rel, ...kit.at(decoratorFile.rel, decoratorFile.sourceFile, dependency.injectorCall), decorator: dependency.decorator,
+          message: `${dependency.decorator}() cannot be followed to its token (${dependency.reason}); name an exported \`unique symbol\` const so a unit spec can provide it.` });
+        continue;
+      }
+      const tokenFile = dependency.declaration ? graph.files.get(kit.graphPath(dependency.declaration)) : null;
+      const homes = [decoratorFile, tokenFile && path.posix.basename(tokenFile.rel).endsWith('.decorators.ts') ? tokenFile : null, indexOf(decoratorFile), indexOf(tokenFile)];
+      if (homes.some(home => exportsName(home, dependency.name))) continue;
+      if (!decoratorFile) continue;
+      violations.push({ ruleId: RULE, path: decoratorFile.rel, ...kit.at(decoratorFile.rel, decoratorFile.sourceFile, dependency.injectorCall), decorator: dependency.decorator, token: dependency.name,
+        message: `${dependency.decorator}() injects ${dependency.name}, which is not exported from ${path.posix.basename(decoratorFile.rel)} nor from the capability index.ts; export the token so a unit spec can provide it (\`{ provide: ${dependency.name}, useValue: double }\`).` });
+    }
+  }
+  return { violations, coverage: { status: 'checked', decorators, files: graph.files.size } };
+}