@starci/hfs 4.0.10 → 4.1.0

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

@@ -1,6 +1,7 @@
 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
@@ -19,16 +20,9 @@ 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 sharedFilesOf = (tree, resolver, domains) => {
   const shared = new Map(); // domain root -> [file]
-  for (const rel of [...tree.files].sort()) {
+  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);
@@ -37,6 +31,10 @@ export function checkHooksAreHooks(input) {
     if (!shared.has(classified.root)) shared.set(classified.root, []);
     shared.get(classified.root).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 });
@@ -49,40 +47,62 @@ export function checkHooksAreHooks(input) {
       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]);
+    }
+  }
+  return found;
+};
 
-  // Helpers declared in more than one file of one domain.
+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 });
+};
+
+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) {
-      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 [name, node] of helperDeclarationsOf(statement, ts)) recordDeclaredHelper(declared, root, name, file, node);
     }
   }
+  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();
+        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 } };
 }

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

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { byCodeUnit } from '../../lib/list.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
@@ -40,15 +41,8 @@ const held = (leaves, full) => leaves.has(full) || [...leaves].some(leaf => leaf
 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();
+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];
@@ -56,9 +50,113 @@ export function checkI18nKeys({ config, graph, context }) {
     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) })));
+    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;
+}
+
+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([node.head.text, ...node.templateSpans.map(span => span.literal.text)].join('\u0000').replaceAll('\u0000', '*').split('.'));
+      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);
+    }
+  }
+  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;
+}
+
+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;
+}
+
+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] : [];
+}
+
+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 });
   }
+}
+
+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);
+}
+
+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 });
+  }
+}
+
+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) {
@@ -68,79 +166,19 @@ export function checkI18nKeys({ config, graph, context }) {
     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);
-    }
+    const patterns = patternsOf(ts, [...own, ...shared]);
 
     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);
-      }
+      const factories = translationFactories(ts, file);
       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);
+      const namespaces = translatorNamespaces(ts, file, factories);
       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);
+      reportTranslationReads(ts, file, checker, namespaces, loaded, app, report);
     }
 
     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 });
-    }
+    reportUnusedCatalogKeys(primary, loaded, patterns, app, violations);
   }
   return { violations, coverage: { status: 'checked', apps } };
 }