@starci/hfs 4.11.22 → 4.12.2

package/runtime/scripts/hfs/architecture/hooks-are-hooks.d.mts

@@ -0,0 +1,24 @@
+import type { MachineInput } from './machine-ast.mjs';
+import type { ArchitectureConfig } from './config.mjs';
+import type { Violation } from './ast-walks.mjs';
+export interface HooksAreHooksResult {
+    violations: Violation[];
+    coverage: {
+        status: 'checked';
+        domains: number;
+    };
+}
+/**
+ * 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 declare const HOOKS_ARE_HOOKS_RULE_IDS: string[];
+export declare function checkHooksAreHooks(input: MachineInput & {
+    config: ArchitectureConfig;
+}): HooksAreHooksResult;

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

@@ -2,7 +2,6 @@ import path from 'node:path';
 import { machineKit } from './machine-ast.mjs';
 import { treeOf } from './required-files.mjs';
 import { byCodeUnit } from '../../lib/list.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
@@ -14,95 +13,106 @@ import { byCodeUnit } from '../../lib/list.mjs';
  *     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;
-
 const sharedFilesOf = (tree, resolver, domains) => {
-  const shared = new Map(); // domain root -> [file]
-  for (const rel of [...tree.files].sort(byCodeUnit)) {
-    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 });
-  }
-  return shared;
+    const shared = new Map(); // domain root -> [file]
+    for (const rel of [...tree.files].sort(byCodeUnit)) {
+        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;
+        let list = shared.get(classified.root);
+        if (!list) {
+            list = [];
+            shared.set(classified.root, list);
+        }
+        list.push({ rel, base });
+    }
+    return shared;
 };
-
 const reportSharedFileViolations = (shared, violations) => {
-  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.`);
+    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.`);
+        }
     }
-  }
 };
-
 const helperDeclarationsOf = (statement, ts) => {
-  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]);
+    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]);
+        }
     }
-  }
-  return found;
+    return found;
 };
-
 const recordDeclaredHelper = (declared, root, name, file, node) => {
-  if (HOOK_NAME.test(name)) return;
-  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 });
+    if (HOOK_NAME.test(name))
+        return;
+    let byName = declared.get(root);
+    if (!byName) {
+        byName = new Map();
+        declared.set(root, byName);
+    }
+    let list = byName.get(name);
+    if (!list) {
+        list = [];
+        byName.set(name, list);
+    }
+    list.push({ file, node });
 };
-
 const declaredHelpersOf = (graph, resolver, ts) => {
-  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) {
-      for (const [name, node] of helperDeclarationsOf(statement, ts)) recordDeclaredHelper(declared, root, name, file, node);
+    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 ?? ''; // a file in the hooks slot was placed by that slot, so its root exists
+        for (const statement of file.sourceFile.statements) {
+            for (const [name, node] of helperDeclarationsOf(statement, ts))
+                recordDeclaredHelper(declared, root, name, file, node);
+        }
     }
-  }
-  return declared;
+    return declared;
 };
-
 const reportDuplicateHelpers = (declared, violations, kit) => {
-  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(byCodeUnit);
-        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.` });
-      }
+    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(byCodeUnit);
+                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.` });
+            }
+        }
     }
-  }
 };
-
 export function checkHooksAreHooks(input) {
-  const { config, graph } = input;
-  const kit = machineKit(input);
-  const { ts, resolver } = kit;
-  const violations = [];
-  const domains = new Set();
-  const shared = sharedFilesOf(treeOf(config.root), resolver, domains);
-  reportSharedFileViolations(shared, violations);
-  reportDuplicateHelpers(declaredHelpersOf(graph, resolver, ts), violations, kit);
-  return { violations, coverage: { status: 'checked', domains: domains.size } };
+    const { config, graph } = input;
+    const kit = machineKit(input);
+    const { ts, resolver } = kit;
+    const violations = [];
+    const domains = new Set();
+    const shared = sharedFilesOf(treeOf(config.root), resolver, domains);
+    reportSharedFileViolations(shared, violations);
+    reportDuplicateHelpers(declaredHelpersOf(graph, resolver, ts), violations, kit);
+    return { violations, coverage: { status: 'checked', domains: domains.size } };
 }

package/runtime/scripts/hfs/architecture/i18n-keys.d.mts

@@ -0,0 +1,31 @@
+import type { ArchitectureConfig } from './config.mjs';
+import type { ArchitectureViolation, HfsGraph } from './hfs-graph.mjs';
+import type { MachineContext } from './machine-ast.mjs';
+/**
+ * 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, `starci app 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 within its dotted segment) 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 declare const I18N_KEYS_RULE_IDS: string[];
+export declare function checkI18nKeys({ config, graph, context }: {
+    config: ArchitectureConfig;
+    graph: HfsGraph;
+    context: MachineContext;
+}): {
+    violations: ArchitectureViolation[];
+    coverage: {
+        status: string;
+        apps: number;
+    };
+};

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

@@ -2,7 +2,6 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { byCodeUnit } from '../../lib/list.mjs';
 import { escapeRegExp } from '../../lib/regex.mjs';
-
 /**
  * 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, `starci app check`); this
@@ -20,180 +19,195 @@ import { escapeRegExp } from '../../lib/regex.mjs';
  * 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]);
-
+    ? 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; }
+    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) => {
-    const leaf = leafSegments[leafSegments.length - pattern.length + index];
-    return segment instanceof RegExp ? segment.test(leaf) : segment === '*' || segment === leaf;
-  });
-
+    && pattern.every((segment, index) => {
+        const leaf = leafSegments[leafSegments.length - pattern.length + index];
+        return segment instanceof RegExp ? segment.test(leaf) : segment === '*' || segment === leaf;
+    });
 function catalogsPerApp(config, graph) {
-  const catalogs = 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(byCodeUnit); } catch { /* the app has no catalog directory: FE_I18N_PLACEMENT's finding */ }
-    if (names.length) catalogs.set(dir, names.map(name => ({ rel: `${dir}${name}`, locale: name.slice(0, -5) })));
-  }
-  return catalogs;
+    const catalogs = 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(byCodeUnit);
+        }
+        catch { /* the app has no catalog directory: FE_I18N_PLACEMENT's finding */ }
+        if (names.length)
+            catalogs.set(dir, names.map(name => ({ rel: `${dir}${name}`, locale: name.slice(0, -5) })));
+    }
+    return catalogs;
 }
-
 /** Each interpolation can fill part or all of a segment; the template's static fragments keep their literal spelling. */
 function templatePatternOf(node) {
-  const pattern = [];
-  for (const segment of [node.head.text, ...node.templateSpans.map(span => span.literal.text)].join('\u0000').split('.')) {
-    if (!segment.includes('\u0000')) { pattern.push(segment); continue; }
-    const parts = segment.split('\u0000');
-    pattern.push(parts.every(part => part === '') ? '*' : new RegExp(`^${parts.map((part) => escapeRegExp(part)).join('.*')}$`, 'su'));
-  }
-  return pattern;
+    const pattern = [];
+    for (const segment of [node.head.text, ...node.templateSpans.map(span => span.literal.text)].join('\u0000').split('.')) {
+        if (!segment.includes('\u0000')) {
+            pattern.push(segment);
+            continue;
+        }
+        const parts = segment.split('\u0000');
+        pattern.push(parts.every(part => part === '') ? '*' : new RegExp(`^${parts.map((part) => escapeRegExp(part)).join('.*')}$`, 'su'));
+    }
+    return pattern;
 }
-
 function patternsOf(ts, files) {
-  const patterns = [];
-  for (const file of files) {
-    const visit = node => {
-      if (ts.isStringLiteralLike(node)) patterns.push(node.text.split('.'));
-      else if (ts.isTemplateExpression(node)) patterns.push(templatePatternOf(node));
-      ts.forEachChild(node, visit);
-    };
-    visit(file.sourceFile);
-  }
-  return patterns;
+    const patterns = [];
+    for (const file of files) {
+        const visit = (node) => {
+            if (ts.isStringLiteralLike(node))
+                patterns.push(node.text.split('.'));
+            else if (ts.isTemplateExpression(node))
+                patterns.push(templatePatternOf(node));
+            ts.forEachChild(node, visit);
+        };
+        visit(file.sourceFile);
+    }
+    return patterns;
 }
-
 function translationFactories(ts, file) {
-  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);
+    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);
+        }
     }
-  }
-  return factories;
+    return factories;
 }
-
 function namespaceForCall(ts, file, init, factories) {
-  let expression = init;
-  if (ts.isAwaitExpression(expression)) expression = expression.expression;
-  if (!ts.isCallExpression(expression) || !ts.isIdentifier(expression.expression) || !factories.has(expression.expression.text)) return null;
-  const [first] = expression.arguments;
-  if (first === undefined) return '';
-  if (ts.isStringLiteralLike(first)) return first.text;
-  if (!ts.isObjectLiteralExpression(first)) return null;
-  const property = first.properties.find(candidate => ts.isPropertyAssignment(candidate) && candidate.name.getText(file.sourceFile) === 'namespace');
-  if (!property) return '';
-  return ts.isStringLiteralLike(property.initializer) ? property.initializer.text : null;
+    let expression = init;
+    if (ts.isAwaitExpression(expression))
+        expression = expression.expression;
+    if (!ts.isCallExpression(expression) || !ts.isIdentifier(expression.expression) || !factories.has(expression.expression.text))
+        return null;
+    const [first] = expression.arguments;
+    if (first === undefined)
+        return '';
+    if (ts.isStringLiteralLike(first))
+        return first.text;
+    if (!ts.isObjectLiteralExpression(first))
+        return null;
+    const property = first.properties.find((candidate) => ts.isPropertyAssignment(candidate) && candidate.name.getText(file.sourceFile) === 'namespace');
+    if (!property)
+        return '';
+    return ts.isStringLiteralLike(property.initializer) ? property.initializer.text : null;
 }
-
 function translatorNamespaces(ts, file, factories) {
-  const namespaces = new Map();
-  const collect = node => {
-    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
-      const namespace = namespaceForCall(ts, file, node.initializer, factories);
-      if (namespace !== null) namespaces.set(node, namespace);
-    }
-    ts.forEachChild(node, collect);
-  };
-  collect(file.sourceFile);
-  return namespaces;
+    const namespaces = new Map();
+    const collect = (node) => {
+        if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+            const namespace = namespaceForCall(ts, file, node.initializer, factories);
+            if (namespace !== null)
+                namespaces.set(node, namespace);
+        }
+        ts.forEachChild(node, collect);
+    };
+    collect(file.sourceFile);
+    return namespaces;
 }
-
 function keysOf(ts, argument) {
-  if (ts.isConditionalExpression(argument)) return [...keysOf(ts, argument.whenTrue), ...keysOf(ts, argument.whenFalse)];
-  if (ts.isParenthesizedExpression(argument) || ts.isAsExpression(argument) || ts.isSatisfiesExpression(argument)) return keysOf(ts, argument.expression);
-  return ts.isStringLiteralLike(argument) ? [argument] : [];
+    if (ts.isConditionalExpression(argument))
+        return [...keysOf(ts, argument.whenTrue), ...keysOf(ts, argument.whenFalse)];
+    if (ts.isParenthesizedExpression(argument) || ts.isAsExpression(argument) || ts.isSatisfiesExpression(argument))
+        return keysOf(ts, argument.expression);
+    return ts.isStringLiteralLike(argument) ? [argument] : [];
 }
-
 function reportCallKeys(reads, node) {
-  const { ts, file, checker, namespaces, loaded, app, report } = reads;
-  const callee = node.expression;
-  let owner = ts.isIdentifier(callee) ? callee : null;
-  if (ts.isPropertyAccessExpression(callee) && READERS.has(callee.name.text) && ts.isIdentifier(callee.expression)) owner = callee.expression;
-  const [first] = node.arguments;
-  const declaration = owner ? checker.getSymbolAtLocation(owner)?.valueDeclaration : null;
-  if (!owner || first === undefined || !namespaces.has(declaration)) return;
-  for (const literal of keysOf(ts, 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 });
-  }
+    const { ts, file, checker, namespaces, loaded, app, report } = reads;
+    const callee = node.expression;
+    let owner = ts.isIdentifier(callee) ? callee : null;
+    if (ts.isPropertyAccessExpression(callee) && READERS.has(callee.name.text) && ts.isIdentifier(callee.expression))
+        owner = callee.expression;
+    const [first] = node.arguments;
+    const declaration = owner ? checker.getSymbolAtLocation(owner)?.valueDeclaration : null;
+    if (!owner || first === undefined || !declaration || !namespaces.has(declaration))
+        return;
+    for (const literal of keysOf(ts, 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 });
+    }
 }
-
 function reportTranslationReads(ts, file, checker, namespaces, loaded, app, report) {
-  const reads = { ts, file, checker, namespaces, loaded, app, report };
-  const read = node => {
-    if (ts.isCallExpression(node)) reportCallKeys(reads, node);
-    ts.forEachChild(node, read);
-  };
-  read(file.sourceFile);
+    const reads = { ts, file, checker, namespaces, loaded, app, report };
+    const read = (node) => {
+        if (ts.isCallExpression(node))
+            reportCallKeys(reads, node);
+        ts.forEachChild(node, read);
+    };
+    read(file.sourceFile);
 }
-
 function reportUnusedCatalogKeys(primary, loaded, patterns, app, violations) {
-  const every = new Set(loaded.flatMap(catalog => [...catalog.leaves]));
-  for (const leaf of [...every].sort(byCodeUnit)) {
-    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 });
-  }
+    const every = new Set(loaded.flatMap(catalog => [...catalog.leaves]));
+    for (const leaf of [...every].sort(byCodeUnit)) {
+        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 });
+    }
 }
-
 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 = catalogsPerApp(config, graph);
-
-  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 = patternsOf(ts, [...own, ...shared]);
-
-    for (const file of own) {
-      const factories = translationFactories(ts, file);
-      if (!factories.size) continue;
-      const checker = context.checkerFor(file.sourceFile.fileName);
-      const namespaces = translatorNamespaces(ts, file, factories);
-      if (!namespaces.size) continue;
-      reportTranslationReads(ts, file, checker, namespaces, loaded, app, report);
+    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 = catalogsPerApp(config, graph);
+    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) => Boolean(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 = patternsOf(ts, [...own, ...shared]);
+        for (const file of own) {
+            const factories = translationFactories(ts, file);
+            if (!factories.size)
+                continue;
+            const checker = context.checkerFor(file.sourceFile.fileName);
+            const namespaces = translatorNamespaces(ts, file, factories);
+            if (!namespaces.size)
+                continue;
+            reportTranslationReads(ts, file, checker, namespaces, loaded, app, report);
+        }
+        const [primary] = [...loaded].sort((a, b) => a.locale.localeCompare(b.locale));
+        reportUnusedCatalogKeys(primary, loaded, patterns, app, violations);
     }
-
-    const [primary] = [...loaded].sort((a, b) => a.locale.localeCompare(b.locale));
-    reportUnusedCatalogKeys(primary, loaded, patterns, app, violations);
-  }
-  return { violations, coverage: { status: 'checked', apps } };
+    return { violations, coverage: { status: 'checked', apps } };
 }

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

@@ -0,0 +1,7 @@
+import type { CheckResult, HfsCheckInput } from './context-map.mjs';
+/** The rule ids the back-end identity machine reports. */
+export declare const IDENTITY_RULE_IDS: readonly string[];
+/** R260 BE_JWT_ALG_PINNED: every jose jwtVerify call pins a literal secure algorithm list and a configured issuer, and binds the principal by a configured audience or the authenticated role. */
+export declare function checkJwtPolicy(input: HfsCheckInput): CheckResult;
+/** The back-end identity machine: the own-JWKS law where the passport integration exists (lite), the JWT policy everywhere. */
+export declare function checkBackendIdentity(input: HfsCheckInput): CheckResult;