@starci/hfs 4.11.22 → 4.12.0

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

@@ -17,238 +17,251 @@ 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';
-
 const CONFIG_FILE = /^((?:[^/]+\/)*?)src\/modules\/integrations\/([^/]+)\/\2\.config\.ts$/;
 const SPEC_SUFFIX = '.integration-spec.ts';
 const OUTAGE_CALLS = Object.freeze({ fake: 'failNext', apps: 'during' });
 /** The outage verbs of `world.infra.<service>` (`connection` leads to one connection's cut/restore/during). */
 const INFRA_OUTAGES = new Set(['cut', 'latency', 'during', 'connection']);
 const HERE = path.dirname(fileURLToPath(import.meta.url));
-
 /** The TypeScript compiler of the app (else of the runtime), or null. */
 const typescriptFor = (repoRoot) => loadTypescript(repoRoot, HERE);
-
 /** The compiler options of the side (its tsconfig.json, `extends` and `paths` resolved by TypeScript itself). */
 function optionsOf(ts, sideRoot) {
-  const file = path.join(sideRoot, 'tsconfig.json');
-  if (!fs.existsSync(file)) return {};
-  const read = ts.readConfigFile(file, ts.sys.readFile);
-  if (read.error) return {};
-  return ts.parseJsonConfigFileContent(read.config, ts.sys, sideRoot).options;
+    const file = path.join(sideRoot, 'tsconfig.json');
+    if (!fs.existsSync(file))
+        return {};
+    const read = ts.readConfigFile(file, ts.sys.readFile);
+    if (read.error)
+        return {};
+    return ts.parseJsonConfigFileContent(read.config, ts.sys, sideRoot).options;
 }
-
 /** One parsed file: its syntax tree and its imports (local name -> { source, imported }). */
 function parse(ts, repoRoot, rel) {
-  const text = readText(repoRoot, rel);
-  if (text === null) return null;
-  const sourceFile = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-  const imports = new Map();
-  for (const statement of sourceFile.statements) {
-    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) continue;
-    const named = statement.importClause?.namedBindings;
-    if (!named || !ts.isNamedImports(named)) continue;
-    for (const element of named.elements) imports.set(element.name.text, { source: statement.moduleSpecifier.text, imported: (element.propertyName ?? element.name).text, node: element });
-  }
-  return { rel, sourceFile, imports };
-}
-
+    const text = readText(repoRoot, rel);
+    if (text === null)
+        return null;
+    const sourceFile = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const imports = new Map();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier))
+            continue;
+        const named = statement.importClause?.namedBindings;
+        if (!named || !ts.isNamedImports(named))
+            continue;
+        for (const element of named.elements)
+            imports.set(element.name.text, { source: statement.moduleSpecifier.text, imported: (element.propertyName ?? element.name).text, node: element });
+    }
+    return { rel, sourceFile, imports };
+}
 /** Walks every node under `node`. */
 function walk(ts, node, visit) {
-  visit(node);
-  ts.forEachChild(node, (child) => walk(ts, child, visit));
+    visit(node);
+    ts.forEachChild(node, (child) => walk(ts, child, visit));
 }
-
 /** The names of a property chain `a.b.c` from its root identifier, or null when the chain does not start at an identifier. */
 function chainOf(ts, expression) {
-  const names = [];
-  let current = expression;
-  while (ts.isPropertyAccessExpression(current)) {
-    names.unshift(current.name.text);
-    current = current.expression;
-  }
-  return ts.isIdentifier(current) ? [current.text, ...names] : null;
-}
-
+    const names = [];
+    let current = expression;
+    while (ts.isPropertyAccessExpression(current)) {
+        names.unshift(current.name.text);
+        current = current.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;
+    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 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.
  */
 function judgeOf(ts, repoRoot, side) {
-  const options = optionsOf(ts, path.join(repoRoot, side));
-  const cache = new Map();
-  const parsed = (rel) => {
-    if (!cache.has(rel)) cache.set(rel, parse(ts, repoRoot, rel));
-    return cache.get(rel);
-  };
-  const resolve = (fromRel, source) => {
-    const resolved = ts.resolveModuleName(source, path.join(repoRoot, fromRel), options, ts.sys).resolvedModule?.resolvedFileName;
-    if (!resolved) return null;
-    const rel = path.relative(repoRoot, resolved).split(path.sep).join('/');
-    return rel.startsWith('..') ? null : rel;
-  };
-  return { parsed, resolve, constOf: (file, name) => topLevelConst(ts, file, name) };
-}
-
+    const options = optionsOf(ts, path.join(repoRoot, side));
+    const cache = new Map();
+    const parsed = (rel) => {
+        if (!cache.has(rel))
+            cache.set(rel, parse(ts, repoRoot, rel));
+        return cache.get(rel);
+    };
+    const resolve = (fromRel, source) => {
+        const resolved = ts.resolveModuleName(source, path.join(repoRoot, fromRel), options, ts.sys).resolvedModule?.resolvedFileName;
+        if (!resolved)
+            return null;
+        const rel = path.relative(repoRoot, resolved).split(path.sep).join('/');
+        return rel.startsWith('..') ? null : rel;
+    };
+    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). */
 const insideFolder = (rel, folder) => rel !== null && (rel === `${folder}/index.ts` || rel.startsWith(`${folder}/`));
-
 /** The array elements `expression` evaluates to in `file`, each with the file it is written in (identifiers, spreads and imports followed). */
 function elementsOf(ts, judge, file, expression, depth = 0) {
-  if (!expression || depth > 6) return [];
-  let node = expression;
-  while (ts.isAsExpression(node) || ts.isSatisfiesExpression?.(node) || ts.isParenthesizedExpression(node)) node = node.expression;
-  if (ts.isArrayLiteralExpression(node)) {
-    return node.elements.flatMap((element) => (ts.isSpreadElement(element) ? elementsOf(ts, judge, file, element.expression, depth + 1) : [{ file, node: element }]));
-  }
-  if (!ts.isIdentifier(node)) return [];
-  const local = judge.constOf(file, node.text);
-  if (local) return elementsOf(ts, judge, file, local, depth + 1);
-  const imported = file.imports.get(node.text);
-  if (!imported) return [];
-  const target = judge.resolve(file.rel, imported.source);
-  const other = target ? judge.parsed(target) : null;
-  return other ? elementsOf(ts, judge, other, judge.constOf(other, imported.imported), depth + 1) : [];
-}
-
+    if (!expression || depth > 6)
+        return [];
+    let node = expression;
+    while (ts.isAsExpression(node) || ts.isSatisfiesExpression?.(node) || ts.isParenthesizedExpression(node))
+        node = node.expression;
+    if (ts.isArrayLiteralExpression(node)) {
+        return node.elements.flatMap((element) => (ts.isSpreadElement(element) ? elementsOf(ts, judge, file, element.expression, depth + 1) : [{ file, node: element }]));
+    }
+    if (!ts.isIdentifier(node))
+        return [];
+    const local = judge.constOf(file, node.text);
+    if (local)
+        return elementsOf(ts, judge, file, local, depth + 1);
+    const imported = file.imports.get(node.text);
+    if (!imported)
+        return [];
+    const target = judge.resolve(file.rel, imported.source);
+    const other = target ? judge.parsed(target) : null;
+    return other ? elementsOf(ts, judge, other, judge.constOf(other, imported.imported), depth + 1) : [];
+}
 /** Whether a factory element calls `<X>.register(...)` with `<X>` imported (in the element's file) from the integration folder. */
 function registersIntegration(ts, judge, element, folder) {
-  let registers = false;
-  walk(ts, element.node, (node) => {
-    if (registers || !ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) return;
-    if (node.expression.name.text !== 'register' || !ts.isIdentifier(node.expression.expression)) return;
-    const binding = element.file.imports.get(node.expression.expression.text);
-    if (binding && insideFolder(judge.resolve(element.file.rel, binding.source), folder)) registers = true;
-  });
-  return registers;
-}
-
+    let registers = false;
+    walk(ts, element.node, (node) => {
+        if (registers || !ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression))
+            return;
+        if (node.expression.name.text !== 'register' || !ts.isIdentifier(node.expression.expression))
+            return;
+        const binding = element.file.imports.get(node.expression.expression.text);
+        if (binding && insideFolder(judge.resolve(element.file.rel, binding.source), folder))
+            registers = true;
+    });
+    return registers;
+}
 /** 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;
-}
-
+    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) {
-    const result = enumExportResult(ts, judge, rel, name, depth, statement);
-    if (result !== null) return result;
-  }
-  return false;
-}
-
+    const file = rel ? judge.parsed(rel) : null;
+    if (!file || depth > 4)
+        return false;
+    for (const statement of file.sourceFile.statements) {
+        const result = enumExportResult(ts, judge, rel, name, depth, statement);
+        if (result !== null)
+            return result;
+    }
+    return false;
+}
 /** 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;
+    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) => {
-    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))) proven = true;
-  });
-  return proven;
-}
-
+    let proven = false;
+    walk(ts, spec.sourceFile, (node) => {
+        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)))
+            proven = true;
+    });
+    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(spec.rel, binding.source);
-      return insideFolder(target, folder) && exportsEnum(ts, judge, target, binding.imported);
-    }).map(([local]) => local),
-  );
-}
-
+    return new Set([...spec.imports].filter(([, binding]) => {
+        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]);
+    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);
+    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 (drivesOutage(ts, node, worlds)) result.outage = true;
-  });
-  return result;
-}
-
+    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 (drivesOutage(ts, node, worlds))
+            result.outage = true;
+    });
+    return result;
+}
 const MISSING_PARTS = Object.freeze({
-  modules: 'call useTestWorld({ modules }) with a factory that registers the integration module (<Provider>Module.register) imported from the integration',
-  errorCode: "reference the integration's ErrorCode enum (its refusal mapping)",
-  outage: 'drive an outage through the world: world.infra.<service>, world.fake.<name>.failNext(...), world.apps.<peer>.during(...) or world.interruptDatabase(...)',
+    modules: 'call useTestWorld({ modules }) with a factory that registers the integration module (<Provider>Module.register) imported from the integration',
+    errorCode: "reference the integration's ErrorCode enum (its refusal mapping)",
+    outage: 'drive an outage through the world: world.infra.<service>, world.fake.<name>.failNext(...), world.apps.<peer>.during(...) or world.interruptDatabase(...)',
 });
-
 /** The full-edition test-world proofs of R112; lite owns its integration lane through R284. */
 export function integrationSpecFindings({ repoRoot, files, repo }) {
-  if (repo?.edition === 'lite') return [];
-  const integrations = files.map((file) => CONFIG_FILE.exec(file)).filter(Boolean).map(([, side, provider]) => ({ side, provider, folder: `${side}src/modules/integrations/${provider}` }));
-  if (integrations.length === 0) return [];
-  const ts = typescriptFor(repoRoot);
-  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(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;
-    }
-    if (ts === null) {
-      findings.push(found(INTEGRATION_SPEC_MISSING, `${folder}/`, `${folder}/ cannot be judged: no TypeScript resolves from the app; install the app's dependencies.`, { provider, missing: ['typescript'] }));
-      continue;
+    if (repo?.edition === 'lite')
+        return [];
+    const integrations = files.map((file) => CONFIG_FILE.exec(file)).filter(Boolean).map(([, side, provider]) => ({ side, provider, folder: `${side}src/modules/integrations/${provider}` }));
+    if (integrations.length === 0)
+        return [];
+    const ts = typescriptFor(repoRoot);
+    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(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;
+        }
+        if (ts === null) {
+            findings.push(found(INTEGRATION_SPEC_MISSING, `${folder}/`, `${folder}/ cannot be judged: no TypeScript resolves from the app; install the app's dependencies.`, { provider, missing: ['typescript'] }));
+            continue;
+        }
+        const judge = judgeOf(ts, repoRoot, side);
+        const verdicts = specs.map((spec) => ({ spec, ...judgeSpec(ts, judge, spec, folder) }));
+        if (verdicts.some((verdict) => verdict.modules && verdict.errorCode && verdict.outage))
+            continue;
+        const best = [...verdicts].sort((a, b) => Number(b.modules) + Number(b.errorCode) + Number(b.outage) - (Number(a.modules) + Number(a.errorCode) + Number(a.outage)))[0];
+        const missing = Object.keys(MISSING_PARTS).filter((part) => !best[part]);
+        findings.push(found(INTEGRATION_SPEC_MISSING, `${folder}/`, `${folder}/ has integration specs (${specs.join(', ')}), but none proves the integration: ${best.spec} must also ${missing.map((part) => MISSING_PARTS[part]).join('; and ')}.`, { provider, missing }));
     }
-    const judge = judgeOf(ts, repoRoot, side);
-    const verdicts = specs.map((spec) => ({ spec, ...judgeSpec(ts, judge, spec, folder) }));
-    if (verdicts.some((verdict) => verdict.modules && verdict.errorCode && verdict.outage)) continue;
-    const best = [...verdicts].sort((a, b) => Number(b.modules) + Number(b.errorCode) + Number(b.outage) - (Number(a.modules) + Number(a.errorCode) + Number(a.outage)))[0];
-    const missing = Object.keys(MISSING_PARTS).filter((part) => !best[part]);
-    findings.push(found(INTEGRATION_SPEC_MISSING, `${folder}/`, `${folder}/ has integration specs (${specs.join(', ')}), but none proves the integration: ${best.spec} must also ${missing.map((part) => MISSING_PARTS[part]).join('; and ')}.`, { provider, missing }));
-  }
-  return findings;
+    return findings;
 }

package/runtime/scripts/hfs/rules/kinds.d.mts

@@ -0,0 +1,6 @@
+import type { Repo } from './rule-types.mjs';
+/** Findings of BE_KIND_DECLARATION and BE_KIND_EMPTY. */
+export declare function kindFindings({ files, repo }: {
+    files: string[];
+    repo: Repo;
+}): import("./rule-types.mjs").Finding[];