@starci/hfs 4.11.21 → 4.12.0

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

@@ -0,0 +1,7 @@
+import type { Resolver } from './rule-types.mjs';
+/** The shape findings of the `.starcistacks` tree at the app root (`repoRoot` is the app root, `files` its own tracked paths). */
+export declare function stacksFindings({ repoRoot, files, resolver }: {
+    repoRoot: string;
+    files: string[];
+    resolver: Resolver;
+}): any[];

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

@@ -11,56 +11,55 @@ import { braceVariants, globExpression } from '../../lib/glob.mjs';
 import { declaredStack, findStackDeclaration, STACK_ROOT, text } from '../../lib/stack-declaration.mjs';
 import { found } from './read.mjs';
 import { hostCrontabFindings, stacksRuntimeFindings } from './stacks-runtime.mjs';
-
 const STACKS_SHAPE = 'HFS_STACKS_SHAPE';
 const STACKS_SLOT = 'app.starcistacks';
 const HOST_SONAR_ROOT = '.claude/ext/sonar';
 const INSIDE_SECRETS = /^[^/]+\/secrets\/[^/]+\.enc(?:\.yaml)?$/;
-
 /** The anchored expressions of a slot's `allows` entries: `<name>` is one path segment, braces alternate. */
 const allowedExpressions = (allows) => allows.flatMap((entry) => braceVariants(entry.replace(/<[a-z][a-z0-9-]*>/g, '*'))).map((variant) => globExpression(variant.endsWith('/') ? `${variant}**` : variant));
-
 const shapeFinding = (file, message, extra) => found(STACKS_SHAPE, file, message, extra);
-
 function treeFindings(files, allowed, prefix) {
-  const findings = [];
-  for (const file of files.filter((f) => f.startsWith(prefix))) {
-    const rel = file.slice(prefix.length);
-    if (/\.enc(?:\.yaml)?$/.test(rel) && !INSIDE_SECRETS.test(rel)) findings.push(shapeFinding(file, `${file} is a sealed secret outside <env>/secrets/<slug>.enc.yaml; move it to .starcistacks/<env>/secrets/`));
-    else if (!allowed.some((expression) => expression.test(rel))) findings.push(shapeFinding(file, `${file} is not part of the standard .starcistacks shape (application-stacks.yaml, images/db/Dockerfile in lite and <env>/{README.md, environment.json, infra, runtime/{config,env}, secrets/<slug>.enc.yaml, seeds}); move or delete it`));
-  }
-  return findings;
+    const findings = [];
+    for (const file of files.filter((f) => f.startsWith(prefix))) {
+        const rel = file.slice(prefix.length);
+        if (/\.enc(?:\.yaml)?$/.test(rel) && !INSIDE_SECRETS.test(rel))
+            findings.push(shapeFinding(file, `${file} is a sealed secret outside <env>/secrets/<slug>.enc.yaml; move it to .starcistacks/<env>/secrets/`));
+        else if (!allowed.some((expression) => expression.test(rel)))
+            findings.push(shapeFinding(file, `${file} is not part of the standard .starcistacks shape (application-stacks.yaml, images/db/Dockerfile in lite and <env>/{README.md, environment.json, infra, runtime/{config,env}, secrets/<slug>.enc.yaml, seeds}); move or delete it`));
+    }
+    return findings;
 }
-
 function declarationFindings(files, prefix, declaration) {
-  const declared = `${prefix}application-stacks.yaml`;
-  if (!files.includes(declared)) return [];
-  const findings = [];
-  if (declaration.error) return [shapeFinding(declared, `${declared} cannot be read: ${declaration.error}`)];
-  const services = declaration.doc?.services;
-  if (services === undefined || typeof services.sonar !== 'object' || services.sonar === null) {
-    findings.push(shapeFinding(declared, `${declared} declares no sonar service; every repository states its Sonar owner (a local one is owned by the host: stack.owner host, root ${HOST_SONAR_ROOT})`));
-    return findings;
-  }
-  for (const [id, entry] of Object.entries(services)) {
-    const stack = declaredStack(entry);
-    if (id === 'sonar' && text(entry?.mode) === 'local' && !(stack?.hostOwned && stack.root === HOST_SONAR_ROOT)) {
-      findings.push(shapeFinding(declared, `${declared} services.sonar is a local Sonar but is not owned by the host; declare stack.owner host with root ${HOST_SONAR_ROOT}`));
+    const declared = `${prefix}application-stacks.yaml`;
+    if (!files.includes(declared))
+        return [];
+    const findings = [];
+    if (declaration.error)
+        return [shapeFinding(declared, `${declared} cannot be read: ${declaration.error}`)];
+    const services = declaration.doc?.services;
+    if (services === undefined || typeof services.sonar !== 'object' || services.sonar === null) {
+        findings.push(shapeFinding(declared, `${declared} declares no sonar service; every repository states its Sonar owner (a local one is owned by the host: stack.owner host, root ${HOST_SONAR_ROOT})`));
+        return findings;
     }
-  }
-  return findings;
+    for (const [id, entry] of Object.entries(services)) {
+        const stack = declaredStack(entry);
+        if (id === 'sonar' && text(entry?.mode) === 'local' && !(stack?.hostOwned && stack.root === HOST_SONAR_ROOT)) {
+            findings.push(shapeFinding(declared, `${declared} services.sonar is a local Sonar but is not owned by the host; declare stack.owner host with root ${HOST_SONAR_ROOT}`));
+        }
+    }
+    return findings;
 }
-
 /** The shape findings of the `.starcistacks` tree at the app root (`repoRoot` is the app root, `files` its own tracked paths). */
 export function stacksFindings({ repoRoot, files, resolver }) {
-  const slot = resolver.slot(STACKS_SLOT);
-  if (!slot) return [];
-  const prefix = `${STACK_ROOT}/`;
-  const declaration = findStackDeclaration(repoRoot);
-  return [
-    ...treeFindings(files, allowedExpressions(slot.allows ?? []), prefix),
-    ...declarationFindings(files, prefix, declaration),
-    ...hostCrontabFindings({ repoRoot, files }),
-    ...(declaration.doc ? stacksRuntimeFindings({ repoRoot, files, doc: declaration.doc, edition: resolver.repo?.edition }) : []),
-  ];
+    const slot = resolver.slot(STACKS_SLOT);
+    if (!slot)
+        return [];
+    const prefix = `${STACK_ROOT}/`;
+    const declaration = findStackDeclaration(repoRoot);
+    return [
+        ...treeFindings(files, allowedExpressions(slot.allows ?? []), prefix),
+        ...declarationFindings(files, prefix, declaration),
+        ...hostCrontabFindings({ repoRoot, files }),
+        ...(declaration.doc ? stacksRuntimeFindings({ repoRoot, files, doc: declaration.doc, edition: resolver.repo?.edition }) : []),
+    ];
 }

package/runtime/scripts/hfs/rules/staged-specs.d.mts

@@ -0,0 +1,10 @@
+import type { Parsed, Ts } from './rule-types.mjs';
+/**
+ * The findings `{ file, code, message }` of the app-relative files the index adds (`added`) whose sibling spec is not among the
+ * paths the index holds (`indexed`, a Set). `manifest` is the slot manifest the coverage scope reads; `staged(file)` answers the
+ * staged text of a file and `ts` the TypeScript parser, which tell a logic file from a constants-only one.
+ */
+export declare function stagedSpecFindings(manifest: Parsed, added: Parsed, indexed: Parsed, { ts, staged }?: {
+    ts?: Ts | null;
+    staged?: (file: string) => string | null;
+}): any;

package/runtime/scripts/hfs/rules/staged-specs.mjs

@@ -3,44 +3,40 @@
 // ruleParams.be.logicRoles below a measured root, outside its none folders) and that holds executable logic (a function, a method, a
 // constructor, an accessor) needs `<name>.<role>.spec.ts` in the same index. A measured file with nothing to execute (constants and
 // types only, such as an error-kind to HTTP-status table) has nothing a spec could call, and the spec rules refuse a spec of it
-// (spec-infra-double-from-kit); the coverage gate still reaches it through its callers. `starci app hygiene` judges the files the
+// (spec-infra-double-from-kit); the coverage gate still reaches it through its callers. `starci app check --staged` judges the files the
 // index adds (packages/hfs/sync/hygiene.mjs, run by the managed pre-commit hook), so a coding agent cannot commit the code first and
 // its spec afterwards. A file that already exists is the coverage gate's.
 import { isMeasured } from '../coverage-scope.mjs';
-
 const SPEC_NOT_STAGED = 'BE_UNIT_SPEC_NOT_STAGED';
 const BE = 'be/';
-
 /** The unit spec beside an app-relative `<name>.<role>.ts`: `<name>.<role>.spec.ts`. */
 const siblingSpec = (file) => file.replace(/\.ts$/u, '.spec.ts');
-
 /** The syntax kinds that execute: a body a spec can call. */
 const EXECUTABLE_KINDS = ['FunctionDeclaration', 'FunctionExpression', 'ArrowFunction', 'MethodDeclaration', 'Constructor', 'GetAccessor', 'SetAccessor'];
-
 /**
  * Whether TypeScript `text` holds executable logic. Without a TypeScript parser (`ts` null) or without the text, the file counts as
  * logic: the gate never relaxes on what it cannot read.
  */
 function holdsLogic(ts, text) {
-  if (!ts || typeof text !== 'string') return true;
-  const kinds = new Set(EXECUTABLE_KINDS.map((name) => ts.SyntaxKind[name]));
-  const source = ts.createSourceFile('subject.ts', text, ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
-  const visit = (node) => kinds.has(node.kind) || ts.forEachChild(node, visit) === true;
-  return ts.forEachChild(source, visit) === true;
+    if (!ts || typeof text !== 'string')
+        return true;
+    const kinds = new Set(EXECUTABLE_KINDS.map((name) => ts.SyntaxKind[name]));
+    const source = ts.createSourceFile('subject.ts', text, ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+    const visit = (node) => kinds.has(node.kind) || ts.forEachChild(node, visit) === true;
+    return ts.forEachChild(source, visit) === true;
 }
-
 /**
  * The findings `{ file, code, message }` of the app-relative files the index adds (`added`) whose sibling spec is not among the
  * paths the index holds (`indexed`, a Set). `manifest` is the slot manifest the coverage scope reads; `staged(file)` answers the
  * staged text of a file and `ts` the TypeScript parser, which tell a logic file from a constants-only one.
  */
 export function stagedSpecFindings(manifest, added, indexed, { ts = null, staged = () => null } = {}) {
-  return added
-    .filter((file) => file.startsWith(BE) && !file.endsWith('.spec.ts') && isMeasured(manifest, file.slice(BE.length)) && !indexed.has(siblingSpec(file)))
-    .filter((file) => holdsLogic(ts, staged(file)))
-    .map((file) => ({
-      file,
-      code: SPEC_NOT_STAGED,
-      message: `is a new back-end logic file the unit coverage measures at 100 per file, staged without ${siblingSpec(file).slice(file.lastIndexOf('/') + 1)} beside it; write the spec in the same change (starci gate read, code and spec, starci gate run --tests) and stage both`,
+    return added
+        .filter((file) => file.startsWith(BE) && !file.endsWith('.spec.ts') && isMeasured(manifest, file.slice(BE.length)) && !indexed.has(siblingSpec(file)))
+        .filter((file) => holdsLogic(ts, staged(file)))
+        .map((file) => ({
+        file,
+        code: SPEC_NOT_STAGED,
+        message: `is a new back-end logic file the unit coverage measures at 100 per file, staged without ${siblingSpec(file).slice(file.lastIndexOf('/') + 1)} beside it; write the spec in the same change (starci gate read, code and spec, starci gate run --tests) and stage both`,
     }));
 }

package/runtime/scripts/hfs/rules/supply-chain.d.mts

@@ -0,0 +1,10 @@
+import type { Repo } from './rule-types.mjs';
+/** Synchronous judge of R269 at the app root; root-wide gates run only when their paths are in scope. */
+export declare function supplyChainFindings({ repoRoot, files, all, repo, isRoot, inScope }: {
+    repoRoot: string;
+    files: string[];
+    all?: string[];
+    repo: Repo;
+    isRoot: boolean;
+    inScope?: (file: string) => boolean;
+}): any[];

package/runtime/scripts/hfs/rules/supply-chain.mjs

@@ -1,205 +1,198 @@
 // R269: app repositories in both editions declare dependency updates, a production audit gate, and image SBOM/provenance.
 import { parseWorkflow, workflowFindings } from '../runtime-rules/workflow-source.mjs';
 import { found, readText } from './read.mjs';
-
 const DEPENDABOT = '.github/dependabot.yml';
 const CI = '.github/workflows/ci.yml';
 const IMAGES = '.github/workflows/images.yml';
 const ECOSYSTEMS = ['npm', 'github-actions', 'docker'];
 const enabled = (entry) => entry && (entry.if === undefined || entry.if === true || entry.if === 'true') && !entry['continue-on-error'];
-
 function shellSeparator(line, index, quote) {
-  if (quote) return null;
-  if (line[index] === ';') return ';';
-  const pair = line.slice(index, index + 2);
-  return pair === '&&' || pair === '||' ? pair : null;
+    if (quote)
+        return null;
+    if (line[index] === ';')
+        return ';';
+    const pair = line.slice(index, index + 2);
+    return pair === '&&' || pair === '||' ? pair : null;
 }
-
 function isShellComment(line, index, quote) {
-  return !quote && line[index] === '#' && (index === 0 || /\s/.test(line[index - 1]));
+    return !quote && line[index] === '#' && (index === 0 || /\s/.test(line[index - 1]));
 }
-
 function shellQuote(char, quote) {
-  if (char === quote) return null;
-  return !quote && (char === '"' || char === "'") ? char : quote;
+    if (char === quote)
+        return null;
+    return !quote && (char === '"' || char === "'") ? char : quote;
 }
-
 function appendShellCommand(commands, state, next) {
-  const tokens = state.command.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g)?.map((token) => token.replace(/^["']|["']$/g, '')) ?? [];
-  if (tokens.length) commands.push({ tokens, separator: state.separator, next });
-  state.separator = next;
-  state.command = '';
+    const tokens = state.command.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g)?.map((token) => token.replace(/^["']|["']$/g, '')) ?? [];
+    if (tokens.length)
+        commands.push({ tokens, separator: state.separator, next });
+    state.separator = next;
+    state.command = '';
 }
-
 function shellLineCommands(line, commands) {
-  /** @type {{quote: string | null, command: string, separator: string | null}} */
-  const state = { quote: null, command: '', separator: null };
-  for (let i = 0; i < line.length; i++) {
-    const char = line[i];
-    if (char === '\\' && state.quote !== "'") {
-      i++;
-      state.command += char + (line[i] ?? '');
-      continue;
+    /** @type {{quote: string | null, command: string, separator: string | null}} */
+    const state = { quote: null, command: '', separator: null };
+    for (let i = 0; i < line.length; i++) {
+        const char = line[i];
+        if (char === '\\' && state.quote !== "'") {
+            i++;
+            state.command += char + (line[i] ?? '');
+            continue;
+        }
+        if (isShellComment(line, i, state.quote))
+            break;
+        const next = shellSeparator(line, i, state.quote);
+        if (next) {
+            appendShellCommand(commands, state, next);
+            if (next.length === 2)
+                i++;
+            continue;
+        }
+        state.quote = shellQuote(char, state.quote);
+        state.command += char;
     }
-    if (isShellComment(line, i, state.quote)) break;
-    const next = shellSeparator(line, i, state.quote);
-    if (next) {
-      appendShellCommand(commands, state, next);
-      if (next.length === 2) i++;
-      continue;
-    }
-    state.quote = shellQuote(char, state.quote);
-    state.command += char;
-  }
-  appendShellCommand(commands, state, null);
+    appendShellCommand(commands, state, null);
 }
-
 /** Shell evidence is an executable command, never quoted text, a comment or a heredoc body. */
 function shellCommands(run) {
-  if (typeof run !== 'string') return [];
-  const commands = [];
-  let heredoc = null;
-  for (const line of run.replace(/\\\r?\n/g, ' ').split(/\r?\n/)) {
-    if (heredoc) {
-      if (line.trim() === heredoc) heredoc = null;
-      continue;
+    if (typeof run !== 'string')
+        return [];
+    const commands = [];
+    let heredoc = null;
+    for (const line of run.replace(/\\\r?\n/g, ' ').split(/\r?\n/)) {
+        if (heredoc) {
+            if (line.trim() === heredoc)
+                heredoc = null;
+            continue;
+        }
+        heredoc = /<<-?\s*['"]?(\w+)['"]?/.exec(line)?.[1] ?? null;
+        shellLineCommands(line, commands);
     }
-    heredoc = /<<-?\s*['"]?(\w+)['"]?/.exec(line)?.[1] ?? null;
-    shellLineCommands(line, commands);
-  }
-  return commands;
+    return commands;
 }
-
 function executableCommands(run) {
-  const commands = shellCommands(run);
-  const uncheckedErrors = commands.some(({ tokens }) => tokens[0] === 'set' && tokens.includes('+e'));
-  if (uncheckedErrors) return [];
-  return commands.filter((command, index) => {
-    if (command.separator === '||' || command.next === '||') return false;
-    if (command.separator === '&&' && commands.slice(0, index).some(({ tokens }) => ['false', 'exit', 'return'].includes(tokens[0]))) return false;
-    return !commands.slice(index + 1).some(({ tokens }) => tokens[0] === 'exit' && tokens[1] === '0');
-  });
-}
-
+    const commands = shellCommands(run);
+    const uncheckedErrors = commands.some(({ tokens }) => tokens[0] === 'set' && tokens.includes('+e'));
+    if (uncheckedErrors)
+        return [];
+    return commands.filter((command, index) => {
+        if (command.separator === '||' || command.next === '||')
+            return false;
+        if (command.separator === '&&' && commands.slice(0, index).some(({ tokens }) => ['false', 'exit', 'return'].includes(tokens[0])))
+            return false;
+        return !commands.slice(index + 1).some(({ tokens }) => tokens[0] === 'exit' && tokens[1] === '0');
+    });
+}
 /** Only enabled jobs and steps can provide a supply-chain gate. Comments, labels and disabled steps are no evidence. */
 function stepsOf(workflow) {
-  return Object.values(workflow?.jobs ?? {}).filter(enabled).flatMap((job) => Array.isArray(job.steps) ? job.steps.filter(enabled) : []);
+    return Object.values(workflow?.jobs ?? {}).filter(enabled).flatMap((job) => Array.isArray(job.steps) ? job.steps.filter(enabled) : []);
 }
-
 /** npm groups admit only minor and patch updates; canon packages are ignored for every update type. */
 function hasNpmPolicy(update) {
-  const groups = update.groups && typeof update.groups === 'object' && !Array.isArray(update.groups) ? Object.values(update.groups) : [];
-  const minorPatch = (group) => Array.isArray(group?.['update-types']) && group['update-types'].includes('minor') && group['update-types'].includes('patch');
-  return groups.length > 0 && groups.every((group) => Array.isArray(group?.['update-types']) && group['update-types'].length > 0 && group['update-types'].every((type) => ['minor', 'patch'].includes(type))) &&
-    groups.some((group) => minorPatch(group) && [undefined, 'version-updates'].includes(group['applies-to'])) &&
-    groups.some((group) => group['applies-to'] === 'security-updates') &&
-    Array.isArray(update.ignore) && update.ignore.some((entry) => entry?.['dependency-name'] === '@starci/*' && entry.versions === undefined && entry['update-types'] === undefined);
-}
-
+    const groups = update.groups && typeof update.groups === 'object' && !Array.isArray(update.groups) ? Object.values(update.groups) : [];
+    const minorPatch = (group) => Array.isArray(group?.['update-types']) && group['update-types'].includes('minor') && group['update-types'].includes('patch');
+    return groups.length > 0 && groups.every((group) => Array.isArray(group?.['update-types']) && group['update-types'].length > 0 && group['update-types'].every((type) => ['minor', 'patch'].includes(type))) &&
+        groups.some((group) => minorPatch(group) && [undefined, 'version-updates'].includes(group['applies-to'])) &&
+        groups.some((group) => group['applies-to'] === 'security-updates') &&
+        Array.isArray(update.ignore) && update.ignore.some((entry) => entry?.['dependency-name'] === '@starci/*' && entry.versions === undefined && entry['update-types'] === undefined);
+}
 function hasDependabot(document) {
-  const directory = (value) => typeof value === 'string' && value.startsWith('/');
-  return document?.version === 2 && Array.isArray(document.updates) && ECOSYSTEMS.every((ecosystem) => document.updates.some((update) =>
-    update?.['package-ecosystem'] === ecosystem &&
-    (directory(update.directory) || Array.isArray(update.directories) && update.directories.length > 0 && update.directories.every(directory)) &&
-    ['daily', 'weekly', 'monthly'].includes(update.schedule?.interval))) &&
-    document.updates.filter((update) => update?.['package-ecosystem'] === 'npm').every(hasNpmPolicy);
-}
-
+    const directory = (value) => typeof value === 'string' && value.startsWith('/');
+    return document?.version === 2 && Array.isArray(document.updates) && ECOSYSTEMS.every((ecosystem) => document.updates.some((update) => update?.['package-ecosystem'] === ecosystem &&
+        (directory(update.directory) || Array.isArray(update.directories) && update.directories.length > 0 && update.directories.every(directory)) &&
+        ['daily', 'weekly', 'monthly'].includes(update.schedule?.interval))) &&
+        document.updates.filter((update) => update?.['package-ecosystem'] === 'npm').every(hasNpmPolicy);
+}
 function pinnedAction(value) {
-  return typeof value === 'string' && (/^\.\/[\w./-]+$/.test(value) ||
-    /^[\w.-]+\/[\w.-]+(?:\/[\w.-]+)*@[a-f\d]{40}$/i.test(value) ||
-    /^docker:\/\/[^\s@]+@sha256:[a-f\d]{64}$/i.test(value));
+    return typeof value === 'string' && (/^\.\/[\w./-]+$/.test(value) ||
+        /^[\w.-]+\/[\w.-]+(?:\/[\w.-]+)*@[a-f\d]{40}$/i.test(value) ||
+        /^docker:\/\/[^\s@]+@sha256:[a-f\d]{64}$/i.test(value));
 }
-
 /** Mark YAML keys before parsing so comments and script scalars are ignored while flow maps and quoted keys retain their source lines. */
 function workflowPinFindings({ path: file, text }) {
-  const marked = text.replace(/(^|[\s{,])(?:"uses"|'uses'|uses)([ \t]*:)/gm, (match, prefix, colon, offset) => {
-    const line = text.slice(0, offset + prefix.length).split('\n').length;
-    return `${prefix}__hfs_action_uses_line_${line}__${colon}`;
-  });
-  const findings = [];
-  function visit(value) {
-    if (!value || typeof value !== 'object') return;
-    for (const [key, member] of Object.entries(value)) {
-      const line = /^__hfs_action_uses_line_(\d+)__$/.exec(key)?.[1];
-      if (line && !pinnedAction(member)) findings.push(found('HFS_WORKFLOW_PIN', file, `${file}:${line}: every remote uses entry needs a full 40-hex commit SHA; container actions need a sha256 digest.`, { line: Number(line) }));
-      visit(member);
+    const marked = text.replace(/(^|[\s{,])(?:"uses"|'uses'|uses)([ \t]*:)/gm, (_match, prefix, colon, offset) => {
+        const line = text.slice(0, offset + prefix.length).split('\n').length;
+        return `${prefix}__hfs_action_uses_line_${line}__${colon}`;
+    });
+    const findings = [];
+    function visit(value) {
+        if (!value || typeof value !== 'object')
+            return;
+        for (const [key, member] of Object.entries(value)) {
+            const line = /^__hfs_action_uses_line_(\d+)__$/.exec(key)?.[1];
+            if (line && !pinnedAction(member))
+                findings.push(found('HFS_WORKFLOW_PIN', file, `${file}:${line}: every remote uses entry needs a full 40-hex commit SHA; container actions need a sha256 digest.`, { line: Number(line) }));
+            visit(member);
+        }
     }
-  }
-  visit(parseWorkflow(marked));
-  return findings;
+    visit(parseWorkflow(marked));
+    return findings;
 }
-
 function hasAudit(steps) {
-  return steps.some((step) => executableCommands(step.run).some(({ tokens }) =>
-    tokens[0] === 'npm' && tokens[1] === 'audit' &&
-    (tokens.includes('--omit=dev') || tokens.some((token, index) => token === '--omit' && tokens[index + 1] === 'dev'))));
+    return steps.some((step) => executableCommands(step.run).some(({ tokens }) => tokens[0] === 'npm' && tokens[1] === 'audit' &&
+        (tokens.includes('--omit=dev') || tokens.some((token, index) => token === '--omit' && tokens[index + 1] === 'dev'))));
 }
-
 const asserted = (value) => value === true || value === 'true';
 const provenanceEnabled = (value) => asserted(value) || typeof value === 'string' && /^mode=(?:min|max)$/.test(value);
-
 function imageActionEvidence(step) {
-  const action = step.uses ?? '';
-  if (action.startsWith('docker/build-push-action@')) {
-    return { sbom: asserted(step.with?.sbom), provenance: provenanceEnabled(step.with?.provenance) };
-  }
-  return {
-    sbom: action.startsWith('actions/attest-sbom@') && Boolean(step.with?.['sbom-path']),
-    provenance: action.startsWith('actions/attest-build-provenance@') && Boolean(step.with?.['subject-path'] || step.with?.['subject-digest']),
-  };
-}
-
+    const action = step.uses ?? '';
+    if (action.startsWith('docker/build-push-action@')) {
+        return { sbom: asserted(step.with?.sbom), provenance: provenanceEnabled(step.with?.provenance) };
+    }
+    return {
+        sbom: action.startsWith('actions/attest-sbom@') && Boolean(step.with?.['sbom-path']),
+        provenance: action.startsWith('actions/attest-build-provenance@') && Boolean(step.with?.['subject-path'] || step.with?.['subject-digest']),
+    };
+}
 function attestationType(value, type) {
-  return value === `type=${type}` || value?.startsWith(`type=${type},`) === true;
+    return value === `type=${type}` || value?.startsWith(`type=${type},`) === true;
 }
-
 function hasAttestation(tokens, type) {
-  return tokens.some((token, index) =>
-    token.startsWith('--attest=') && attestationType(token.slice('--attest='.length), type) ||
-    token === '--attest' && attestationType(tokens[index + 1], type));
+    return tokens.some((token, index) => token.startsWith('--attest=') && attestationType(token.slice('--attest='.length), type) ||
+        token === '--attest' && attestationType(tokens[index + 1], type));
 }
-
 function isSbomCommand(tokens) {
-  if (tokens[0] === 'syft') {
-    return tokens.length > 1 && !tokens.some((token) => ['--help', '--version', 'help', 'version'].includes(token));
-  }
-  return tokens[0] === 'docker' && tokens[1] === 'sbom' && tokens.length > 2 && !tokens.includes('--help');
+    if (tokens[0] === 'syft') {
+        return tokens.length > 1 && !tokens.some((token) => ['--help', '--version', 'help', 'version'].includes(token));
+    }
+    return tokens[0] === 'docker' && tokens[1] === 'sbom' && tokens.length > 2 && !tokens.includes('--help');
 }
-
 function imageCommandEvidence(tokens) {
-  if (tokens.slice(0, 3).join(' ') !== 'docker buildx build') return { sbom: isSbomCommand(tokens), provenance: false };
-  return {
-    sbom: tokens.includes('--sbom') || tokens.includes('--sbom=true') || hasAttestation(tokens, 'sbom'),
-    provenance: tokens.some((token) => /^--provenance(?:=(?:true|mode=(?:min|max)))?$/.test(token)) || hasAttestation(tokens, 'provenance'),
-  };
+    if (tokens.slice(0, 3).join(' ') !== 'docker buildx build')
+        return { sbom: isSbomCommand(tokens), provenance: false };
+    return {
+        sbom: tokens.includes('--sbom') || tokens.includes('--sbom=true') || hasAttestation(tokens, 'sbom'),
+        provenance: tokens.some((token) => /^--provenance(?:=(?:true|mode=(?:min|max)))?$/.test(token)) || hasAttestation(tokens, 'provenance'),
+    };
 }
-
 function imageEvidence(steps) {
-  let sbom = false;
-  let provenance = false;
-  for (const step of steps) {
-    const action = imageActionEvidence(step);
-    sbom ||= action.sbom;
-    provenance ||= action.provenance;
-    for (const { tokens } of executableCommands(step.run)) {
-      const command = imageCommandEvidence(tokens);
-      sbom ||= command.sbom;
-      provenance ||= command.provenance;
+    let sbom = false;
+    let provenance = false;
+    for (const step of steps) {
+        const action = imageActionEvidence(step);
+        sbom ||= action.sbom;
+        provenance ||= action.provenance;
+        for (const { tokens } of executableCommands(step.run)) {
+            const command = imageCommandEvidence(tokens);
+            sbom ||= command.sbom;
+            provenance ||= command.provenance;
+        }
     }
-  }
-  return sbom && provenance;
+    return sbom && provenance;
 }
-
 /** Synchronous judge of R269 at the app root; root-wide gates run only when their paths are in scope. */
 export function supplyChainFindings({ repoRoot, files, all = files, repo, isRoot, inScope = () => true }) {
-  if (repo?.kind !== 'app' || !['lite', 'full'].includes(repo.edition) || isRoot === false) return [];
-  const tracked = new Set(all);
-  const parsed = (file) => tracked.has(file) ? parseWorkflow(readText(repoRoot, file) ?? '') : null;
-  const findings = [];
-  if (inScope(DEPENDABOT) && !hasDependabot(parsed(DEPENDABOT))) findings.push(found('HFS_DEPENDABOT_MISSING', DEPENDABOT, 'Declare Dependabot version 2 updates for npm, github-actions and docker, each with a directory and schedule; every npm update must group minor+patch version updates, restrict every group to minor/patch (never major), include a security-updates group, and ignore all @starci/* updates (canon pins move only by starci upgrade).'));
-  if (inScope(CI) && !hasAudit(stepsOf(parsed(CI)))) findings.push(found('HFS_AUDIT_STEP_MISSING', CI, 'CI must run npm audit --omit=dev in an enabled step whose failure stops the job.'));
-  if (inScope(IMAGES) && !imageEvidence(stepsOf(parsed(IMAGES)))) findings.push(found('HFS_SBOM_MISSING', IMAGES, 'The images workflow must generate an SBOM and provenance for its release images in enabled steps.'));
-  findings.push(...workflowFindings({ files: [...tracked].filter((file) => inScope(file)), read: (file) => readText(repoRoot, file) }, workflowPinFindings));
-  return findings;
+    if (repo?.kind !== 'app' || !['lite', 'full'].some((value) => value === repo.edition) || isRoot === false)
+        return [];
+    const tracked = new Set(all);
+    const parsed = (file) => tracked.has(file) ? parseWorkflow(readText(repoRoot, file) ?? '') : null;
+    const findings = [];
+    if (inScope(DEPENDABOT) && !hasDependabot(parsed(DEPENDABOT)))
+        findings.push(found('HFS_DEPENDABOT_MISSING', DEPENDABOT, 'Declare Dependabot version 2 updates for npm, github-actions and docker, each with a directory and schedule; every npm update must group minor+patch version updates, restrict every group to minor/patch (never major), include a security-updates group, and ignore all @starci/* updates (canon pins move only by starci upgrade).'));
+    if (inScope(CI) && !hasAudit(stepsOf(parsed(CI))))
+        findings.push(found('HFS_AUDIT_STEP_MISSING', CI, 'CI must run npm audit --omit=dev in an enabled step whose failure stops the job.'));
+    if (inScope(IMAGES) && !imageEvidence(stepsOf(parsed(IMAGES))))
+        findings.push(found('HFS_SBOM_MISSING', IMAGES, 'The images workflow must generate an SBOM and provenance for its release images in enabled steps.'));
+    findings.push(...workflowFindings({ files: [...tracked].filter((file) => inScope(file)), read: (file) => readText(repoRoot, file) }, workflowPinFindings));
+    return findings;
 }

package/runtime/scripts/hfs/rules/test-topology.d.mts

@@ -0,0 +1,5 @@
+/** The findings of R47 over the tracked paths `files` of a back-end repository at `repoRoot`. */
+export declare function testTopologyFindings({ repoRoot, files }: {
+    repoRoot: string;
+    files: string[];
+}): import("./rule-types.mts").Finding[];

package/runtime/scripts/hfs/rules/test-topology.mjs

@@ -7,39 +7,41 @@
 // (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';
-
 const TEST_TOPOLOGY = 'BE_TEST_TOPOLOGY';
 const DOT_TEST = /\.test\.[cm]?[jt]sx?$/;
 const JEST_CONFIG_NAMED = /(?:^|\/)jest(?:\.[^/]+)?\.config(?:\.[^/]+)?\.(?:[cm]?[jt]s|json)$/;
 const JEST_CONFIG_ANY_EXTENSION = /(?:^|\/)jest\.config\.[^/]+$/;
 const ROOT_JEST_CONFIG = 'jest.config.js';
-
 const isJestConfig = (file) => JEST_CONFIG_NAMED.test(file) || JEST_CONFIG_ANY_EXTENSION.test(file);
-
 /** The finding of the tracked file's own path, else null. */
 function pathFinding(file) {
-  if (DOT_TEST.test(file)) return found(TEST_TOPOLOGY, file, `${file} is a \`.test\` file; a unit spec is <name>.spec.ts beside its subject and an integration, e2e or contract spec is *.integration-spec.ts, *.e2e-spec.ts or *.contract-spec.ts under its own src/tests folder`);
-  if (file.split('/').slice(0, -1).includes('testing')) return found(TEST_TOPOLOGY, file, `${file} sits in a testing/ folder; doubles and builders live in src/tests/fixtures/ and specs sit beside their subject`);
-  if (isJestConfig(file) && file !== ROOT_JEST_CONFIG) return found(TEST_TOPOLOGY, file, `${file} is a second jest configuration; the one root ${ROOT_JEST_CONFIG} declares the projects unit, integration, e2e and contract`);
-  return null;
+    if (DOT_TEST.test(file))
+        return found(TEST_TOPOLOGY, file, `${file} is a \`.test\` file; a unit spec is <name>.spec.ts beside its subject and an integration, e2e or contract spec is *.integration-spec.ts, *.e2e-spec.ts or *.contract-spec.ts under its own src/tests folder`);
+    if (file.split('/').slice(0, -1).includes('testing'))
+        return found(TEST_TOPOLOGY, file, `${file} sits in a testing/ folder; doubles and builders live in src/tests/fixtures/ and specs sit beside their subject`);
+    if (isJestConfig(file) && file !== ROOT_JEST_CONFIG)
+        return found(TEST_TOPOLOGY, file, `${file} is a second jest configuration; the one root ${ROOT_JEST_CONFIG} declares the projects unit, integration, e2e and contract`);
+    return null;
 }
-
 /** The finding of a package.json that carries a `jest` key, else null. */
 function packageFinding(repoRoot, file) {
-  if (file !== 'package.json' && !file.endsWith('/package.json')) return null;
-  if (file.includes('node_modules/')) return null;
-  const pkg = readJson(repoRoot, file);
-  return pkg && Object.hasOwn(pkg, 'jest') ? found(TEST_TOPOLOGY, file, `${file} carries a jest key; jest is configured only by the root ${ROOT_JEST_CONFIG}`) : null;
+    if (file !== 'package.json' && !file.endsWith('/package.json'))
+        return null;
+    if (file.includes('node_modules/'))
+        return null;
+    const pkg = readJson(repoRoot, file);
+    return pkg && Object.hasOwn(pkg, 'jest') ? found(TEST_TOPOLOGY, file, `${file} carries a jest key; jest is configured only by the root ${ROOT_JEST_CONFIG}`) : null;
 }
-
 /** The findings of R47 over the tracked paths `files` of a back-end repository at `repoRoot`. */
 export function testTopologyFindings({ repoRoot, files }) {
-  const findings = [];
-  for (const file of files) {
-    const own = pathFinding(file);
-    if (own) findings.push(own);
-    const packaged = packageFinding(repoRoot, file);
-    if (packaged) findings.push(packaged);
-  }
-  return findings;
+    const findings = [];
+    for (const file of files) {
+        const own = pathFinding(file);
+        if (own)
+            findings.push(own);
+        const packaged = packageFinding(repoRoot, file);
+        if (packaged)
+            findings.push(packaged);
+    }
+    return findings;
 }