@starci/hfs 4.0.9 → 4.1.0

package/runtime/scripts/hfs/rules/event-bus.mjs

@@ -29,26 +29,39 @@ const TEST_CALLEES = new Set(['it', 'test']);
 const typescriptFor = (repoRoot) => loadTypescript(repoRoot, HERE);
 
 /** The event-bus pattern file name of an event name: dots become dashes (`order.placed` -> `order-placed`). */
-export const stemOfEvent = (name) => name.split('.').join('-');
+export const stemOfEvent = (name) => name.replaceAll('.', '-');
+
+/** The initializer of a `static` property member with an identifier name, parentheses and `as` casts stripped, else null. */
+function staticMemberValue(ts, member) {
+  if (!ts.isPropertyDeclaration(member) || !member.initializer || !member.name || !ts.isIdentifier(member.name)) return null;
+  const isStatic = member.modifiers?.some((m) => m.kind === ts.SyntaxKind.StaticKeyword);
+  if (!isStatic) return null;
+  let value = member.initializer;
+  while (ts.isAsExpression(value) || ts.isParenthesizedExpression(value)) value = value.expression;
+  return value;
+}
 
 /** The `eventName` and `version` literals a class declares as `static readonly` members, with the line of the class. */
+function eventClassInfo(ts, node) {
+  let name = null;
+  let version = null;
+  for (const member of node.members) {
+    const value = staticMemberValue(ts, member);
+    if (!value) continue;
+    if (member.name.text === 'eventName') name = literalText(ts, value);
+    if (member.name.text === 'version' && ts.isNumericLiteral(value)) version = Number(value.text);
+  }
+  if (name !== null || version !== null || node.name) return { className: node.name?.text ?? '<anonymous>', name, version };
+  return null;
+}
+
 function readEventClass(ts, text, file) {
   const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
   const classes = [];
   const visit = (node) => {
     if (ts.isClassDeclaration(node)) {
-      let name = null;
-      let version = null;
-      for (const member of node.members) {
-        if (!ts.isPropertyDeclaration(member) || !member.initializer || !member.name || !ts.isIdentifier(member.name)) continue;
-        const isStatic = member.modifiers?.some((m) => m.kind === ts.SyntaxKind.StaticKeyword);
-        if (!isStatic) continue;
-        let value = member.initializer;
-        while (ts.isAsExpression(value) || ts.isParenthesizedExpression(value)) value = value.expression;
-        if (member.name.text === 'eventName') name = literalText(ts, value);
-        if (member.name.text === 'version' && ts.isNumericLiteral(value)) version = Number(value.text);
-      }
-      if (name !== null || version !== null || node.name) classes.push({ className: node.name?.text ?? '<anonymous>', name, version });
+      const info = eventClassInfo(ts, node);
+      if (info) classes.push(info);
     }
     ts.forEachChild(node, visit);
   };
@@ -56,34 +69,42 @@ function readEventClass(ts, text, file) {
   return classes;
 }
 
-/** Findings of BE_EVENT_CLASS_CONTRACT. */
-export function eventClassContractFindings({ repoRoot, files, repo }) {
-  const patterns = repo.sides?.be?.patterns ?? [];
-  if (!patterns.includes('event-bus')) return [];
-  const ts = typescriptFor(repoRoot);
-  if (!ts) return [];
+/** The service and file stem of a `be/src/modules/events/<service>/<event>.event.ts` path, else null. */
+function eventFileParts(file) {
+  if (!file.startsWith(EVENT_FILE_PREFIX) || !file.endsWith(EVENT_SUFFIX)) return null;
+  const rest = file.slice(EVENT_FILE_PREFIX.length).split('/');
+  if (rest.length !== 2) return null;
+  const [service, base] = rest;
+  return { service, stem: base.slice(0, -EVENT_SUFFIX.length) };
+}
+
+function recordEventClass(ts, text, file, { service, stem }, findings, classesByService) {
+  const classes = readEventClass(ts, text, file).filter((c) => c.name !== null || c.version !== null);
+  if (classes.length !== 1 || classes[0].name === null || classes[0].version === null) {
+    const candidates = classes.length === 1 ? 'one without both literals' : `${classes.length} candidates`;
+    findings.push(found(EVENT_CLASS_CONTRACT, file, `${file} must declare exactly one event class with literal \`static readonly eventName\` and \`static readonly version\` members (the typed event of be/contracts/${service}/${CONTRACT_NAME}); found ${candidates}.`, { service }));
+    return;
+  }
+  const [event] = classes;
+  if (stemOfEvent(event.name) !== stem) findings.push(found(EVENT_CLASS_CONTRACT, file, `${file} declares the event \`${event.name}\`, so the file is \`${stemOfEvent(event.name)}${EVENT_SUFFIX}\`: a class file is named after its event.`, { service, event: event.name }));
+  if (!classesByService.has(service)) classesByService.set(service, new Map());
+  classesByService.get(service).set(event.name, { file, version: event.version });
+}
+
+function eventClassesOf(repoRoot, files, ts) {
   const findings = [];
   const classesByService = new Map();
   for (const file of files) {
-    if (!file.startsWith(EVENT_FILE_PREFIX) || !file.endsWith(EVENT_SUFFIX)) continue;
-    const rest = file.slice(EVENT_FILE_PREFIX.length).split('/');
-    if (rest.length !== 2) continue;
-    const [service, base] = rest;
-    const stem = base.slice(0, -EVENT_SUFFIX.length);
+    const parts = eventFileParts(file);
+    if (!parts) continue;
     const text = readText(repoRoot, file);
     if (text === null) continue;
-    const classes = readEventClass(ts, text, file).filter((c) => c.name !== null || c.version !== null);
-    if (classes.length !== 1 || classes[0].name === null || classes[0].version === null) {
-      findings.push(found(EVENT_CLASS_CONTRACT, file, `${file} must declare exactly one event class with literal \`static readonly eventName\` and \`static readonly version\` members (the typed event of be/contracts/${service}/${CONTRACT_NAME}); found ${classes.length === 1 ? 'one without both literals' : `${classes.length} candidates`}.`, { service }));
-      continue;
-    }
-    const [event] = classes;
-    if (stemOfEvent(event.name) !== stem) {
-      findings.push(found(EVENT_CLASS_CONTRACT, file, `${file} declares the event \`${event.name}\`, so the file is \`${stemOfEvent(event.name)}${EVENT_SUFFIX}\`: a class file is named after its event.`, { service, event: event.name }));
-    }
-    if (!classesByService.has(service)) classesByService.set(service, new Map());
-    classesByService.get(service).set(event.name, { file, version: event.version });
+    recordEventClass(ts, text, file, parts, findings, classesByService);
   }
+  return { findings, classesByService };
+}
+
+function eventContractsOf(repoRoot, files) {
   const contracts = new Map();
   for (const file of files) {
     if (!file.startsWith(CONTRACT_PREFIX) || !file.endsWith(`/${CONTRACT_NAME}`)) continue;
@@ -91,6 +112,11 @@ export function eventClassContractFindings({ repoRoot, files, repo }) {
     if (rest.length !== 2) continue;
     contracts.set(rest[0], { file, doc: readJson(repoRoot, file) });
   }
+  return contracts;
+}
+
+function classContractFindings(classesByService, contracts) {
+  const findings = [];
   for (const [service, byName] of classesByService) {
     const contract = contracts.get(service);
     for (const [name, { file, version }] of byName) {
@@ -100,6 +126,11 @@ export function eventClassContractFindings({ repoRoot, files, repo }) {
       else if (entry.version !== version) findings.push(found(EVENT_CLASS_CONTRACT, file, `${file} declares \`${name}\` at version ${version} but ${contract.file} lists version ${entry.version}; a version changes in the class and the contract together.`, { service, event: name }));
     }
   }
+  return findings;
+}
+
+function contractClassFindings(classesByService, contracts) {
+  const findings = [];
   for (const [service, contract] of contracts) {
     const events = contract.doc?.events;
     if (events === null || typeof events !== 'object') continue;
@@ -110,6 +141,30 @@ export function eventClassContractFindings({ repoRoot, files, repo }) {
   return findings;
 }
 
+/** Findings of BE_EVENT_CLASS_CONTRACT. */
+export function eventClassContractFindings({ repoRoot, files, repo }) {
+  const patterns = repo.sides?.be?.patterns ?? [];
+  if (!patterns.includes('event-bus')) return [];
+  const ts = typescriptFor(repoRoot);
+  if (!ts) return [];
+  const classes = eventClassesOf(repoRoot, files, ts);
+  const contracts = eventContractsOf(repoRoot, files);
+  return [...classes.findings, ...classContractFindings(classes.classesByService, contracts), ...contractClassFindings(classes.classesByService, contracts)];
+}
+
+/** Adds the `<pattern>` of every `<pattern>/<scenario>:` test title (the first argument of an `it(` or `test(` call) of the source. */
+function addProvenScenarios(ts, source, proven) {
+  const visit = (node) => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && TEST_CALLEES.has(node.expression.text)) {
+      const title = literalText(ts, node.arguments[0]);
+      const colon = title === null ? -1 : title.indexOf(':');
+      if (colon > 0) proven.add(title.slice(0, colon));
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+}
+
 /** The scenario ids a back end proves: every `<pattern>/<scenario>:` test title of an e2e or integration spec. */
 function provenScenarios(ts, repoRoot, files) {
   const proven = new Set();
@@ -117,16 +172,7 @@ function provenScenarios(ts, repoRoot, files) {
     if (!TEST_FOLDERS.some((folder) => file.startsWith(folder)) || !SPEC_SUFFIXES.some((suffix) => file.endsWith(suffix))) continue;
     const text = readText(repoRoot, file);
     if (text === null) continue;
-    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
-    const visit = (node) => {
-      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && TEST_CALLEES.has(node.expression.text)) {
-        const title = literalText(ts, node.arguments[0]);
-        const colon = title === null ? -1 : title.indexOf(':');
-        if (colon > 0) proven.add(title.slice(0, colon));
-      }
-      ts.forEachChild(node, visit);
-    };
-    visit(source);
+    addProvenScenarios(ts, ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true), proven);
   }
   return proven;
 }

package/runtime/scripts/hfs/rules/fe-contract-documents.mjs

@@ -7,6 +7,7 @@
 // an object without one is a finding on the document. The finding names the service and every problem.
 import { operationProblems, parseDocument, parseSchema, rootFieldsOf } from '../../lib/graphql-contract.mjs';
 import { found, readText } from './read.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 export const FE_GRAPHQL_CONTRACT = 'FE_GRAPHQL_CONTRACT';
 
@@ -30,9 +31,23 @@ function contractsOf(repoRoot, files, findings) {
   return contracts;
 }
 
+function operationFindings(file, document, operation, contracts) {
+  const label = operation.name ?? `anonymous ${operation.operation}`;
+  const [first] = rootFieldsOf(operation);
+  const serving = contracts.filter(({ schema }) => schema.types.get(schema.roots[operation.operation])?.fields?.has(first));
+  if (serving.length === 0) {
+    const where = contracts.length === 0 ? 'the app keeps no be/contracts/<service>/schema.graphql' : `no contract of ${contracts.map((c) => c.path).join(', ')} declares ${operation.operation} ${first}`;
+    return [found(FE_GRAPHQL_CONTRACT, file, `${file}: ${label} asks ${operation.operation} ${first}, but ${where}; the front end sends only what a back end serves.`, { operation: label, service: null })];
+  }
+  const [contract] = serving;
+  const problems = operationProblems(contract.schema, document, operation);
+  if (problems.length > 0) return [found(FE_GRAPHQL_CONTRACT, file, `${file}: ${label} does not match the ${contract.service} contract (${contract.path}): ${problems.join('; ')}.`, { operation: label, service: contract.service, problems })];
+  return [];
+}
+
 /** The findings of R113 over the tracked paths `files` of the app at `repoRoot`. */
 export function feContractFindings({ repoRoot, files }) {
-  const documents = files.filter(isDocument).sort();
+  const documents = files.filter(isDocument).sort(byCodeUnit);
   if (documents.length === 0) return [];
   const findings = [];
   const contracts = contractsOf(repoRoot, files, findings);
@@ -46,21 +61,7 @@ export function feContractFindings({ repoRoot, files }) {
       findings.push(found(FE_GRAPHQL_CONTRACT, file, `${file} is not a GraphQL document: ${error.message}.`));
       continue;
     }
-    for (const operation of document.operations) {
-      const label = operation.name ?? `anonymous ${operation.operation}`;
-      const [first] = rootFieldsOf(operation);
-      const serving = contracts.filter(({ schema }) => schema.types.get(schema.roots[operation.operation])?.fields?.has(first));
-      if (serving.length === 0) {
-        const where = contracts.length === 0 ? 'the app keeps no be/contracts/<service>/schema.graphql' : `no contract of ${contracts.map((c) => c.path).join(', ')} declares ${operation.operation} ${first}`;
-        findings.push(found(FE_GRAPHQL_CONTRACT, file, `${file}: ${label} asks ${operation.operation} ${first}, but ${where}; the front end sends only what a back end serves.`, { operation: label, service: null }));
-        continue;
-      }
-      const [contract] = serving;
-      const problems = operationProblems(contract.schema, document, operation);
-      if (problems.length > 0) {
-        findings.push(found(FE_GRAPHQL_CONTRACT, file, `${file}: ${label} does not match the ${contract.service} contract (${contract.path}): ${problems.join('; ')}.`, { operation: label, service: contract.service, problems }));
-      }
-    }
+    for (const operation of document.operations) findings.push(...operationFindings(file, document, operation, contracts));
   }
   return findings;
 }

package/runtime/scripts/hfs/rules/fe-no-tests.mjs

@@ -15,34 +15,54 @@ const TEST_DIRECTORY = /(?:^|\/)(?:e2e|__tests__|__mocks__|test-support)\//;
 export const TEST_TOOL_FILE = /(?:^|\/)(?:(?:vitest|jest|playwright)\.[^/]+|cypress\.config\.[^/]+|tsconfig\.e2e\.json|e2e\.ya?ml)$/;
 // The edition rule (rules/edition.mjs, L01) applies the same lists to the whole app tree in lite: they are the test vocabulary.
 export const TEST_SCRIPT_NAME = /^(?:pre|post)?test(?::|$)/;
-export const TEST_RUNNER_COMMAND = /(?:^|[\s&|;(])(?:npx\s+)?(?:vitest|jest|playwright|cypress|mocha)(?=$|[\s&|;)])|\bnode\s+(?:--\S+\s+)*--test\b/;
-export const TEST_DEPENDENCY = /^(?:vitest|@vitest\/.+|playwright|playwright-core|@playwright\/.+|jest|@jest\/.+|ts-jest|babel-jest|@types\/jest|jest-[\w-]+|mocha|@types\/mocha|cypress|@testing-library\/.+|jsdom|@types\/jsdom|happy-dom|axe-core|@axe-core\/.+|vitest-axe|@starci\/(?:vitest|jest|playwright)-preset)$/;
+const TEST_RUNNER_COMMAND_SOURCE = String.raw`(?:^|[\s&|;(])(?:npx\s+)?(?:vitest|jest|playwright|cypress|mocha)(?=$|[\s&|;)])|\bnode\s+(?:--\S+\s+)*--test\b`;
+export const TEST_RUNNER_COMMAND = new RegExp(TEST_RUNNER_COMMAND_SOURCE);
+const TEST_DEPENDENCY_SOURCE = String.raw`^(?:vitest|@vitest\/.+|playwright|playwright-core|@playwright\/.+|jest|@jest\/.+|ts-jest|babel-jest|@types\/jest|jest-[\w-]+|mocha|@types\/mocha|cypress|@testing-library\/.+|jsdom|@types\/jsdom|happy-dom|axe-core|@axe-core\/.+|vitest-axe|@starci\/(?:vitest|jest|playwright)-preset)$`;
+export const TEST_DEPENDENCY = new RegExp(TEST_DEPENDENCY_SOURCE);
 export const DEPENDENCY_SECTIONS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
 
 /** True for a path FE_NO_TESTS owns: a spec file, a test directory or a test-tool file. */
 export const isFeTestPath = (file) => SPEC_FILE.test(file) || TEST_DIRECTORY.test(file) || TEST_TOOL_FILE.test(file);
 
+function testPathFinding(file) {
+  let what = 'test tooling';
+  if (SPEC_FILE.test(file)) what = 'a test file';
+  else if (TEST_DIRECTORY.test(file)) what = 'inside a test directory';
+  return found(FE_NO_TESTS, file, `${file} is ${what}; a front-end repository has no tests, no test tooling and no exception: delete it`);
+}
+
+function testDependencyFindings(file, pkg) {
+  const findings = [];
+  for (const section of DEPENDENCY_SECTIONS) {
+    for (const name of Object.keys(pkg[section] ?? {})) {
+      if (TEST_DEPENDENCY.test(name)) findings.push(found(FE_NO_TESTS, file, `${file} ${section} names ${name}, a test dependency; a front-end repository has no tests: delete the dependency`));
+    }
+  }
+  return findings;
+}
+
+function packageTestFindings(repoRoot, file) {
+  if (file !== 'package.json' && !file.endsWith('/package.json')) return [];
+  if (file.includes('node_modules/')) return [];
+  const pkg = readJson(repoRoot, file);
+  if (!pkg || typeof pkg !== 'object') return [];
+  const findings = [];
+  for (const [name, command] of Object.entries(pkg.scripts ?? {})) {
+    if (TEST_SCRIPT_NAME.test(name) || TEST_RUNNER_COMMAND.test(String(command))) findings.push(found(FE_NO_TESTS, file, `${file} script ${name} is a test script (${String(command).slice(0, 80)}); a front-end repository has no tests: delete the script`));
+  }
+  findings.push(...testDependencyFindings(file, pkg));
+  return findings;
+}
+
 /** The findings of R97 over the tracked paths `files` of a front-end repository at `repoRoot`. */
 export function feNoTestsFindings({ repoRoot, files }) {
   const findings = [];
   for (const file of files) {
     if (isFeTestPath(file)) {
-      const what = SPEC_FILE.test(file) ? 'a test file' : TEST_DIRECTORY.test(file) ? 'inside a test directory' : 'test tooling';
-      findings.push(found(FE_NO_TESTS, file, `${file} is ${what}; a front-end repository has no tests, no test tooling and no exception: delete it`));
+      findings.push(testPathFinding(file));
       continue;
     }
-    if (file !== 'package.json' && !file.endsWith('/package.json')) continue;
-    if (file.includes('node_modules/')) continue;
-    const pkg = readJson(repoRoot, file);
-    if (!pkg || typeof pkg !== 'object') continue;
-    for (const [name, command] of Object.entries(pkg.scripts ?? {})) {
-      if (TEST_SCRIPT_NAME.test(name) || TEST_RUNNER_COMMAND.test(String(command))) findings.push(found(FE_NO_TESTS, file, `${file} script ${name} is a test script (${String(command).slice(0, 80)}); a front-end repository has no tests: delete the script`));
-    }
-    for (const section of DEPENDENCY_SECTIONS) {
-      for (const name of Object.keys(pkg[section] ?? {})) {
-        if (TEST_DEPENDENCY.test(name)) findings.push(found(FE_NO_TESTS, file, `${file} ${section} names ${name}, a test dependency; a front-end repository has no tests: delete the dependency`));
-      }
-    }
+    findings.push(...packageTestFindings(repoRoot, file));
   }
   return findings;
 }

package/runtime/scripts/hfs/rules/frontend-tree.mjs

@@ -13,6 +13,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { found, readJson } from './read.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 const WIRE_GENERATED = 'FE_WIRE_GENERATED';
 const I18N_PLACEMENT = 'FE_I18N_PLACEMENT';
@@ -77,7 +78,7 @@ function placementFindings({ repoRoot, app, tracked }) {
   const base = `apps/${app}`;
   const findings = [];
   if (!tracked.includes(`${base}/src/proxy.ts`)) findings.push(found(I18N_PLACEMENT, `${base}/src/proxy.ts`, `${app} has no src/proxy.ts; locale routing lives in proxy.ts`, { app }));
-  for (const file of tracked.filter((f) => new RegExp(`^${base}/src/middleware\.[cm]?[jt]s$`).test(f))) findings.push(found(I18N_PLACEMENT, file, `${file} is a middleware file; Next 16 routes through src/proxy.ts`, { app }));
+  for (const file of tracked.filter((f) => new RegExp(`^${base}/src/middleware.[cm]?[jt]s$`).test(f))) findings.push(found(I18N_PLACEMENT, file, `${file} is a middleware file; Next 16 routes through src/proxy.ts`, { app }));
   const appDir = `${base}/src/app/`;
   for (const file of tracked.filter((f) => f.startsWith(appDir) && ROUTE_FILE.test(f))) {
     const rel = file.slice(appDir.length);
@@ -96,7 +97,7 @@ function placementFindings({ repoRoot, app, tracked }) {
 
 function catalogFindings({ repoRoot, app, tracked }) {
   const messages = `apps/${app}/src/modules/i18n/messages/`;
-  const catalogs = tracked.filter((f) => f.startsWith(messages) && f.endsWith('.json') && f.slice(messages.length).indexOf('/') === -1);
+  const catalogs = tracked.filter((f) => f.startsWith(messages) && f.endsWith('.json') && !f.slice(messages.length).includes('/'));
   const keys = new Map();
   for (const file of catalogs) {
     const parsed = readJson(repoRoot, file);
@@ -106,7 +107,7 @@ function catalogFindings({ repoRoot, app, tracked }) {
   const all = new Set([...keys.values()].flatMap((set) => [...set]));
   const findings = [];
   for (const [file, set] of keys) {
-    const missing = [...all].filter((key) => !set.has(key)).sort();
+    const missing = [...all].filter((key) => !set.has(key)).sort(byCodeUnit);
     if (missing.length) findings.push(found(I18N_CATALOG, file, `${file} lacks ${missing.length} key${missing.length === 1 ? '' : 's'} another locale has (${missing.slice(0, 5).join(', ')}${missing.length > 5 ? ', ...' : ''}); every catalog holds the same keys`, { app, missing }));
   }
   return findings;

package/runtime/scripts/hfs/rules/integration-specs.mjs

@@ -16,6 +16,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadTypescript } from '../../lib/package-at.mjs';
 import { found, readText } from './read.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 const INTEGRATION_SPEC_MISSING = 'BE_INTEGRATION_SPEC_MISSING';
 
@@ -70,6 +71,17 @@ function chainOf(ts, expression) {
   return ts.isIdentifier(current) ? [current.text, ...names] : null;
 }
 
+/** The initializer of `const <name> = ...` at the top level of `file`. */
+function topLevelConst(ts, file, name) {
+  for (const statement of file.sourceFile.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (ts.isIdentifier(declaration.name) && declaration.name.text === name && declaration.initializer) return declaration.initializer;
+    }
+  }
+  return null;
+}
+
 /**
  * The judge of one app: resolves an import of a parsed file to a repository-relative path, finds the top-level const of a file,
  * and reads files once.
@@ -87,17 +99,7 @@ function judgeOf(ts, repoRoot, side) {
     const rel = path.relative(repoRoot, resolved).split(path.sep).join('/');
     return rel.startsWith('..') ? null : rel;
   };
-  /** The initializer of `const <name> = ...` at the top level of `file`. */
-  const constOf = (file, name) => {
-    for (const statement of file.sourceFile.statements) {
-      if (!ts.isVariableStatement(statement)) continue;
-      for (const declaration of statement.declarationList.declarations) {
-        if (ts.isIdentifier(declaration.name) && declaration.name.text === name && declaration.initializer) return declaration.initializer;
-      }
-    }
-    return null;
-  };
-  return { parsed, resolve, constOf };
+  return { parsed, resolve, constOf: (file, name) => topLevelConst(ts, file, name) };
 }
 
 /** Whether `rel` lies in the integration folder `folder` (its index or any file of it). */
@@ -134,53 +136,85 @@ function registersIntegration(ts, judge, element, folder) {
 }
 
 /** Whether `name`, exported by the module `rel`, is declared as an enum there or in the file it is re-exported from. */
+function enumExportResult(ts, judge, rel, name, depth, statement) {
+  if (ts.isEnumDeclaration(statement) && statement.name.text === name) return true;
+  if (!ts.isExportDeclaration(statement) || !statement.exportClause || !ts.isNamedExports(statement.exportClause)) return null;
+  for (const element of statement.exportClause.elements) {
+    if (element.name.text !== name) continue;
+    const original = (element.propertyName ?? element.name).text;
+    if (statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)) return exportsEnum(ts, judge, judge.resolve(rel, statement.moduleSpecifier.text), original, depth + 1);
+    return exportsEnum(ts, judge, rel, original, depth + 1);
+  }
+  return null;
+}
+
 function exportsEnum(ts, judge, rel, name, depth = 0) {
   const file = rel ? judge.parsed(rel) : null;
   if (!file || depth > 4) return false;
   for (const statement of file.sourceFile.statements) {
-    if (ts.isEnumDeclaration(statement) && statement.name.text === name) return true;
-    if (!ts.isExportDeclaration(statement) || !statement.exportClause || !ts.isNamedExports(statement.exportClause)) continue;
-    for (const element of statement.exportClause.elements) {
-      if (element.name.text !== name) continue;
-      const original = (element.propertyName ?? element.name).text;
-      if (statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)) return exportsEnum(ts, judge, judge.resolve(rel, statement.moduleSpecifier.text), original, depth + 1);
-      return exportsEnum(ts, judge, rel, original, depth + 1);
-    }
+    const result = enumExportResult(ts, judge, rel, name, depth, statement);
+    if (result !== null) return result;
   }
   return false;
 }
 
-/** What one spec proves about the integration in `folder`: { modules, errorCode, outage }. */
-function judgeSpec(ts, judge, rel, folder) {
-  const spec = judge.parsed(rel);
-  const result = { modules: false, errorCode: false, outage: false };
-  if (!spec) return result;
-  const worlds = new Set();
+/** The `modules` property of a `useTestWorld({ modules })` call that `node` is, or null. */
+function worldModulesProperty(ts, spec, node) {
+  if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression) || node.expression.text !== 'useTestWorld' || !spec.imports.has('useTestWorld')) return null;
+  const [argument] = node.arguments;
+  if (!argument || !ts.isObjectLiteralExpression(argument)) return null;
+  return argument.properties.find((property) => ts.isPropertyAssignment(property) && ts.isIdentifier(property.name) && property.name.text === 'modules') ?? null;
+}
+
+/** Whether a `useTestWorld` call of `spec` registers the integration; the variables holding a world join `worlds`. */
+function registersInWorld(ts, judge, spec, folder, worlds) {
+  let proven = false;
   walk(ts, spec.sourceFile, (node) => {
-    if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression) || node.expression.text !== 'useTestWorld' || !spec.imports.has('useTestWorld')) return;
-    const [argument] = node.arguments;
-    if (!argument || !ts.isObjectLiteralExpression(argument)) return;
-    const modules = argument.properties.find((property) => ts.isPropertyAssignment(property) && ts.isIdentifier(property.name) && property.name.text === 'modules');
+    const modules = worldModulesProperty(ts, spec, node);
     if (!modules) return;
     if (ts.isVariableDeclaration(node.parent) && ts.isIdentifier(node.parent.name)) worlds.add(node.parent.name.text);
-    if (elementsOf(ts, judge, spec, modules.initializer).some((element) => registersIntegration(ts, judge, element, folder))) result.modules = true;
+    if (elementsOf(ts, judge, spec, modules.initializer).some((element) => registersIntegration(ts, judge, element, folder))) proven = true;
   });
-  const enumBindings = new Set(
+  return proven;
+}
+
+/** The local names of the enums the spec imports from the integration folder. */
+function enumBindingsOf(ts, judge, spec, folder) {
+  return new Set(
     [...spec.imports].filter(([, binding]) => {
-      const target = judge.resolve(rel, binding.source);
+      const target = judge.resolve(spec.rel, binding.source);
       return insideFolder(target, folder) && exportsEnum(ts, judge, target, binding.imported);
     }).map(([local]) => local),
   );
+}
+
+/** Whether the property access `node` of the world chain `chain` is a call of an outage verb. */
+function isOutageCall(ts, node, chain) {
+  const [, area, name, call] = chain;
+  if (!(ts.isCallExpression(node.parent) && node.parent.expression === node)) return false;
+  return (area === 'infra' && name !== undefined && INFRA_OUTAGES.has(call))
+    || area === 'interruptDatabase'
+    || (OUTAGE_CALLS[area] !== undefined && name !== undefined && call === OUTAGE_CALLS[area]);
+}
+
+/** Whether `node` reaches an outage through a world variable of `worlds`. */
+function drivesOutage(ts, node, worlds) {
+  if (!ts.isPropertyAccessExpression(node)) return false;
+  const chain = chainOf(ts, node);
+  return Boolean(chain) && worlds.has(chain[0]) && isOutageCall(ts, node, chain);
+}
+
+/** What one spec proves about the integration in `folder`: { modules, errorCode, outage }. */
+function judgeSpec(ts, judge, rel, folder) {
+  const spec = judge.parsed(rel);
+  const result = { modules: false, errorCode: false, outage: false };
+  if (!spec) return result;
+  const worlds = new Set();
+  result.modules = registersInWorld(ts, judge, spec, folder, worlds);
+  const enumBindings = enumBindingsOf(ts, judge, spec, folder);
   walk(ts, spec.sourceFile, (node) => {
     if (ts.isIdentifier(node) && enumBindings.has(node.text) && !ts.isImportSpecifier(node.parent)) result.errorCode = true;
-    if (!ts.isPropertyAccessExpression(node)) return;
-    const chain = chainOf(ts, node);
-    if (!chain || !worlds.has(chain[0])) return;
-    const [, area, name, call] = chain;
-    const called = ts.isCallExpression(node.parent) && node.parent.expression === node;
-    if (area === 'infra' && name !== undefined && INFRA_OUTAGES.has(call) && called) result.outage = true;
-    else if (area === 'interruptDatabase' && called) result.outage = true;
-    else if (OUTAGE_CALLS[area] !== undefined && name !== undefined && call === OUTAGE_CALLS[area] && called) result.outage = true;
+    if (drivesOutage(ts, node, worlds)) result.outage = true;
   });
   return result;
 }
@@ -199,7 +233,7 @@ export function integrationSpecFindings({ repoRoot, files }) {
   const findings = [];
   for (const { side, provider, folder } of integrations) {
     const specDir = `${side}src/tests/integration/${provider}/`;
-    const specs = files.filter((file) => file.startsWith(specDir) && file.endsWith(SPEC_SUFFIX) && !file.slice(specDir.length).includes('/')).sort();
+    const specs = files.filter((file) => file.startsWith(specDir) && file.endsWith(SPEC_SUFFIX) && !file.slice(specDir.length).includes('/')).sort(byCodeUnit);
     if (specs.length === 0) {
       findings.push(found(INTEGRATION_SPEC_MISSING, `${folder}/`, `${folder}/ is an integration with no integration spec: add ${specDir}<name>${SPEC_SUFFIX} that ${MISSING_PARTS.modules}, ${MISSING_PARTS.errorCode}, and ${MISSING_PARTS.outage}.`, { provider, missing: ['spec'] }));
       continue;

package/runtime/scripts/hfs/rules/kinds.mjs

@@ -8,6 +8,7 @@
 // `features/cli/` is the one cli feature root (its module and group folders), so it is in use as soon as it holds a file.
 import { loadSlotManifest, ruleParams } from '../slots.mjs';
 import { found } from './read.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 const KIND_DECLARATION = 'BE_KIND_DECLARATION';
 const KIND_EMPTY = 'BE_KIND_EMPTY';
@@ -32,23 +33,22 @@ const facts = () => {
   return memo;
 };
 
-/** Findings of BE_KIND_DECLARATION and BE_KIND_EMPTY. */
-export function kindFindings({ files, repo }) {
-  const be = repo.sides?.be;
-  if (!be) return [];
-  const { triggerKinds, kindPatterns, platform } = facts();
-  const kindFolders = new Set(triggerKinds);
+/** The path parts below the features root of a file inside a known kind folder, else null. */
+function kindPathParts(file, kindFolders) {
+  if (!file.startsWith(FEATURES)) return null;
+  const rest = file.slice(FEATURES.length).split('/');
+  return rest.length < 2 || !kindFolders.has(rest[0]) ? null : rest;
+}
+
+function kindUsageOf(files, kindFolders) {
   const findings = [];
   const instances = new Map();
   const sources = new Map();
   const roots = new Set();
-  const tracked = new Set(files);
   for (const file of files) {
-    if (!file.startsWith(FEATURES)) continue;
-    const rest = file.slice(FEATURES.length).split('/');
-    if (rest.length < 2) continue;
+    const rest = kindPathParts(file, kindFolders);
+    if (!rest) continue;
     const [first, second] = rest;
-    if (!kindFolders.has(first)) continue;
     if (first === CLI) { roots.add(CLI); continue; }
     if (rest.length === 2) {
       findings.push(found(KIND_EMPTY, file, `${file} sits directly in the kind folder ${FEATURES}${first}/, which holds only instance folders (${first}/<name>/); an empty kind folder is never kept: run \`starci app add\` to create the first member.`, { kind: first }));
@@ -59,26 +59,60 @@ export function kindFindings({ files, repo }) {
     const key = `${first}/${second}`;
     sources.set(key, (sources.get(key) ?? 0) + (/\.[cm]?tsx?$/.test(file) ? 1 : 0));
   }
+  return { findings, instances, sources, roots };
+}
+
+function emptyInstanceFindings(sources) {
+  const findings = [];
   for (const [key, count] of sources) {
     if (count === 0) findings.push(found(KIND_EMPTY, `${FEATURES}${key}/`, `${FEATURES}${key}/ holds no TypeScript source: a kind member without code is an empty folder; add its files with \`starci app add\` or remove the folder.`, { kind: key.split('/')[0] }));
   }
-  const present = new Set([...instances.keys(), ...roots]);
-  const declared = new Set(be.kinds ?? []);
-  const patterns = new Set(be.patterns ?? []);
-  for (const kind of [...present].sort()) {
+  return findings;
+}
+
+function undeclaredKindFindings(present, declared) {
+  const findings = [];
+  for (const kind of [...present].sort(byCodeUnit)) {
     if (!declared.has(kind)) findings.push(found(KIND_DECLARATION, 'hfs.json', `hfs.json sides.be.kinds does not declare the kind \`${kind}\`, which ${FEATURES}${kind}/ uses; declare every kind in use (\`starci app add\` registers it).`, { kind }));
   }
-  for (const kind of [...declared].sort()) {
-    if (!present.has(kind)) {
-      findings.push(found(KIND_DECLARATION, 'hfs.json', `hfs.json sides.be.kinds declares \`${kind}\` but no feature of that kind exists; a kind is declared only when it is used, so remove it or add its first member with \`starci app add\`.`, { kind }));
-      continue;
-    }
-    for (const pattern of kindPatterns[kind] ?? []) {
-      if (!patterns.has(pattern)) findings.push(found(KIND_DECLARATION, 'hfs.json', `the kind \`${kind}\` needs the pattern \`${pattern}\`, which hfs.json sides.be.patterns does not declare.`, { kind, pattern }));
-      for (const capability of platform.get(pattern) ?? []) {
-        if (!tracked.has(`be/src/modules/platform/${capability}/index.ts`)) findings.push(found(KIND_DECLARATION, `be/src/modules/platform/${capability}/`, `the kind \`${kind}\` needs the platform capability \`${capability}\` (pattern ${pattern}), which is not tracked at be/src/modules/platform/${capability}/; \`starci app add\` generates it with the first member of the kind.`, { kind, pattern, capability }));
-      }
+  return findings;
+}
+
+function kindPatternFindings(kind, { kindPatterns, patterns, platform, tracked }) {
+  const findings = [];
+  for (const pattern of kindPatterns[kind] ?? []) {
+    if (!patterns.has(pattern)) findings.push(found(KIND_DECLARATION, 'hfs.json', `the kind \`${kind}\` needs the pattern \`${pattern}\`, which hfs.json sides.be.patterns does not declare.`, { kind, pattern }));
+    for (const capability of platform.get(pattern) ?? []) {
+      if (!tracked.has(`be/src/modules/platform/${capability}/index.ts`)) findings.push(found(KIND_DECLARATION, `be/src/modules/platform/${capability}/`, `the kind \`${kind}\` needs the platform capability \`${capability}\` (pattern ${pattern}), which is not tracked at be/src/modules/platform/${capability}/; \`starci app add\` generates it with the first member of the kind.`, { kind, pattern, capability }));
     }
   }
   return findings;
 }
+
+function declaredKindFindings({ declared, present, kindPatterns, patterns, platform, tracked }) {
+  const findings = [];
+  for (const kind of [...declared].sort(byCodeUnit)) {
+    if (present.has(kind)) findings.push(...kindPatternFindings(kind, { kindPatterns, patterns, platform, tracked }));
+    else findings.push(found(KIND_DECLARATION, 'hfs.json', `hfs.json sides.be.kinds declares \`${kind}\` but no feature of that kind exists; a kind is declared only when it is used, so remove it or add its first member with \`starci app add\`.`, { kind }));
+  }
+  return findings;
+}
+
+/** Findings of BE_KIND_DECLARATION and BE_KIND_EMPTY. */
+export function kindFindings({ files, repo }) {
+  const be = repo.sides?.be;
+  if (!be) return [];
+  const { triggerKinds, kindPatterns, platform } = facts();
+  const kindFolders = new Set(triggerKinds);
+  const tracked = new Set(files);
+  const usage = kindUsageOf(files, kindFolders);
+  const findings = usage.findings;
+  const instances = usage.instances;
+  const roots = usage.roots;
+  findings.push(...emptyInstanceFindings(usage.sources));
+  const present = new Set([...instances.keys(), ...roots]);
+  const declared = new Set(be.kinds ?? []);
+  const patterns = new Set(be.patterns ?? []);
+  findings.push(...undeclaredKindFindings(present, declared), ...declaredKindFindings({ declared, present, kindPatterns, patterns, platform, tracked }));
+  return findings;
+}