@starci/hfs 4.11.21 → 4.12.0

package/runtime/scripts/hfs/architecture/unit-spec-providers.d.mts

@@ -0,0 +1,34 @@
+import type { ArchitectureConfig } from './config.mjs';
+import type { ArchitectureViolation, HfsGraph } from './hfs-graph.mjs';
+import type { MachineContext } from './machine-ast.mjs';
+/**
+ * R48 `unit-spec-providers` (BE_SPEC_QUALITY), the unit test standard's rule 3: the unit spec of a service builds its
+ * subject with `Test.createTestingModule({ providers: [...] })`, and that providers array EQUALS the constructor
+ * dependencies of the service under test: the service class first, then one provider for each constructor parameter.
+ *
+ * The service under test is the sibling `<name>.service.ts` of every `<name>.service.spec.ts` under src/ or apps/ (a spec is
+ * outside the production program, so it is read from disk). A parameter decorated with a custom `Inject<Thing>()` provides
+ * the token that decorator's `injector<T>(TOKEN)` names; an undecorated parameter of a class type provides that class (see
+ * constructor-deps.mjs). Providers are matched by the exported name of the imported binding (`import { CACHE as C }` is
+ * CACHE), never by text. A provider is a class, or `{ provide: TOKEN, useValue: double }` and nothing else. A sibling
+ * containing only exported functions instead provides its complete real function object and exercises it through module.get;
+ * the constants, enums, re-exports and overload signatures beside those functions do not count. A value-object subject (an
+ * undecorated class whose constructor parameters carry no injection token) is built with `new`, Nest never constructs it.
+ *
+ * Findings: an extra provider, a missing provider, a service that is not the first provider, a dependency whose token cannot
+ * be resolved, a spec with no createTestingModule providers array, and a provider that is neither a class nor
+ * `{ provide, useValue }`. Which double a `useValue` is, and whether other specs exist at all, are other rules' business.
+ */
+export declare const UNIT_SPEC_PROVIDERS_RULE_IDS: string[];
+export declare function checkUnitSpecProviders(input: {
+    config: ArchitectureConfig;
+    context: MachineContext;
+    graph: HfsGraph;
+}): {
+    violations: ArchitectureViolation[];
+    coverage: {
+        status: string;
+        specs: number;
+        files: number;
+    };
+};

package/runtime/scripts/hfs/architecture/unit-spec-providers.mjs

@@ -6,7 +6,6 @@ import { treeOf } from './required-files.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
 import { importsOf } from '../../lib/ts-analysis.mjs';
 import { checkFunctionSubject, functionSubjectExports, keyOf as literalKey, valueObjectSubjects } from './function-spec-providers.mjs';
-
 /**
  * R48 `unit-spec-providers` (BE_SPEC_QUALITY), the unit test standard's rule 3: the unit spec of a service builds its
  * subject with `Test.createTestingModule({ providers: [...] })`, and that providers array EQUALS the constructor
@@ -26,115 +25,134 @@ import { checkFunctionSubject, functionSubjectExports, keyOf as literalKey, valu
  * `{ provide, useValue }`. Which double a `useValue` is, and whether other specs exist at all, are other rules' business.
  */
 export const UNIT_SPEC_PROVIDERS_RULE_IDS = ['BE_SPEC_QUALITY'];
-
 const RULE = 'BE_SPEC_QUALITY';
 const SPEC_ROOT = /^(?:src|apps)\//u;
-
 /** The `Test.createTestingModule(...)` calls of a spec. */
 function testingModules(ts, sourceFile) {
-  const calls = [];
-  const visit = node => {
-    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'createTestingModule') calls.push(node);
-    ts.forEachChild(node, visit);
-  };
-  visit(sourceFile);
-  return calls;
+    const calls = [];
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'createTestingModule')
+            calls.push(node);
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return calls;
 }
-
-
 function providerList(ts, call, rel, report) {
-  const options = call.arguments[0];
-  const property = options && ts.isObjectLiteralExpression(options) ? options.properties.find(item => literalKey(ts, item) === 'providers') : null;
-  const list = property && ts.isPropertyAssignment(property) && ts.isArrayLiteralExpression(property.initializer) ? property.initializer : null;
-  if (!list) report(call, `${rel}: Test.createTestingModule has no literal \`providers\` array; list the service and each constructor dependency there.`);
-  return list;
+    const options = call.arguments[0];
+    const property = options && ts.isObjectLiteralExpression(options) ? options.properties.find(item => literalKey(ts, item) === 'providers') : null;
+    const list = property && ts.isPropertyAssignment(property) && ts.isArrayLiteralExpression(property.initializer) ? property.initializer : null;
+    if (!list)
+        report(call, `${rel}: Test.createTestingModule has no literal \`providers\` array; list the service and each constructor dependency there.`);
+    return list;
 }
-
 function readProviders(ts, list, rel, nameOf, report) {
-  const provided = [];
-  let readable = true;
-  for (const element of list.elements) {
-    if (ts.isIdentifier(element)) { provided.push({ name: nameOf(element), node: element, isClass: true }); continue; }
-    if (ts.isObjectLiteralExpression(element)) {
-      const keys = element.properties.map(item => literalKey(ts, item));
-      const provide = element.properties.find(item => literalKey(ts, item) === 'provide');
-      const value = provide && ts.isPropertyAssignment(provide) ? provide.initializer : null;
-      if (keys.length === 2 && keys.includes('useValue') && value && ts.isIdentifier(value)) { provided.push({ name: nameOf(value), node: element, isClass: false }); continue; }
+    const provided = [];
+    let readable = true;
+    for (const element of list.elements) {
+        if (ts.isIdentifier(element)) {
+            provided.push({ name: nameOf(element), node: element, isClass: true });
+            continue;
+        }
+        if (ts.isObjectLiteralExpression(element)) {
+            const keys = element.properties.map(item => literalKey(ts, item));
+            const provide = element.properties.find(item => literalKey(ts, item) === 'provide');
+            const value = provide && ts.isPropertyAssignment(provide) ? provide.initializer : null;
+            if (keys.length === 2 && keys.includes('useValue') && value && ts.isIdentifier(value)) {
+                provided.push({ name: nameOf(value), node: element, isClass: false });
+                continue;
+            }
+        }
+        readable = false;
+        report(element, `${rel}: a provider is a class or \`{ provide: TOKEN, useValue: double }\` and nothing else (no useClass, useFactory, useExisting, spread or computed token).`);
     }
-    readable = false;
-    report(element, `${rel}: a provider is a class or \`{ provide: TOKEN, useValue: double }\` and nothing else (no useClass, useFactory, useExisting, spread or computed token).`);
-  }
-  return { provided, readable };
+    return { provided, readable };
 }
-
 function serviceClassFor(ts, rel, serviceRel, serviceFile, imports, list, report) {
-  const first = list.elements[0];
-  const serviceName = first && ts.isIdentifier(first) ? imports.get(first.text) : null;
-  const target = serviceName ? path.posix.normalize(path.posix.join(path.posix.dirname(rel), serviceName.module)).replace(/\.[cm]?[jt]s$/u, '') : null;
-  const serviceClass = serviceName && target === serviceRel.replace(/\.ts$/u, '')
-    ? serviceFile.sourceFile.statements.find(statement => ts.isClassDeclaration(statement) && statement.name?.text === serviceName.name) : null;
-  if (!serviceClass) report(first ?? list, `${rel}: the first provider is the service under test, imported from ./${path.posix.basename(serviceRel, '.ts')}.`);
-  return serviceClass ? { serviceClass, serviceName } : null;
+    const first = list.elements[0];
+    const serviceName = first && ts.isIdentifier(first) ? imports.get(first.text) : null;
+    const target = serviceName ? path.posix.normalize(path.posix.join(path.posix.dirname(rel), serviceName.module)).replace(/\.[cm]?[jt]s$/u, '') : null;
+    const serviceClass = serviceName && target === serviceRel.replace(/\.ts$/u, '')
+        ? serviceFile.sourceFile.statements.find((statement) => ts.isClassDeclaration(statement) && statement.name?.text === serviceName.name) : null;
+    if (!serviceClass)
+        report(first ?? list, `${rel}: the first provider is the service under test, imported from ./${path.posix.basename(serviceRel, '.ts')}.`);
+    return serviceClass ? { serviceClass, serviceName: serviceName } : null; // a class is found only when the service name resolved
 }
-
 function checkDependencies(kit, rel, service, serviceFile, list, provided, report) {
-  const { serviceName, serviceClass } = service;
-  const dependencies = constructorDependencies(kit, serviceFile, serviceClass);
-  const expected = [];
-  for (const dependency of dependencies) {
-    if (dependency.kind === 'unresolved') {
-      report(list, `${rel}: a constructor dependency of ${serviceName.name} cannot be resolved to a token (${dependency.reason}), so its provider cannot be checked; inject it through an exported Inject<Thing>() decorator or a class type.`);
-      continue;
+    const { serviceName, serviceClass } = service;
+    const dependencies = constructorDependencies(kit, serviceFile, serviceClass);
+    const expected = [];
+    for (const dependency of dependencies) {
+        if (dependency.kind === 'unresolved') {
+            report(list, `${rel}: a constructor dependency of ${serviceName.name} cannot be resolved to a token (${dependency.reason}), so its provider cannot be checked; inject it through an exported Inject<Thing>() decorator or a class type.`);
+            continue;
+        }
+        expected.push(dependency.name);
     }
-    expected.push(dependency.name);
-  }
-  const remaining = [...expected];
-  for (const item of provided.slice(1)) {
-    const index = remaining.indexOf(item.name);
-    if (index === -1) report(item.node, `${rel}: ${item.name} is provided but is not a constructor dependency of ${serviceName.name}; a unit spec provides exactly what the constructor needs.`);
-    else remaining.splice(index, 1);
-  }
-  for (const name of remaining) report(list, `${rel}: ${name} is a constructor dependency of ${serviceName.name} but is not provided; add \`{ provide: ${name}, useValue: double }\` (or the class itself) to the providers.`);
+    const remaining = [...expected];
+    for (const item of provided.slice(1)) {
+        const index = remaining.indexOf(item.name);
+        if (index === -1)
+            report(item.node, `${rel}: ${item.name} is provided but is not a constructor dependency of ${serviceName.name}; a unit spec provides exactly what the constructor needs.`);
+        else
+            remaining.splice(index, 1);
+    }
+    for (const name of remaining)
+        report(list, `${rel}: ${name} is a constructor dependency of ${serviceName.name} but is not provided; add \`{ provide: ${name}, useValue: double }\` (or the class itself) to the providers.`);
 }
-
 function checkTestingModule({ ts, kit, rel, serviceRel, serviceFile, imports, call, report }) {
-  const list = providerList(ts, call, rel, report);
-  if (!list) return;
-  const names = functionSubjectExports(ts, serviceFile.sourceFile);
-  if (names) return checkFunctionSubject({ ts, rel, serviceRel, imports, call, list, names, report });
-  const nameOf = identifier => imports.get(identifier.text)?.name ?? identifier.text;
-  const { provided, readable } = readProviders(ts, list, rel, nameOf, report);
-  if (!readable) return;
-  const service = serviceClassFor(ts, rel, serviceRel, serviceFile, imports, list, report);
-  if (!service) return;
-  checkDependencies(kit, rel, service, serviceFile, list, provided, report);
+    const list = providerList(ts, call, rel, report);
+    if (!list)
+        return;
+    const names = functionSubjectExports(ts, serviceFile.sourceFile);
+    if (names) {
+        checkFunctionSubject({ ts, rel, serviceRel, imports, call, list, names, report });
+        return;
+    }
+    const nameOf = (identifier) => imports.get(identifier.text)?.name ?? identifier.text;
+    const { provided, readable } = readProviders(ts, list, rel, nameOf, report);
+    if (!readable)
+        return;
+    const service = serviceClassFor(ts, rel, serviceRel, serviceFile, imports, list, report);
+    if (!service)
+        return;
+    checkDependencies(kit, rel, service, serviceFile, list, provided, report);
 }
-
 function checkServiceSpec({ config, graph, kit, ts, rel, violations }) {
-  const abs = path.join(config.root, ...rel.split('/'));
-  if (!fs.existsSync(abs)) return false;
-  const sourceFile = ts.createSourceFile(abs, fs.readFileSync(abs, 'utf8'), ts.ScriptTarget.Latest, true);
-  const report = (node, message) => violations.push({ ruleId: RULE, path: rel, ...kit.at(rel, sourceFile, node), message });
-  const imports = importsOf(ts, sourceFile);
-  const serviceRel = rel.replace(/\.spec\.ts$/u, '.ts');
-  const serviceFile = graph.files.get(serviceRel);
-  if (!serviceFile) { report(sourceFile, `${rel} has no ${path.posix.basename(serviceRel)} beside it; a service spec sits next to the service it tests.`); return true; }
-  const modules = testingModules(ts, sourceFile);
-  if (!modules.length && valueObjectSubjects(ts, serviceFile.sourceFile)) return true;
-  if (!modules.length) { report(sourceFile, `${rel} never calls Test.createTestingModule({ providers: [...] }); build the service from a testing module holding exactly its constructor dependencies.`); return true; }
-  for (const call of modules) checkTestingModule({ ts, kit, rel, serviceRel, serviceFile, imports, call, report });
-  return true;
+    const abs = path.join(config.root, ...rel.split('/'));
+    if (!fs.existsSync(abs))
+        return false;
+    const sourceFile = ts.createSourceFile(abs, fs.readFileSync(abs, 'utf8'), ts.ScriptTarget.Latest, true);
+    const report = (node, message) => { violations.push({ ruleId: RULE, path: rel, ...kit.at(rel, sourceFile, node), message }); };
+    // importsOf stores every binding's specifier under moduleKey, which defaults to 'module'
+    const imports = new Map(Array.from(importsOf(ts, sourceFile), ([local, record]) => [local, { name: record.name, module: record.module }]));
+    const serviceRel = rel.replace(/\.spec\.ts$/u, '.ts');
+    const serviceFile = graph.files.get(serviceRel);
+    if (!serviceFile) {
+        report(sourceFile, `${rel} has no ${path.posix.basename(serviceRel)} beside it; a service spec sits next to the service it tests.`);
+        return true;
+    }
+    const modules = testingModules(ts, sourceFile);
+    if (!modules.length && valueObjectSubjects(ts, serviceFile.sourceFile))
+        return true;
+    if (!modules.length) {
+        report(sourceFile, `${rel} never calls Test.createTestingModule({ providers: [...] }); build the service from a testing module holding exactly its constructor dependencies.`);
+        return true;
+    }
+    for (const call of modules)
+        checkTestingModule({ ts, kit, rel, serviceRel, serviceFile, imports, call, report });
+    return true;
 }
-
 export function checkUnitSpecProviders(input) {
-  const { config, graph } = input;
-  const kit = machineKit(input);
-  const { ts } = kit;
-  const violations = [];
-  let specs = 0;
-  const tree = treeOf(config.root);
-  for (const rel of [...tree.files].filter(file => SPEC_ROOT.test(file) && file.endsWith('.service.spec.ts')).sort(byCodeUnit)) {
-    if (checkServiceSpec({ config, graph, kit, ts, rel, violations })) specs += 1;
-  }
-  return { violations, coverage: { status: 'checked', specs, files: graph.files.size } };
+    const { config, graph } = input;
+    const kit = machineKit(input);
+    const { ts } = kit;
+    const violations = [];
+    let specs = 0;
+    const tree = treeOf(config.root);
+    for (const rel of [...tree.files].filter(file => SPEC_ROOT.test(file) && file.endsWith('.service.spec.ts')).sort(byCodeUnit)) {
+        if (checkServiceSpec({ config, graph, kit, ts, rel, violations }))
+            specs += 1;
+    }
+    return { violations, coverage: { status: 'checked', specs, files: graph.files.size } };
 }

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

@@ -0,0 +1,13 @@
+import { checkArchitecture } from './architecture/index.mjs';
+export { checkArchitecture };
+/** The parsed command line: the repository root and the optional `--base` commit. */
+export interface ArchitectureArgs {
+    root: string;
+    base: string | undefined;
+}
+/** Injectable seams of the entry point. */
+export interface ArchitectureMainIo {
+    check?: typeof checkArchitecture;
+    write?: (text: string) => unknown;
+    fail?: (text: string) => unknown;
+}

package/runtime/scripts/hfs/architecture.mjs

@@ -5,37 +5,47 @@
 // Prints one starci/architecture-check@1 record. Exit 0: ok. Exit 1: violations or errors (a check that
 // cannot run is an error, never a pass). Exit 2: bad arguments.
 import path from 'node:path';
-import {checkArchitecture} from './architecture/index.mjs';
+import { checkArchitecture } from './architecture/index.mjs';
 import { isMain } from '../lib/is-main.mjs';
-
-export {checkArchitecture};
-
+export { checkArchitecture };
 const USAGE = 'usage: starci runtime architecture <repo-root> [--base <commit>]';
-
 function parseArchitectureArgs(argv) {
-  let root = null, base;
-  for (let index = 0; index < argv.length; index += 1) {
-    const value = argv[index];
-    if (value === '--base') {
-      base = argv[++index];
-      if (!base) throw new Error(`--base needs a commit; ${USAGE}`);
-    } else if (value.startsWith('-') || root !== null) throw new Error(`unexpected argument ${value}; ${USAGE}`);
-    else root = value;
-  }
-  if (root === null) throw new Error(USAGE);
-  return {root, base};
+    let root = null, base;
+    for (let index = 0; index < argv.length; index += 1) {
+        const value = argv[index];
+        if (value === '--base') {
+            base = argv[++index];
+            if (!base)
+                throw new Error(`--base needs a commit; ${USAGE}`);
+        }
+        else if (value.startsWith('-') || root !== null)
+            throw new Error(`unexpected argument ${value}; ${USAGE}`);
+        else
+            root = value;
+    }
+    if (root === null)
+        throw new Error(USAGE);
+    return { root, base };
 }
-
-function architectureMain(argv, {check = checkArchitecture, write = (text) => process.stdout.write(text), fail = (text) => process.stderr.write(text)} = {}) {
-  let parsed;
-  try { parsed = parseArchitectureArgs(argv); } catch (error) { fail(`${error.message}\n`); return 2; }
-  let report;
-  try { report = check({repositoryRoot: path.resolve(parsed.root), base: parsed.base}); } catch (error) {
-    report = {schema: 'starci/architecture-check@1', ok: false, repository: parsed.root, kinds: [], files: 0, violations: [],
-      errors: [{ruleId: 'ARCH_EXECUTION_UNAVAILABLE', message: String(error?.message ?? error)}]};
-  }
-  write(`${JSON.stringify(report, null, 2)}\n`);
-  return report?.ok === true ? 0 : 1;
+function architectureMain(argv, { check = checkArchitecture, write = (text) => process.stdout.write(text), fail = (text) => process.stderr.write(text) } = {}) {
+    let parsed;
+    try {
+        parsed = parseArchitectureArgs(argv);
+    }
+    catch (error) {
+        fail(`${error.message}\n`);
+        return 2;
+    }
+    let report;
+    try {
+        report = check({ repositoryRoot: path.resolve(parsed.root), base: parsed.base });
+    }
+    catch (error) {
+        report = { schema: 'starci/architecture-check@1', ok: false, repository: parsed.root, kinds: [], files: 0, violations: [],
+            errors: [{ ruleId: 'ARCH_EXECUTION_UNAVAILABLE', message: String(error?.message ?? error) }] };
+    }
+    write(`${JSON.stringify(report, null, 2)}\n`);
+    return report?.ok === true ? 0 : 1;
 }
-
-if (isMain(import.meta.url)) process.exitCode = architectureMain(process.argv.slice(2));
+if (isMain(import.meta.url))
+    process.exitCode = architectureMain(process.argv.slice(2));

package/runtime/scripts/hfs/canon-pins.d.mts

@@ -0,0 +1,26 @@
+/** The runtime-relative file of the bundled pins. */
+export declare const CANON_PINS_FILE = "knowledge/hfs/canon-pins.yaml";
+/** The npm name of the command line that runs @starci/hfs, pinned at its own version. */
+export declare const HARNESS_PACKAGE = "starci-harness";
+/** The pin map of knowledge/hfs/canon-pins.yaml under `root` (the bundled runtime by default). */
+/** One pin row of canon-pins.yaml. */
+export interface CanonPin {
+    version: string;
+    group?: string;
+    install?: string;
+    side?: string;
+    [key: string]: unknown;
+}
+/** The pin map: package name to its pin row. */
+export type CanonPins = Record<string, CanonPin>;
+export declare const bundledPins: (root?: string) => CanonPins;
+/**
+ * The pin map an app answers to: the bundled pins plus the `starci-harness` row at `harness.version`, the version of the CLI that
+ * runs this package; without `harness` the bundled pins alone.
+ */
+export declare function canonPins({ root, harness }?: {
+    root?: string;
+    harness?: {
+        version?: string | undefined;
+    } | undefined;
+}): CanonPins;

package/runtime/scripts/hfs/canon-pins.mjs

@@ -7,21 +7,18 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { skillRoot } from '../../engine/runtime-root.mjs';
 import { parseYaml } from '../../engine/yaml.mjs';
-
 /** The runtime-relative file of the bundled pins. */
 export const CANON_PINS_FILE = 'knowledge/hfs/canon-pins.yaml';
 /** The npm name of the command line that runs @starci/hfs, pinned at its own version. */
 export const HARNESS_PACKAGE = 'starci-harness';
-
-/** The pin map of knowledge/hfs/canon-pins.yaml under `root` (the bundled runtime by default). */
-export const bundledPins = (root = skillRoot) => parseYaml(fs.readFileSync(path.join(root, CANON_PINS_FILE), 'utf8'))?.pins ?? {};
-
+export const bundledPins = (root = skillRoot) => parseYaml(fs.readFileSync(path.join(root, CANON_PINS_FILE), 'utf8'))?.pins ?? {}; // reason: parsed YAML from disk, shaped by canon-pins.yaml
 /**
  * The pin map an app answers to: the bundled pins plus the `starci-harness` row at `harness.version`, the version of the CLI that
  * runs this package; without `harness` the bundled pins alone.
  */
 export function canonPins({ root = skillRoot, harness } = {}) {
-  const pins = bundledPins(root);
-  if (harness?.version === undefined) return pins;
-  return { ...pins, [HARNESS_PACKAGE]: { version: harness.version, group: 'starci', install: 'registry', side: 'both' } };
+    const pins = bundledPins(root);
+    if (harness?.version === undefined)
+        return pins;
+    return { ...pins, [HARNESS_PACKAGE]: { version: harness.version, group: 'starci', install: 'registry', side: 'both' } };
 }

package/runtime/scripts/hfs/catalog-once.d.mts

@@ -0,0 +1,2 @@
+/** The parsed YAML catalog at `file`; the megabyte of text is parsed once per file state (path, size, mtime), not once per check. */
+export declare function readCatalogOnce(file: string): any;

package/runtime/scripts/hfs/catalog-once.mjs

@@ -1,15 +1,14 @@
 import fs from 'node:fs';
 import { parseYaml } from '../../engine/yaml.mjs';
-
+// reason: parsed YAML from disk; its shape is the catalog file's, read by the callers.
 const parsed = new Map();
-
 /** The parsed YAML catalog at `file`; the megabyte of text is parsed once per file state (path, size, mtime), not once per check. */
 export function readCatalogOnce(file) {
-  const { size, mtimeMs } = fs.statSync(file);
-  const key = `${file}|${size}|${mtimeMs}`;
-  if (!parsed.has(key)) {
-    parsed.clear();
-    parsed.set(key, parseYaml(fs.readFileSync(file, 'utf8')));
-  }
-  return parsed.get(key);
+    const { size, mtimeMs } = fs.statSync(file);
+    const key = `${file}|${size}|${mtimeMs}`;
+    if (!parsed.has(key)) {
+        parsed.clear();
+        parsed.set(key, parseYaml(fs.readFileSync(file, 'utf8')));
+    }
+    return parsed.get(key);
 }

package/runtime/scripts/hfs/check-results.d.mts

@@ -0,0 +1,29 @@
+/** Attach the localized catalog explanation to every finding. */
+/** A check finding: a rule code and level, with whatever fields the rule adds. */
+export interface Finding {
+    code: string;
+    level: string;
+    [key: string]: unknown;
+}
+/** The localized catalog explanation of one code. */
+export interface Why {
+    title: string;
+    titleVi: string;
+    whyVi: string;
+    nextStepVi: string;
+}
+/** Findings counted by severity and by code. */
+export interface Summary {
+    error: number;
+    warning: number;
+    info: number;
+    byCode: Record<string, {
+        level: string;
+        count: number;
+    }>;
+}
+export declare function withWhy(findings: Finding[], why: Record<string, Why>): Finding[];
+/** Count findings by severity and code without dropping report-only results. */
+export declare function summarize(findings: Finding[]): Summary;
+/** Keep findings judged in this edition; uncatalogued refusal codes always remain. */
+export declare function judgedFindings(findings: Finding[], edition: string, root: string): Finding[];

package/runtime/scripts/hfs/check-results.mjs

@@ -1,28 +1,24 @@
 // Common result shaping for the slot check and its optional proof reports.
 import { loadRuleCatalog } from './slots.mjs';
-
-/** Attach the localized catalog explanation to every finding. */
 export function withWhy(findings, why) {
-  return findings.map((f) => ({ ...f, title: why[f.code].title, titleVi: why[f.code].titleVi, whyVi: why[f.code].whyVi, nextStepVi: why[f.code].nextStepVi }));
+    return findings.map((f) => ({ ...f, title: why[f.code].title, titleVi: why[f.code].titleVi, whyVi: why[f.code].whyVi, nextStepVi: why[f.code].nextStepVi }));
 }
-
 /** Count findings by severity and code without dropping report-only results. */
 export function summarize(findings) {
-  const byCode = {};
-  for (const f of findings) {
-    byCode[f.code] ??= { level: f.level, count: 0 };
-    byCode[f.code].count += 1;
-  }
-  return {
-    error: findings.filter((f) => f.level === 'error').length,
-    warning: findings.filter((f) => f.level === 'warning').length,
-    info: findings.filter((f) => f.level === 'info').length,
-    byCode,
-  };
+    const byCode = {};
+    for (const f of findings) {
+        byCode[f.code] ??= { level: f.level, count: 0 };
+        byCode[f.code].count += 1;
+    }
+    return {
+        error: findings.filter((f) => f.level === 'error').length,
+        warning: findings.filter((f) => f.level === 'warning').length,
+        info: findings.filter((f) => f.level === 'info').length,
+        byCode,
+    };
 }
-
 /** Keep findings judged in this edition; uncatalogued refusal codes always remain. */
 export function judgedFindings(findings, edition, root) {
-  const catalog = loadRuleCatalog({ root });
-  return findings.filter((finding) => catalog.judgedIn(finding.code, edition));
+    const catalog = loadRuleCatalog({ root });
+    return findings.filter((finding) => catalog.judgedIn(finding.code, edition));
 }