@starci/hfs 4.11.21 → 4.12.0

package/runtime/scripts/gates/sonar-gate.mjs

@@ -14,48 +14,57 @@ import { parseYaml } from '../../engine/yaml.mjs';
 import { braceVariants, globExpression } from '../lib/glob.mjs';
 import { trimTrailingSlashes } from '../lib/path-key.mjs';
 import { declarationEdition } from '../hfs/edition-slots.mjs';
-
+import { errorCode } from '../api/fs/lib.mjs';
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const GATE_FILE = 'knowledge/sonar-gate.yaml';
 export const GATE_SCHEMA = 'starci/sonar-gate@1';
 export const SCAN_SCHEMA_PREFIX = 'starci/sonar-local-scan@';
-
 let cache = null;
 /** Read the canonical gate for the repository's declared edition; cache the document, never a selected app view. */
 export function loadSonarGate({ base = root, file = null, cwd = null } = {}) {
-  const gate = !file && cache?.base === base ? cache.gate : parseYaml(fs.readFileSync(file ?? path.join(base, GATE_FILE), 'utf8'));
-  if (gate?.schema !== GATE_SCHEMA) throw new Error(`${file ?? GATE_FILE}: schema must be ${GATE_SCHEMA}`);
-  for (const key of ['gate', 'newCode', 'overall', 'enforcedOps'])
-    if (gate[key] == null) throw new Error(`${file ?? GATE_FILE}: ${key} is required`);
-  // Coverage is a required policy descriptor of the full block; the lite block carries the same descriptor (owner ruling 2026-10-12).
-  for (const area of ['newCode', 'overall']) {
-    const coverage = gate[area].coverage;
-    if (!coverage || typeof coverage.metric !== 'string' || !coverage.metric.trim() || !Number.isFinite(coverage.minPercent) || coverage.minPercent < 0 || coverage.minPercent > 100)
-      throw new Error(`${file ?? GATE_FILE}: ${area}.coverage requires a metric and minPercent from 0 to 100`);
-  }
-  if (!file) cache = { base, gate };
-  if (!cwd) return gate;
-  return gateForCwd(gate, { cwd, file });
+    const gate = !file && cache?.base === base ? cache.gate : parseYaml(fs.readFileSync(file ?? path.join(base, GATE_FILE), 'utf8'));
+    if (gate?.schema !== GATE_SCHEMA)
+        throw new Error(`${file ?? GATE_FILE}: schema must be ${GATE_SCHEMA}`);
+    for (const key of ['gate', 'newCode', 'overall', 'enforcedOps'])
+        if (gate[key] == null)
+            throw new Error(`${file ?? GATE_FILE}: ${key} is required`);
+    // Coverage is a required policy descriptor of the full block; the lite block carries the same descriptor (owner ruling 2026-10-12).
+    for (const area of ['newCode', 'overall']) {
+        const coverage = gate[area].coverage;
+        if (!coverage || typeof coverage.metric !== 'string' || !coverage.metric.trim() || !Number.isFinite(coverage.minPercent) || coverage.minPercent < 0 || coverage.minPercent > 100)
+            throw new Error(`${file ?? GATE_FILE}: ${area}.coverage requires a metric and minPercent from 0 to 100`);
+    }
+    if (!file)
+        cache = { base, gate };
+    if (!cwd)
+        return gate;
+    return gateForCwd(gate, { cwd, file });
 }
-
 /** The canonical gate limited to the repository's declared edition (the lite block: its own gate name, the same conditions). */
 const gateForCwd = (gate, { cwd, file }) => {
-  let declaration;
-  try { declaration = JSON.parse(fs.readFileSync(path.join(cwd, 'hfs.json'), 'utf8')); }
-  catch (error) {
-    if (error?.code === 'ENOENT') return gate;
-    throw error;
-  }
-  const { edition, valid } = declarationEdition({}, declaration);
-  if (!valid) throw new Error('hfs.json declares an unsupported Sonar edition');
-  if (edition === 'full') return gate;
-  if (declaration.kind !== 'app') throw new Error('hfs.json lite Sonar policy requires an app declaration');
-  const selected = gate[edition];
-  for (const key of ['gate', 'newCode', 'overall'])
-    if (selected?.[key] == null) throw new Error(`${file ?? GATE_FILE}: ${edition}.${key} is required`);
-  return { ...gate, ...selected };
+    let declaration;
+    try {
+        declaration = JSON.parse(fs.readFileSync(path.join(cwd, 'hfs.json'), 'utf8'));
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT')
+            return gate;
+        throw error;
+    }
+    const { edition, valid } = declarationEdition({}, declaration);
+    if (!valid)
+        throw new Error('hfs.json declares an unsupported Sonar edition');
+    if (edition === 'full')
+        return gate;
+    if (declaration.kind !== 'app')
+        throw new Error('hfs.json lite Sonar policy requires an app declaration');
+    const overlay = gate[edition];
+    const selected = typeof overlay === 'object' && overlay !== null ? overlay : undefined;
+    for (const key of ['gate', 'newCode', 'overall'])
+        if (selected?.[key] == null)
+            throw new Error(`${file ?? GATE_FILE}: ${edition}.${key} is required`);
+    return { ...gate, ...selected };
 };
-
 /**
  * The conditions the server gate carries: [{metric, op, error}] (SonarQube api/qualitygates conditions): the new-code ones
  * (coverage, duplication, hotspots, blocking issues), then the overall-code ones (coverage, open issues of any origin,
@@ -63,42 +72,34 @@ const gateForCwd = (gate, { cwd, file }) => {
  * the scope is what sonar.coverage.exclusions of the managed sonar-project.properties leaves (coverageScopeOf).
  */
 export function serverConditions(gate) {
-  const n = gate.newCode;
-  const o = gate.overall;
-  const out = [
-    ...(n.coverage ? [{ metric: n.coverage.metric, op: 'LT', error: String(n.coverage.minPercent) }] : []),
-    { metric: n.duplication.metric, op: 'GT', error: String(n.duplication.maxPercent) },
-    { metric: n.hotspots.metric, op: 'LT', error: String(n.hotspots.minReviewedPercent) },
-  ];
-  for (const severity of n.issues.blockingSeverities) out.push({ metric: n.issues.metrics[severity], op: 'GT', error: String(n.issues.max) });
-  out.push(
-    ...(o.coverage ? [{ metric: o.coverage.metric, op: 'LT', error: String(o.coverage.minPercent) }] : []),
-    { metric: o.issues.metric, op: 'GT', error: String(o.issues.max) },
-    { metric: o.hotspots.metric, op: 'LT', error: String(o.hotspots.minReviewedPercent) },
-    { metric: o.duplication.metric, op: 'GT', error: String(o.duplication.maxPercent) },
-  );
-  return out;
+    const n = gate.newCode;
+    const o = gate.overall;
+    const out = [
+        ...(n.coverage ? [{ metric: n.coverage.metric, op: 'LT', error: String(n.coverage.minPercent) }] : []),
+        { metric: n.duplication.metric, op: 'GT', error: String(n.duplication.maxPercent) },
+        { metric: n.hotspots.metric, op: 'LT', error: String(n.hotspots.minReviewedPercent) },
+    ];
+    for (const severity of n.issues.blockingSeverities)
+        out.push({ metric: n.issues.metrics[severity], op: 'GT', error: String(n.issues.max) });
+    out.push(...(o.coverage ? [{ metric: o.coverage.metric, op: 'LT', error: String(o.coverage.minPercent) }] : []), { metric: o.issues.metric, op: 'GT', error: String(o.issues.max) }, { metric: o.hotspots.metric, op: 'LT', error: String(o.hotspots.minReviewedPercent) }, { metric: o.duplication.metric, op: 'GT', error: String(o.duplication.maxPercent) });
+    return out;
 }
-
 /** The ops the runtime holds to the gate at settle. */
 export const enforcedOps = (gate) => new Set(gate.enforcedOps);
-
 /** What the slice verdict is judged against: the numbers a scan copies into its summary (`gate`). */
 export function thresholdsOf(gate) {
-  const n = gate.newCode;
-  return {
-    name: gate.gate.name,
-    ignoreBelowChangedLines: n.ignoreBelowChangedLines,
-    duplicationMaxPercent: n.duplication.maxPercent,
-    blockingSeverities: [...n.issues.blockingSeverities],
-    blockingIssuesMax: n.issues.max,
-    unreviewedHotspotsMax: n.hotspots.unreviewedMax,
-    coverageMinPercent: gate.overall.coverage?.minPercent ?? null,
-  };
+    const n = gate.newCode;
+    return {
+        name: gate.gate.name,
+        ignoreBelowChangedLines: n.ignoreBelowChangedLines,
+        duplicationMaxPercent: n.duplication.maxPercent,
+        blockingSeverities: [...n.issues.blockingSeverities],
+        blockingIssuesMax: n.issues.max,
+        unreviewedHotspotsMax: n.hotspots.unreviewedMax,
+        coverageMinPercent: gate.overall.coverage?.minPercent ?? null,
+    };
 }
-
 const listOf = (props, key) => String(props[key] ?? '').split(',').map((glob) => glob.trim()).filter(Boolean);
-
 /**
  * The coverage scope of a sonar-project.properties map (readProperties), as Sonar computes it: SonarQube has no coverage
  * inclusions, so the files it measures coverage on are the source files of `sonar.sources` that neither `sonar.exclusions`,
@@ -107,31 +108,29 @@ const listOf = (props, key) => String(props[key] ?? '').split(',').map((glob) =>
  * Returns {exclusions, sources, excluded, tests}; `exclusions` empty means the repository declares no coverage scope.
  */
 export function coverageScopeOf(props = {}) {
-  return { exclusions: listOf(props, 'sonar.coverage.exclusions'), sources: listOf(props, 'sonar.sources'), excluded: listOf(props, 'sonar.exclusions'), tests: listOf(props, 'sonar.test.inclusions') };
+    return { exclusions: listOf(props, 'sonar.coverage.exclusions'), sources: listOf(props, 'sonar.sources'), excluded: listOf(props, 'sonar.exclusions'), tests: listOf(props, 'sonar.test.inclusions') };
 }
-
 const SOURCE_FILE = /\.(?:[cm]?[jt]sx?)$/;
-
 /** True for a repository-relative path Sonar measures coverage on under `scope` (coverageScopeOf; Sonar's glob subset, scripts/lib/glob.mjs). */
 export function coverageTargetOf(scope) {
-  const patterns = (globs) => (globs ?? []).flatMap(braceVariants).map(globExpression);
-  const excluded = patterns([...(scope.exclusions ?? []), ...(scope.excluded ?? [])]);
-  const tests = patterns(scope.tests);
-  const roots = (scope.sources ?? []).map((dir) => `${trimTrailingSlashes(String(dir))}/`);
-  return (file) => {
-    const rel = String(file).replaceAll('\\', '/');
-    return SOURCE_FILE.test(rel) && (!roots.length || roots.some((dir) => rel.startsWith(dir)))
-      && !excluded.some((pattern) => pattern.test(rel)) && !tests.some((pattern) => pattern.test(rel));
-  };
+    const patterns = (globs) => (globs ?? []).flatMap(braceVariants).map(globExpression);
+    const excluded = patterns([...(scope.exclusions ?? []), ...(scope.excluded ?? [])]);
+    const tests = patterns(scope.tests);
+    const roots = (scope.sources ?? []).map((dir) => `${trimTrailingSlashes(String(dir))}/`);
+    return (file) => {
+        const rel = String(file).replaceAll('\\', '/');
+        return SOURCE_FILE.test(rel) && (!roots.length || roots.some((dir) => rel.startsWith(dir)))
+            && !excluded.some((pattern) => pattern.test(rel)) && !tests.some((pattern) => pattern.test(rel));
+    };
 }
-
 const asNumber = (value) => (value === undefined || value === null || value === '' || !Number.isFinite(Number(value)) ? null : Number(value));
 const byPath = (a, b) => {
-  if (a.path < b.path) return -1;
-  if (a.path > b.path) return 1;
-  return 0;
+    if (a.path < b.path)
+        return -1;
+    if (a.path > b.path)
+        return 1;
+    return 0;
 };
-
 /**
  * The per-file coverage verdict: `files` are [{path, coverage}] (coverage the Sonar `coverage` measure of the file, a number
  * or null when Sonar has none), `scope` the repository's coverage scope (coverageScopeOf). Only a file of the scope is a
@@ -142,56 +141,67 @@ const byPath = (a, b) => {
  * Returns {applied, exclusions, minPercent, files: [{path, coverage, ok}], failures: [text]}.
  */
 export function judgeCoverage(files, { scope = coverageScopeOf(), minPercent }) {
-  const isTarget = coverageTargetOf(scope);
-  const result = { applied: scope.exclusions.length > 0, exclusions: [...scope.exclusions], minPercent, files: [], failures: [] };
-  if (!result.applied) return { ...result, note: 'the repository declares no sonar.coverage.exclusions: no coverage scope' };
-  for (const file of [...files].sort(byPath)) {
-    const rel = String(file.path).replaceAll('\\', '/');
-    if (!isTarget(rel)) continue;
-    const coverage = asNumber(file.coverage);
-    const ok = coverage !== null && coverage >= minPercent;
-    result.files.push({ path: rel, coverage, ok });
-    if (coverage === null) result.failures.push(`${rel} has no coverage measure (the be unit run's lcov is not imported or does not name it)`);
-    else if (!ok) result.failures.push(`coverage of ${rel} ${coverage}% < ${minPercent}%`);
-  }
-  return result;
+    const isTarget = coverageTargetOf(scope);
+    const result = { applied: scope.exclusions.length > 0, exclusions: [...scope.exclusions], minPercent, files: [], failures: [] };
+    if (!result.applied)
+        return { ...result, note: 'the repository declares no sonar.coverage.exclusions: no coverage scope' };
+    for (const file of [...files].sort(byPath)) {
+        const rel = String(file.path).replaceAll('\\', '/');
+        if (!isTarget(rel))
+            continue;
+        const coverage = asNumber(file.coverage);
+        const ok = coverage !== null && coverage >= minPercent;
+        result.files.push({ path: rel, coverage, ok });
+        if (coverage === null)
+            result.failures.push(`${rel} has no coverage measure (the be unit run's lcov is not imported or does not name it)`);
+        else if (!ok)
+            result.failures.push(`coverage of ${rel} ${coverage}% < ${minPercent}%`);
+    }
+    return result;
 }
-
 /** The issue, hotspot and duplication measures of the dashboard: their numbers and failures. */
 const measureFailures = (o, measures, numbers) => {
-  const failures = [];
-  for (const metric of Object.keys(o.issues.types)) {
-    numbers[metric] = asNumber(measures[metric]);
-    if (numbers[metric] === null) failures.push(`${metric} is not measured`);
-    else if (numbers[metric] > o.issues.max) failures.push(`${metric} ${numbers[metric]} > ${o.issues.max}`);
-  }
-  const reviewed = asNumber(measures[o.hotspots.metric]);
-  numbers.security_hotspots = asNumber(measures.security_hotspots);
-  numbers[o.hotspots.metric] = reviewed === null && numbers.security_hotspots === 0 ? 100 : reviewed;
-  if (numbers[o.hotspots.metric] === null) failures.push(`${o.hotspots.metric} is not measured`);
-  else if (numbers[o.hotspots.metric] < o.hotspots.minReviewedPercent) failures.push(`${o.hotspots.metric} ${numbers[o.hotspots.metric]}% < ${o.hotspots.minReviewedPercent}%`);
-  numbers[o.duplication.metric] = asNumber(measures[o.duplication.metric]);
-  if (numbers[o.duplication.metric] === null) failures.push(`${o.duplication.metric} is not measured`);
-  else if (numbers[o.duplication.metric] > o.duplication.maxPercent) failures.push(`${o.duplication.metric} ${numbers[o.duplication.metric]}% > ${o.duplication.maxPercent}%`);
-  return failures;
+    const failures = [];
+    for (const metric of Object.keys(o.issues.types)) {
+        numbers[metric] = asNumber(measures[metric]);
+        if (numbers[metric] === null)
+            failures.push(`${metric} is not measured`);
+        else if (numbers[metric] > o.issues.max)
+            failures.push(`${metric} ${numbers[metric]} > ${o.issues.max}`);
+    }
+    const reviewed = asNumber(measures[o.hotspots.metric]);
+    numbers.security_hotspots = asNumber(measures.security_hotspots);
+    numbers[o.hotspots.metric] = reviewed === null && numbers.security_hotspots === 0 ? 100 : reviewed;
+    if (numbers[o.hotspots.metric] === null)
+        failures.push(`${o.hotspots.metric} is not measured`);
+    else if (numbers[o.hotspots.metric] < o.hotspots.minReviewedPercent)
+        failures.push(`${o.hotspots.metric} ${numbers[o.hotspots.metric]}% < ${o.hotspots.minReviewedPercent}%`);
+    numbers[o.duplication.metric] = asNumber(measures[o.duplication.metric]);
+    if (numbers[o.duplication.metric] === null)
+        failures.push(`${o.duplication.metric} is not measured`);
+    else if (numbers[o.duplication.metric] > o.duplication.maxPercent)
+        failures.push(`${o.duplication.metric} ${numbers[o.duplication.metric]}% > ${o.duplication.maxPercent}%`);
+    return failures;
 };
-
 /** The coverage block of the dashboard verdict: {coverage, failures}. */
 const coverageBlock = (o, files, scope, measures, numbers) => {
-  const coverage = o.coverage ? judgeCoverage(files, { scope, minPercent: o.coverage.minPercent })
-    : { applied: false, status: 'not-required', files: [], failures: [], note: 'the declared Sonar policy has no coverage condition' };
-  const failures = [];
-  if (o.coverage) {
-    numbers[o.coverage.metric] = asNumber(measures[o.coverage.metric]);
-    if (!coverage.applied) failures.push("the repository declares no sonar.coverage.exclusions: the services' coverage cannot be judged");
-    else if (!coverage.files.length) failures.push('no file of the coverage scope is measured: the scope is empty or the lcov report was not imported');
-    failures.push(...coverage.failures);
-    if (numbers[o.coverage.metric] === null) failures.push(`${o.coverage.metric} is not measured`);
-    else if (numbers[o.coverage.metric] < o.coverage.minPercent) failures.push(`${o.coverage.metric} ${numbers[o.coverage.metric]}% < ${o.coverage.minPercent}%`);
-  }
-  return { coverage, failures };
+    const coverage = o.coverage ? judgeCoverage(files, { scope, minPercent: o.coverage.minPercent })
+        : { applied: false, status: 'not-required', files: [], failures: [], note: 'the declared Sonar policy has no coverage condition' };
+    const failures = [];
+    if (o.coverage) {
+        numbers[o.coverage.metric] = asNumber(measures[o.coverage.metric]);
+        if (!coverage.applied)
+            failures.push("the repository declares no sonar.coverage.exclusions: the services' coverage cannot be judged");
+        else if (!coverage.files.length)
+            failures.push('no file of the coverage scope is measured: the scope is empty or the lcov report was not imported');
+        failures.push(...coverage.failures);
+        if (numbers[o.coverage.metric] === null)
+            failures.push(`${o.coverage.metric} is not measured`);
+        else if (numbers[o.coverage.metric] < o.coverage.minPercent)
+            failures.push(`${o.coverage.metric} ${numbers[o.coverage.metric]}% < ${o.coverage.minPercent}%`);
+    }
+    return { coverage, failures };
 };
-
 /**
  * The dashboard verdict of a whole project (`sonar-local dashboard`): `measures` the project's measures by metric key
  * (bugs, code_smells, vulnerabilities, security_hotspots, security_hotspots_reviewed, duplicated_lines_density, coverage), `files` the per-file
@@ -200,14 +210,13 @@ const coverageBlock = (o, files, scope, measures, numbers) => {
  * none to review), duplication meets its declared maximum, and required coverage meets its per-file threshold. Returns {verdict, numbers, coverage, failures}.
  */
 export function judgeDashboard({ measures = {}, files = [], scope = coverageScopeOf() }, gate) {
-  const o = gate.overall;
-  const numbers = {};
-  const failures = [...measureFailures(o, measures, numbers)];
-  const block = coverageBlock(o, files, scope, measures, numbers);
-  failures.push(...block.failures);
-  return { verdict: failures.length ? 'fail' : 'pass', numbers, coverage: block.coverage, failures };
+    const o = gate.overall;
+    const numbers = {};
+    const failures = [...measureFailures(o, measures, numbers)];
+    const block = coverageBlock(o, files, scope, measures, numbers);
+    failures.push(...block.failures);
+    return { verdict: failures.length ? 'fail' : 'pass', numbers, coverage: block.coverage, failures };
 }
-
 /**
  * What a filed sonar.json says, as a settle judgment. `summary` is the parsed scan summary (or null when the op attached
  * none). Returns {status, code, detail, findings[]}:
@@ -221,31 +230,35 @@ export function judgeDashboard({ measures = {}, files = [], scope = coverageScop
  * conditions with `coverage: 'not-measured'` and the owner-mode `note`, never as a plain pass, and only when `specs` (the
  * owner switches the caller read) confirms unit is off; otherwise the claim is refused as sonar-proof-missing.
  */
-export function judgeSummary(summary, gate, { specs = null } = {}) {
-  if (!summary || typeof summary !== 'object' || !String(summary.schema ?? '').startsWith(SCAN_SCHEMA_PREFIX))
-    return { status: 'missing', code: 'sonar-proof-missing', detail: 'no sonar.json scan summary (schema starci/sonar-local-scan) is attached to the report', findings: [] };
-  const why = String(summary.reason ?? '').replace(/\s+/g, ' ').slice(0, 300);
-  switch (summary.outcome) {
-    case 'pass':
-      if (summary.scope !== 'slice') return { status: 'missing', code: 'sonar-proof-missing', detail: `the summary's scope is ${summary.scope ?? 'unknown'}, not the slice's own (scope slice is required)`, findings: [] };
-      // Owner mode (specs.unit off): the slice passes on the other conditions, and the judgment says coverage was not measured.
-      if (summary.ownerMode && specs?.unit !== false) return { status: 'missing', code: 'sonar-proof-missing', detail: 'the summary claims owner mode specs.unit=false (coverage not measured) but the owner config has unit tests on: rerun the scan', findings: [] };
-      if (summary.ownerMode?.coverage === 'not-measured') return { status: 'pass', code: null, detail: null, coverage: 'not-measured', note: String(summary.ownerMode.note ?? 'owner mode: coverage not measured'), findings: [] };
-      return { status: 'pass', code: null, detail: null, findings: [] };
-    case 'fail': {
-      const findings = Array.isArray(summary.slice?.failures) && summary.slice.failures.length ? summary.slice.failures.map(String) : [why || 'the slice fails the gate'];
-      return { status: 'red', code: 'sonar-gate-red', detail: findings.join('; '), findings };
+export function judgeSummary(summary, _gate, { specs = null } = {}) {
+    if (!summary || typeof summary !== 'object' || !String(summary.schema ?? '').startsWith(SCAN_SCHEMA_PREFIX))
+        return { status: 'missing', code: 'sonar-proof-missing', detail: 'no sonar.json scan summary (schema starci/sonar-local-scan) is attached to the report', findings: [] };
+    const why = String(summary.reason ?? '').replace(/\s+/g, ' ').slice(0, 300);
+    switch (summary.outcome) {
+        case 'pass':
+            if (summary.scope !== 'slice')
+                return { status: 'missing', code: 'sonar-proof-missing', detail: `the summary's scope is ${summary.scope ?? 'unknown'}, not the slice's own (scope slice is required)`, findings: [] };
+            // Owner mode (specs.unit off): the slice passes on the other conditions, and the judgment says coverage was not measured.
+            if (summary.ownerMode && specs?.unit !== false)
+                return { status: 'missing', code: 'sonar-proof-missing', detail: 'the summary claims owner mode specs.unit=false (coverage not measured) but the owner config has unit tests on: rerun the scan', findings: [] };
+            if (summary.ownerMode?.coverage === 'not-measured')
+                return { status: 'pass', code: null, detail: null, coverage: 'not-measured', note: String(summary.ownerMode.note ?? 'owner mode: coverage not measured'), findings: [] };
+            return { status: 'pass', code: null, detail: null, findings: [] };
+        case 'fail': {
+            const findings = Array.isArray(summary.slice?.failures) && summary.slice.failures.length ? summary.slice.failures.map(String) : [why || 'the slice fails the gate'];
+            return { status: 'red', code: 'sonar-gate-red', detail: findings.join('; '), findings };
+        }
+        case 'blocked':
+            return { status: 'unavailable', code: 'sonar-unavailable', detail: why || 'Sonar could not judge the slice', findings: [] };
+        case 'disabled':
+            return { status: 'pass', code: null, detail: null, note: `Sonar is disabled by the repository's declaration: ${why}`, findings: [] };
+        case 'refused':
+            if (summary.code === 'SLICE_EMPTY')
+                return { status: 'pass', code: null, detail: null, note: 'the slice changed no file, so there is no new code to judge', findings: [] };
+            return { status: 'refused', code: 'sonar-scan-refused', detail: `${summary.code ?? 'refused'}: ${why}`, findings: [] };
+        case 'submitted':
+            return { status: 'missing', code: 'sonar-proof-missing', detail: 'the scan was submitted without --wait: no processed verdict', findings: [] };
+        default:
+            return { status: 'missing', code: 'sonar-proof-missing', detail: `the summary has no verdict (outcome ${summary.outcome ?? 'absent'})`, findings: [] };
     }
-    case 'blocked':
-      return { status: 'unavailable', code: 'sonar-unavailable', detail: why || 'Sonar could not judge the slice', findings: [] };
-    case 'disabled':
-      return { status: 'pass', code: null, detail: null, note: `Sonar is disabled by the repository's declaration: ${why}`, findings: [] };
-    case 'refused':
-      if (summary.code === 'SLICE_EMPTY') return { status: 'pass', code: null, detail: null, note: 'the slice changed no file, so there is no new code to judge', findings: [] };
-      return { status: 'refused', code: 'sonar-scan-refused', detail: `${summary.code ?? 'refused'}: ${why}`, findings: [] };
-    case 'submitted':
-      return { status: 'missing', code: 'sonar-proof-missing', detail: 'the scan was submitted without --wait: no processed verdict', findings: [] };
-    default:
-      return { status: 'missing', code: 'sonar-proof-missing', detail: `the summary has no verdict (outcome ${summary.outcome ?? 'absent'})`, findings: [] };
-  }
 }

package/runtime/scripts/gates/starcistacks-ci.d.mts

@@ -0,0 +1,35 @@
+import type { AddFinding, StackServiceEntry } from './starcistacks-form.mjs';
+/** A service's reporting hook: records an ambiguity of its declaration. */
+export type Ambiguous = (message: string) => void;
+/** What the service checks read from the check context of starcistacks.mjs. */
+export type ParsedDocument = any;
+/** One services.<id> entry of the parsed declaration. */
+export type ServiceDeclaration = ParsedDocument;
+export interface QualityServiceContext {
+    governing: object | null;
+    name: string;
+    ciUses: Record<string, string[]>;
+    ciText: string;
+    add: AddFinding;
+    ambiguous: Ambiguous;
+}
+/** One catalogued service: its providers and the CI text that shows a workflow calls it. */
+export interface CatalogEntry {
+    providers: string[];
+    words: string[];
+    ci: RegExp[];
+}
+/** The closed service catalog: its providers and the CI text that shows a workflow calls it. */
+export declare const SERVICE_CATALOG: Record<string, CatalogEntry>;
+/** The catalog entry of a catalogued service id; throws for an id the catalog does not know. */
+export declare const catalogOf: (id: string) => CatalogEntry;
+export declare const checkServiceForm: (service: StackServiceEntry, id: string, entry: ServiceDeclaration, at: string, kind: string, add: AddFinding, ambiguous: Ambiguous) => void;
+/** Validate the additive CI declaration and the public example secret policy. */
+export declare function checkCiDeclaration(declaration: {
+    doc?: ParsedDocument | null;
+} | null | undefined, declFile: string, kind: string, declarationSchema: () => ParsedDocument, schemaErrors: (value: unknown, shape: unknown, at?: string) => Array<{
+    path: string;
+    message: string;
+}>, add: AddFinding): void;
+/** Quality services use their CI binding without requiring hosted project or custody fields. */
+export declare function checkQualityService(service: StackServiceEntry, id: string, at: string, context: QualityServiceContext, checkServiceCi: (service: StackServiceEntry, id: string, at: string, context: QualityServiceContext) => void): boolean;

package/runtime/scripts/gates/starcistacks-ci.mjs

@@ -1,55 +1,63 @@
 // starcistacks-ci.mjs - service catalog, CI declarations and quality-service example policy.
 import { readCiDeclaration } from '../hfs/ci-declaration.mjs';
-
 /** The closed service catalog: its providers and the CI text that shows a workflow calls it. */
 export const SERVICE_CATALOG = {
-  codecov: { providers: ['codecov'], words: ['codecov'], ci: [/codecov\/codecov-action/i] },
-  dependabot: { providers: ['github'], words: ['dependabot'], ci: [] },
-  audit: { providers: ['npm'], words: ['audit'], ci: [/\bnpm audit\b/] },
-  sonar: { providers: ['sonarqube', 'sonarcloud'], words: ['sonar', 'sonarqube', 'sonarcloud'],
-    ci: [/SonarSource\/sonar(?:qube|cloud)-[a-z-]+-action/i, /\bsonar-scanner\b/i, /\bSONAR_TOKEN\b/] },
-  'container-registry': { providers: ['ghcr', 'dockerhub', 'ecr', 'gar'], words: ['ghcr', 'registry', 'docker hub', 'dockerhub'],
-    ci: [/docker\/login-action/i] },
-  analytics: { providers: ['posthog', 'plausible', 'umami', 'google-analytics'], words: ['posthog', 'plausible', 'umami', 'analytics'], ci: [] },
-  'error-tracking': { providers: ['sentry', 'glitchtip'], words: ['sentry', 'glitchtip'], ci: [/getsentry\/action-release/i, /\bSENTRY_AUTH_TOKEN\b/] },
+    codecov: { providers: ['codecov'], words: ['codecov'], ci: [/codecov\/codecov-action/i] },
+    dependabot: { providers: ['github'], words: ['dependabot'], ci: [] },
+    audit: { providers: ['npm'], words: ['audit'], ci: [/\bnpm audit\b/] },
+    sonar: { providers: ['sonarqube', 'sonarcloud'], words: ['sonar', 'sonarqube', 'sonarcloud'],
+        ci: [/SonarSource\/sonar(?:qube|cloud)-[a-z-]+-action/i, /\bsonar-scanner\b/i, /\bSONAR_TOKEN\b/] },
+    'container-registry': { providers: ['ghcr', 'dockerhub', 'ecr', 'gar'], words: ['ghcr', 'registry', 'docker hub', 'dockerhub'],
+        ci: [/docker\/login-action/i] },
+    analytics: { providers: ['posthog', 'plausible', 'umami', 'google-analytics'], words: ['posthog', 'plausible', 'umami', 'analytics'], ci: [] },
+    'error-tracking': { providers: ['sentry', 'glitchtip'], words: ['sentry', 'glitchtip'], ci: [/getsentry\/action-release/i, /\bSENTRY_AUTH_TOKEN\b/] },
+};
+/** The catalog entry of a catalogued service id; throws for an id the catalog does not know. */
+export const catalogOf = (id) => {
+    const entry = SERVICE_CATALOG[id];
+    if (!entry)
+        throw new TypeError(`${id} is not a catalogued service`);
+    return entry;
 };
 export const checkServiceForm = (service, id, entry, at, kind, add, ambiguous) => {
-  if (service.provider && !SERVICE_CATALOG[id].providers.includes(service.provider))
-    add('refuse', 'STACKS_PROVIDER_UNKNOWN', `${at}.provider`, `${service.provider} is not a ${id} provider (${SERVICE_CATALOG[id].providers.join(', ')})`);
-  if (Object.hasOwn(entry?.ci ?? {}, 'secrets') || Object.hasOwn(entry?.ci ?? {}, 'vars'))
-    add('suspect', 'STACKS_CI_LEGACY_FORM', `${at}.ci`, 'move the names to the top-level ci block and name them by services.<id>.ci.token / hostVar');
-  if (id === 'sonar' && service.provider === 'sonarcloud' && !service.organization
-    && !(kind === 'example' && service.runtimeSecrets.length && !service.credentials.length && service.ci.organizationVar))
-    ambiguous('provider sonarcloud requires organization; the runtime example form may use ci.organizationVar');
-  if (kind === 'example' && id === 'sonar' && service.provider !== 'sonarcloud')
-    add('refuse', 'STACKS_EXAMPLE_FORM', at, 'an example sonar provider must be sonarcloud');
-  if (kind === 'example' && id === 'codecov' && (service.auth !== 'oidc' || service.ci.token))
-    add('refuse', 'STACKS_EXAMPLE_FORM', at, 'an example codecov service uses auth oidc without a token');
+    if (service.provider && !catalogOf(id).providers.includes(service.provider))
+        add('refuse', 'STACKS_PROVIDER_UNKNOWN', `${at}.provider`, `${service.provider} is not a ${id} provider (${catalogOf(id).providers.join(', ')})`);
+    if (Object.hasOwn(entry?.ci ?? {}, 'secrets') || Object.hasOwn(entry?.ci ?? {}, 'vars'))
+        add('suspect', 'STACKS_CI_LEGACY_FORM', `${at}.ci`, 'move the names to the top-level ci block and name them by services.<id>.ci.token / hostVar');
+    if (id === 'sonar' && service.provider === 'sonarcloud' && !service.organization
+        && !(kind === 'example' && service.runtimeSecrets.length && !service.credentials.length && service.ci.organizationVar))
+        ambiguous('provider sonarcloud requires organization; the runtime example form may use ci.organizationVar');
+    if (kind === 'example' && id === 'sonar' && service.provider !== 'sonarcloud')
+        add('refuse', 'STACKS_EXAMPLE_FORM', at, 'an example sonar provider must be sonarcloud');
+    if (kind === 'example' && id === 'codecov' && (service.auth !== 'oidc' || service.ci.token))
+        add('refuse', 'STACKS_EXAMPLE_FORM', at, 'an example codecov service uses auth oidc without a token');
 };
 /** Examples may document optional workflow secret names, but never a Codecov token or a required extra secret. */
 function forbiddenExampleSecret(item) {
-  return item.name === ('CODECOV' + '_TOKEN') || (item.name !== 'SONAR_TOKEN' && item.optional !== true);
+    return item.name === ('CODECOV' + '_TOKEN') || (item.name !== 'SONAR_TOKEN' && item.optional !== true);
 }
 /** Validate the additive CI declaration and the public example secret policy. */
 export function checkCiDeclaration(declaration, declFile, kind, declarationSchema, schemaErrors, add) {
-  if (declaration?.doc && Object.hasOwn(declaration.doc, 'ci')) {
-    for (const issue of schemaErrors(declaration.doc.ci, declarationSchema().$defs.ciDeclaration, 'ci'))
-      add('refuse', 'CI_DECLARATION_INVALID', `${declFile}#${issue.path}`, issue.message);
-    const ci = readCiDeclaration(declaration.doc);
-    for (const problem of ci.problems) add('refuse', problem.code, `${declFile}#${problem.at}`, problem.message);
-    if (kind === 'example' && ci.secrets.some(forbiddenExampleSecret))
-      add('refuse', 'STACKS_EXAMPLE_FORM', `${declFile}#ci.secrets`, 'STACKS_EXAMPLE_FORM: an example declares CI secrets other than SONAR_TOKEN only with optional: true to document workflow names; no Codecov token or stored credentials');
-  }
+    if (declaration?.doc && Object.hasOwn(declaration.doc, 'ci')) {
+        for (const issue of schemaErrors(declaration.doc.ci, declarationSchema().$defs.ciDeclaration, 'ci'))
+            add('refuse', 'CI_DECLARATION_INVALID', `${declFile}#${issue.path}`, issue.message);
+        const ci = readCiDeclaration(declaration.doc);
+        for (const problem of ci.problems)
+            add('refuse', problem.code, `${declFile}#${problem.at}`, problem.message);
+        if (kind === 'example' && ci.secrets.some(forbiddenExampleSecret))
+            add('refuse', 'STACKS_EXAMPLE_FORM', `${declFile}#ci.secrets`, 'STACKS_EXAMPLE_FORM: an example declares CI secrets other than SONAR_TOKEN only with optional: true to document workflow names; no Codecov token or stored credentials');
+    }
 }
-
 /** Quality services use their CI binding without requiring hosted project or custody fields. */
 export function checkQualityService(service, id, at, context, checkServiceCi) {
-  const { ambiguous } = context;
-  if (['codecov', 'dependabot', 'audit'].includes(id)) {
-    if (id === 'codecov' && !['oidc', 'token'].includes(service.auth)) ambiguous('codecov auth must be oidc or token');
-    if (id === 'codecov' && service.auth === 'token' && !service.ci.token) ambiguous('codecov auth token requires ci.token');
-    checkServiceCi(service, id, at, context);
-    return true;
-  }
-  return false;
+    const { ambiguous } = context;
+    if (['codecov', 'dependabot', 'audit'].includes(id)) {
+        if (id === 'codecov' && !['oidc', 'token'].includes(service.auth ?? ''))
+            ambiguous('codecov auth must be oidc or token');
+        if (id === 'codecov' && service.auth === 'token' && !service.ci.token)
+            ambiguous('codecov auth token requires ci.token');
+        checkServiceCi(service, id, at, context);
+        return true;
+    }
+    return false;
 }