@starci/hfs 4.11.22 → 4.12.0

package/runtime/scripts/hfs/rules/ci-standard.mjs

@@ -3,7 +3,7 @@
 //   job-shape              the managed ci.yml holds exactly the edition's jobs; the unit run is in `test`, the proof and the Codecov upload in `coverage` (the one OIDC job)
 //   full-history-base-ref  every actions/checkout fetches the full history; a job that lints writes STARCI_BASE_REF before it lints
 //   heap-per-step          every heavy step (heap.steps) declares NODE_OPTIONS --max-old-space-size >= heap.minMiB on the step
-//   sonar-lint-per-side    a lint with --sonar names --side
+//   sonar-lint-per-side    a lint with --out names --side
 //   required-providers      no continue-on-error; Codecov fail_ci_if_error true; no availability probe, no secret-gated Codecov or Sonar step
 //   test-sharding          the test job is a shard matrix; each shard runs --shard=i/N with STARCI_COVERAGE_SHARD and no threshold or pass-empty flag; the coverage job merges, then proves
 //   lint-parallel          the lint job is a matrix over side [be, fe]
@@ -19,198 +19,205 @@ import { found } from './read.mjs';
 import { appWorkflowFindings } from './app-workflow-findings.mjs';
 import { isPlainObject as record } from '../../../engine/plain-object.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
-
 export const CI_STANDARD = 'CI_STANDARD';
 const STANDARD_FILE = new URL('../../../knowledge/hfs/ci-standard.yaml', import.meta.url);
 const APP_CI = '.github/workflows/ci.yml';
 const SHA_PIN = /@[0-9a-f]{40}$/;
 const DIGEST_PIN = /@sha256:[0-9a-f]{64}$/;
-
 let cached = null;
 /** The standard (knowledge/hfs/ci-standard.yaml), read once. */
 /** The coverage proof step: the coverage judgement over the merged lcov (`starci app coverage verify`), never the whole app check. */
 const COVERAGE_PROOF = /app coverage verify\b/;
-
 function ciStandard() {
-  if (!cached) {
-    const doc = parseYaml(fs.readFileSync(STANDARD_FILE, 'utf8'));
-    if (doc?.schema !== 'starci/ci-standard@1' || !Array.isArray(doc.items)) throw new Error('knowledge/hfs/ci-standard.yaml is not a starci/ci-standard@1 standard');
-    cached = doc;
-  }
-  return cached;
+    if (!cached) {
+        const doc = parseYaml(fs.readFileSync(STANDARD_FILE, 'utf8'));
+        if (doc?.schema !== 'starci/ci-standard@1' || !Array.isArray(doc.items))
+            throw new Error('knowledge/hfs/ci-standard.yaml is not a starci/ci-standard@1 standard');
+        cached = doc;
+    }
+    return cached;
 }
-
 const jobsOf = (doc) => (record(doc?.jobs) ? Object.entries(doc.jobs).filter(([, job]) => record(job)) : []);
 const stepsOf = (job) => (Array.isArray(job.steps) ? job.steps.filter(record) : []);
 const usesOf = (step) => String(step.uses ?? '').trim();
 const runOf = (step) => (typeof step.run === 'string' ? step.run : '');
-
 /** The items of the standard this file checks for `scope`: their ids. */
 const checkedItems = (standard, scope) => new Set(standard.items.filter((item) => item.check === 'ci-standard' && item.covers.includes(scope)).map((item) => item.id));
-
 function jobShape(doc, edition, standard, say) {
-  const shape = standard.jobs[edition] ?? standard.jobs.full;
-  const ids = jobsOf(doc).map(([id]) => id);
-  const out = [];
-  const missing = shape.required.filter((id) => !ids.includes(id));
-  const extra = ids.filter((id) => !shape.required.includes(id) && !shape.optional.includes(id));
-  const gaps = [missing.length ? 'missing ' + missing.join(', ') : '', extra.length ? 'not in the standard ' + extra.join(', ') : ''].filter(Boolean).join('; ');
-  if (gaps) out.push(say('job-shape', `the jobs must be ${shape.required.join(', ')} (optional ${shape.optional.join(', ')}); ${gaps}`));
-  const withStep = (match) => jobsOf(doc).filter(([, job]) => stepsOf(job).some((step) => match(step))).map(([id]) => id);
-  const unit = withStep((step) => step.name === 'unit');
-  const upload = withStep((step) => usesOf(step).startsWith('codecov/codecov-action@'));
-  const proof = withStep((step) => COVERAGE_PROOF.test(runOf(step)));
-  if (unit.join() !== 'test') out.push(say('job-shape', `the unit run must be a step of the test job alone, not of ${unit.join(', ') || 'no job'}`));
-  if (proof.join() !== 'coverage') out.push(say('job-shape', `the coverage proof must be a step of the coverage job alone, not of ${proof.join(', ') || 'no job'}`));
-  if (upload.length && upload.join() !== 'coverage') out.push(say('job-shape', `the Codecov upload must be a step of the coverage job alone, not of ${upload.join(', ')}`));
-  const oidc = jobsOf(doc).filter(([, job]) => job.permissions?.['id-token'] === 'write').map(([id]) => id);
-  if (upload.length && oidc.join() !== 'coverage') out.push(say('job-shape', `only the coverage job holds the OIDC id-token (id-token: write), not ${oidc.join(', ') || 'no job'}`));
-  return out;
+    const shape = standard.jobs[edition] ?? standard.jobs.full;
+    const ids = jobsOf(doc).map(([id]) => id);
+    const out = [];
+    const missing = shape.required.filter((id) => !ids.includes(id));
+    const extra = ids.filter((id) => !shape.required.includes(id) && !shape.optional.includes(id));
+    const gaps = [missing.length ? 'missing ' + missing.join(', ') : '', extra.length ? 'not in the standard ' + extra.join(', ') : ''].filter(Boolean).join('; ');
+    if (gaps)
+        out.push(say('job-shape', `the jobs must be ${shape.required.join(', ')} (optional ${shape.optional.join(', ')}); ${gaps}`));
+    const withStep = (match) => jobsOf(doc).filter(([, job]) => stepsOf(job).some((step) => match(step))).map(([id]) => id);
+    const unit = withStep((step) => step.name === 'unit');
+    const upload = withStep((step) => usesOf(step).startsWith('codecov/codecov-action@'));
+    const proof = withStep((step) => COVERAGE_PROOF.test(runOf(step)));
+    if (unit.join() !== 'test')
+        out.push(say('job-shape', `the unit run must be a step of the test job alone, not of ${unit.join(', ') || 'no job'}`));
+    if (proof.join() !== 'coverage')
+        out.push(say('job-shape', `the coverage proof must be a step of the coverage job alone, not of ${proof.join(', ') || 'no job'}`));
+    if (upload.length && upload.join() !== 'coverage')
+        out.push(say('job-shape', `the Codecov upload must be a step of the coverage job alone, not of ${upload.join(', ')}`));
+    const oidc = jobsOf(doc).filter(([, job]) => job.permissions?.['id-token'] === 'write').map(([id]) => id);
+    if (upload.length && oidc.join() !== 'coverage')
+        out.push(say('job-shape', `only the coverage job holds the OIDC id-token (id-token: write), not ${oidc.join(', ') || 'no job'}`));
+    return out;
 }
-
 function testSharding(doc, say) {
-  const test = record(doc.jobs?.test) ? doc.jobs.test : null;
-  if (!test) return [];
-  const out = [];
-  const shards = test.strategy?.matrix?.shard;
-  if (!Array.isArray(shards) || !shards.length) out.push(say('test-sharding', 'the test job must be a matrix over shard (ci.jobs.test.shards)'));
-  const unit = stepsOf(test).find((step) => step.name === 'unit');
-  const total = /--shard=\$\{\{\s*matrix\.shard\s*\}\}\/(\d+)/.exec(unit ? runOf(unit) : '');
-  if (unit && !total) out.push(say('test-sharding', 'the unit run must pass --shard=${{ matrix.shard }}/<N>'));
-  if (total && Array.isArray(shards) && Number(total[1]) !== shards.length) out.push(say('test-sharding', `the unit run's shard total ${total[1]} must equal the ${shards.length} matrix shards`));
-  if (unit && String(unit.env?.STARCI_COVERAGE_SHARD ?? '') !== '1') out.push(say('test-sharding', 'a shard runs the unit step with STARCI_COVERAGE_SHARD: "1": it measures only the files it loads and writes the istanbul JSON the coverage job merges'));
-  if (unit && /--passWithNoTests|--coverageThreshold/.test(runOf(unit))) out.push(say('test-sharding', 'a shard passes neither --passWithNoTests nor --coverageThreshold: the preset owns shard mode (no per-file threshold; the coverage job proves it on the merged report) and the shard count never exceeds what the unit specs fill'));
-  const coverage = record(doc.jobs?.coverage) ? stepsOf(doc.jobs.coverage) : [];
-  const merge = coverage.findIndex((step) => /app coverage merge\b/.test(runOf(step)));
-  const proof = coverage.findIndex((step) => COVERAGE_PROOF.test(runOf(step)));
-  if (merge < 0 || (proof >= 0 && merge > proof)) out.push(say('test-sharding', 'the coverage job must merge the shard reports (starci app coverage merge) before the coverage proof'));
-  return out;
+    const test = record(doc.jobs?.test) ? doc.jobs.test : null;
+    if (!test)
+        return [];
+    const out = [];
+    const shards = test.strategy?.matrix?.shard;
+    if (!Array.isArray(shards) || !shards.length)
+        out.push(say('test-sharding', 'the test job must be a matrix over shard (ci.jobs.test.shards)'));
+    const unit = stepsOf(test).find((step) => step.name === 'unit');
+    const total = /--shard=\$\{\{\s*matrix\.shard\s*\}\}\/(\d+)/.exec(unit ? runOf(unit) : '');
+    if (unit && !total)
+        out.push(say('test-sharding', 'the unit run must pass --shard=${{ matrix.shard }}/<N>'));
+    if (total && Array.isArray(shards) && Number(total[1]) !== shards.length)
+        out.push(say('test-sharding', `the unit run's shard total ${total[1]} must equal the ${shards.length} matrix shards`));
+    if (unit && String(unit.env?.STARCI_COVERAGE_SHARD ?? '') !== '1')
+        out.push(say('test-sharding', 'a shard runs the unit step with STARCI_COVERAGE_SHARD: "1": it measures only the files it loads and writes the istanbul JSON the coverage job merges'));
+    if (unit && /--passWithNoTests|--coverageThreshold/.test(runOf(unit)))
+        out.push(say('test-sharding', 'a shard passes neither --passWithNoTests nor --coverageThreshold: the preset owns shard mode (no per-file threshold; the coverage job proves it on the merged report) and the shard count never exceeds what the unit specs fill'));
+    const coverage = record(doc.jobs?.coverage) ? stepsOf(doc.jobs.coverage) : [];
+    const merge = coverage.findIndex((step) => /app coverage merge\b/.test(runOf(step)));
+    const proof = coverage.findIndex((step) => COVERAGE_PROOF.test(runOf(step)));
+    if (merge < 0 || (proof >= 0 && merge > proof))
+        out.push(say('test-sharding', 'the coverage job must merge the shard reports (starci app coverage merge) before the coverage proof'));
+    return out;
 }
-
 function lintParallel(doc, say) {
-  const sides = record(doc.jobs?.lint) ? doc.jobs.lint.strategy?.matrix?.side : null;
-  return Array.isArray(sides) && sides.map(String).sort(byCodeUnit).join() === 'be,fe' ? [] : [say('lint-parallel', 'the lint job must be a matrix over side [be, fe]')];
+    const sides = record(doc.jobs?.lint) ? doc.jobs.lint.strategy?.matrix?.side : null;
+    return Array.isArray(sides) && sides.map(String).sort(byCodeUnit).join() === 'be,fe' ? [] : [say('lint-parallel', 'the lint job must be a matrix over side [be, fe]')];
 }
-
 function cacheSavedAlways(doc, say) {
-  const out = [];
-  for (const [id, job] of jobsOf(doc)) {
-    for (const step of stepsOf(job)) {
-      const uses = usesOf(step);
-      if (/^actions\/cache(?:\/restore)?@/.test(uses) && String(step.with?.key ?? '').includes('github.sha')) out.push(say('cache-saved-always', `job ${id}: a cache keyed by the commit sha never warms; key it by the lockfile hash (and the run) with restore-keys`));
-      if (uses.startsWith('actions/cache/save@') && !/^(?:\$\{\{\s*)?always\(\)/.test(String(step.if ?? '').trim())) out.push(say('cache-saved-always', `job ${id}: actions/cache/save runs under if: always(), so a red run still warms the cache`));
+    const out = [];
+    for (const [id, job] of jobsOf(doc)) {
+        for (const step of stepsOf(job)) {
+            const uses = usesOf(step);
+            if (/^actions\/cache(?:\/restore)?@/.test(uses) && String(step.with?.key ?? '').includes('github.sha'))
+                out.push(say('cache-saved-always', `job ${id}: a cache keyed by the commit sha never warms; key it by the lockfile hash (and the run) with restore-keys`));
+            if (uses.startsWith('actions/cache/save@') && !/^(?:\$\{\{\s*)?always\(\)/.test(String(step.if ?? '').trim()))
+                out.push(say('cache-saved-always', `job ${id}: actions/cache/save runs under if: always(), so a red run still warms the cache`));
+        }
     }
-  }
-  return out;
+    return out;
 }
-
 function fullHistory(doc, say) {
-  const out = [];
-  for (const [id, job] of jobsOf(doc)) {
-    for (const step of stepsOf(job)) {
-      if (usesOf(step).startsWith('actions/checkout@') && String(step.with?.['fetch-depth']) !== '0') out.push(say('full-history-base-ref', `job ${id}: actions/checkout must fetch the full history (fetch-depth: 0)`));
+    const out = [];
+    for (const [id, job] of jobsOf(doc)) {
+        for (const step of stepsOf(job)) {
+            if (usesOf(step).startsWith('actions/checkout@') && String(step.with?.['fetch-depth']) !== '0')
+                out.push(say('full-history-base-ref', `job ${id}: actions/checkout must fetch the full history (fetch-depth: 0)`));
+        }
+    }
+    for (const [id, job] of jobsOf(doc)) {
+        const steps = stepsOf(job);
+        const base = steps.findIndex((step) => /STARCI_BASE_REF=.*>>\s*"?\$GITHUB_ENV"?/.test(runOf(step)));
+        const lint = steps.findIndex((step) => /\bnpm run lint\b|\bstarci app lint\b/.test(runOf(step)));
+        if (lint >= 0 && (base < 0 || base > lint))
+            out.push(say('full-history-base-ref', `job ${id} must write STARCI_BASE_REF to GITHUB_ENV before its first lint step`));
     }
-  }
-  for (const [id, job] of jobsOf(doc)) {
-    const steps = stepsOf(job);
-    const base = steps.findIndex((step) => /STARCI_BASE_REF=.*>>\s*"?\$GITHUB_ENV"?/.test(runOf(step)));
-    const lint = steps.findIndex((step) => /\bnpm run lint\b|\bstarci app lint\b/.test(runOf(step)));
-    if (lint >= 0 && (base < 0 || base > lint)) out.push(say('full-history-base-ref', `job ${id} must write STARCI_BASE_REF to GITHUB_ENV before its first lint step`));
-  }
-  return out;
+    return out;
 }
-
 function heapPerStep(doc, standard, say) {
-  const out = [];
-  for (const [id, job] of jobsOf(doc)) {
-    for (const step of stepsOf(job)) {
-      const run = runOf(step);
-      if (!standard.heap.steps.some((needle) => run.includes(needle))) continue;
-      const heap = /--max-old-space-size=(\d+)/.exec(String(step.env?.NODE_OPTIONS ?? ''));
-      if (!heap || Number(heap[1]) < standard.heap.minMiB) out.push(say('heap-per-step', `job ${id}, step ${step.name ?? run.split('\n')[0].slice(0, 60)}: a heavy step declares NODE_OPTIONS --max-old-space-size=${standard.heap.minMiB} (or more) on the step`));
+    const out = [];
+    for (const [id, job] of jobsOf(doc)) {
+        for (const step of stepsOf(job)) {
+            const run = runOf(step);
+            if (!standard.heap.steps.some((needle) => run.includes(needle)))
+                continue;
+            const heap = /--max-old-space-size=(\d+)/.exec(String(step.env?.NODE_OPTIONS ?? ''));
+            if (!heap || Number(heap[1]) < standard.heap.minMiB)
+                out.push(say('heap-per-step', `job ${id}, step ${step.name ?? run.split('\n')[0].slice(0, 60)}: a heavy step declares NODE_OPTIONS --max-old-space-size=${standard.heap.minMiB} (or more) on the step`));
+        }
     }
-  }
-  return out;
+    return out;
 }
-
 function sonarLintPerSide(doc, say) {
-  const out = [];
-  for (const [id, job] of jobsOf(doc)) {
-    for (const step of stepsOf(job)) {
-      const run = runOf(step);
-      if (/\b(?:npm run lint|starci(?:\.mjs)?["']?\s+app lint|app lint)\b/.test(run) && /\s--sonar\b/.test(run) && !/\s--side\s+(?:be\b|fe\b|\$\{\{\s*matrix\.side\s*\}\})/.test(run)) {
-        out.push(say('sonar-lint-per-side', `job ${id}, step ${step.name ?? 'lint'}: a lint with a Sonar import must name its side (--side be|fe) and the reports are merged afterwards; a combined lint with Sonar breaks the standard`));
-      }
+    const out = [];
+    for (const [id, job] of jobsOf(doc)) {
+        for (const step of stepsOf(job)) {
+            const run = runOf(step);
+            if (/\b(?:npm run lint|starci(?:\.mjs)?["']?\s+app lint|app lint)\b/.test(run) && /\s--out\b/.test(run) && !/\s--side\s+(?:be\b|fe\b|\$\{\{\s*matrix\.side\s*\}\})/.test(run)) {
+                out.push(say('sonar-lint-per-side', `job ${id}, step ${step.name ?? 'lint'}: a lint with a Sonar import must name its side (--side be|fe) and the reports are merged afterwards; a combined lint with Sonar breaks the standard`));
+            }
+        }
     }
-  }
-  return out;
+    return out;
 }
-
 const PROVIDER_STEP = /^(?:codecov\/codecov-action|SonarSource\/)/;
 const PROVIDER_SECRET_GATE = /\bsecrets\.|\bCODECOV_TOKEN\b|\bSONAR_TOKEN\b/;
-const PROBE_IDS =new Set(['codecov-availability', 'sonar-availability']);
+const PROBE_IDS = new Set(['codecov-availability', 'sonar-availability']);
 const truthy = (value) => value === true || String(value).toLowerCase() === 'true';
-
 /** The findings of one step: it continues on error, it is a probe, or it is a Codecov or Sonar step that a secret gates or that tolerates a failed upload. */
 function providerStepFindings(id, step, say) {
-  const name = step.name ?? usesOf(step) ?? step.id;
-  const out = [];
-  if (truthy(step['continue-on-error'])) out.push(say('required-providers', `job ${id}, step ${name}: continue-on-error lets a red step pass`));
-  if (PROBE_IDS.has(step.id)) out.push(say('required-providers', `job ${id}: ${step.id} probes a required provider to skip it; an unreachable provider is red`));
-  if (!PROVIDER_STEP.test(usesOf(step))) return out;
-  if (PROVIDER_SECRET_GATE.test(String(step.if ?? ''))) out.push(say('required-providers', `job ${id}, step ${name}: gated on a secret, so a missing token skips it instead of failing the job`));
-  if (usesOf(step).startsWith('codecov/codecov-action@') && !truthy(step.with?.fail_ci_if_error)) out.push(say('required-providers', `job ${id}, step ${name}: the upload must set fail_ci_if_error: true`));
-  return out;
+    const name = step.name ?? usesOf(step) ?? step.id;
+    const out = [];
+    if (truthy(step['continue-on-error']))
+        out.push(say('required-providers', `job ${id}, step ${name}: continue-on-error lets a red step pass`));
+    if (PROBE_IDS.has(step.id))
+        out.push(say('required-providers', `job ${id}: ${step.id} probes a required provider to skip it; an unreachable provider is red`));
+    if (!PROVIDER_STEP.test(usesOf(step)))
+        return out;
+    if (PROVIDER_SECRET_GATE.test(String(step.if ?? '')))
+        out.push(say('required-providers', `job ${id}, step ${name}: gated on a secret, so a missing token skips it instead of failing the job`));
+    if (usesOf(step).startsWith('codecov/codecov-action@') && !truthy(step.with?.fail_ci_if_error))
+        out.push(say('required-providers', `job ${id}, step ${name}: the upload must set fail_ci_if_error: true`));
+    return out;
 }
-
 function requiredProviders(doc, say) {
-  return jobsOf(doc).flatMap(([id, job]) => [
-    ...(truthy(job['continue-on-error']) ? [say('required-providers', `job ${id}: continue-on-error lets a red job pass`)] : []),
-    ...stepsOf(job).flatMap((step) => providerStepFindings(id, step, say)),
-  ]);
+    return jobsOf(doc).flatMap(([id, job]) => [
+        ...(truthy(job['continue-on-error']) ? [say('required-providers', `job ${id}: continue-on-error lets a red job pass`)] : []),
+        ...stepsOf(job).flatMap((step) => providerStepFindings(id, step, say)),
+    ]);
 }
-
 function timeouts(doc, say) {
-  return jobsOf(doc).filter(([, job]) => !Number.isFinite(Number(job['timeout-minutes'])) || job['timeout-minutes'] === null || job['timeout-minutes'] === '')
-    .filter(([, job]) => job.uses === undefined).map(([id]) => say('timeouts', `job ${id} must declare timeout-minutes`));
+    return jobsOf(doc).filter(([, job]) => !Number.isFinite(Number(job['timeout-minutes'])) || job['timeout-minutes'] === null || job['timeout-minutes'] === '')
+        .filter(([, job]) => job.uses === undefined).map(([id]) => say('timeouts', `job ${id} must declare timeout-minutes`));
 }
-
 function shaPinned(doc, say) {
-  const out = [];
-  for (const [id, job] of jobsOf(doc)) {
-    for (const uses of [job.uses, ...stepsOf(job).map((step) => step.uses)].filter((value) => typeof value === 'string')) {
-      const ref = uses.trim();
-      if (ref.startsWith('./')) continue;
-      const pinned = ref.startsWith('docker://') ? DIGEST_PIN.test(ref) : SHA_PIN.test(ref);
-      if (!pinned) out.push(say('sha-pinned-actions', `job ${id}: ${ref} must be pinned to a commit sha (a docker:// action to a sha256 digest)`));
+    const out = [];
+    for (const [id, job] of jobsOf(doc)) {
+        for (const uses of [job.uses, ...stepsOf(job).map((step) => step.uses)].filter((value) => typeof value === 'string')) {
+            const ref = uses.trim();
+            if (ref.startsWith('./'))
+                continue;
+            const pinned = ref.startsWith('docker://') ? DIGEST_PIN.test(ref) : SHA_PIN.test(ref);
+            if (!pinned)
+                out.push(say('sha-pinned-actions', `job ${id}: ${ref} must be pinned to a commit sha (a docker:// action to a sha256 digest)`));
+        }
     }
-  }
-  return out;
+    return out;
 }
-
 /** The R301 findings of one workflow document: scope `app-ci` (with the app's edition) or `runtime`. Pure over the document and the standard. */
 export function ciStandardFindings({ doc, file, scope, edition = 'full', standard = ciStandard() }) {
-  if (!record(doc)) return [];
-  const items = checkedItems(standard, scope);
-  const say = (item, why) => found(CI_STANDARD, file, `${CI_STANDARD} ${file}: [${item}] ${why} (knowledge/hfs/ci-standard.yaml)`, { item });
-  const checks = {
-    'job-shape': () => jobShape(doc, edition, standard, say),
-    'full-history-base-ref': () => fullHistory(doc, say),
-    'heap-per-step': () => heapPerStep(doc, standard, say),
-    'sonar-lint-per-side': () => sonarLintPerSide(doc, say),
-    'required-providers': () => requiredProviders(doc, say),
-    'test-sharding': () => testSharding(doc, say),
-    'lint-parallel': () => lintParallel(doc, say),
-    'cache-saved-always': () => cacheSavedAlways(doc, say),
-    timeouts: () => timeouts(doc, say),
-    'sha-pinned-actions': () => shaPinned(doc, say),
-  };
-  return Object.entries(checks).filter(([id]) => items.has(id)).flatMap(([, check]) => check());
+    if (!record(doc))
+        return [];
+    const items = checkedItems(standard, scope);
+    const say = (item, why) => found(CI_STANDARD, file, `${CI_STANDARD} ${file}: [${item}] ${why} (knowledge/hfs/ci-standard.yaml)`, { item });
+    const checks = {
+        'job-shape': () => jobShape(doc, edition, standard, say),
+        'full-history-base-ref': () => fullHistory(doc, say),
+        'heap-per-step': () => heapPerStep(doc, standard, say),
+        'sonar-lint-per-side': () => sonarLintPerSide(doc, say),
+        'required-providers': () => requiredProviders(doc, say),
+        'test-sharding': () => testSharding(doc, say),
+        'lint-parallel': () => lintParallel(doc, say),
+        'cache-saved-always': () => cacheSavedAlways(doc, say),
+        timeouts: () => timeouts(doc, say),
+        'sha-pinned-actions': () => shaPinned(doc, say),
+    };
+    return Object.entries(checks).filter(([id]) => items.has(id)).flatMap(([, check]) => check());
 }
-
 /** R301 over an app: its managed .github/workflows/ci.yml (the app check, and the runtime check over every example app). */
 export function ciStandardAppFindings(ctx) {
-  const edition = ctx.repo?.edition === 'lite' ? 'lite' : 'full';
-  return appWorkflowFindings({ ...ctx, inScope: (file) => file === APP_CI && (ctx.inScope ?? (() => true))(file) },
-    ({ path: file, text }) => ciStandardFindings({ doc: parseWorkflow(text), file, scope: 'app-ci', edition }), { dedupe: true });
+    const edition = ctx.repo?.edition === 'lite' ? 'lite' : 'full';
+    return appWorkflowFindings({ ...ctx, inScope: (file) => file === APP_CI && (ctx.inScope ?? (() => true))(file) }, ({ path: file, text }) => ciStandardFindings({ doc: parseWorkflow(text), file, scope: 'app-ci', edition }), { dedupe: true });
 }

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

@@ -0,0 +1,7 @@
+import type { Repo, Resolver } from './rule-types.mjs';
+/** The findings of R147 over the tracked paths `files` (app-relative) of the app `repo`; `resolver` is the app's. */
+export declare function cliFindings({ files, repo, resolver }: {
+    files: string[];
+    repo: Repo;
+    resolver: Resolver;
+}): import("./rule-types.mjs").Finding[];

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

@@ -6,36 +6,37 @@
 // unit-test-colocated over ruleParams.be.unitRoles).
 // Paths are app-relative; the cli app and the cli feature root are read from the slot manifest through the resolver.
 import { found } from './read.mjs';
-
 const CLI_REQUIRED = 'BE_CLI_REQUIRED';
-
 /** The one name of the cli app, its kind, and what its image is called below it. */
 const CLI_APP = 'cli';
 const CLI_KIND = 'cli';
 const IMAGE = 'Dockerfile';
 const CLI_FEATURE_SLOT = 'be.cli';
 const CLI_APP_SLOT = 'be.app.cli';
-
 /** The findings of R147 over the tracked paths `files` (app-relative) of the app `repo`; `resolver` is the app's. */
 export function cliFindings({ files, repo, resolver }) {
-  if (!repo?.sides) return [];
-  const be = repo.sides.be;
-  const beResolver = resolver.sides?.be ?? resolver;
-  const onBe = files.filter((file) => file.startsWith('be/')).map((file) => file.slice('be/'.length));
-  const tracked = new Set(onBe);
-  const commandFiles = onBe.filter((file) => beResolver.classifyPath(file).slot === CLI_FEATURE_SLOT);
-  const findings = [];
-  const cliApps = be.apps.filter((app) => app.kind === CLI_KIND);
-  // Where the cli app is only optional (litePresence: schema migration is `starci app db migrate`'s job) a connection no longer forces it; a tracked command still does.
-  const migrates = (be.connections ?? []).length > 0 && beResolver.slot(CLI_APP_SLOT)?.presence !== 'optional';
-  const needs = migrates || commandFiles.length > 0;
-  let why = 'it tracks commands under be/src/features/cli/';
-  if (migrates) {
-    const plural = be.connections.length === 1 ? '' : 's';
-    why = `it declares the connection${plural} ${be.connections.map((c) => c.name).join(', ')} (their migrations run as \`cli migrate run\`)`;
-  }
-  if (needs && cliApps.length === 0) findings.push(found(CLI_REQUIRED, 'hfs.json', `the back end declares no cli app, but ${why}; declare { "name": "${CLI_APP}", "kind": "${CLI_KIND}" } in sides.be.apps and build be/apps/${CLI_APP} on nest-commander: every one-off action of the back end is one of its commands.`, { needs: why }));
-  for (const app of cliApps.filter((entry) => entry.name !== CLI_APP)) findings.push(found(CLI_REQUIRED, 'hfs.json', `the cli app is named ${app.name}; the back end has ONE cli app, be/apps/${CLI_APP}, so its image and its command line are the same in every app.`, { app: app.name }));
-  if (cliApps.length > 0 && !tracked.has(`apps/${CLI_APP}/${IMAGE}`) && cliApps.some((app) => app.name === CLI_APP)) findings.push(found(CLI_REQUIRED, `be/apps/${CLI_APP}/${IMAGE}`, `be/apps/${CLI_APP} has no image: track be/apps/${CLI_APP}/${IMAGE}, the one cli image every one-off action runs from (\`cli <group> <command>\`).`, { app: CLI_APP }));
-  return findings;
+    if (!repo?.sides)
+        return [];
+    const be = repo.sides.be;
+    const beResolver = resolver.sides?.be ?? resolver;
+    const onBe = files.filter((file) => file.startsWith('be/')).map((file) => file.slice('be/'.length));
+    const tracked = new Set(onBe);
+    const commandFiles = onBe.filter((file) => beResolver.classifyPath(file).slot === CLI_FEATURE_SLOT);
+    const findings = [];
+    const cliApps = be.apps.filter((app) => app.kind === CLI_KIND);
+    // Where the cli app is only optional (litePresence: schema migration is `starci app db migrate`'s job) a connection no longer forces it; a tracked command still does.
+    const migrates = (be.connections ?? []).length > 0 && beResolver.slot(CLI_APP_SLOT)?.presence !== 'optional';
+    const needs = migrates || commandFiles.length > 0;
+    let why = 'it tracks commands under be/src/features/cli/';
+    if (migrates) {
+        const plural = be.connections.length === 1 ? '' : 's';
+        why = `it declares the connection${plural} ${be.connections.map((c) => c.name).join(', ')} (their migrations run as \`cli migrate run\`)`;
+    }
+    if (needs && cliApps.length === 0)
+        findings.push(found(CLI_REQUIRED, 'hfs.json', `the back end declares no cli app, but ${why}; declare { "name": "${CLI_APP}", "kind": "${CLI_KIND}" } in sides.be.apps and build be/apps/${CLI_APP} on nest-commander: every one-off action of the back end is one of its commands.`, { needs: why }));
+    for (const app of cliApps.filter((entry) => entry.name !== CLI_APP))
+        findings.push(found(CLI_REQUIRED, 'hfs.json', `the cli app is named ${app.name}; the back end has ONE cli app, be/apps/${CLI_APP}, so its image and its command line are the same in every app.`, { app: app.name }));
+    if (cliApps.length > 0 && !tracked.has(`apps/${CLI_APP}/${IMAGE}`) && cliApps.some((app) => app.name === CLI_APP))
+        findings.push(found(CLI_REQUIRED, `be/apps/${CLI_APP}/${IMAGE}`, `be/apps/${CLI_APP} has no image: track be/apps/${CLI_APP}/${IMAGE}, the one cli image every one-off action runs from (\`cli <group> <command>\`).`, { app: CLI_APP }));
+    return findings;
 }

package/runtime/scripts/hfs/rules/contract-compat.d.mts

@@ -0,0 +1,11 @@
+import type { Parsed } from './rule-types.mjs';
+/** The breaking changes of `current` against `pinned`: [{event, message}]. */
+export declare function breakingChanges(pinned: Parsed, current: Parsed): {
+    event: string;
+    message: string;
+}[];
+/** R177: the findings of every service whose contract is pinned. `files` are the repository-relative tracked paths. */
+export declare function contractCompatFindings({ repoRoot, files }: {
+    repoRoot: string;
+    files: string[];
+}): import("./rule-types.mjs").Finding[];

package/runtime/scripts/hfs/rules/contract-compat.mjs

@@ -13,77 +13,88 @@ import path from 'node:path';
 import { isPlainObject } from '../../../engine/plain-object.mjs';
 import { found, readJson } from './read.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
-
 const CONTRACT_BREAKING = 'BE_CONTRACT_BREAKING';
-
 const CONTRACTS = /^be\/contracts\/([^/]+)\/events\.pin\.json$/;
-
 const same = (a, b) => JSON.stringify(sortKeys(a)) === JSON.stringify(sortKeys(b));
 function sortKeys(value) {
-  if (Array.isArray(value)) return value.map(sortKeys);
-  if (!isPlainObject(value)) return value;
-  return Object.fromEntries(Object.keys(value).sort(byCodeUnit).map((key) => [key, sortKeys(value[key])]));
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (!isPlainObject(value))
+        return value;
+    return Object.fromEntries(Object.keys(value).sort(byCodeUnit).map((key) => [key, sortKeys(value[key])]));
 }
 /** {type, optional} of a payload field spelling (`string`, `number?`, `string[]`). */
 const fieldOf = (spelling) => (typeof spelling === 'string' && spelling.endsWith('?') ? { type: spelling.slice(0, -1), optional: true } : { type: spelling, optional: false });
-
 function eventMetadataChanges(name, before, after) {
-  const problems = [];
-  for (const key of Object.keys(before)) {
-    if (key === 'payload') continue;
-    if (!same(before[key], after[key])) problems.push({ event: name, message: `event ${name} changed its ${key} from ${JSON.stringify(before[key])} to ${JSON.stringify(after[key] ?? null)}; a published event keeps its ${key}. Add ${name}.v2 for the new shape.` });
-  }
-  return problems;
+    const problems = [];
+    for (const key of Object.keys(before)) {
+        if (key === 'payload')
+            continue;
+        if (!same(before[key], after[key]))
+            problems.push({ event: name, message: `event ${name} changed its ${key} from ${JSON.stringify(before[key])} to ${JSON.stringify(after[key] ?? null)}; a published event keeps its ${key}. Add ${name}.v2 for the new shape.` });
+    }
+    return problems;
 }
-
 function existingPayloadChanges(name, was, now) {
-  const problems = [];
-  for (const [field, spelling] of Object.entries(was)) {
-    if (!(field in now)) { problems.push({ event: name, message: `event ${name} lost payload field ${field}; fields are only ever added. Keep it, and add ${name}.v2 for the new shape.` }); continue; }
-    const a = fieldOf(spelling);
-    const b = fieldOf(now[field]);
-    if (a.type !== b.type) problems.push({ event: name, message: `event ${name} changed payload field ${field} from ${a.type} to ${b.type}; a field keeps its type. Add ${name}.v2 for the new shape.` });
-    else if (a.optional !== b.optional) problems.push({ event: name, message: `event ${name} changed payload field ${field} from ${a.optional ? 'optional' : 'required'} to ${b.optional ? 'optional' : 'required'}; a field keeps its optionality. Add ${name}.v2 for the new shape.` });
-  }
-  return problems;
+    const problems = [];
+    for (const [field, spelling] of Object.entries(was)) {
+        if (!(field in now)) {
+            problems.push({ event: name, message: `event ${name} lost payload field ${field}; fields are only ever added. Keep it, and add ${name}.v2 for the new shape.` });
+            continue;
+        }
+        const a = fieldOf(spelling);
+        const b = fieldOf(now[field]);
+        if (a.type !== b.type)
+            problems.push({ event: name, message: `event ${name} changed payload field ${field} from ${a.type} to ${b.type}; a field keeps its type. Add ${name}.v2 for the new shape.` });
+        else if (a.optional !== b.optional)
+            problems.push({ event: name, message: `event ${name} changed payload field ${field} from ${a.optional ? 'optional' : 'required'} to ${b.optional ? 'optional' : 'required'}; a field keeps its optionality. Add ${name}.v2 for the new shape.` });
+    }
+    return problems;
 }
-
 function addedRequiredPayloadChanges(name, was, now) {
-  const problems = [];
-  for (const [field, spelling] of Object.entries(now)) {
-    if (!(field in was) && !fieldOf(spelling).optional) problems.push({ event: name, message: `event ${name} gained required payload field ${field}; events already on the wire do not carry it, so a new field is optional (${field}?). Make it optional, or add ${name}.v2.` });
-  }
-  return problems;
+    const problems = [];
+    for (const [field, spelling] of Object.entries(now)) {
+        if (!(field in was) && !fieldOf(spelling).optional)
+            problems.push({ event: name, message: `event ${name} gained required payload field ${field}; events already on the wire do not carry it, so a new field is optional (${field}?). Make it optional, or add ${name}.v2.` });
+    }
+    return problems;
 }
-
 function eventChanges(name, before, after) {
-  if (!isPlainObject(after)) return [{ event: name, message: `event ${name} was removed; a published event is never deleted while it can still be on the wire. Keep it, and add ${name}.v2 for the new shape.` }];
-  const was = isPlainObject(before.payload) ? before.payload : {};
-  const now = isPlainObject(after.payload) ? after.payload : {};
-  return [...eventMetadataChanges(name, before, after), ...existingPayloadChanges(name, was, now), ...addedRequiredPayloadChanges(name, was, now)];
+    if (!isPlainObject(after))
+        return [{ event: name, message: `event ${name} was removed; a published event is never deleted while it can still be on the wire. Keep it, and add ${name}.v2 for the new shape.` }];
+    const was = isPlainObject(before.payload) ? before.payload : {};
+    const now = isPlainObject(after.payload) ? after.payload : {};
+    return [...eventMetadataChanges(name, before, after), ...existingPayloadChanges(name, was, now), ...addedRequiredPayloadChanges(name, was, now)];
 }
-
 /** The breaking changes of `current` against `pinned`: [{event, message}]. */
 export function breakingChanges(pinned, current) {
-  const problems = [];
-  const pinnedEvents = isPlainObject(pinned?.events) ? pinned.events : {};
-  const currentEvents = isPlainObject(current?.events) ? current.events : {};
-  for (const [name, before] of Object.entries(pinnedEvents)) problems.push(...eventChanges(name, before, currentEvents[name]));
-  return problems;
+    const problems = [];
+    const pinnedEvents = isPlainObject(pinned?.events) ? pinned.events : {};
+    const currentEvents = isPlainObject(current?.events) ? current.events : {};
+    for (const [name, before] of Object.entries(pinnedEvents))
+        problems.push(...eventChanges(name, before, currentEvents[name]));
+    return problems;
 }
-
 /** R177: the findings of every service whose contract is pinned. `files` are the repository-relative tracked paths. */
 export function contractCompatFindings({ repoRoot, files }) {
-  const findings = [];
-  for (const rel of [...files].sort(byCodeUnit)) {
-    const match = CONTRACTS.exec(rel);
-    if (!match) continue;
-    const current = `be/contracts/${match[1]}/events.json`;
-    const pinned = readJson(repoRoot, rel);
-    const snapshot = readJson(repoRoot, current);
-    if (!isPlainObject(pinned) || !isPlainObject(pinned.events)) { findings.push(found(CONTRACT_BREAKING, rel, `${rel} is not a readable event contract (an object with an events table); copy a published ${path.posix.basename(current)} over it.`)); continue; }
-    if (!isPlainObject(snapshot) || !isPlainObject(snapshot.events)) { findings.push(found(CONTRACT_BREAKING, current, `${current} is missing or unreadable while ${rel} pins the contract of service ${match[1]}; the contract of a published service is never dropped. Emit it again.`)); continue; }
-    for (const { event, message } of breakingChanges(pinned, snapshot)) findings.push(found(CONTRACT_BREAKING, current, `${current}: ${message}`, { event, service: match[1] }));
-  }
-  return findings;
+    const findings = [];
+    for (const rel of [...files].sort(byCodeUnit)) {
+        const match = CONTRACTS.exec(rel);
+        if (!match)
+            continue;
+        const current = `be/contracts/${match[1]}/events.json`;
+        const pinned = readJson(repoRoot, rel);
+        const snapshot = readJson(repoRoot, current);
+        if (!isPlainObject(pinned) || !isPlainObject(pinned.events)) {
+            findings.push(found(CONTRACT_BREAKING, rel, `${rel} is not a readable event contract (an object with an events table); copy a published ${path.posix.basename(current)} over it.`));
+            continue;
+        }
+        if (!isPlainObject(snapshot) || !isPlainObject(snapshot.events)) {
+            findings.push(found(CONTRACT_BREAKING, current, `${current} is missing or unreadable while ${rel} pins the contract of service ${match[1]}; the contract of a published service is never dropped. Emit it again.`));
+            continue;
+        }
+        for (const { event, message } of breakingChanges(pinned, snapshot))
+            findings.push(found(CONTRACT_BREAKING, current, `${current}: ${message}`, { event, service: match[1] }));
+    }
+    return findings;
 }