@starci/hfs 4.11.22 → 4.12.0

package/runtime/scripts/hfs/rules/saga-delivery.mjs

@@ -1,66 +1,74 @@
 // Trace the delivery parameter into command constructor arguments, rather than arbitrary reads.
 import { accessName, isConstVariable } from '../../lib/ts-ast.mjs';
 import { sourceValue } from './database-queue-sources.mjs';
-
 function unwrap(ts, node) {
-  const value = sourceValue(ts, node);
-  return value && ts.isNonNullExpression(value) ? unwrap(ts, value.expression) : value;
+    const value = sourceValue(ts, node);
+    return value && ts.isNonNullExpression(value) ? unwrap(ts, value.expression) : value;
 }
-
 function resolve(ts, node, aliases, seen = new Set()) {
-  const value = unwrap(ts, node);
-  if (!value || !ts.isIdentifier(value) || !aliases.has(value.text) || seen.has(value.text)) return value;
-  return resolve(ts, aliases.get(value.text), aliases, new Set(seen).add(value.text));
+    const value = unwrap(ts, node);
+    if (!value || !ts.isIdentifier(value) || !aliases.has(value.text) || seen.has(value.text))
+        return value;
+    return resolve(ts, aliases.get(value.text), aliases, new Set(seen).add(value.text));
 }
-
 function carriesKey(ts, node, delivery, aliases, seen = new Set()) {
-  const value = resolve(ts, node, aliases);
-  if (!value || seen.has(value)) return false;
-  const next = new Set(seen).add(value);
-  if (accessName(ts, value) === 'eventId') {
-    const receiver = resolve(ts, value.expression, aliases);
-    return ts.isIdentifier(receiver) && receiver.text === delivery;
-  }
-  if (ts.isObjectLiteralExpression(value)) return value.properties.some((property) => carriesKey(ts, property, delivery, aliases, next));
-  if (ts.isPropertyAssignment(value)) return carriesKey(ts, value.initializer, delivery, aliases, next);
-  if (ts.isShorthandPropertyAssignment(value)) return carriesKey(ts, value.name, delivery, aliases, next);
-  if (ts.isArrayLiteralExpression(value)) return value.elements.some((element) => carriesKey(ts, element, delivery, aliases, next));
-  return false;
+    const value = resolve(ts, node, aliases);
+    if (!value || seen.has(value))
+        return false;
+    const next = new Set(seen).add(value);
+    if (accessName(ts, value) === 'eventId') {
+        const receiver = resolve(ts, value.expression, aliases);
+        return ts.isIdentifier(receiver) && receiver.text === delivery;
+    }
+    if (ts.isObjectLiteralExpression(value))
+        return value.properties.some((property) => carriesKey(ts, property, delivery, aliases, next));
+    if (ts.isPropertyAssignment(value))
+        return carriesKey(ts, value.initializer, delivery, aliases, next);
+    if (ts.isShorthandPropertyAssignment(value))
+        return carriesKey(ts, value.name, delivery, aliases, next);
+    if (ts.isArrayLiteralExpression(value))
+        return value.elements.some((element) => carriesKey(ts, element, delivery, aliases, next));
+    return false;
 }
-
 function localAliases(ts, method) {
-  const aliases = new Map();
-  for (const statement of method.body?.statements ?? []) {
-    if (!ts.isVariableStatement(statement)) continue;
-    for (const declaration of statement.declarationList.declarations) {
-      if (ts.isIdentifier(declaration.name) && declaration.initializer && isConstVariable(ts, declaration)) aliases.set(declaration.name.text, declaration.initializer);
+    const aliases = new Map();
+    for (const statement of method.body?.statements ?? []) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (ts.isIdentifier(declaration.name) && declaration.initializer && isConstVariable(ts, declaration))
+                aliases.set(declaration.name.text, declaration.initializer);
+        }
     }
-  }
-  return aliases;
+    return aliases;
 }
-
 function methodForwards(ts, method) {
-  const parameter = method.parameters[0]?.name;
-  if (!parameter || !ts.isIdentifier(parameter)) return false;
-  const aliases = localAliases(ts, method);
-  const commands = [];
-  const visit = (node) => {
-    // A read in a nested function does not forward the handler's delivery.
-    if (ts.isFunctionLike(node)) return;
-    if (ts.isCallExpression(node) && accessName(ts, node.expression) === 'execute') commands.push(resolve(ts, node.arguments[0], aliases));
-    ts.forEachChild(node, visit);
-  };
-  if (method.body) visit(method.body);
-  return commands.length > 0 && commands.every((command) => command && ts.isNewExpression(command)
-    && (command.arguments ?? []).some((argument) => carriesKey(ts, argument, parameter.text, aliases)));
+    const parameter = method.parameters[0]?.name;
+    if (!parameter || !ts.isIdentifier(parameter))
+        return false;
+    const aliases = localAliases(ts, method);
+    const commands = [];
+    const visit = (node) => {
+        // A read in a nested function does not forward the handler's delivery.
+        if (ts.isFunctionLike(node))
+            return;
+        if (ts.isCallExpression(node) && accessName(ts, node.expression) === 'execute')
+            commands.push(resolve(ts, node.arguments[0], aliases));
+        ts.forEachChild(node, visit);
+    };
+    if (method.body)
+        visit(method.body);
+    return commands.length > 0 && commands.every((command) => command && ts.isNewExpression(command)
+        && (command.arguments ?? []).some((argument) => carriesKey(ts, argument, parameter.text, aliases)));
 }
-
 export function forwardsDeliveryKey(ts, source) {
-  const handlers = [];
-  const visit = (node) => {
-    if (ts.isMethodDeclaration(node) && node.name.getText(source) === 'handle') handlers.push(node);
-    else ts.forEachChild(node, visit);
-  };
-  visit(source);
-  return handlers.length > 0 && handlers.every((method) => methodForwards(ts, method));
+    const handlers = [];
+    const visit = (node) => {
+        if (ts.isMethodDeclaration(node) && node.name.getText(source) === 'handle')
+            handlers.push(node);
+        else
+            ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return handlers.length > 0 && handlers.every((method) => methodForwards(ts, method));
 }

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

@@ -0,0 +1,7 @@
+import type { Repo } from './rule-types.mjs';
+/** Findings of R169 to R173 over the tracked paths `files` of the app at `repoRoot`. */
+export declare function sagaFindings({ repoRoot, files, repo }: {
+    repoRoot: string;
+    files: string[];
+    repo?: Repo;
+}): import("./rule-types.mjs").Finding[];

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

@@ -21,13 +21,11 @@ import { loadTypescript } from '../../lib/package-at.mjs';
 import { found, readJson, readText } from './read.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
 import { forwardsDeliveryKey } from './saga-delivery.mjs';
-
 const SAGA_STEP_COMPENSATION = 'BE_SAGA_STEP_COMPENSATION';
 const SAGA_STATE_VERSIONED = 'BE_SAGA_STATE_VERSIONED';
 const SAGA_EVENT_CONTRACT = 'BE_SAGA_EVENT_CONTRACT';
 const SAGA_CONSUMER_DEDUPE = 'BE_SAGA_CONSUMER_DEDUPE';
 const SAGA_E2E_MISSING = 'BE_SAGA_E2E_MISSING';
-
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const SAGA_FILE = /^be\/src\/features\/saga\/([^/]+)\/(?:(?:steps|compensations)\/)?[^/]+\.(?:saga\.service|saga-state|saga-step|compensation)\.ts$/;
 const ORCHESTRATOR = /^be\/src\/features\/saga\/([^/]+)\/([^/]+)\.saga\.service\.ts$/;
@@ -40,190 +38,198 @@ const CONTRACT = /^be\/contracts\/[^/]+\/events\.json$/;
 const USE_TEST_WORLD = /\buseTestWorld\s*\(/;
 const INJECTION = /\.(?:during|cut|latency|failNext|interruptDatabase)\s*\(/;
 const STORE_MODULE = /(?:^|\/)platform\/saga$/;
-
 /** The TypeScript compiler of the app (else of the runtime), or null. */
 const typescriptFor = (repoRoot) => loadTypescript(repoRoot, HERE);
-
 const parse = (ts, text) => ts.createSourceFile('saga.ts', text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-
 /** The module specifiers a source file imports or re-exports. */
 function specifiersOf(ts, sourceFile) {
-  const out = [];
-  for (const statement of sourceFile.statements) {
-    if ((ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) && statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)) out.push(statement.moduleSpecifier.text);
-  }
-  return out;
+    const out = [];
+    for (const statement of sourceFile.statements) {
+        if ((ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) && statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier))
+            out.push(statement.moduleSpecifier.text);
+    }
+    return out;
 }
-
 /** The string literal of the class property `event` (`readonly event = "order.placed"`), or null. */
 function eventOf(ts, sourceFile) {
-  let name = null;
-  const visit = (node) => {
-    if (ts.isPropertyDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === 'event' && node.initializer && ts.isStringLiteralLike(node.initializer)) name = node.initializer.text;
-    ts.forEachChild(node, visit);
-  };
-  visit(sourceFile);
-  return name;
+    let name = null;
+    const visit = (node) => {
+        if (ts.isPropertyDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === 'event' && node.initializer && ts.isStringLiteralLike(node.initializer))
+            name = node.initializer.text;
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return name;
 }
-
 /** Whether an exported interface or type alias of the file declares `status` and a `version: number` member. */
 function statesVersion(ts, sourceFile) {
-  let versioned = false;
-  const memberNames = (members) => new Map(members.filter((member) => ts.isPropertySignature(member) && ts.isIdentifier(member.name)).map((member) => [member.name.text, member.type]));
-  for (const statement of sourceFile.statements) {
-    if (!statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue;
-    let members = null;
-    if (ts.isInterfaceDeclaration(statement)) members = statement.members;
-    else if (ts.isTypeAliasDeclaration(statement) && ts.isTypeLiteralNode(statement.type)) members = statement.type.members;
-    if (members === null) continue;
-    const named = memberNames(members);
-    if (named.has('status') && named.get('version')?.kind === ts.SyntaxKind.NumberKeyword) versioned = true;
-  }
-  return versioned;
+    let versioned = false;
+    const memberNames = (members) => new Map(members.filter((member) => ts.isPropertySignature(member) && ts.isIdentifier(member.name)).map((member) => [member.name.text, member.type]));
+    for (const statement of sourceFile.statements) {
+        if (!statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword))
+            continue;
+        let members = null;
+        if (ts.isInterfaceDeclaration(statement))
+            members = statement.members;
+        else if (ts.isTypeAliasDeclaration(statement) && ts.isTypeLiteralNode(statement.type))
+            members = statement.type.members;
+        if (members === null)
+            continue;
+        const named = memberNames(members);
+        if (named.has('status') && named.get('version')?.kind === ts.SyntaxKind.NumberKeyword)
+            versioned = true;
+    }
+    return versioned;
 }
-
 /** The sagas of the app: every folder of the saga kind (`be/src/features/saga/<saga>/`). */
 const featuresOf = (files) => [...new Set(files.map((file) => SAGA_FILE.exec(file)?.[1]).filter((feature) => feature !== undefined))].sort(byCodeUnit);
-
 function filesForFeature(files, pattern, feature) {
-  return files.filter((file) => pattern.test(file) && pattern.exec(file)[1] === feature);
+    return files.filter((file) => pattern.test(file) && pattern.exec(file)[1] === feature);
 }
-
 function featureParts(files, feature) {
-  const steps = new Map(filesForFeature(files, STEP, feature).map((file) => [STEP.exec(file)[2], file]));
-  const compensations = new Map(filesForFeature(files, COMPENSATION, feature).map((file) => [COMPENSATION.exec(file)[2], file]));
-  const orchestrators = filesForFeature(files, ORCHESTRATOR, feature);
-  const states = new Map(filesForFeature(files, STATE, feature).map((file) => [STATE.exec(file)[2], file]));
-  return { steps, compensations, orchestrators, states };
+    const steps = new Map(filesForFeature(files, STEP, feature).map((file) => [STEP.exec(file)[2], file]));
+    const compensations = new Map(filesForFeature(files, COMPENSATION, feature).map((file) => [COMPENSATION.exec(file)[2], file]));
+    const orchestrators = filesForFeature(files, ORCHESTRATOR, feature);
+    const states = new Map(filesForFeature(files, STATE, feature).map((file) => [STATE.exec(file)[2], file]));
+    return { steps, compensations, orchestrators, states };
 }
-
 function stepCompensationFindings(folder, steps, compensations, orchestrators) {
-  const findings = [];
-  for (const [stem, file] of steps) if (!compensations.has(stem)) findings.push(found(SAGA_STEP_COMPENSATION, file, `${file} is a saga step with no compensation: add ${folder}compensations/${stem}.compensation.ts, the command that undoes it; every forward step of a saga has one.`, { step: stem }));
-  for (const [stem, file] of compensations) if (!steps.has(stem)) findings.push(found(SAGA_STEP_COMPENSATION, file, `${file} is a compensation of no step: ${folder}steps/${stem}.saga-step.ts does not exist; a compensation undoes the step of the same name.`, { step: stem }));
-  if (orchestrators.length === 0 && (steps.size > 0 || compensations.size > 0)) findings.push(found(SAGA_STEP_COMPENSATION, folder, `${folder} holds steps or compensations but no orchestrator: add <saga>.saga.service.ts, the list of the steps and their compensations.`));
-  return findings;
+    const findings = [];
+    for (const [stem, file] of steps)
+        if (!compensations.has(stem))
+            findings.push(found(SAGA_STEP_COMPENSATION, file, `${file} is a saga step with no compensation: add ${folder}compensations/${stem}.compensation.ts, the command that undoes it; every forward step of a saga has one.`, { step: stem }));
+    for (const [stem, file] of compensations)
+        if (!steps.has(stem))
+            findings.push(found(SAGA_STEP_COMPENSATION, file, `${file} is a compensation of no step: ${folder}steps/${stem}.saga-step.ts does not exist; a compensation undoes the step of the same name.`, { step: stem }));
+    if (orchestrators.length === 0 && (steps.size > 0 || compensations.size > 0))
+        findings.push(found(SAGA_STEP_COMPENSATION, folder, `${folder} holds steps or compensations but no orchestrator: add <saga>.saga.service.ts, the list of the steps and their compensations.`));
+    return findings;
 }
-
 function orchestratorFindings(ts, repoRoot, orchestrator, folder, steps, compensations, states) {
-  const text = readText(repoRoot, orchestrator);
-  if (text === null) return [];
-  const findings = [];
-  const sourceFile = parse(ts, text);
-  const imported = new Set(specifiersOf(ts, sourceFile).map((specifier) => path.posix.normalize(path.posix.join(path.posix.dirname(orchestrator), specifier))));
-  for (const file of [...steps.values(), ...compensations.values()]) {
-    if (!imported.has(file.replace(/\.ts$/, ''))) findings.push(found(SAGA_STEP_COMPENSATION, orchestrator, `${orchestrator} does not list ${file}: the orchestrator imports every step and every compensation of its saga, so a step nobody runs cannot hide.`, { step: file }));
-  }
-  const stem = ORCHESTRATOR.exec(orchestrator)[2];
-  const stateFile = states.get(stem);
-  if (stateFile === undefined) findings.push(found(SAGA_STATE_VERSIONED, orchestrator, `${orchestrator} has no ${folder}${stem}.saga-state.ts: the persisted state of a run is typed there, with its status and its version fence.`, { saga: stem }));
-  if (!specifiersOf(ts, sourceFile).some((specifier) => STORE_MODULE.test(specifier))) findings.push(found(SAGA_STATE_VERSIONED, orchestrator, `${orchestrator} does not use the fenced store of platform/saga: a run is persisted and moved only through it (every transition names the version it read), never by a write of its own.`, { saga: stem }));
-  return findings;
+    const text = readText(repoRoot, orchestrator);
+    if (text === null)
+        return [];
+    const findings = [];
+    const sourceFile = parse(ts, text);
+    const imported = new Set(specifiersOf(ts, sourceFile).map((specifier) => path.posix.normalize(path.posix.join(path.posix.dirname(orchestrator), specifier))));
+    for (const file of [...steps.values(), ...compensations.values()]) {
+        if (!imported.has(file.replace(/\.ts$/, '')))
+            findings.push(found(SAGA_STEP_COMPENSATION, orchestrator, `${orchestrator} does not list ${file}: the orchestrator imports every step and every compensation of its saga, so a step nobody runs cannot hide.`, { step: file }));
+    }
+    const stem = ORCHESTRATOR.exec(orchestrator)[2];
+    const stateFile = states.get(stem);
+    if (stateFile === undefined)
+        findings.push(found(SAGA_STATE_VERSIONED, orchestrator, `${orchestrator} has no ${folder}${stem}.saga-state.ts: the persisted state of a run is typed there, with its status and its version fence.`, { saga: stem }));
+    if (!specifiersOf(ts, sourceFile).some((specifier) => STORE_MODULE.test(specifier)))
+        findings.push(found(SAGA_STATE_VERSIONED, orchestrator, `${orchestrator} does not use the fenced store of platform/saga: a run is persisted and moved only through it (every transition names the version it read), never by a write of its own.`, { saga: stem }));
+    return findings;
 }
-
 function stateFindings(ts, repoRoot, states) {
-  const findings = [];
-  for (const [stem, file] of states) {
-    const text = readText(repoRoot, file);
-    if (text !== null && !statesVersion(ts, parse(ts, text))) findings.push(found(SAGA_STATE_VERSIONED, file, `${file} exports no state type with a \`status\` and a \`version: number\`; a saga run is persisted with a version, the fence that stops a zombie delivery from moving it twice.`, { saga: stem }));
-  }
-  return findings;
+    const findings = [];
+    for (const [stem, file] of states) {
+        const text = readText(repoRoot, file);
+        if (text !== null && !statesVersion(ts, parse(ts, text)))
+            findings.push(found(SAGA_STATE_VERSIONED, file, `${file} exports no state type with a \`status\` and a \`version: number\`; a saga run is persisted with a version, the fence that stops a zombie delivery from moving it twice.`, { saga: stem }));
+    }
+    return findings;
 }
-
 const STEP_EVENT = { label: 'step', action: 'puts on the wire', key: (stem) => `step:${stem}` };
 const COMPENSATION_EVENT = { label: 'compensation', action: 'answers', key: (stem) => `compensation:${stem}` };
-
 /** Findings for the steps (or compensations) that name no event or an event no vendored contract declares; fills `eventOfFile`. */
 function declaredEventFindings(ts, repoRoot, kind, entries, events, eventOfFile) {
-  const findings = [];
-  for (const [stem, file] of entries) {
-    const text = readText(repoRoot, file);
-    const name = text === null ? null : eventOf(ts, parse(ts, text));
-    eventOfFile.set(kind.key(stem), name);
-    if (name === null) findings.push(found(SAGA_EVENT_CONTRACT, file, `${file} names no event: a ${kind.label} of a saga declares \`readonly event = "<name>"\`, the event of the contract it ${kind.action}.`, { step: stem }));
-    else if (!events.has(name)) findings.push(found(SAGA_EVENT_CONTRACT, file, `${file} names the event "${name}", which no be/contracts/<service>/events.json declares; every event of a saga is in a vendored contract.`, { step: stem, event: name }));
-  }
-  return findings;
+    const findings = [];
+    for (const [stem, file] of entries) {
+        const text = readText(repoRoot, file);
+        const name = text === null ? null : eventOf(ts, parse(ts, text));
+        eventOfFile.set(kind.key(stem), name);
+        if (name === null)
+            findings.push(found(SAGA_EVENT_CONTRACT, file, `${file} names no event: a ${kind.label} of a saga declares \`readonly event = "<name>"\`, the event of the contract it ${kind.action}.`, { step: stem }));
+        else if (!events.has(name))
+            findings.push(found(SAGA_EVENT_CONTRACT, file, `${file} names the event "${name}", which no be/contracts/<service>/events.json declares; every event of a saga is in a vendored contract.`, { step: stem, event: name }));
+    }
+    return findings;
 }
-
 /** Findings for compensation events whose contract does not name the step event it undoes, with the compensation paths found. */
 function compensatesFindings(compensations, events, eventOfFile) {
-  const findings = [];
-  const compensationPaths = [];
-  for (const [stem, file] of compensations) {
-    const compensationEvent = eventOfFile.get(COMPENSATION_EVENT.key(stem));
-    const stepEvent = eventOfFile.get(STEP_EVENT.key(stem));
-    if (compensationEvent && stepEvent && events.has(compensationEvent) && events.get(compensationEvent).compensates !== stepEvent) {
-      findings.push(found(SAGA_EVENT_CONTRACT, file, `${file}: the contract of "${compensationEvent}" (${events.get(compensationEvent).contract}) does not declare \`compensates: "${stepEvent}"\`; the failure event of a compensation says which step's event it undoes.`, { step: stem, event: compensationEvent }));
+    const findings = [];
+    const compensationPaths = [];
+    for (const [stem, file] of compensations) {
+        const compensationEvent = eventOfFile.get(COMPENSATION_EVENT.key(stem));
+        const stepEvent = eventOfFile.get(STEP_EVENT.key(stem));
+        if (compensationEvent && stepEvent && events.has(compensationEvent) && events.get(compensationEvent).compensates !== stepEvent) {
+            findings.push(found(SAGA_EVENT_CONTRACT, file, `${file}: the contract of "${compensationEvent}" (${events.get(compensationEvent).contract}) does not declare \`compensates: "${stepEvent}"\`; the failure event of a compensation says which step's event it undoes.`, { step: stem, event: compensationEvent }));
+        }
+        if (compensationEvent)
+            compensationPaths.push({ file, stem, event: compensationEvent });
     }
-    if (compensationEvent) compensationPaths.push({ file, stem, event: compensationEvent });
-  }
-  return { findings, compensationPaths };
+    return { findings, compensationPaths };
 }
-
 function eventFindings(ts, repoRoot, steps, compensations, events) {
-  const eventOfFile = new Map();
-  const findings = [
-    ...declaredEventFindings(ts, repoRoot, STEP_EVENT, steps, events, eventOfFile),
-    ...declaredEventFindings(ts, repoRoot, COMPENSATION_EVENT, compensations, events, eventOfFile),
-  ];
-  const compensated = compensatesFindings(compensations, events, eventOfFile);
-  findings.push(...compensated.findings);
-  return { findings, compensationPaths: compensated.compensationPaths };
+    const eventOfFile = new Map();
+    const findings = [
+        ...declaredEventFindings(ts, repoRoot, STEP_EVENT, steps, events, eventOfFile),
+        ...declaredEventFindings(ts, repoRoot, COMPENSATION_EVENT, compensations, events, eventOfFile),
+    ];
+    const compensated = compensatesFindings(compensations, events, eventOfFile);
+    findings.push(...compensated.findings);
+    return { findings, compensationPaths: compensated.compensationPaths };
 }
-
 function consumerFindings(ts, repoRoot, feature, files) {
-  const findings = [];
-  for (const file of filesForFeature(files, CONSUMER, feature)) {
-    const text = readText(repoRoot, file);
-    if (text !== null && !forwardsDeliveryKey(ts, parse(ts, text))) findings.push(found(SAGA_CONSUMER_DEDUPE, file, `${file} is a consumer of the saga ${feature} but does not pass the delivery id (\`message.eventId\`) to every dispatched command; the saga takes every event through the inbox, so the consumer hands the id to its command.`, { feature }));
-  }
-  return findings;
+    const findings = [];
+    for (const file of filesForFeature(files, CONSUMER, feature)) {
+        const text = readText(repoRoot, file);
+        if (text !== null && !forwardsDeliveryKey(ts, parse(ts, text)))
+            findings.push(found(SAGA_CONSUMER_DEDUPE, file, `${file} is a consumer of the saga ${feature} but does not pass the delivery id (\`message.eventId\`) to every dispatched command; the saga takes every event through the inbox, so the consumer hands the id to its command.`, { feature }));
+    }
+    return findings;
 }
-
 function featureFindings(ts, repoRoot, files, feature, events) {
-  const { steps, compensations, orchestrators, states } = featureParts(files, feature);
-  const folder = `be/src/features/saga/${feature}/`;
-  const findings = stepCompensationFindings(folder, steps, compensations, orchestrators);
-  for (const orchestrator of orchestrators) findings.push(...orchestratorFindings(ts, repoRoot, orchestrator, folder, steps, compensations, states));
-  findings.push(...stateFindings(ts, repoRoot, states));
-  const eventResult = eventFindings(ts, repoRoot, steps, compensations, events);
-  findings.push(...eventResult.findings, ...consumerFindings(ts, repoRoot, feature, files));
-  return { findings, compensationPaths: eventResult.compensationPaths };
+    const { steps, compensations, orchestrators, states } = featureParts(files, feature);
+    const folder = `be/src/features/saga/${feature}/`;
+    const findings = stepCompensationFindings(folder, steps, compensations, orchestrators);
+    for (const orchestrator of orchestrators)
+        findings.push(...orchestratorFindings(ts, repoRoot, orchestrator, folder, steps, compensations, states));
+    findings.push(...stateFindings(ts, repoRoot, states));
+    const eventResult = eventFindings(ts, repoRoot, steps, compensations, events);
+    findings.push(...eventResult.findings, ...consumerFindings(ts, repoRoot, feature, files));
+    return { findings, compensationPaths: eventResult.compensationPaths };
 }
-
 function compensationE2eFindings(compensationPaths, specs) {
-  const findings = [];
-  for (const { file, stem, event } of compensationPaths) {
-    const named = specs.filter(({ text }) => text.includes(event));
-    const expected = `be/src/tests/e2e/<area>/<name>.e2e-spec.ts`;
-    if (named.length === 0) findings.push(found(SAGA_E2E_MISSING, file, `${file}: the compensation path of "${event}" has no e2e spec; add ${expected}, which boots the apps with useTestWorld, drives the failure and reads the compensated state back.`, { step: stem, event }));
-    else if (!named.some(({ text }) => INJECTION.test(text))) findings.push(found(SAGA_E2E_MISSING, named[0].file, `${named[0].file} names "${event}" but injects no failure; the compensation path is proven with a fault through the world (an outage of an infra service or an app with \`during\`, \`cut\`, \`latency\`, a fake's \`failNext\`, \`interruptDatabase\`), not only the happy flow.`, { step: stem, event }));
-  }
-  return findings;
+    const findings = [];
+    for (const { file, stem, event } of compensationPaths) {
+        const named = specs.filter(({ text }) => text.includes(event));
+        const expected = `be/src/tests/e2e/<area>/<name>.e2e-spec.ts`;
+        if (named.length === 0)
+            findings.push(found(SAGA_E2E_MISSING, file, `${file}: the compensation path of "${event}" has no e2e spec; add ${expected}, which boots the apps with useTestWorld, drives the failure and reads the compensated state back.`, { step: stem, event }));
+        else if (!named.some(({ text }) => INJECTION.test(text)))
+            findings.push(found(SAGA_E2E_MISSING, named[0].file, `${named[0].file} names "${event}" but injects no failure; the compensation path is proven with a fault through the world (an outage of an infra service or an app with \`during\`, \`cut\`, \`latency\`, a fake's \`failNext\`, \`interruptDatabase\`), not only the happy flow.`, { step: stem, event }));
+    }
+    return findings;
 }
-
 /** Findings of R169 to R173 over the tracked paths `files` of the app at `repoRoot`. */
 export function sagaFindings({ repoRoot, files, repo }) {
-  const features = featuresOf(files);
-  if (features.length === 0) return [];
-  const ts = typescriptFor(repoRoot);
-  if (ts === null) return [];
-  const events = new Map();
-  for (const contract of files.filter((file) => CONTRACT.test(file))) {
-    for (const [name, event] of Object.entries(readJson(repoRoot, contract)?.events ?? {})) events.set(name, { contract, ...event });
-  }
-  const findings = [];
-  const compensationPaths = [];
-  for (const feature of features) {
-    const result = featureFindings(ts, repoRoot, files, feature, events);
-    findings.push(...result.findings);
-    compensationPaths.push(...result.compensationPaths);
-  }
-  // R173 is the full-edition test-world proof; lite keeps R169-R172 and proves its scenarios through R284.
-  if (repo?.edition !== 'lite') {
-    const specs = files.filter((file) => E2E_SPEC.test(file)).map((file) => ({ file, text: readText(repoRoot, file) ?? '' })).filter(({ text }) => USE_TEST_WORLD.test(text));
-    findings.push(...compensationE2eFindings(compensationPaths, specs));
-  }
-  return findings;
+    const features = featuresOf(files);
+    if (features.length === 0)
+        return [];
+    const ts = typescriptFor(repoRoot);
+    if (ts === null)
+        return [];
+    const events = new Map();
+    for (const contract of files.filter((file) => CONTRACT.test(file))) {
+        for (const [name, event] of Object.entries(readJson(repoRoot, contract)?.events ?? {}))
+            events.set(name, { contract, ...event });
+    }
+    const findings = [];
+    const compensationPaths = [];
+    for (const feature of features) {
+        const result = featureFindings(ts, repoRoot, files, feature, events);
+        findings.push(...result.findings);
+        compensationPaths.push(...result.compensationPaths);
+    }
+    // R173 is the full-edition test-world proof; lite keeps R169-R172 and proves its scenarios through R284.
+    if (repo?.edition !== 'lite') {
+        const specs = files.filter((file) => E2E_SPEC.test(file)).map((file) => ({ file, text: readText(repoRoot, file) ?? '' })).filter(({ text }) => USE_TEST_WORLD.test(text));
+        findings.push(...compensationE2eFindings(compensationPaths, specs));
+    }
+    return findings;
 }

package/runtime/scripts/hfs/rules/script-hygiene.d.mts

@@ -0,0 +1,11 @@
+import type { Repo, Resolver } from './rule-types.mjs';
+/** Both editions share this custody boundary; the app root scans `all` once, including its sides. */
+export declare function scriptHygieneFindings({ repoRoot, files, all, repo, isRoot, inScope }: {
+    repoRoot: string;
+    files?: string[];
+    all?: string[];
+    repo: Repo;
+    resolver?: Resolver;
+    isRoot: boolean;
+    inScope?: (file: string) => boolean;
+}): import("./rule-types.mjs").Finding[];