@starci/hfs 4.11.22 → 4.12.0

package/runtime/scripts/hfs/rules/release-provenance.mjs

@@ -10,205 +10,242 @@ import { revParseQuery } from '../../api/git/rev-parse-query.mjs';
 import { tag } from '../../api/git/tag.mjs';
 import { gitOutputOf, withoutGitLocalEnv } from '../../lib/git.mjs';
 import { found, readJson, readText } from './read.mjs';
-
 export const HFS_RELEASE_TAG_MISMATCH = 'HFS_RELEASE_TAG_MISMATCH';
 export const HFS_DB_DEPLOY_UNGUARDED = 'HFS_DB_DEPLOY_UNGUARDED';
-const SEMVER_NUMBER = String.raw`(?:0|[1-9]\d*)`;
-const SEMVER_PRERELEASE_ID = String.raw`(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)`;
+const SEMVER_NUMBER = String.raw `(?:0|[1-9]\d*)`;
+const SEMVER_PRERELEASE_ID = String.raw `(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)`;
 const SEMVER_BUILD_ID = '[0-9A-Za-z-]+';
-const SEMVER = new RegExp(String.raw`^${SEMVER_NUMBER}\.${SEMVER_NUMBER}\.${SEMVER_NUMBER}(?:-${SEMVER_PRERELEASE_ID}(?:\.${SEMVER_PRERELEASE_ID})*)?(?:\+${SEMVER_BUILD_ID}(?:\.${SEMVER_BUILD_ID})*)?$`);
+const SEMVER = new RegExp(String.raw `^${SEMVER_NUMBER}\.${SEMVER_NUMBER}\.${SEMVER_NUMBER}(?:-${SEMVER_PRERELEASE_ID}(?:\.${SEMVER_PRERELEASE_ID})*)?(?:\+${SEMVER_BUILD_ID}(?:\.${SEMVER_BUILD_ID})*)?$`);
 const WORKFLOW = /^\.github\/workflows\/(images|db-deploy)\.ya?ml$/;
 const TAG = 1;
 const VERSION_PREFIX = 2;
 const RELEASE_REF = TAG | VERSION_PREFIX;
-
 function gitTags(repoRoot, env) {
-  const options = { cwd: repoRoot, env: withoutGitLocalEnv(env), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000, maxBuffer: 64 * 1024, windowsHide: true };
-  try {
-    // A nested example belongs to its own product, never to an ancestor runtime's tags.
-    const top = gitOutputOf(revParseQuery(['--show-toplevel'], options)).trim();
-    if (path.relative(fs.realpathSync(top), fs.realpathSync(repoRoot)) !== '') return [];
-    const tags = gitOutputOf(tag(['--points-at', 'HEAD'], options)).trim().split(/\r?\n/).filter((value) => value.startsWith('v'));
-    if (env.GITHUB_ACTIONS === 'true' && env.GITHUB_REF?.startsWith('refs/tags/v')) tags.push(env.GITHUB_REF.slice('refs/tags/'.length));
-    return [...new Set(tags)];
-  } catch { return []; }
-}
-
+    const options = { cwd: repoRoot, env: withoutGitLocalEnv(env), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000, maxBuffer: 64 * 1024, windowsHide: true };
+    try {
+        // A nested example belongs to its own product, never to an ancestor runtime's tags.
+        const top = gitOutputOf(revParseQuery(['--show-toplevel'], options)).trim();
+        if (path.relative(fs.realpathSync(top), fs.realpathSync(repoRoot)) !== '')
+            return [];
+        const tags = gitOutputOf(tag(['--points-at', 'HEAD'], options)).trim().split(/\r?\n/).filter((value) => value.startsWith('v'));
+        if (env.GITHUB_ACTIONS === 'true' && env.GITHUB_REF?.startsWith('refs/tags/v'))
+            tags.push(env.GITHUB_REF.slice('refs/tags/'.length));
+        return [...new Set(tags)];
+    }
+    catch {
+        return [];
+    }
+}
 function tagFindings(repoRoot, version, env) {
-  return gitTags(repoRoot, env).filter((tag) => !SEMVER.test(tag.slice(1)) || tag.slice(1) !== version)
-    .map((tag) => found(HFS_RELEASE_TAG_MISMATCH, 'package.json', 'the release tag at HEAD must be v<semver> and equal the root package.json version; align the version before cutting the release', { tag, version: typeof version === 'string' ? version : null }));
+    return gitTags(repoRoot, env).filter((tag) => !SEMVER.test(tag.slice(1)) || tag.slice(1) !== version)
+        .map((tag) => found(HFS_RELEASE_TAG_MISMATCH, 'package.json', 'the release tag at HEAD must be v<semver> and equal the root package.json version; align the version before cutting the release', { tag, version: typeof version === 'string' ? version : null }));
 }
-
 // Split only outside strings/function calls; arbitrary expressions remain unproved atoms.
 function splitBoolean(expression, operator) {
-  const parts = [];
-  let start = 0, depth = 0, quote = '';
-  for (let i = 0; i < expression.length; i += 1) {
-    const char = expression[i];
-    if (quote) { if (char === quote) { quote = ''; } continue; }
-    if (char === "'" || char === '"') { quote = char; continue; }
-    if (char === '(') depth += 1;
-    if (char === ')') depth -= 1;
-    if (depth === 0 && expression.slice(i, i + 2) === operator) { parts.push(expression.slice(start, i)); start = i + 2; i += 1; }
-  }
-  parts.push(expression.slice(start));
-  return parts;
-}
-
+    const parts = [];
+    let start = 0, depth = 0, quote = '';
+    for (let i = 0; i < expression.length; i += 1) {
+        const char = expression[i];
+        if (quote) {
+            if (char === quote) {
+                quote = '';
+            }
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char;
+            continue;
+        }
+        if (char === '(')
+            depth += 1;
+        if (char === ')')
+            depth -= 1;
+        if (depth === 0 && expression.slice(i, i + 2) === operator) {
+            parts.push(expression.slice(start, i));
+            start = i + 2;
+            i += 1;
+        }
+    }
+    parts.push(expression.slice(start));
+    return parts;
+}
 function enclosingParentheses(text) {
-  let depth = 0, quote = '';
-  for (let i = 0; i < text.length - 1; i += 1) {
-    const char = text[i];
-    if (quote) { if (char === quote) { quote = ''; } continue; }
-    if (char === "'" || char === '"') { quote = char; continue; }
-    if (char === '(') depth += 1;
-    if (char === ')' && --depth === 0) return false;
-  }
-  return true;
-}
-
+    let depth = 0, quote = '';
+    for (let i = 0; i < text.length - 1; i += 1) {
+        const char = text[i];
+        if (quote) {
+            if (char === quote) {
+                quote = '';
+            }
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char;
+            continue;
+        }
+        if (char === '(')
+            depth += 1;
+        if (char === ')' && --depth === 0)
+            return false;
+    }
+    return true;
+}
 function unwrap(expression) {
-  let text = expression.trim();
-  while (text.startsWith('(') && text.endsWith(')') && enclosingParentheses(text)) text = text.slice(1, -1).trim();
-  return text;
+    let text = expression.trim();
+    while (text.startsWith('(') && text.endsWith(')') && enclosingParentheses(text))
+        text = text.slice(1, -1).trim();
+    return text;
 }
-
 function workflowExpression(value) {
-  const text = value.trim();
-  return text.startsWith('${{') && text.endsWith('}}') ? text.slice(3, -2).trim() : text;
+    const text = value.trim();
+    return text.startsWith('${{') && text.endsWith('}}') ? text.slice(3, -2).trim() : text;
 }
-
 function refProof(value) {
-  if (typeof value !== 'string') return 0;
-  const expression = unwrap(workflowExpression(value));
-  const alternatives = splitBoolean(expression, '||');
-  if (alternatives.length > 1) return alternatives.map(refProof).reduce((a, b) => a & b, RELEASE_REF);
-  const conjuncts = splitBoolean(expression, '&&');
-  if (conjuncts.length > 1) return conjuncts.map(refProof).reduce((a, b) => a | b, 0);
-  if (/^startsWith\(\s*github\.ref\s*,\s*(['"])refs\/tags\/v\1\s*\)$/.test(expression)) return RELEASE_REF;
-  const exact = /^github\.ref\s*==\s*(['"])refs\/tags\/v([^'"\s]+)\1$/.exec(expression);
-  if (exact && SEMVER.test(exact[2])) return RELEASE_REF;
-  if (/^(?:github\.ref_type\s*==\s*(['"])tag\1|(['"])tag\2\s*==\s*github\.ref_type)$/.test(expression)) return TAG;
-  if (/^startsWith\(\s*github\.ref_name\s*,\s*(['"])v\1\s*\)$/.test(expression)) return VERSION_PREFIX;
-  return 0;
-}
-
+    if (typeof value !== 'string')
+        return 0;
+    const expression = unwrap(workflowExpression(value));
+    const alternatives = splitBoolean(expression, '||');
+    if (alternatives.length > 1)
+        return alternatives.map(refProof).reduce((a, b) => a & b, RELEASE_REF);
+    const conjuncts = splitBoolean(expression, '&&');
+    if (conjuncts.length > 1)
+        return conjuncts.map(refProof).reduce((a, b) => a | b, 0);
+    if (/^startsWith\(\s*github\.ref\s*,\s*(['"])refs\/tags\/v\1\s*\)$/.test(expression))
+        return RELEASE_REF;
+    const exact = /^github\.ref\s*==\s*(['"])refs\/tags\/v([^'"\s]+)\1$/.exec(expression);
+    if (exact && SEMVER.test(exact[2]))
+        return RELEASE_REF;
+    if (/^(?:github\.ref_type\s*==\s*(['"])tag\1|(['"])tag\2\s*==\s*github\.ref_type)$/.test(expression))
+        return TAG;
+    if (/^startsWith\(\s*github\.ref_name\s*,\s*(['"])v\1\s*\)$/.test(expression))
+        return VERSION_PREFIX;
+    return 0;
+}
 function tagOnlyTrigger(workflow) {
-  const events = workflow.on;
-  if (!events || typeof events !== 'object' || Array.isArray(events) || Object.keys(events).join() !== 'push') return false;
-  const push = events.push;
-  if (!push || typeof push !== 'object' || push.branches || push['branches-ignore'] || push['tags-ignore']) return false;
-  const tags = Array.isArray(push.tags) ? push.tags : [];
-  const included = tags.filter((tag) => typeof tag === 'string' && !tag.startsWith('!'));
-  return included.length > 0 && included.every((tag) => tag.startsWith('v'));
-}
-
+    const events = workflow.on;
+    if (!events || typeof events !== 'object' || Array.isArray(events) || Object.keys(events).join() !== 'push')
+        return false;
+    const push = events.push;
+    if (!push || typeof push !== 'object' || push.branches || push['branches-ignore'] || push['tags-ignore'])
+        return false;
+    const tags = Array.isArray(push.tags) ? push.tags : [];
+    const included = tags.filter((tag) => typeof tag === 'string' && !tag.startsWith('!'));
+    return included.length > 0 && included.every((tag) => tag.startsWith('v'));
+}
 function shellTagGuard(step) {
-  if (step.if !== undefined || step['continue-on-error'] || typeof step.run !== 'string') return false;
-  const command = step.run.trim().replace(/^set -[a-z]+(?:\s+pipefail)?\s*\n/, '').trim();
-  // The whole guard step must reject a non-release ref; a nested, commented or later guard is insufficient.
-  return /^\[\[\s*["']?\$(?:GITHUB_REF|\{GITHUB_REF\})["']?\s*==\s*refs\/tags\/v\*\s*\]\]\s*\|\|\s*exit\s+[1-9]\d*\s*;?$/.test(command)
-    || /^case\s+["']?\$(?:GITHUB_REF|\{GITHUB_REF\})["']?\s+in\s+refs\/tags\/v\*\)\s*;;\s*\*\)\s*exit\s+[1-9]\d*\s*;;\s*esac\s*;?$/.test(command);
+    if (step.if !== undefined || step['continue-on-error'] || typeof step.run !== 'string')
+        return false;
+    const command = step.run.trim().replace(/^set -[a-z]+(?:\s+pipefail)?\s*\n/, '').trim();
+    // The whole guard step must reject a non-release ref; a nested, commented or later guard is insufficient.
+    return /^\[\[\s*["']?\$(?:GITHUB_REF|\{GITHUB_REF\})["']?\s*==\s*refs\/tags\/v\*\s*\]\]\s*\|\|\s*exit\s+[1-9]\d*\s*;?$/.test(command)
+        || /^case\s+["']?\$(?:GITHUB_REF|\{GITHUB_REF\})["']?\s+in\s+refs\/tags\/v\*\)\s*;;\s*\*\)\s*exit\s+[1-9]\d*\s*;;\s*esac\s*;?$/.test(command);
 }
-
 function checkoutPreservesRef(job) {
-  return (job.steps ?? []).filter((step) => (step.uses ?? '').startsWith('actions/checkout@')).every((step) => {
-    const ref = step.with?.ref;
-    return ref === undefined || /^\$\{\{\s*github\.(?:ref|ref_name|sha)\s*\}\}$/.test(String(ref));
-  });
+    return (job.steps ?? []).filter((step) => (step.uses ?? '').startsWith('actions/checkout@')).every((step) => {
+        const ref = step.with?.ref;
+        return ref === undefined || /^\$\{\{\s*github\.(?:ref|ref_name|sha)\s*\}\}$/.test(String(ref));
+    });
 }
-
 function setupStep(step) {
-  return /^(?:actions\/checkout|actions\/setup-node)@/.test(step.uses ?? '')
-    || (typeof step.run === 'string' && /^npm ci --ignore-scripts\s*$/.test(step.run.trim()));
+    return /^(?:actions\/checkout|actions\/setup-node)@/.test(step.uses ?? '')
+        || (typeof step.run === 'string' && /^npm ci --ignore-scripts\s*$/.test(step.run.trim()));
 }
-
 function unguardedDeployStep(step, shellGuarded, guarded) {
-  // Checkout, Node setup and script-disabled npm install may precede the guard. Opaque commands may deploy.
-  // A later always()/failure() step can run despite the rejecting shell guard's failure.
-  const shellConstrained = shellGuarded && !/\b(?:always|failure|cancelled)\s*\(/.test(String(step.if ?? ''));
-  return (step.run || step.uses) && !setupStep(step) && !guarded && !shellConstrained && refProof(step.if) !== RELEASE_REF;
+    // Checkout, Node setup and script-disabled npm install may precede the guard. Opaque commands may deploy.
+    // A later always()/failure() step can run despite the rejecting shell guard's failure.
+    const shellConstrained = shellGuarded && !/\b(?:always|failure|cancelled)\s*\(/.test(String(step.if ?? ''));
+    return (step.run || step.uses) && !setupStep(step) && !guarded && !shellConstrained && refProof(step.if) !== RELEASE_REF;
 }
-
 function dbJobConstrained(job, guarded) {
-  let shellGuarded = false;
-  let constrained = !job.uses || guarded;
-  for (const step of job.steps ?? []) {
-    if (shellTagGuard(step)) { shellGuarded = true; continue; }
-    if (unguardedDeployStep(step, shellGuarded, guarded)) constrained = false;
-  }
-  if (!job.uses && !(job.steps ?? []).some((step) => step.run || step.uses)) constrained = false;
-  return constrained;
-}
-
+    let shellGuarded = false;
+    let constrained = !job.uses || guarded;
+    for (const step of job.steps ?? []) {
+        if (shellTagGuard(step)) {
+            shellGuarded = true;
+            continue;
+        }
+        if (unguardedDeployStep(step, shellGuarded, guarded))
+            constrained = false;
+    }
+    if (!job.uses && !(job.steps ?? []).some((step) => step.run || step.uses))
+        constrained = false;
+    return constrained;
+}
 function dbFindings(file, workflow) {
-  const jobs = Object.entries(workflow.jobs ?? {});
-  if (!jobs.length) return [found(HFS_DB_DEPLOY_UNGUARDED, file, `${file} has no verifiable database deploy job; require a release tag before migration`)];
-  const findings = [];
-  for (const [name, job] of jobs) {
-    if (!job || typeof job !== 'object') continue;
-    const guarded = tagOnlyTrigger(workflow) || refProof(job.if) === RELEASE_REF;
-    const constrained = dbJobConstrained(job, guarded);
-    if (!constrained || !checkoutPreservesRef(job)) findings.push(found(HFS_DB_DEPLOY_UNGUARDED, file, `${file} job ${name} can deploy a non-release ref; require refs/tags/v at the job or before any deploy command, and check out that ref`, { job: name }));
-  }
-  return findings;
-}
-
+    const jobs = Object.entries(workflow.jobs ?? {});
+    if (!jobs.length)
+        return [found(HFS_DB_DEPLOY_UNGUARDED, file, `${file} has no verifiable database deploy job; require a release tag before migration`)];
+    const findings = [];
+    for (const [name, job] of jobs) {
+        if (!job || typeof job !== 'object')
+            continue;
+        const guarded = tagOnlyTrigger(workflow) || refProof(job.if) === RELEASE_REF;
+        const constrained = dbJobConstrained(job, guarded);
+        if (!constrained || !checkoutPreservesRef(job))
+            findings.push(found(HFS_DB_DEPLOY_UNGUARDED, file, `${file} job ${name} can deploy a non-release ref; require refs/tags/v at the job or before any deploy command, and check out that ref`, { job: name }));
+    }
+    return findings;
+}
 function validJob(job) {
-  return isPlainObject(job) && (job.steps === undefined || (Array.isArray(job.steps) && job.steps.every(isPlainObject)));
+    return isPlainObject(job) && (job.steps === undefined || (Array.isArray(job.steps) && job.steps.every(isPlainObject)));
 }
-
 function validWorkflow(workflow) {
-  return isPlainObject(workflow) && isPlainObject(workflow.jobs) && Object.values(workflow.jobs).every(validJob);
+    return isPlainObject(workflow) && isPlainObject(workflow.jobs) && Object.values(workflow.jobs).every(validJob);
 }
-
 function imageTagIsRelease(value, version) {
-  if (typeof value !== 'string') return false;
-  const tags = value.split(/[\n,]+/).map((tag) => tag.trim()).filter(Boolean);
-  return tags.length > 0 && tags.every((tag) => {
-    const ref = tag.replace(/\$\{\{\s*github\.ref_name\s*\}\}/g, '<release-ref>');
-    if (ref.endsWith(':<release-ref>')) return true;
-    return SEMVER.test(String(version)) && ref.endsWith(`:v${version}`);
-  });
-}
-
+    if (typeof value !== 'string')
+        return false;
+    const tags = value.split(/[\n,]+/).map((tag) => tag.trim()).filter(Boolean);
+    return tags.length > 0 && tags.every((tag) => {
+        const ref = tag.replace(/\$\{\{\s*github\.ref_name\s*\}\}/g, '<release-ref>');
+        if (ref.endsWith(':<release-ref>'))
+            return true;
+        return SEMVER.test(String(version)) && ref.endsWith(`:v${version}`);
+    });
+}
 function imageFindings(file, workflow, version) {
-  const findings = [];
-  let builds = 0;
-  for (const [name, job] of Object.entries(workflow.jobs ?? {})) {
-    for (const step of job?.steps ?? []) {
-      if (!(step.uses ?? '').startsWith('docker/build-push-action@')) continue;
-      builds += 1;
-      const guarded = tagOnlyTrigger(workflow) || refProof(job.if) === RELEASE_REF || refProof(step.if) === RELEASE_REF;
-      if (!guarded || !checkoutPreservesRef(job) || !imageTagIsRelease(step.with?.tags, version)) findings.push(found(HFS_RELEASE_TAG_MISMATCH, file, `${file} job ${name} must build the checked-out release ref and tag every image with v<package.json version> or github.ref_name under a release-tag guard`, { job: name }));
+    const findings = [];
+    let builds = 0;
+    for (const [name, job] of Object.entries(workflow.jobs ?? {})) {
+        for (const step of job?.steps ?? []) {
+            if (!(step.uses ?? '').startsWith('docker/build-push-action@'))
+                continue;
+            builds += 1;
+            const guarded = tagOnlyTrigger(workflow) || refProof(job.if) === RELEASE_REF || refProof(step.if) === RELEASE_REF;
+            if (!guarded || !checkoutPreservesRef(job) || !imageTagIsRelease(step.with?.tags, version))
+                findings.push(found(HFS_RELEASE_TAG_MISMATCH, file, `${file} job ${name} must build the checked-out release ref and tag every image with v<package.json version> or github.ref_name under a release-tag guard`, { job: name }));
+        }
     }
-  }
-  if (!builds) findings.push(found(HFS_RELEASE_TAG_MISMATCH, file, `${file} has no verifiable release image tags; declare docker/build-push-action tags from the release ref`));
-  return findings;
+    if (!builds)
+        findings.push(found(HFS_RELEASE_TAG_MISMATCH, file, `${file} has no verifiable release image tags; declare docker/build-push-action tags from the release ref`));
+    return findings;
 }
-
 function productRoot(repo, isRoot) {
-  return isRoot !== false && !['be', 'fe', 'runtime'].includes(repo.profile)
-    && (!repo.kind || repo.kind === 'app') && ['lite', 'full'].includes(repo.edition ?? 'full');
+    return isRoot !== false && !['be', 'fe', 'runtime'].some((value) => value === repo.profile)
+        && (!repo.kind || repo.kind === 'app') && ['lite', 'full'].includes(repo.edition ?? 'full');
 }
-
 /** Synchronous product-root provenance findings; root and workflows are judged in lite and full, never a side or runtime. */
 export function releaseProvenanceFindings({ repoRoot, files = [], repo = {}, isRoot, inScope = () => true, env = process.env } = {}) {
-  if (!productRoot(repo, isRoot)) return [];
-  const version = readJson(repoRoot, 'package.json')?.version;
-  const packageInScope = files.includes('package.json') && inScope('package.json');
-  const findings = packageInScope ? tagFindings(repoRoot, version, env) : [];
-  for (const file of files) {
-    const match = WORKFLOW.exec(file);
-    if (!match || (!inScope(file) && !packageInScope)) continue;
-    const code = match[1] === 'images' ? HFS_RELEASE_TAG_MISMATCH : HFS_DB_DEPLOY_UNGUARDED;
-    let workflow;
-    try { workflow = parseYaml(readText(repoRoot, file) ?? ''); } catch { /* unreadable YAML cannot prove a release */ }
-    if (!validWorkflow(workflow)) {
-      findings.push(found(code, file, `${file} cannot be parsed as a workflow; restore its release tag checks`));
-      continue;
+    if (!productRoot(repo, isRoot))
+        return [];
+    const version = readJson(repoRoot, 'package.json')?.version;
+    const packageInScope = files.includes('package.json') && inScope('package.json');
+    const findings = packageInScope ? tagFindings(repoRoot, version, env) : [];
+    for (const file of files) {
+        const match = WORKFLOW.exec(file);
+        if (!match || (!inScope(file) && !packageInScope))
+            continue;
+        const code = match[1] === 'images' ? HFS_RELEASE_TAG_MISMATCH : HFS_DB_DEPLOY_UNGUARDED;
+        let workflow;
+        try {
+            workflow = parseYaml(readText(repoRoot, file) ?? '');
+        }
+        catch { /* unreadable YAML cannot prove a release */ }
+        if (!validWorkflow(workflow)) {
+            findings.push(found(code, file, `${file} cannot be parsed as a workflow; restore its release tag checks`));
+            continue;
+        }
+        findings.push(...(match[1] === 'images' ? imageFindings(file, workflow, version) : dbFindings(file, workflow)));
     }
-    findings.push(...(match[1] === 'images' ? imageFindings(file, workflow, version) : dbFindings(file, workflow)));
-  }
-  return findings;
+    return findings;
 }

package/runtime/scripts/hfs/rules/repo-local-checks.d.mts

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

package/runtime/scripts/hfs/rules/repo-local-checks.mjs

@@ -8,30 +8,32 @@
 // swaps the configuration (HFS_TOOL_CONFIG_LOCAL, R16), and an eslint.config that differs from the render, a relative import of a local plugin
 // included (HFS_RULE_OFF_WITHOUT_REPLACEMENT, R17). This rule adds the forbidden roles by name: what a check or a rule file is called.
 import { found, readJson } from './read.mjs';
-
 const REPO_LOCAL_CHECK = 'HFS_REPO_LOCAL_CHECK';
 const LOCAL_RULE_FILE = /(?:^|\/)(?:eslint-local-rules|eslint-plugin|eslint-local-plugin)[^/]*(?:\/|$)|(?:^|\/)(?:eslint-rules|lint-rules)\//;
 const CHECK_SCRIPT = /(?:^|\/)(?:scripts|tools)\/check-[^/]+$/;
 const RUNS_CHECK = /(?:^|[\s&|;(])(?:\.\/)?(?:scripts|tools)\/check-[^\s&|;)]+/;
-
 /** The findings of the package.json scripts of `file` that run a repository-local check. */
 function scriptFindings(repoRoot, file) {
-  const findings = [];
-  const pkg = readJson(repoRoot, file);
-  for (const [name, command] of Object.entries(pkg?.scripts ?? {})) {
-    if (RUNS_CHECK.test(String(command))) findings.push(found(REPO_LOCAL_CHECK, file, `${file} script ${name} runs a repository-local check (${String(command).slice(0, 80)}); delete the script, the check belongs to the .claude runtime`));
-  }
-  return findings;
+    const findings = [];
+    const pkg = readJson(repoRoot, file);
+    for (const [name, command] of Object.entries(pkg?.scripts ?? {})) {
+        if (RUNS_CHECK.test(String(command)))
+            findings.push(found(REPO_LOCAL_CHECK, file, `${file} script ${name} runs a repository-local check (${String(command).slice(0, 80)}); delete the script, the check belongs to the .claude runtime`));
+    }
+    return findings;
 }
-
 /** The findings of R103 over the tracked paths `files` of the repository at `repoRoot`. */
 export function repoLocalCheckFindings({ repoRoot, files }) {
-  const findings = [];
-  for (const file of files) {
-    if (file.includes('node_modules/')) continue;
-    if (LOCAL_RULE_FILE.test(file)) findings.push(found(REPO_LOCAL_CHECK, file, `${file} is a local lint rule or plugin; a repository keeps no rule of its own: the rule is proposed to the canon (@starci/eslint-canon-*) in the .claude runtime`));
-    else if (CHECK_SCRIPT.test(file)) findings.push(found(REPO_LOCAL_CHECK, file, `${file} is a check kept in the repository; every check lives in the .claude runtime (starci app check, the canons), so a repository has none to keep`));
-    else if (file === 'package.json' || file.endsWith('/package.json')) findings.push(...scriptFindings(repoRoot, file));
-  }
-  return findings;
+    const findings = [];
+    for (const file of files) {
+        if (file.includes('node_modules/'))
+            continue;
+        if (LOCAL_RULE_FILE.test(file))
+            findings.push(found(REPO_LOCAL_CHECK, file, `${file} is a local lint rule or plugin; a repository keeps no rule of its own: the rule is proposed to the canon (@starci/eslint-canon-*) in the .claude runtime`));
+        else if (CHECK_SCRIPT.test(file))
+            findings.push(found(REPO_LOCAL_CHECK, file, `${file} is a check kept in the repository; every check lives in the .claude runtime (starci app check, the canons), so a repository has none to keep`));
+        else if (file === 'package.json' || file.endsWith('/package.json'))
+            findings.push(...scriptFindings(repoRoot, file));
+    }
+    return findings;
 }

package/runtime/scripts/hfs/rules/rule-types.d.mts

@@ -0,0 +1,40 @@
+/** A value parsed from disk (JSON, YAML, a SQL or TypeScript AST node) whose shape the reading rule judges itself. */
+export type Parsed = any;
+/** The TypeScript compiler API module, as `loadTypescript(repoRoot, here)` returns it. */
+export type Ts = typeof import('typescript');
+/** One finding of a rule: its code, level, file and message, plus the rule's own fields. */
+export interface Finding {
+    code: string;
+    level: string;
+    path: string;
+    message: string;
+    [field: string]: unknown;
+}
+/** What a rule reads of the declaration (hfs.json) of the repository it judges. */
+export interface Repo {
+    profile?: string;
+    edition?: string | undefined;
+    apps?: readonly Parsed[];
+    sides?: Record<string, Parsed>;
+    [field: string]: Parsed;
+}
+/** The slot resolver of a repository (scripts/hfs/slots.mjs): classification of a path, slot lookup, ownership. */
+export interface Resolver {
+    sides?: Record<string, Resolver>;
+    classifyPath(file: string): Parsed;
+    slot(name: string): Parsed;
+    [member: string]: Parsed;
+}
+/** The context `starci app check` passes to every finder of a rule. */
+export interface RuleContext {
+    repoRoot: string;
+    files: string[];
+    all?: string[];
+    repo: Repo;
+    resolver: Resolver;
+    manifest: Parsed;
+    isRoot?: boolean;
+    inScope?: (file: string) => boolean;
+}
+/** A finder: the findings of one rule over one repository. */
+export type Finder = (context: RuleContext) => Finding[];

package/runtime/scripts/hfs/rules/rule-types.mjs

@@ -0,0 +1,4 @@
+// rule-types.mts - the shapes the hfs content rules (scripts/hfs/rules, runtime-rules) share. Types only, no runtime code.
+// The declaration read from hfs.json, the slot resolver and the parsed documents (YAML, JSON, SQL ASTs, compiler nodes)
+// are judged by the rules themselves, so they enter as `Parsed`: the one parsed-input boundary of this area.
+export {};

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

@@ -0,0 +1,2 @@
+import type { Parsed, Ts } from './rule-types.mjs';
+export declare function forwardsDeliveryKey(ts: Ts, source: Parsed): boolean;