@starci/hfs 4.0.7 → 4.0.9

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

@@ -0,0 +1,170 @@
+// saga.mjs - the saga pattern of a product that declares `patterns: ["saga"]` in hfs.json (R169 to R173). A saga is a feature of the saga kind
+//   be/src/features/saga/<saga>/
+//     <saga>.saga.service.ts              the orchestrator: the list of its steps and compensations (a service, unit-tested beside it)
+//     <saga>.saga-state.ts                the persisted state of a run, typed with its `status` and its `version` fence
+//     steps/<step>.saga-step.ts                one step, dispatching one command, naming the event it puts on the wire
+//     compensations/<step>.compensation.ts  the compensation of that step, naming the failure event that triggers it
+//   be/src/features/saga/<saga>/transport/message/<event>.consumer.ts   the consumers that advance it, through the inbox
+//   be/contracts/<service>/events.json   every event, a compensating one declaring `compensates: "<step event>"`
+// Five tree checks (the slot manifest owns the paths: an undeclared saga folder is HFS_SLOT_NOT_ENABLED):
+//   R169 BE_SAGA_STEP_COMPENSATION  every step has a compensation of the same name and the other way round, and the orchestrator imports them all;
+//   R170 BE_SAGA_STATE_VERSIONED    every orchestrator has its `.saga-state.ts` whose exported state type carries `status` and a numeric `version`,
+//                                   and imports the fenced store of `platform/saga`;
+//   R171 BE_SAGA_EVENT_CONTRACT     a step and a compensation each name their event (`readonly event = "<name>"`), both are in a contract, and the
+//                                   contract of the compensation's event says it compensates the step's event;
+//   R172 BE_SAGA_CONSUMER_DEDUPE    a consumer of a saga feature passes the id of the delivery (`message.eventId`) on to the command, so the inbox can dedupe it;
+//   R173 BE_SAGA_E2E_MISSING        every compensation path has an e2e spec through the world that names its event and injects a failure
+//                                   (an outage of an infra service, an app or a fake: `during`, `cut`, `latency`, `failNext`, `interruptDatabase`).
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../../lib/package-at.mjs';
+import { found, readJson, readText } from './read.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$/;
+const STATE = /^be\/src\/features\/saga\/([^/]+)\/([^/]+)\.saga-state\.ts$/;
+const STEP = /^be\/src\/features\/saga\/([^/]+)\/steps\/([^/]+)\.saga-step\.ts$/;
+const COMPENSATION = /^be\/src\/features\/saga\/([^/]+)\/compensations\/([^/]+)\.compensation\.ts$/;
+const CONSUMER = /^be\/src\/features\/saga\/([^/]+)\/transport\/message\/[^/]+\.consumer\.ts$/;
+const E2E_SPEC = /^be\/src\/tests\/e2e\/[^/]+\/[^/]+\.e2e-spec\.ts$/;
+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;
+}
+
+/** 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;
+}
+
+/** 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;
+    const members = ts.isInterfaceDeclaration(statement) ? statement.members : ts.isTypeAliasDeclaration(statement) && ts.isTypeLiteralNode(statement.type) ? statement.type.members : null;
+    if (members === null) continue;
+    const named = memberNames(members);
+    if (named.has('status') && named.get('version')?.kind === ts.SyntaxKind.NumberKeyword) versioned = true;
+  }
+  return versioned;
+}
+
+/** Whether a source text reads `.eventId` of something (the id of the delivery travels on). */
+function readsEventId(ts, sourceFile) {
+  let read = false;
+  const visit = (node) => {
+    if (ts.isPropertyAccessExpression(node) && node.name.text === 'eventId') read = true;
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return read;
+}
+
+/** 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();
+
+/** Findings of R169 to R173 over the tracked paths `files` of the app at `repoRoot`. */
+export function sagaFindings({ repoRoot, files }) {
+  const features = featuresOf(files);
+  if (features.length === 0) return [];
+  const ts = typescriptFor(repoRoot);
+  if (ts === null) return [];
+  const findings = [];
+  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 specs = files.filter((file) => E2E_SPEC.test(file)).map((file) => ({ file, text: readText(repoRoot, file) ?? '' })).filter(({ text }) => USE_TEST_WORLD.test(text));
+  const compensationPaths = [];
+  for (const feature of features) {
+    const under = (pattern) => files.filter((file) => pattern.test(file) && pattern.exec(file)[1] === feature);
+    const steps = new Map(under(STEP).map((file) => [STEP.exec(file)[2], file]));
+    const compensations = new Map(under(COMPENSATION).map((file) => [COMPENSATION.exec(file)[2], file]));
+    const orchestrators = under(ORCHESTRATOR);
+    const states = new Map(under(STATE).map((file) => [STATE.exec(file)[2], file]));
+    const folder = `be/src/features/saga/${feature}/`;
+    // R169
+    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.`));
+    for (const orchestrator of orchestrators) {
+      const text = readText(repoRoot, orchestrator);
+      if (text === null) continue;
+      const sourceFile = parse(ts, text);
+      const imported = 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.includes(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 }));
+      }
+      // R170
+      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 }));
+    }
+    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 }));
+    }
+    // R171
+    const eventOfFile = new Map();
+    for (const [kind, map] of [['step', steps], ['compensation', compensations]]) {
+      for (const [stem, file] of map) {
+        const text = readText(repoRoot, file);
+        const name = text === null ? null : eventOf(ts, parse(ts, text));
+        eventOfFile.set(`${kind}:${stem}`, name);
+        if (name === null) findings.push(found(SAGA_EVENT_CONTRACT, file, `${file} names no event: a ${kind} of a saga declares \`readonly event = "<name>"\`, the event of the contract it ${kind === 'step' ? 'puts on the wire' : 'answers'}.`, { 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 }));
+      }
+    }
+    for (const [stem, file] of compensations) {
+      const compensationEvent = eventOfFile.get(`compensation:${stem}`);
+      const stepEvent = eventOfFile.get(`step:${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 });
+    }
+    // R172
+    for (const file of under(CONSUMER)) {
+      const text = readText(repoRoot, file);
+      if (text !== null && !readsEventId(ts, parse(ts, text))) findings.push(found(SAGA_CONSUMER_DEDUPE, file, `${file} is a consumer of the saga ${feature} but never passes the id of the delivery on (\`message.eventId\`); the saga takes every event through the inbox, so the consumer hands the id to its command.`, { feature }));
+    }
+  }
+  // R173
+  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;
+}

package/runtime/scripts/{lib/hfs-rules → hfs/rules}/secrets.mjs

@@ -5,11 +5,11 @@
 //   - a tracked `.enc` that is not a sops envelope (an encrypted-looking file that holds plaintext);
 //   - a line of any other tracked text file that matches a secret pattern.
 // A finding names the file, the line and the pattern, never the value.
-import { FORBIDDEN_FILES, secretHits } from '../secret-patterns.mjs';
-import { isSopsEnvelope } from '../test-secrets.mjs';
+import { FORBIDDEN_FILES, secretHits } from '../../lib/secret-patterns.mjs';
+import { isSopsEnvelope } from '../../lib/sops-envelope.mjs';
 import { found, readText } from './read.mjs';
 
-export const PLAINTEXT_SECRET = 'HFS_PLAINTEXT_SECRET';
+const PLAINTEXT_SECRET = 'HFS_PLAINTEXT_SECRET';
 /** Files whose lines are not secrets: a lockfile carries integrity hashes, never a credential. */
 const NOT_SCANNED = /(^|\/)package-lock\.json$/;
 
@@ -19,7 +19,7 @@ export const slotOwnsSecrets = (slot) => slot?.rules?.includes(PLAINTEXT_SECRET)
 /**
  * The findings of R06 for one tracked file that no forbidden slot claims: a secret by being (an env file, a key file), an `.enc` that is
  * no sops envelope, or a line that matches a secret pattern. `text` is the file's text, or null when it cannot be read (binary, too
- * large, absent). The whole-tree check reads the work tree and the commit hook (`hfs work-hygiene`) reads the staged blob: one judgement.
+ * large, absent). The whole-tree check reads the work tree and the commit hook (`starci app hygiene`) reads the staged blob: one judgement.
  */
 export function secretFileFindings({ file, text }) {
   const being = FORBIDDEN_FILES.find((rule) => rule.test(file));

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

@@ -0,0 +1,220 @@
+// services.mjs - the microservice policy of a product that runs more than one service (R163 to R167).
+// A product keeps every back-end service as a Nest app at `be/apps/<service>/` of the one repository, sharing the `be/src` libraries and
+// the one package.json; the services it does not own stay pinned images in the stack. Five tree checks:
+//   R163 HFS_SERVICE_PLACEMENT      a service root (a Dockerfile, or a package.json other than the app's own and a workspace package's)
+//                                   exists only at be/apps/<service>/ (fe/apps/<app>/Dockerfile is a front end's);
+//   R164 HFS_IMAGE_UNPINNED         in a multi-service product every component image of application-stacks.yaml is a digest or an exact
+//                                   version (x.y.z), never a missing tag, `latest`, a branch word or a major/minor-only tag;
+//   R165 HFS_SERVICE_STACK_DECLARATION  each api or worker app of a multi-service product is a `role: service` component of the stack;
+//   R166 HFS_EVENT_CONTRACT         the async contract is vendored: `be/contracts/<service>/events.json` equals the provider's
+//                                   `apps/<service>/src/events.ts` table (an event may declare `compensates: "<event>"`), every event a
+//                                   consumer's `apps/<app>/src/consumes.ts` names exists in that snapshot at the same version;
+//   R167 BE_ASYNC_SPEC_MISSING      every consumed event (a consumes.ts entry) is named by an e2e spec through `useTestWorld`; the spec of a
+//                                   saga step (an event whose contract says `compensates`) also names the compensated event, so the whole
+//                                   flow is driven, not the undo alone.
+// "Multi-service" = two or more be apps of kind api or worker. A single-service product is judged by R163 and R166-R167 only.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findStackDeclaration } from '../../lib/stack-declaration.mjs';
+import { loadTypescript } from '../../lib/package-at.mjs';
+import { propertyText } from '../../lib/ts-ast.mjs';
+import { folded, readEventClasses, snapshotText } from '../../lib/event-contract.mjs';
+import { found, readText } from './read.mjs';
+
+const SERVICE_PLACEMENT = 'HFS_SERVICE_PLACEMENT';
+const IMAGE_UNPINNED = 'HFS_IMAGE_UNPINNED';
+const SERVICE_STACK_DECLARATION = 'HFS_SERVICE_STACK_DECLARATION';
+const EVENT_CONTRACT = 'HFS_EVENT_CONTRACT';
+const ASYNC_SPEC_MISSING = 'BE_ASYNC_SPEC_MISSING';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SERVICE_KINDS = new Set(['api', 'worker']);
+const BE_SERVICE_FILE = /^be\/apps\/([^/]+)\/(.+)$/;
+const DOCKERFILE = /(?:^|\/)Dockerfile(?:\.[^/]+)?$/;
+const WORKSPACE_PACKAGE_JSON = /^fe\/(?:packages|apps)\/[^/]+\/package\.json$/;
+const SNAPSHOT = /^be\/contracts\/([^/]+)\/events\.json$/;
+const DIGEST = /@sha256:[0-9a-f]{64}$/;
+const EXACT_TAG = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+const EVENT_CLASS_FILE = /^be\/src\/modules\/events\/([^/]+)\/[^/]+\.event\.ts$/;
+const CONSUMER_FILE = /^be\/src\/features\/(?:[^/]+\/)+transport\/message\/[^/]+\.consumer\.ts$/;
+const E2E_SPEC = /^be\/src\/tests\/e2e\/[^/]+\/[^/]+\.e2e-spec\.ts$/;
+const USE_TEST_WORLD = /\buseTestWorld\s*\(/;
+
+/** The be apps of kind api or worker. */
+const servicesOf = (repo) => (repo.sides?.be?.apps ?? []).filter((app) => SERVICE_KINDS.has(app.kind));
+
+/** The TypeScript compiler of the app (else of the runtime), or null. */
+const typescriptFor = (repoRoot) => loadTypescript(repoRoot, HERE);
+
+// ------------------------------------------------------------------------------------------------ R163 placement
+
+/** Findings of R163: a service root outside `be/apps/<service>/`. */
+function servicePlacementFindings({ files }) {
+  const findings = [];
+  for (const file of files) {
+    if (file.startsWith('.starciwork/') || file.startsWith('.starcistacks/') || file.includes('node_modules/')) continue;
+    const dockerfile = DOCKERFILE.test(file) && !BE_SERVICE_FILE.test(file) && !/^fe\/apps\/[^/]+\/Dockerfile(?:\.[^/]+)?$/.test(file) && file !== 'Dockerfile';
+    const manifest = path.posix.basename(file) === 'package.json' && file !== 'package.json' && !WORKSPACE_PACKAGE_JSON.test(file);
+    const rootDockerfile = file === 'Dockerfile';
+    if (!dockerfile && !manifest && !rootDockerfile) continue;
+    const what = manifest ? 'a package.json of its own' : 'a Dockerfile';
+    findings.push(found(SERVICE_PLACEMENT, file, `${file} gives a folder ${what}, which makes it a service root outside be/apps/<service>/; a back-end service is a Nest app at be/apps/<service>/ (own Dockerfile there) sharing the be/src libraries and the one package.json, never a folder of its own.`));
+  }
+  return findings;
+}
+
+// ------------------------------------------------------------------------------------------------ R164 pinned images
+
+/** The image reference with `${VAR:-default}` resolved to its default, or null when it cannot be (a bare `${VAR}`). */
+function resolvedImage(image) {
+  let unresolved = false;
+  const resolved = image.replace(/\$\{[^}:]+(?::-([^}]*))?\}/g, (_all, fallback) => { if (fallback === undefined) unresolved = true; return fallback ?? ''; });
+  return unresolved ? null : resolved;
+}
+
+/** Why an image is not pinned, or null when it is: a digest, or an exact version tag. */
+function unpinnedReason(image) {
+  const resolved = resolvedImage(image);
+  if (resolved === null) return 'its reference is an environment variable with no default';
+  if (DIGEST.test(resolved)) return null;
+  const name = resolved.slice(resolved.lastIndexOf('/') + 1);
+  const colon = name.indexOf(':');
+  if (colon < 0) return 'it has no tag';
+  const tag = name.slice(colon + 1);
+  return EXACT_TAG.test(tag) ? null : `its tag \`${tag}\` is not an exact version (x.y.z) or a digest, so it moves`;
+}
+
+/** Findings of R164 over a multi-service product's stack declaration. */
+function imagePinFindings({ repoRoot, repo }) {
+  if (servicesOf(repo).length < 2) return [];
+  const declaration = findStackDeclaration(repoRoot);
+  const components = declaration.doc?.components;
+  if (components === null || typeof components !== 'object' || components === undefined) return [];
+  const file = '.starcistacks/application-stacks.yaml';
+  const findings = [];
+  for (const [name, component] of Object.entries(components)) {
+    const image = component?.image;
+    if (typeof image !== 'string') continue;
+    const reason = unpinnedReason(image);
+    if (reason !== null) findings.push(found(IMAGE_UNPINNED, file, `${file} components.${name}.image ${image}: ${reason}. A product with more than one service pins every image: an exact version (\`<repo>/<service>:1.2.3\`, \`postgres:16.4\`) or a digest (\`@sha256:...\`).`, { component: name, image }));
+  }
+  return findings;
+}
+
+// ------------------------------------------------------------------------------------------------ R165 stack declaration
+
+/** Findings of R165: each service app of a multi-service product is a `role: service` component. */
+function serviceStackFindings({ repoRoot, repo }) {
+  const services = servicesOf(repo);
+  if (services.length < 2) return [];
+  const declaration = findStackDeclaration(repoRoot);
+  if (declaration.doc === undefined) return [];
+  const components = declaration.doc.components ?? {};
+  const file = '.starcistacks/application-stacks.yaml';
+  const findings = [];
+  for (const app of services) {
+    const component = components[app.name];
+    if (component === null || typeof component !== 'object') findings.push(found(SERVICE_STACK_DECLARATION, file, `${file} declares no component \`${app.name}\` for the ${app.kind} app be/apps/${app.name}; every service of a multi-service product is a \`role: service\` component (own image \`<repo>/${app.name}:<exact version>\`, built from be/apps/${app.name}/Dockerfile).`, { app: app.name }));
+    else if (component.role !== 'service') findings.push(found(SERVICE_STACK_DECLARATION, file, `${file} components.${app.name} is the stack's face of be/apps/${app.name} and must be \`role: service\`, not \`${String(component.role)}\`.`, { app: app.name }));
+  }
+  return findings;
+}
+
+// ------------------------------------------------------------------------------------------------ R166 event contract
+
+/** The typed event classes of every service: `[{ service, file, className, name, version, compensates, payload }]` and the problems of the ones that cannot be read. */
+function eventClassesOf({ repoRoot, files, ts }) {
+  const classes = [];
+  const problems = [];
+  for (const file of files.filter((candidate) => EVENT_CLASS_FILE.test(candidate)).sort()) {
+    const service = EVENT_CLASS_FILE.exec(file)[1];
+    const read = readEventClasses(ts, readText(repoRoot, file) ?? '', file);
+    for (const event of read.events) classes.push({ service, file, ...event });
+    for (const problem of read.problems) problems.push({ service, file, problem });
+  }
+  return { classes, problems };
+}
+
+/** Findings of R166: each service's event classes are the one source of its vendored `events.json`, and a compensating event names a declared event. */
+function eventContractFindings({ repoRoot, files }) {
+  const classFiles = files.filter((file) => EVENT_CLASS_FILE.test(file));
+  const snapshots = files.filter((file) => SNAPSHOT.test(file));
+  if (classFiles.length === 0 && snapshots.length === 0) return [];
+  const ts = typescriptFor(repoRoot);
+  if (ts === null) return [];
+  const tracked = new Set(files);
+  const { classes, problems } = eventClassesOf({ repoRoot, files, ts });
+  const findings = problems.map(({ service, file, problem }) => found(EVENT_CONTRACT, file, `${file} is not an event class the contract can be emitted from: ${problem}.`, { service }));
+  const services = [...new Set(classes.map((event) => event.service))].sort();
+  const declared = new Set(classes.map((event) => event.name));
+  for (const service of services) {
+    const snapshot = `be/contracts/${service}/events.json`;
+    const events = classes.filter((event) => event.service === service);
+    if (!tracked.has(snapshot)) findings.push(found(EVENT_CONTRACT, snapshot, `${service} declares event classes (be/src/modules/events/${service}/) but ${snapshot} is not committed; run \`npm run contract:emit\` and commit the snapshot, the contract its consumers rely on.`, { service }));
+    else if (folded(readText(repoRoot, snapshot) ?? '') !== snapshotText(service, events)) findings.push(found(EVENT_CONTRACT, snapshot, `${snapshot} differs from what the event classes of ${service} emit now; run \`npm run contract:emit\` and commit the result.`, { service, drift: 'stale' }));
+  }
+  for (const snapshot of snapshots) {
+    const service = SNAPSHOT.exec(snapshot)[1];
+    if (!services.includes(service) && !problems.some((entry) => entry.service === service)) findings.push(found(EVENT_CONTRACT, snapshot, `${snapshot} is committed but be/src/modules/events/${service}/ declares no event class; delete the snapshot or restore the classes.`, { service, drift: 'left-behind' }));
+  }
+  for (const event of classes) {
+    if (event.compensates !== undefined && !declared.has(event.compensates)) findings.push(found(EVENT_CONTRACT, event.file, `${event.file}: event "${event.name}" compensates "${event.compensates}", which no event class declares; name the event whose step it undoes.`, { service: event.service, event: event.name }));
+  }
+  return findings;
+}
+
+// ------------------------------------------------------------------------------------------------ R167 async specs
+
+/** The class an expression names, from `readonly event = <Class>` of a consumer: the identifier, or null. */
+function consumedClassOf(ts, text) {
+  return propertyText(ts, text, { file: 'consumer.ts', key: 'event', declaration: true, kind: 'identifier' });
+}
+
+/** The events the consumers consume: `[{ file, className, service, event }]` from `readonly event = <EventClass>` of every `transport/message/*.consumer.ts`. */
+function consumedEvents({ repoRoot, files, ts }) {
+  const { classes } = eventClassesOf({ repoRoot, files, ts });
+  const consumed = [];
+  for (const file of files.filter((candidate) => CONSUMER_FILE.test(candidate))) {
+    const className = consumedClassOf(ts, readText(repoRoot, file) ?? '');
+    const event = classes.find((candidate) => candidate.className === className);
+    if (event !== undefined) consumed.push({ file, className, service: event.service, event: event.name, compensates: event.compensates });
+  }
+  return consumed;
+}
+
+/** Findings of R167: every consumed event has an e2e spec through the world; a saga step's spec also names the event it compensates. */
+function asyncSpecFindings({ repoRoot, files }) {
+  const ts = typescriptFor(repoRoot);
+  if (ts === null) return [];
+  const consumed = consumedEvents({ repoRoot, files, ts });
+  if (consumed.length === 0) return [];
+  const specs = files
+    .filter((file) => E2E_SPEC.test(file))
+    .map((file) => ({ file, text: readText(repoRoot, file) ?? '' }))
+    .filter(({ text }) => USE_TEST_WORLD.test(text));
+  const findings = [];
+  for (const { file, className, service, event, compensates } of consumed) {
+    const named = specs.filter(({ text }) => text.includes(event));
+    if (named.length === 0) {
+      findings.push(found(ASYNC_SPEC_MISSING, file, `${file}: the consumer of ${service} event "${event}" (${className}) has no e2e spec; add be/src/tests/e2e/<area>/<name>.e2e-spec.ts, which boots the apps with useTestWorld and names it: publish the event, read the persisted effect back and redeliver it.`, { service, event }));
+      continue;
+    }
+    if (typeof compensates === 'string' && !named.some(({ text }) => text.includes(compensates))) {
+      findings.push(found(ASYNC_SPEC_MISSING, named[0].file, `${named[0].file} is the spec of the saga step "${event}", which undoes "${compensates}", but never names it; the spec drives the whole flow: the step, the failure, then the compensated state.`, { service, event, compensates }));
+    }
+  }
+  return findings;
+}
+
+// ------------------------------------------------------------------------------------------------ entry
+
+/** Every finding of the microservice policy over the app at `repoRoot`; `files` are its tracked app-relative paths. */
+export function serviceFindings({ repoRoot, files, repo }) {
+  return [
+    ...servicePlacementFindings({ files }),
+    ...imagePinFindings({ repoRoot, repo }),
+    ...serviceStackFindings({ repoRoot, repo }),
+    ...eventContractFindings({ repoRoot, files }),
+    ...asyncSpecFindings({ repoRoot, files }),
+  ];
+}

package/runtime/scripts/{lib/hfs-rules → hfs/rules}/spec-placement.mjs

@@ -7,7 +7,7 @@
 // finding names the rule rather than only the missing slot. Which folder is a layer is read from the slot manifest, never spelled here.
 import { found } from './read.mjs';
 
-export const SPEC_PLACEMENT = 'BE_SPEC_PLACEMENT';
+const SPEC_PLACEMENT = 'BE_SPEC_PLACEMENT';
 const SPEC_FILE = /(?:\.(?:spec|test)|-spec)\.[cm]?[jt]sx?$/;
 const TEST_SLOT_TESTS = new Set(['unit-beside', 'e2e']);
 

package/runtime/scripts/{lib/hfs-rules → hfs/rules}/stacks.mjs

@@ -6,13 +6,13 @@
 //   - the declaration (read by scripts/lib/stack-declaration.mjs, the one reader of it) states a sonar service, a local
 //     Sonar is owned by the host (`stack.owner: host`, root `.claude/ext/sonar`), and no service still points at `.stacks`.
 // The declaration's services contract (custody, CI wiring, project keys) stays check-starcistacks's; this file judges shape only.
-import { braceVariants, globExpression } from '../glob.mjs';
-import { declaredStack, findStackDeclaration, STACK_ROOT, text } from '../stack-declaration.mjs';
+import { braceVariants, globExpression } from '../../lib/glob.mjs';
+import { declaredStack, findStackDeclaration, STACK_ROOT, text } from '../../lib/stack-declaration.mjs';
 import { found } from './read.mjs';
 
-export const STACKS_SHAPE = 'HFS_STACKS_SHAPE';
-export const STACKS_SLOT = 'app.starcistacks';
-export const HOST_SONAR_ROOT = '.claude/ext/sonar';
+const STACKS_SHAPE = 'HFS_STACKS_SHAPE';
+const STACKS_SLOT = 'app.starcistacks';
+const HOST_SONAR_ROOT = '.claude/ext/sonar';
 const SEALED = /\.enc$/;
 const INSIDE_SECRETS = /^[^/]+\/secrets\/[^/]+\.enc$/;
 const RETIRED_ROOT = /^\.?stacks(?:\/|$)/;

package/runtime/scripts/hfs/rules/supabase-secrets.mjs

@@ -0,0 +1,89 @@
+// supabase-secrets.mjs - L17 extends the one R06 secret scan for edition lite. It keeps the ordinary
+// HFS_PLAINTEXT_SECRET judgement, then adds the reduced lite custody tree and provider-shaped literals
+// which are meaningful only in the Supabase/FE surface. Findings name shapes, never captured values.
+import { Buffer } from 'node:buffer';
+import { secretFindings } from './secrets.mjs';
+import { found, readText } from './read.mjs';
+
+const LITE_SECRET_CUSTODY = 'HFS_LITE_SECRET_CUSTODY';
+
+const LOCKFILE = /(^|\/)package-lock\.json$/u;
+const ROOT_ENV = /^\.env(?:\..*)?$/iu;
+const SECRETS_ENV = /^secrets\.env$/iu;
+const SECRETS_DIRECTORY = /^\.secrets(?:\/|$)/iu;
+const SEALED_HOME = /^\.starcistacks\/[^/]+\/secrets\/[^/]+\.enc$/iu;
+
+const LITE_SECRET_PATTERNS = Object.freeze([
+  { name: 'supabase-personal-access-token', re: /\bsbp_[A-Za-z0-9_-]{20,}\b/u },
+  { name: 'supabase-publishable-key', re: /\bsb_publishable_[A-Za-z0-9_-]{20,}\b/u },
+  { name: 'supabase-secret-token', re: /\bsb_secret_[A-Za-z0-9_-]{20,}\b/u },
+  { name: 'password-connection-string', re: /\b(?:postgres(?:ql)?|mysql|mariadb|mongodb(?:\+srv)?|redis):\/\/[^:\s/@]+:[^@\s/${}]{8,}@/iu },
+]);
+const JWT_CANDIDATE = /(?<![A-Za-z0-9_-])eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}(?![A-Za-z0-9_-])/gu;
+
+const jsonObject = segment => {
+  try {
+    const value = JSON.parse(Buffer.from(segment, 'base64url').toString('utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+};
+
+const validJwt = candidate => {
+  const [header, payload, signature, extra] = candidate.split('.');
+  if (extra !== undefined || !signature) return false;
+  const decodedHeader = jsonObject(header);
+  const decodedPayload = jsonObject(payload);
+  return typeof decodedHeader?.alg === 'string' && decodedHeader.alg.toLowerCase() !== 'none' && decodedPayload !== null;
+};
+
+const liteSecretPatterns = line => {
+  const names = LITE_SECRET_PATTERNS.filter(pattern => pattern.re.test(line)).map(pattern => pattern.name);
+  if ([...line.matchAll(JWT_CANDIDATE)].some(match => validJwt(match[0]))) names.push('supabase-eyj-service-token');
+  return names;
+};
+
+const inSecretFreeTree = (repo, file) => repo.profile === 'fe' || file.startsWith('fe/') || file.startsWith('supabase/');
+
+/** Raw L17 findings. The catalog-driven findings filter decides which editions judge them. */
+export function liteSecretCustodyFindings({ repoRoot, files, repo }) {
+  const findings = [];
+  for (const file of files) {
+    if (repo.profile === 'app') {
+      if (ROOT_ENV.test(file) || SECRETS_ENV.test(file) || SECRETS_DIRECTORY.test(file)) {
+        findings.push(found(LITE_SECRET_CUSTODY, file, `${file} is forbidden at the lite app root; lite keeps no .env*, secrets.env or .secrets/ custody path.`, { pattern: 'lite-forbidden-entry' }));
+        continue;
+      }
+      if (file.endsWith('.enc') && !SEALED_HOME.test(file)) {
+        findings.push(found(LITE_SECRET_CUSTODY, file, `${file} is a sealed file outside .starcistacks/<env>/secrets/; lite has exactly one encrypted custody path.`, { pattern: 'sealed-file-home' }));
+      }
+    } else if (file.endsWith('.enc')) {
+      findings.push(found(LITE_SECRET_CUSTODY, file, `${file} is a sealed file inside a side tree; lite keeps *.enc only at the app root under .starcistacks/<env>/secrets/.`, { pattern: 'sealed-file-home' }));
+    }
+    if (!inSecretFreeTree(repo, file) || LOCKFILE.test(file)) continue;
+    const text = readText(repoRoot, file);
+    if (text === null) continue;
+    const seen = new Set();
+    const lines = text.split(/\r?\n/u);
+    for (let index = 0; index < lines.length; index += 1) {
+      for (const pattern of liteSecretPatterns(lines[index])) {
+        if (seen.has(pattern)) continue;
+        seen.add(pattern);
+        findings.push(found(LITE_SECRET_CUSTODY, file, `${file}:${index + 1} holds a provider-shaped secret (${pattern}); lite keeps no secret literal under fe/ or supabase/.`, { line: index + 1, pattern }));
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * Drop-in extension of secretFindings for scripts/hfs/check.mjs. When an L17 finding identifies the same file/line as
+ * the generic R06 scanner (a complete JWT, for example), the specific lite code wins so one physical issue is emitted once.
+ */
+export function supabaseSecretFindings(input) {
+  const ordinary = secretFindings(input);
+  const lite = liteSecretCustodyFindings(input);
+  const liteJwtAuthority = (input.repo.edition ?? 'full') === 'lite';
+  return [...ordinary.filter(item => !(liteJwtAuthority && item.pattern === 'jwt' && inSecretFreeTree(input.repo, item.path))), ...lite];
+}

package/runtime/scripts/{lib/hfs-rules → hfs/rules}/test-topology.mjs

@@ -4,11 +4,11 @@
 //   - one `jest.config.js` at the root: a second jest config (`jest.config.<x>.js`, `jest.<x>.config.*`, one per app) and a
 //     `jest` key in a package.json are refused.
 // `int-spec`, `harness-spec`, the retired test folders and the per-lane configs under src/tests are the architecture machine's
-// (HFS_TEST_KIND_RETIRED, a sub-code of this rule); that jest.config.js is the rendered one (projects `unit`, `integration`, `e2e` and
+// (reported under this same code, BE_TEST_TOPOLOGY); that jest.config.js is the rendered one (projects `unit`, `integration`, `e2e` and
 // `contract`, diagnostics off) is the managed-file check's (HFS_MANAGED_FILE_DRIFT); a spec whose suffix disagrees with its src/tests folder has no slot (HFS_SLOT_UNDECLARED).
 import { found, readJson } from './read.mjs';
 
-export const TEST_TOPOLOGY = 'BE_TEST_TOPOLOGY';
+const TEST_TOPOLOGY = 'BE_TEST_TOPOLOGY';
 const DOT_TEST = /\.test\.[cm]?[jt]sx?$/;
 const JEST_CONFIG = /(?:^|\/)jest(?:\.[^/]+)*\.config(?:\.[^/]+)*\.(?:[cm]?[jt]s|json)$|(?:^|\/)jest\.config\.[^/]+$/;
 const ROOT_JEST_CONFIG = 'jest.config.js';