@starci/hfs 4.11.22 → 4.12.2

package/runtime/scripts/hfs/ci-declaration.d.mts

@@ -0,0 +1,77 @@
+import type { Dirent } from 'node:fs';
+type ParsedDoc = any;
+/** The synchronous filesystem seam the caller injects. */
+export interface CiFsSeam {
+    readdirSync(dir: string, options: {
+        withFileTypes: true;
+    }): Dirent[];
+    readFileSync(file: string, encoding: 'utf8'): string;
+}
+export interface CiProblem {
+    code: 'CI_DECLARATION_INVALID';
+    at: string;
+    message: string;
+}
+export interface CiEntry {
+    name: unknown;
+    scope: unknown;
+    environment: unknown;
+    purpose: unknown;
+    optional: boolean;
+    value?: unknown;
+    ownerValue?: boolean;
+}
+export interface CiDeclaration {
+    secrets: CiEntry[];
+    vars: CiEntry[];
+    dependabotSecrets: CiEntry[];
+    problems: CiProblem[];
+}
+/** An entry of a declaration readCiDeclaration found no problem in: an uppercase name, its scope, and the environment an environment scope names (else null). */
+export type ValidCiEntry = CiEntry & {
+    name: string;
+} & ({
+    scope: 'repository';
+    environment: null;
+} | {
+    scope: 'environment';
+    environment: string;
+});
+/** A CI declaration without problems, so every entry is valid. */
+export interface ValidCiDeclaration extends CiDeclaration {
+    secrets: ValidCiEntry[];
+    vars: ValidCiEntry[];
+    dependabotSecrets: ValidCiEntry[];
+}
+/** True when readCiDeclaration found no problem in `declaration`. */
+export declare const isValidCiDeclaration: (declaration: CiDeclaration) => declaration is ValidCiDeclaration;
+/** Each CI name belongs to one class and scope; declarations contain names and public configuration only. */
+export declare function readCiDeclaration(doc: ParsedDoc): CiDeclaration;
+/** Missing quality blocks preserve the existing rendered defaults; disabled services remain explicitly disabled. */
+export declare function qualityServices(doc: ParsedDoc, { example }?: {
+    example?: boolean;
+}): ParsedDoc;
+/** Read only encrypted envelope key names, never decrypting or returning any sealed value. */
+export declare function sealedKeyNames(root: string, { fs }: {
+    fs: CiFsSeam;
+}): Array<{
+    env: string;
+    member: string;
+    key: string;
+    file: string;
+}>;
+/** Collect every static secrets and vars reference inside workflow expressions, excluding the automatic GitHub token. */
+export declare function workflowReferences(root: string, { fs }: {
+    fs: CiFsSeam;
+}): Array<{
+    file: string;
+    kind: string;
+    name: string;
+}>;
+/** Service CI bindings name the shared declaration classes, including the readable legacy lists. */
+export declare function ciNamesOfServices(doc: ParsedDoc): Array<{
+    service: string;
+    name: unknown;
+    kind: 'secret' | 'var';
+}>;
+export {};

package/runtime/scripts/hfs/ci-declaration.mjs

@@ -2,114 +2,126 @@ import path from 'node:path';
 import { isSealedName, memberOfName } from '../lib/sealed-member.mjs';
 import { list } from '../lib/list.mjs';
 import { parseYaml } from '../../engine/yaml.mjs';
-
+/** True when readCiDeclaration found no problem in `declaration`. */
+export const isValidCiDeclaration = (declaration) => declaration.problems.length === 0;
 const nameOf = (item) => typeof item === 'string' ? item : item?.name;
-
 /** A public CI variable declares either a manifest value or an owner-supplied value, never both. */
 function variableProblems(item, at, invalid) {
-  const hasValue = item != null && Object.hasOwn(item, 'value');
-  const hasOwnerValue = item != null && Object.hasOwn(item, 'ownerValue');
-  if (hasValue && hasOwnerValue) invalid(at, 'a variable has either a value or ownerValue');
-  else if (!hasValue && item?.ownerValue !== true) invalid(at, 'a variable needs a value or ownerValue: true');
+    const hasValue = item != null && Object.hasOwn(item, 'value');
+    const hasOwnerValue = item != null && Object.hasOwn(item, 'ownerValue');
+    if (hasValue && hasOwnerValue)
+        invalid(at, 'a variable has either a value or ownerValue');
+    else if (!hasValue && item?.ownerValue !== true)
+        invalid(at, 'a variable needs a value or ownerValue: true');
 }
-
 /** Each CI name belongs to one class and scope; declarations contain names and public configuration only. */
 export function readCiDeclaration(doc) {
-  const problems = [], seen = new Set();
-  const invalid = (at, message) => problems.push({ code: 'CI_DECLARATION_INVALID', at, message });
-  const normalize = (entries, at, dependabot = false, variable = false) => list(entries).map((item, index) => {
-    const where = `${at}[${index}]`, name = item?.name;
-    if (seen.has(name)) invalid(`${where}.name`, 'a name must appear once across all CI classes');
-    seen.add(name);
-    if (typeof name !== 'string' || !/^[A-Z][A-Z0-9_]*$/.test(name) || name.startsWith('GITHUB_')) invalid(`${where}.name`, 'use an uppercase CI name outside the reserved GITHUB_ namespace');
-    const scope = dependabot ? 'repository' : item?.scope;
-    if (!['repository', 'environment'].includes(scope)) invalid(`${where}.scope`, 'scope must be repository or environment');
-    if (scope === 'environment' && (typeof item?.environment !== 'string' || !/^[a-z][a-z0-9-]*$/.test(item.environment))) invalid(`${where}.environment`, 'environment scope requires an environment name');
-    if ((dependabot || scope !== 'environment') && item && Object.hasOwn(item, 'environment')) invalid(`${where}.environment`, 'only environment scope may name an environment');
-    if (variable) variableProblems(item, where, invalid);
-    return { name, scope, environment: item?.environment ?? null, purpose: item?.purpose ?? null,
-      optional: item?.optional === true, ...(variable ? { value: item?.value, ownerValue: item?.ownerValue === true } : {}) };
-  });
-  const ci = doc?.ci;
-  const secrets = normalize(ci?.secrets, 'ci.secrets');
-  const vars = normalize(ci?.vars, 'ci.vars', false, true);
-  const dependabotSecrets = normalize(ci?.dependabot?.secrets, 'ci.dependabot.secrets', true);
-  return { secrets, vars, dependabotSecrets, problems };
+    const problems = [], seen = new Set();
+    const invalid = (at, message) => { problems.push({ code: 'CI_DECLARATION_INVALID', at, message }); };
+    const normalize = (entries, at, dependabot = false, variable = false) => list(entries).map((item, index) => {
+        const where = `${at}[${index}]`, name = item?.name;
+        if (seen.has(name))
+            invalid(`${where}.name`, 'a name must appear once across all CI classes');
+        seen.add(name);
+        if (typeof name !== 'string' || !/^[A-Z][A-Z0-9_]*$/.test(name) || name.startsWith('GITHUB_'))
+            invalid(`${where}.name`, 'use an uppercase CI name outside the reserved GITHUB_ namespace');
+        const scope = dependabot ? 'repository' : item?.scope;
+        if (!['repository', 'environment'].includes(scope))
+            invalid(`${where}.scope`, 'scope must be repository or environment');
+        if (scope === 'environment' && (typeof item?.environment !== 'string' || !/^[a-z][a-z0-9-]*$/.test(item.environment)))
+            invalid(`${where}.environment`, 'environment scope requires an environment name');
+        if ((dependabot || scope !== 'environment') && item && Object.hasOwn(item, 'environment'))
+            invalid(`${where}.environment`, 'only environment scope may name an environment');
+        if (variable)
+            variableProblems(item, where, invalid);
+        return { name, scope, environment: item?.environment ?? null, purpose: item?.purpose ?? null,
+            optional: item?.optional === true, ...(variable ? { value: item?.value, ownerValue: item?.ownerValue === true } : {}) };
+    });
+    const ci = doc?.ci;
+    const secrets = normalize(ci?.secrets, 'ci.secrets');
+    const vars = normalize(ci?.vars, 'ci.vars', false, true);
+    const dependabotSecrets = normalize(ci?.dependabot?.secrets, 'ci.dependabot.secrets', true);
+    return { secrets, vars, dependabotSecrets, problems };
 }
-
 /** Missing quality blocks preserve the existing rendered defaults; disabled services remain explicitly disabled. */
 export function qualityServices(doc, { example = false } = {}) {
-  const services = doc?.services ?? {}, sonar = services.sonar, codecov = services.codecov ?? {};
-  const dependabot = services.dependabot ?? {}, audit = services.audit ?? {};
-  return {
-    sonar: !sonar || sonar.mode === 'disabled' ? null : {
-      provider: sonar.provider, mode: sonar.mode, host: sonar.host?.public || sonar.host?.local || null,
-      organization: sonar.organization ?? null,
-      organizationVar: sonar.ci?.organizationVar ?? (sonar.provider === 'sonarcloud' && (example || list(sonar.runtimeSecrets).length > 0) && !list(sonar.credentials).length ? 'SONAR_ORGANIZATION' : null), projectKey: sonar.projects?.[0]?.key ?? null,
-      qualityGate: sonar.qualityGate ?? (example ? 'starci-quality-lite' : 'starci-quality'), wiring: sonar.ci?.wiring ?? 'required',
-      token: sonar.ci?.token || nameOf(sonar.ci?.secrets?.[0]) || 'SONAR_TOKEN', hostVar: sonar.ci?.hostVar || 'SONAR_HOST_URL',
-    },
-    codecov: { enabled: codecov.mode !== 'disabled', auth: codecov.auth ?? 'oidc', token: codecov.ci?.token ?? null,
-      flag: codecov.flag ?? null, target: codecov.target ?? 100, components: codecov.components ?? 'auto', required: codecov.required ?? true, wiring: codecov.ci?.wiring ?? 'required' },
-    dependabot: { ecosystems: [...(dependabot.ecosystems ?? ['npm', 'github-actions', 'docker'])],
-      schedule: { interval: 'weekly', ...dependabot.schedule }, groups: { minorPatch: 'grouped', major: 'per-package', ...dependabot.groups },
-      ignore: [...(dependabot.ignore ?? ['@starci/*'])], security: dependabot.security ?? 'immediate' },
-    audit: { level: audit.level ?? 'high', omitDev: audit.omitDev ?? true, in: [...(audit.in ?? ['release-gate', 'ci'])] },
-  };
+    const services = doc?.services ?? {}, sonar = services.sonar, codecov = services.codecov ?? {};
+    const dependabot = services.dependabot ?? {}, audit = services.audit ?? {};
+    return {
+        sonar: !sonar || sonar.mode === 'disabled' ? null : {
+            provider: sonar.provider, mode: sonar.mode, host: sonar.host?.public || sonar.host?.local || null,
+            organization: sonar.organization ?? null,
+            organizationVar: sonar.ci?.organizationVar ?? (sonar.provider === 'sonarcloud' && (example || list(sonar.runtimeSecrets).length > 0) && !list(sonar.credentials).length ? 'SONAR_ORGANIZATION' : null), projectKey: sonar.projects?.[0]?.key ?? null,
+            qualityGate: sonar.qualityGate ?? (example ? 'starci-quality-lite' : 'starci-quality'), wiring: sonar.ci?.wiring ?? 'required',
+            token: sonar.ci?.token || nameOf(sonar.ci?.secrets?.[0]) || 'SONAR_TOKEN', hostVar: sonar.ci?.hostVar || 'SONAR_HOST_URL',
+        },
+        codecov: { enabled: codecov.mode !== 'disabled', auth: codecov.auth ?? 'oidc', token: codecov.ci?.token ?? null,
+            flag: codecov.flag ?? null, target: codecov.target ?? 100, components: codecov.components ?? 'auto', required: codecov.required ?? true, wiring: codecov.ci?.wiring ?? 'required' },
+        dependabot: { ecosystems: [...(dependabot.ecosystems ?? ['npm', 'github-actions', 'docker'])],
+            schedule: { interval: 'weekly', ...dependabot.schedule }, groups: { minorPatch: 'grouped', major: 'per-package', ...dependabot.groups },
+            ignore: [...(dependabot.ignore ?? ['@starci/*'])], security: dependabot.security ?? 'immediate' },
+        audit: { level: audit.level ?? 'high', omitDev: audit.omitDev ?? true, in: [...(audit.in ?? ['release-gate', 'ci'])] },
+    };
 }
-
 /** Enumerate a missing directory as empty; all filesystem access uses the caller's injected synchronous seam. */
 function entries(dir, fs) {
-  try { return fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)); }
-  catch (error) {
-    if (error.code === 'ENOENT') return [];
-    throw error;
-  }
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
 }
-
 /** Read only encrypted envelope key names, never decrypting or returning any sealed value. */
 export function sealedKeyNames(root, { fs }) {
-  const out = [], base = path.join(root, '.starcistacks');
-  for (const env of entries(base, fs).filter((entry) => entry.isDirectory())) {
-    for (const member of entries(path.join(base, env.name, 'secrets'), fs).filter((entry) => entry.isFile() && isSealedName(entry.name))) {
-      const file = `.starcistacks/${env.name}/secrets/${member.name}`;
-      const source = fs.readFileSync(path.join(root, file), 'utf8');
-      const dotenv = [...source.matchAll(/^([A-Za-z_]\w*)=ENC\[/gm)].map((match) => match[1]).filter((key) => !key.startsWith('sops_'));
-      let keys = dotenv;
-      if (!dotenv.length) {
-        const doc = parseYaml(source);
-        keys = doc && typeof doc === 'object' && !Array.isArray(doc) ? Object.keys(doc).filter((key) => key !== 'sops' && !key.startsWith('sops_')) : [];
-      }
-      for (const key of keys) out.push({ env: env.name, member: memberOfName(member.name), key, file });
+    const out = [], base = path.join(root, '.starcistacks');
+    for (const env of entries(base, fs).filter((entry) => entry.isDirectory())) {
+        for (const member of entries(path.join(base, env.name, 'secrets'), fs).filter((entry) => entry.isFile() && isSealedName(entry.name))) {
+            const file = `.starcistacks/${env.name}/secrets/${member.name}`;
+            const source = fs.readFileSync(path.join(root, file), 'utf8');
+            const dotenv = [...source.matchAll(/^([A-Za-z_]\w*)=ENC\[/gm)].map((match) => match[1]).filter((key) => !key.startsWith('sops_'));
+            let keys = dotenv;
+            if (!dotenv.length) {
+                const doc = parseYaml(source);
+                keys = doc && typeof doc === 'object' && !Array.isArray(doc) ? Object.keys(doc).filter((key) => key !== 'sops' && !key.startsWith('sops_')) : [];
+            }
+            for (const key of keys)
+                out.push({ env: env.name, member: memberOfName(member.name), key, file });
+        }
     }
-  }
-  return out;
+    return out;
 }
-
 /** Collect every static secrets and vars reference inside workflow expressions, excluding the automatic GitHub token. */
 export function workflowReferences(root, { fs }) {
-  const out = [], dir = path.join(root, '.github', 'workflows');
-  for (const entry of entries(dir, fs).filter((item) => item.isFile() && /\.ya?ml$/i.test(item.name))) {
-    const file = `.github/workflows/${entry.name}`, source = fs.readFileSync(path.join(root, file), 'utf8');
-    for (const expression of source.matchAll(/\$\{\{([^}]*)/g)) {
-      for (const match of expression[1].matchAll(/\b(secrets|vars)\.([A-Z][A-Z0-9_]*)/g)) {
-        if (match[2] !== 'GITHUB_TOKEN') out.push({ file, kind: match[1], name: match[2] });
-      }
+    const out = [], dir = path.join(root, '.github', 'workflows');
+    for (const entry of entries(dir, fs).filter((item) => item.isFile() && /\.ya?ml$/i.test(item.name))) {
+        const file = `.github/workflows/${entry.name}`, source = fs.readFileSync(path.join(root, file), 'utf8');
+        for (const expression of source.matchAll(/\$\{\{([^}]*)/g)) {
+            for (const match of expression[1].matchAll(/\b(secrets|vars)\.([A-Z][A-Z0-9_]*)/g)) {
+                if (match[2] !== 'GITHUB_TOKEN')
+                    out.push({ file, kind: match[1], name: match[2] });
+            }
+        }
     }
-  }
-  return out;
+    return out;
 }
-
 /** Service CI bindings name the shared declaration classes, including the readable legacy lists. */
 export function ciNamesOfServices(doc) {
-  const out = [];
-  for (const [service, entry] of Object.entries(doc?.services ?? {})) {
-    const ci = entry?.ci ?? {};
-    if (ci.token) out.push({ service, name: ci.token, kind: 'secret' });
-    if (ci.hostVar) out.push({ service, name: ci.hostVar, kind: 'var' });
-    if (ci.organizationVar) out.push({ service, name: ci.organizationVar, kind: 'var' });
-    for (const item of list(ci.secrets)) out.push({ service, name: nameOf(item), kind: 'secret' });
-    for (const item of list(ci.vars)) out.push({ service, name: nameOf(item), kind: 'var' });
-  }
-  return out;
+    const out = [];
+    for (const [service, entry] of Object.entries((doc?.services ?? {}))) {
+        const ci = entry?.ci ?? {};
+        if (ci.token)
+            out.push({ service, name: ci.token, kind: 'secret' });
+        if (ci.hostVar)
+            out.push({ service, name: ci.hostVar, kind: 'var' });
+        if (ci.organizationVar)
+            out.push({ service, name: ci.organizationVar, kind: 'var' });
+        for (const item of list(ci.secrets))
+            out.push({ service, name: nameOf(item), kind: 'secret' });
+        for (const item of list(ci.vars))
+            out.push({ service, name: nameOf(item), kind: 'var' });
+    }
+    return out;
 }

package/runtime/scripts/hfs/coverage-from.d.mts

@@ -0,0 +1,22 @@
+type Parsed = any;
+export interface CoverageFromOptions {
+    repoRoot?: string;
+    coverageFrom?: string | undefined;
+    files?: string[];
+    repo?: Parsed;
+    manifest?: Parsed;
+    lcov?: Parsed;
+}
+export interface CoverageFromIo {
+    cwd?: string;
+    stdout?: (text: string) => unknown;
+    stderr?: (text: string) => unknown;
+    run?: (options: CoverageFromOptions) => Parsed;
+}
+/** Report for the coordinator's dispatcher; supply its findings as checkRepository's extraFindings. */
+export declare function coverageFrom({ repoRoot, coverageFrom: reportPath, files, repo, manifest, lcov }?: CoverageFromOptions): Parsed;
+/** Human-readable measured scope, excluded scope and every unmeasured source file; suitable for normal check output. */
+export declare function formatCoverageReport(report: Parsed): string;
+/** Standalone coordinator entry point: exit 0 proof passed, 2 proof or invocation refused. */
+export declare function coverageFromMain(argv: string[], { cwd, stdout, stderr, run }?: CoverageFromIo): number;
+export {};

package/runtime/scripts/hfs/coverage-from.mjs

@@ -6,65 +6,68 @@ import { gitOutputOf } from '../lib/git.mjs';
 import { lsFiles } from '../api/git/ls-files.mjs';
 import { loadSlotManifest, readRepoDeclaration } from './slots.mjs';
 import { coverageBelowReport } from './rules/coverage-below.mjs';
-
 /** Report for the coordinator's dispatcher; supply its findings as checkRepository's extraFindings. */
 export function coverageFrom({ repoRoot = invocationDir(), coverageFrom: reportPath, files, repo, manifest = loadSlotManifest(), lcov } = {}) {
-  const declaration = repo ?? readRepoDeclaration(manifest, repoRoot);
-  if (!['app', 'be'].includes(declaration.profile)) throw new Error('coverage proof requires an app root or its be side');
-  const tracked = files ?? gitOutputOf(lsFiles(['-z', '--cached', '--exclude-standard'], { dir: repoRoot, maxBuffer: 256 * 1024 * 1024 }), 'git ls-files').split('\0').filter(Boolean);
-  return coverageBelowReport({ repoRoot, files: tracked, repo: declaration, manifest, coverageFrom: reportPath, lcov });
+    const declaration = repo ?? readRepoDeclaration(manifest, repoRoot);
+    if (!['app', 'be'].includes(declaration.profile))
+        throw new Error('coverage proof requires an app root or its be side');
+    const tracked = files ?? gitOutputOf(lsFiles(['-z', '--cached', '--exclude-standard'], { dir: repoRoot, maxBuffer: 256 * 1024 * 1024 }), 'git ls-files').split('\0').filter(Boolean);
+    return coverageBelowReport({ repoRoot, files: tracked, repo: declaration, manifest, ...(reportPath === undefined ? {} : { coverageFrom: reportPath }), lcov });
 }
-
 function setValueOption(opts, flag, value) {
-  const key = flag === '--cwd' ? 'cwd' : 'coverageFrom';
-  if (value === undefined || !value || value.startsWith('--')) throw new Error(`${flag} needs a value`);
-  if (Object.hasOwn(opts, key)) throw new Error(`${flag} may be given only once`);
-  opts[key] = value;
+    const key = flag === '--cwd' ? 'cwd' : 'coverageFrom';
+    if (value === undefined || !value || value.startsWith('--'))
+        throw new Error(`${flag} needs a value`);
+    if (Object.hasOwn(opts, key))
+        throw new Error(`${flag} may be given only once`);
+    opts[key] = value;
 }
-
 function parse(argv) {
-  const opts = {};
-  for (let index = 0; index < argv.length; index += 1) {
-    const [flag, inline] = argv[index].split(/=(.*)/su);
-    if (flag === '--json' && inline === undefined) opts.json = true;
-    else if (['--coverage-from', '--cwd'].includes(flag)) {
-      const value = inline ?? argv[++index];
-      setValueOption(opts, flag, value);
-    } else throw new Error(`unknown argument ${argv[index]}`);
-  }
-  if (!opts.coverageFrom) throw new Error('usage: starci app check --coverage-from <lcov> [--cwd <app>] [--json]');
-  return opts;
+    const opts = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const [flag = '', inline] = argv[index].split(/=(.*)/su);
+        if (flag === '--json' && inline === undefined)
+            opts.json = true;
+        else if (['--coverage-from', '--cwd'].includes(flag)) {
+            const value = inline ?? argv[++index];
+            setValueOption(opts, flag, value);
+        }
+        else
+            throw new Error(`unknown argument ${argv[index]}`);
+    }
+    if (!opts.coverageFrom)
+        throw new Error('usage: starci app check --coverage-from <lcov> [--cwd <app>] [--json]');
+    return opts;
 }
-
 /** Human-readable measured scope, excluded scope and every unmeasured source file; suitable for normal check output. */
 export function formatCoverageReport(report) {
-  const roles = report.scope?.roles ?? [];
-  const rolePattern = roles.length === 1 ? roles[0] : '{' + roles.join(',') + '}';
-  const lines = [
-    `coverage: ${report.ok ? 'passed' : 'refused'} (${report.measured.length} measured logic files; lines/functions/branches at 100% per file)`,
-    'statement coverage is enforced by the unit runner; lcov does not carry statement counts',
-    'measured scope:',
-    ...(report.scope?.roots ?? []).map((root) => `  ${report.prefix ?? ''}${root}**/*.${rolePattern}.ts`),
-    'unmeasured scope:',
-    ...report.unmeasuredScopes.map((entry) => `  ${entry}${entry.endsWith('/') ? '**' : ''}`),
-    'unmeasured source files:',
-    ...(report.unmeasured.length ? report.unmeasured.map((file) => `  ${file}`) : ['  (none)']),
-    ...report.findings.map((finding) => `${finding.code} ${finding.path}: ${finding.message}`),
-  ];
-  return `${lines.join('\n')}\n`;
+    const roles = report.scope?.roles ?? [];
+    const rolePattern = roles.length === 1 ? roles[0] : '{' + roles.join(',') + '}';
+    const lines = [
+        `coverage: ${report.ok ? 'passed' : 'refused'} (${report.measured.length} measured logic files; lines/functions/branches at 100% per file)`,
+        'statement coverage is enforced by the unit runner; lcov does not carry statement counts',
+        'measured scope:',
+        ...(report.scope?.roots ?? []).map((root) => `  ${report.prefix ?? ''}${root}**/*.${rolePattern}.ts`),
+        'unmeasured scope:',
+        ...report.unmeasuredScopes.map((entry) => `  ${entry}${entry.endsWith('/') ? '**' : ''}`),
+        'unmeasured source files:',
+        ...(report.unmeasured.length ? report.unmeasured.map((file) => `  ${file}`) : ['  (none)']),
+        ...report.findings.map((finding) => `${finding.code} ${finding.path}: ${finding.message}`),
+    ];
+    return `${lines.join('\n')}\n`;
 }
-
 /** Standalone coordinator entry point: exit 0 proof passed, 2 proof or invocation refused. */
 export function coverageFromMain(argv, { cwd = invocationDir(), stdout = (text) => process.stdout.write(text), stderr = (text) => process.stderr.write(text), run = coverageFrom } = {}) {
-  try {
-    const opts = parse(argv);
-    const report = run({ repoRoot: path.resolve(cwd, opts.cwd ?? '.'), coverageFrom: opts.coverageFrom });
-    stdout(opts.json ? `${JSON.stringify(report, null, 2)}\n` : formatCoverageReport(report));
-    return report.ok ? 0 : 2;
-  } catch (error) {
-    stderr(`starci app check --coverage-from: ${String(error.code ?? error.message).split('\n')[0]}\n`);
-    return 2;
-  }
+    try {
+        const opts = parse(argv);
+        const report = run({ repoRoot: path.resolve(cwd, opts.cwd ?? '.'), coverageFrom: opts.coverageFrom });
+        stdout(opts.json ? `${JSON.stringify(report, null, 2)}\n` : formatCoverageReport(report));
+        return report.ok ? 0 : 2;
+    }
+    catch (error) {
+        stderr(`starci app check --coverage-from: ${String(error.code ?? error.message).split('\n')[0]}\n`);
+        return 2;
+    }
 }
-
-if (isMain(import.meta.url)) process.exitCode = coverageFromMain(process.argv.slice(2));
+if (isMain(import.meta.url))
+    process.exitCode = coverageFromMain(process.argv.slice(2));

package/runtime/scripts/hfs/coverage-scope.d.mts

@@ -0,0 +1,87 @@
+import { type Slot, type SlotManifest } from './manifest-shape.mjs';
+/** The slot and manifest shapes the coverage derivation reads (manifest-shape.mts). */
+export type ScopeSlot = Slot;
+export type ScopeManifest = SlotManifest;
+/** What `coverageScope` derives from the manifest. */
+export interface CoverageScope {
+    roles: string[];
+    roots: string[];
+    files: string[];
+    excludes: string[];
+    none: string[];
+    sonar: string[];
+    codecovPaths: string[];
+}
+/** A Codecov component: one service app, or the platform. */
+export interface CoverageComponent {
+    id: string;
+    name: string;
+    paths: string[];
+}
+/** A declared back-end app. */
+export interface BeApp {
+    name: string;
+    kind: string;
+}
+/** The providers the app's connections declare; a connection that names none contributes undefined, which enables no slot. */
+type Providers = readonly (string | undefined)[];
+/** `text` with every `<placeholder>` (a `<`, at least one character, the next `>`) replaced by `*`; a `<` with no closing `>` stays. */
+export declare const star: (text: unknown) => string;
+export declare const segments: (dir: string, trimSlashes?: boolean) => string[];
+/** True when directory pattern `inner` lies inside `outer` (an outer `*` segment matches any one inner segment) or is the same. */
+export declare function nested(inner: string, outer: string): boolean;
+/** The exclusion entries that no other entry already matches: a glob covered by a broader one adds nothing to the scope. */
+export declare const withoutCovered: (entries: string[]) => string[];
+/**
+ * The scope of an app's back end, derived from the manifest: { roles, roots, excludes, none, sonar, codecovPaths }.
+ *   roles     ruleParams.be.logicRoles;
+ *   roots     the minimal required directories (be-relative, `*` for a placeholder, trailing slash), sorted;
+ *   excludes  the none directories inside a root (never measured though their root is);
+ *   files     the declared logic files of the required slots (be-relative, `*` for a placeholder) outside every none directory, sorted;
+ *   none      the minimal none paths of the whole back end (a directory ends in a slash), sorted;
+ *   sonar     sonar.coverage.exclusions, repository-relative from the app root, sorted;
+ *   codecovPaths  the measured roots as `be/<root>**`.
+ */
+export declare function coverageScope(manifest: ScopeManifest, providers?: Providers): CoverageScope;
+/** The glob a root measures: every file of a logic role below it (`src/modules/domain/*\/**\/*.{service,policy}.ts`). */
+export declare const rootGlob: (root: string, roles: string[]) => string;
+/** The jest coverage options of the rendered be/jest.config.js: { roots, roles, files, excludes }. */
+export declare function jestCoverage(manifest: ScopeManifest, providers?: Providers): {
+    roots: string[];
+    roles: string[];
+    files: string[];
+    excludes: string[];
+};
+/** Sonar's sonar.coverage.exclusions of an app: the complement of the measured files, repository-relative from the app root. */
+export declare const sonarCoverageExclusions: (manifest: ScopeManifest, providers?: Providers) => string[];
+/** The Codecov paths of an app: the measured roots, repository-relative from the app root. */
+export declare const codecovPaths: (manifest: ScopeManifest, providers?: Providers) => string[];
+/**
+ * The Codecov components of an app, [{ id, name, paths }] (paths repository-relative from the app root): one per service app (api or worker)
+ * that composes the capabilities nothing else composes, then `platform`. A capability of a root whose last segment is a placeholder
+ * (`src/modules/domain/<capability>/`, projections, integrations) belongs to the one service app whose composition root
+ * (`apps/<app>/`) imports `@modules/<tier>/<capability>`; when several import it, the service app named like the capability (the
+ * `identity` service and the `identity` capability) owns it; one that nothing singles out belongs to platform, as does the whole platform tier. The measured roots of the tier `platform` are never split.
+ *
+ * @param manifest the slot manifest
+ * @param source be-relative source files, a reader, the declared be apps
+ */
+export declare function coverageComponents(manifest: ScopeManifest, { files, read, apps, providers }: {
+    files: string[];
+    read: (file: string) => string;
+    apps: readonly BeApp[];
+    providers?: Providers;
+}): CoverageComponent[];
+/**
+ * The one test of whether a be-relative file is measured, over a coverage scope: a declared logic file of `files`, or `<name>.<role>.ts`
+ * of a logic role below a measured root and inside no none directory of it. isMeasured and R273 (rules/coverage-below.mjs) ask it.
+ */
+export declare function measuredBy({ roots, roles, files, excludes }: {
+    roots: string[];
+    roles: string[];
+    files: string[];
+    excludes: string[];
+}): (file: string) => boolean;
+/** True when the be-relative `file` is measured by the scope of the whole manifest (measuredBy). */
+export declare const isMeasured: (manifest: ScopeManifest, file: string) => boolean;
+export {};