@starci/hfs 4.11.22 → 4.12.0

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

@@ -24,13 +24,11 @@ import { folded, readEventClasses, snapshotText } from '../../lib/event-contract
 import { found, readText } from './read.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
 import { eventTableFindings, eventTableServices } from './event-tables.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\/([^/]+)\/(.+)$/;
@@ -43,70 +41,71 @@ 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;
+    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;
+    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`;
+    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;
+    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
-
 /**
  * The component names that stand for `app`: the app's own name, then every `environments.<env>.deploy.images` key whose `app` is
  * the app (the one tie between component and app the declaration states, read by scripts/hfs/stack-deploy-config.mjs). A product
@@ -114,139 +113,140 @@ function imagePinFindings({ repoRoot, repo }) {
  * service and put the short app alias on a shared network (R294).
  */
 function componentNamesOf(doc, app) {
-  return [...new Set([app, ...deployImageApps(doc).filter((tie) => tie.app === app).map((tie) => tie.service)])];
+    return [...new Set([app, ...deployImageApps(doc).filter((tie) => tie.app === app).map((tie) => tie.service)])];
 }
-
 /** Findings of R165: each service app of a multi-service product is a `role: service` component, named after it or mapped to it by deploy.images. */
 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 names = componentNamesOf(declaration.doc, app.name);
-    const declared = names.filter((name) => components[name] !== null && typeof components[name] === 'object');
-    if (declared.some((name) => components[name].role === 'service')) continue;
-    if (!declared.length) findings.push(found(SERVICE_STACK_DECLARATION, file, `${file} declares no component for the ${app.kind} app be/apps/${app.name}: none named \`${app.name}\` and none mapped to it by \`environments.<env>.deploy.images.<component>.app: ${app.name}\`; every service of a multi-service product is a \`role: service\` component (own image at an exact version, built from be/apps/${app.name}/Dockerfile).`, { app: app.name }));
-    else findings.push(found(SERVICE_STACK_DECLARATION, file, `${file} ${declared.map((name) => 'components.' + name).join(', ')} is the stack's face of be/apps/${app.name} and must be \`role: service\`, not \`${String(components[declared[0]].role)}\`.`, { app: app.name, components: declared }));
-  }
-  return findings;
+    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 names = componentNamesOf(declaration.doc, app.name);
+        const declared = names.filter((name) => components[name] !== null && typeof components[name] === 'object');
+        if (declared.some((name) => components[name].role === 'service'))
+            continue;
+        if (!declared.length)
+            findings.push(found(SERVICE_STACK_DECLARATION, file, `${file} declares no component for the ${app.kind} app be/apps/${app.name}: none named \`${app.name}\` and none mapped to it by \`environments.<env>.deploy.images.<component>.app: ${app.name}\`; every service of a multi-service product is a \`role: service\` component (own image at an exact version, built from be/apps/${app.name}/Dockerfile).`, { app: app.name }));
+        else
+            findings.push(found(SERVICE_STACK_DECLARATION, file, `${file} ${declared.map((name) => 'components.' + name).join(', ')} is the stack's face of be/apps/${app.name} and must be \`role: service\`, not \`${String(components[declared[0]].role)}\`.`, { app: app.name, components: declared }));
+    }
+    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(byCodeUnit)) {
-    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 };
+    const classes = [];
+    const problems = [];
+    for (const file of files.filter((candidate) => EVENT_CLASS_FILE.test(candidate)).sort(byCodeUnit)) {
+        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 for each service whose vendored `events.json` is missing or differs from what its event classes emit. */
 function snapshotDriftFindings(repoRoot, tracked, services, classes) {
-  const findings = [];
-  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' }));
-  }
-  return findings;
+    const findings = [];
+    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' }));
+    }
+    return findings;
 }
-
 /** Findings for committed snapshots of a service that declares no event class. */
 function leftBehindSnapshotFindings(snapshots, services, problems) {
-  const findings = [];
-  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' }));
-  }
-  return findings;
+    const findings = [];
+    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' }));
+    }
+    return findings;
 }
-
 /** Findings for compensating events that name an event no class declares. */
 function undeclaredCompensationFindings(classes, declared) {
-  return classes
-    .filter((event) => event.compensates !== undefined && !declared.has(event.compensates))
-    .map((event) => 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 classes
+        .filter((event) => event.compensates !== undefined && !declared.has(event.compensates))
+        .map((event) => 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 }));
 }
-
 /** Findings of R166: event classes and literal tables match their snapshots, consumers agree, and compensation targets exist. */
 function eventContractFindings({ repoRoot, files }) {
-  const snapshots = files.filter((file) => SNAPSHOT.test(file));
-  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(byCodeUnit);
-  const declared = new Set(classes.map((event) => event.name));
-  const providers = [...services, ...eventTableServices(files)];
-  findings.push(...snapshotDriftFindings(repoRoot, tracked, services, classes), ...leftBehindSnapshotFindings(snapshots, providers, problems), ...undeclaredCompensationFindings(classes, declared), ...eventTableFindings({ ts, repoRoot, files }));
-  return findings;
+    const snapshots = files.filter((file) => SNAPSHOT.test(file));
+    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(byCodeUnit);
+    const declared = new Set(classes.map((event) => event.name));
+    const providers = [...services, ...eventTableServices(files)];
+    findings.push(...snapshotDriftFindings(repoRoot, tracked, services, classes), ...leftBehindSnapshotFindings(snapshots, providers, problems), ...undeclaredCompensationFindings(classes, declared), ...eventTableFindings({ ts, repoRoot, files }));
+    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' });
+    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;
+    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 }));
+    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;
+    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 }),
-  ];
+    return [
+        ...servicePlacementFindings({ files }),
+        ...imagePinFindings({ repoRoot, repo }),
+        ...serviceStackFindings({ repoRoot, repo }),
+        ...eventContractFindings({ repoRoot, files }),
+        ...asyncSpecFindings({ repoRoot, files }),
+    ];
 }

package/runtime/scripts/hfs/rules/spec-placement.d.mts

@@ -0,0 +1,8 @@
+import type { Resolver } from './rule-types.mjs';
+/** True for a file name that is a spec or a test. */
+export declare const isSpecFile: (file: string) => boolean;
+/** The findings of R102 over the tracked paths `files` of a back-end repository; `resolver` names the slots. */
+export declare function specPlacementFindings({ files, resolver }: {
+    files: string[];
+    resolver: Resolver;
+}): import("./rule-types.mjs").Finding[];

package/runtime/scripts/hfs/rules/spec-placement.mjs

@@ -6,24 +6,23 @@
 // carries no spec, and a spec that guards one moves into a layer or goes. A file no slot owns (`tools/x.spec.ts`) is judged too, so the
 // 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';
-
 const SPEC_PLACEMENT = 'BE_SPEC_PLACEMENT';
 const SPEC_FILE = /(?:\.(?:spec|test)|-spec)\.[cm]?[jt]sx?$/;
 const TEST_SLOT_TESTS = new Set(['unit-beside', 'e2e']);
-
 /** True for a file name that is a spec or a test. */
 export const isSpecFile = (file) => SPEC_FILE.test(file);
-
 /** The findings of R102 over the tracked paths `files` of a back-end repository; `resolver` names the slots. */
 export function specPlacementFindings({ files, resolver }) {
-  const findings = [];
-  for (const file of files) {
-    if (!isSpecFile(file) || file.includes('node_modules/')) continue;
-    const classified = resolver.classifyPath(file);
-    const slot = classified.status === 'owned' ? resolver.slot(classified.slot) : null;
-    if (slot && TEST_SLOT_TESTS.has(slot.tests)) continue;
-    const where = slot ? `slot ${slot.id}` : 'no slot';
-    findings.push(found(SPEC_PLACEMENT, file, `${file} is a spec outside the test layers (${where}); a unit spec is <name>.service.spec.ts beside its service and an integration, e2e or contract spec sits under src/tests/{integration,e2e,contract}; an operational script or a tool carries no spec`));
-  }
-  return findings;
+    const findings = [];
+    for (const file of files) {
+        if (!isSpecFile(file) || file.includes('node_modules/'))
+            continue;
+        const classified = resolver.classifyPath(file);
+        const slot = classified.status === 'owned' ? resolver.slot(classified.slot) : null;
+        if (slot && TEST_SLOT_TESTS.has(slot.tests))
+            continue;
+        const where = slot ? `slot ${slot.id}` : 'no slot';
+        findings.push(found(SPEC_PLACEMENT, file, `${file} is a spec outside the test layers (${where}); a unit spec is <name>.service.spec.ts beside its service and an integration, e2e or contract spec sits under src/tests/{integration,e2e,contract}; an operational script or a tool carries no spec`));
+    }
+    return findings;
 }

package/runtime/scripts/hfs/rules/stack-tooling.d.mts

@@ -0,0 +1,11 @@
+import type { Repo } from './rule-types.mjs';
+export declare const STACK_TOOLING_REIMPLEMENTED = "STACK_TOOLING_REIMPLEMENTED";
+/** Findings are names and paths only: no source snippet leaves this finder. One finding per file and replacing verb. */
+export declare function stackToolingFindings({ repoRoot, files, all, repo, isRoot, inScope }: {
+    repoRoot: string;
+    files: string[];
+    all?: string[] | undefined;
+    repo?: Repo | undefined;
+    isRoot?: boolean | undefined;
+    inScope?: ((file: string) => boolean) | undefined;
+}): any[];

package/runtime/scripts/hfs/rules/stack-tooling.mjs

@@ -3,9 +3,7 @@
 // stack-deploy.yml) must not call a docker command a verb owns, and deploy/ holds no file named after a verb. A finding names the
 // replacing verb and the file, never a snippet of the source.
 import { found, readText } from './read.mjs';
-
 export const STACK_TOOLING_REIMPLEMENTED = 'STACK_TOOLING_REIMPLEMENTED';
-
 const MANAGED_WORKFLOW = /(?:^|\/)\.github\/workflows\/stack-deploy\.ya?ml$/;
 const WORKFLOW = /(?:^|\/)\.github\/workflows\/[^/]+\.ya?ml$/;
 const DEPLOY_DIR = /(?:^|\/)deploy\//;
@@ -21,76 +19,71 @@ const VERB_FILE = /^(render|provision|converge|verify|prune|rollback|release|bac
 const COMMENT_LINE = /^[ \t]*(?:#|\/\/).*$/gm;
 const LINE_CONTINUATION = /\\\r?\n\s*/g;
 const VERB_COMMAND = /\bapp\s+stack\b[^\n;&|]*/g;
-const DOCKER_OPTIONS = String.raw`(?:\s+(?:--(?:context|host)(?:\s+|=)\S+|-H\s+\S+))*`;
-const SHELL_CALL = new RegExp(String.raw`\bdocker${DOCKER_OPTIONS}\s+(stack|secret|config|service|swarm|volume|node)\s+([a-z]+)\b`, 'g');
+const DOCKER_OPTIONS = String.raw `(?:\s+(?:--(?:context|host)(?:\s+|=)\S+|-H\s+\S+))*`;
+const SHELL_CALL = new RegExp(String.raw `\bdocker${DOCKER_OPTIONS}\s+(stack|secret|config|service|swarm|volume|node)\s+([a-z]+)\b`, 'g');
 const ARGV_CALL = /['"]docker['"]\s*,\s*\[\s*['"](stack|secret|config|service|swarm|volume|node)['"]\s*,\s*['"]([a-z]+)['"]/g;
-
 /** `docker <noun> <action>` pairs the canon owns, mapped to the verb that replaces them. */
 const OWNED = new Map([
-  ['stack deploy', 'deploy'], ['stack config', 'render'],
-  ['secret create', 'deploy'], ['secret rm', 'prune'], ['config create', 'deploy'], ['config rm', 'prune'],
-  ['service ls', 'converge'], ['service ps', 'converge'], ['service inspect', 'verify'], ['service update', 'rollback'],
-  ['swarm init', 'prepare'], ['volume create', 'prepare'], ['node ls', 'doctor'],
+    ['stack deploy', 'deploy'], ['stack config', 'render'],
+    ['secret create', 'deploy'], ['secret rm', 'prune'], ['config create', 'deploy'], ['config rm', 'prune'],
+    ['service ls', 'converge'], ['service ps', 'converge'], ['service inspect', 'verify'], ['service update', 'rollback'],
+    ['swarm init', 'prepare'], ['volume create', 'prepare'], ['node ls', 'prepare'],
 ]);
-
 /** Comments run nothing; a `starci app stack ...` command line is the canon call itself and is never judged. */
 function executableText(text) {
-  return text.replaceAll(COMMENT_LINE, '').replaceAll(LINE_CONTINUATION, ' ').replaceAll(VERB_COMMAND, ' ');
+    return text.replaceAll(COMMENT_LINE, '').replaceAll(LINE_CONTINUATION, ' ').replaceAll(VERB_COMMAND, ' ');
 }
-
 function ownedVerbs(text) {
-  const verbs = new Set();
-  for (const pattern of [SHELL_CALL, ARGV_CALL]) {
-    for (const [, noun, action] of text.matchAll(pattern)) {
-      const verb = OWNED.get(`${noun} ${action}`);
-      if (verb) verbs.add(verb);
+    const verbs = new Set();
+    for (const pattern of [SHELL_CALL, ARGV_CALL]) {
+        for (const [, noun, action] of text.matchAll(pattern)) {
+            const verb = OWNED.get(`${noun} ${action}`);
+            if (verb)
+                verbs.add(verb);
+        }
     }
-  }
-  return verbs;
+    return verbs;
 }
-
 function packageScripts(text) {
-  try {
-    return Object.values(JSON.parse(text)?.scripts ?? {}).filter((command) => typeof command === 'string').join('\n');
-  } catch { return ''; }
+    try {
+        return Object.values(JSON.parse(text)?.scripts ?? {}).filter((command) => typeof command === 'string').join('\n');
+    }
+    catch {
+        return '';
+    }
 }
-
 function sourceText(file, raw) {
-  return executableText(PACKAGE_JSON.test(file) ? packageScripts(raw) : raw);
+    return executableText(PACKAGE_JSON.test(file) ? packageScripts(raw) : raw);
 }
-
 function deploySource(file) {
-  if (MANAGED_WORKFLOW.test(file) || isCredentialFile(file) || TEST_FILE.test(file)) return false;
-  if (PACKAGE_JSON.test(file) || WORKFLOW.test(file)) return true;
-  return (DEPLOY_DIR.test(file) || SCRIPTS_DIR.test(file)) && SOURCE_FILE.test(file);
+    if (MANAGED_WORKFLOW.test(file) || isCredentialFile(file) || TEST_FILE.test(file))
+        return false;
+    if (PACKAGE_JSON.test(file) || WORKFLOW.test(file))
+        return true;
+    return (DEPLOY_DIR.test(file) || SCRIPTS_DIR.test(file)) && SOURCE_FILE.test(file);
 }
-
-const replacement = (file, verb) => found(
-  STACK_TOOLING_REIMPLEMENTED,
-  file,
-  `${file} re-implements deploy tooling the canon ships; call \`starci app stack ${verb}\` instead`,
-  { verb },
-);
-
+const replacement = (file, verb) => found(STACK_TOOLING_REIMPLEMENTED, file, `${file} re-implements deploy tooling the canon ships; call \`starci app stack ${verb}\` instead`, { verb });
 function fileFindings(repoRoot, file) {
-  const raw = readText(repoRoot, file);
-  if (raw === null) return [];
-  return [...ownedVerbs(sourceText(file, raw))].map((verb) => replacement(file, verb));
+    const raw = readText(repoRoot, file);
+    if (raw === null)
+        return [];
+    return [...ownedVerbs(sourceText(file, raw))].map((verb) => replacement(file, verb));
 }
-
 function verbNamedFile(file) {
-  const verb = DEPLOY_DIR.test(file) ? VERB_FILE.exec(file.slice(file.lastIndexOf('/') + 1))?.[1] : undefined;
-  return verb ? [replacement(file, verb)] : [];
+    const verb = DEPLOY_DIR.test(file) ? VERB_FILE.exec(file.slice(file.lastIndexOf('/') + 1))?.[1] : undefined;
+    return verb ? [replacement(file, verb)] : [];
 }
-
 /** Findings are names and paths only: no source snippet leaves this finder. One finding per file and replacing verb. */
 export function stackToolingFindings({ repoRoot, files, all, repo, isRoot, inScope = () => true }) {
-  if (repo?.kind !== 'app' || !['lite', 'full'].includes(repo.edition) || isRoot === false) return [];
-  const findings = new Map();
-  for (const file of new Set(all ?? files)) {
-    if (!inScope(file)) continue;
-    const candidates = [...verbNamedFile(file), ...(deploySource(file) ? fileFindings(repoRoot, file) : [])];
-    for (const finding of candidates) findings.set(`${finding.path}\0${finding.verb}`, finding);
-  }
-  return [...findings.values()];
+    if (repo?.kind !== 'app' || !['lite', 'full'].some((value) => value === repo.edition) || isRoot === false)
+        return [];
+    const findings = new Map();
+    for (const file of new Set(all ?? files)) {
+        if (!inScope(file))
+            continue;
+        const candidates = [...verbNamedFile(file), ...(deploySource(file) ? fileFindings(repoRoot, file) : [])];
+        for (const finding of candidates)
+            findings.set(`${finding.path}\0${finding.verb}`, finding);
+    }
+    return [...findings.values()];
 }

package/runtime/scripts/hfs/rules/stacks-auth-cookie-domain.d.mts

@@ -0,0 +1,30 @@
+import type { Parsed } from './rule-types.mjs';
+export declare const HFS_AUTH_COOKIE_DOMAIN_MISSING = "HFS_AUTH_COOKIE_DOMAIN_MISSING";
+export declare const AUTH_COOKIE_DOMAIN = "AUTH_COOKIE_DOMAIN";
+interface Issue {
+    code: string;
+    at: string;
+    message: string;
+}
+/** The public hosts the environment declares for its web and its api; undefined when the stack does not state one. */
+export declare function publicHosts({ model, spec }: {
+    model: unknown;
+    spec: unknown;
+}): {
+    web?: string;
+    api?: string;
+};
+/** The longest shared host suffix of at least two labels that is not a second-level public suffix, or undefined. */
+export declare function commonParentDomain(left: string, right: string): string | undefined;
+/** The R337 issues of one rendered environment. `passport` says whether the api uses the skeleton's passport. */
+export declare function authCookieDomainIssues(input: {
+    environment: string;
+    spec: unknown;
+    model: unknown;
+    files: string[];
+    repoRoot?: string;
+    passport: boolean;
+}): Issue[];
+/** HFS finder over the tracked rendered Swarm environments of the lite app root whose api uses the skeleton's passport. */
+export declare function stacksAuthCookieDomainFindings(context: Parsed): import("./rule-types.mjs").Finding[];
+export {};