@starci/hfs 4.11.21 → 4.12.0

package/release/records.d.mts

@@ -0,0 +1,18 @@
+export declare const URGENT_SCHEMA = "starci-app-urgent-record/1";
+/** The owner's ruling an urgent record cites: CI and the full gate wait for the back-fill, the safety floor of the deploy never does. */
+export declare const URGENT_RULING = "owner ruling urgent-release 2026-10-29: an urgent release ships after the fast local checks; the full gate runs later on the same tag (release gate --backfill) and the deploy safety floor is never skipped";
+type Json = any;
+/** The sha256 of a file, or null when it cannot be read. */
+export declare const fileSha256: (file: string) => string | null;
+export declare const l4Path: (dir: string, head: string) => string;
+export declare const urgentPath: (dir: string, head: string) => string;
+/** The urgent record of `head`, or null when there is none or it is not an urgent record of that head. */
+export declare function readUrgent(dir: string, head: string): Json;
+export declare const writeUrgent: (dir: string, record: Json) => void;
+/** Appends a gate row to the rows of `head` (a row of the same name is replaced). */
+export declare function recordRow(dir: string, head: string, row: {
+    name: string;
+}): void;
+/** The recorded green row of `head` whose name and command match and whose log still has the recorded sha256, or null. */
+export declare function greenRow(dir: string, head: string, name: string, command: string): Json;
+export {};

package/release/records.mjs

@@ -8,47 +8,48 @@
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-
 export const URGENT_SCHEMA = 'starci-app-urgent-record/1';
 /** The owner's ruling an urgent record cites: CI and the full gate wait for the back-fill, the safety floor of the deploy never does. */
 export const URGENT_RULING = 'owner ruling urgent-release 2026-10-29: an urgent release ships after the fast local checks; the full gate runs later on the same tag (release gate --backfill) and the deploy safety floor is never skipped';
-
 const readJson = (file) => {
-  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
 };
-
 const writeJson = (file, value) => {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
 };
-
 /** The sha256 of a file, or null when it cannot be read. */
 export const fileSha256 = (file) => {
-  try { return createHash('sha256').update(fs.readFileSync(file)).digest('hex'); } catch { return null; }
+    try {
+        return createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+    }
+    catch {
+        return null;
+    }
 };
-
 export const l4Path = (dir, head) => path.join(dir, `${head}.l4.json`);
 export const urgentPath = (dir, head) => path.join(dir, `${head}.urgent.json`);
 const rowsPath = (dir, head) => path.join(dir, head.slice(0, 12), 'rows.json');
-
 /** The urgent record of `head`, or null when there is none or it is not an urgent record of that head. */
 export function readUrgent(dir, head) {
-  const record = readJson(urgentPath(dir, head));
-  return record?.schema === URGENT_SCHEMA && record.head === head ? record : null;
+    const record = readJson(urgentPath(dir, head));
+    return record?.schema === URGENT_SCHEMA && record.head === head ? record : null;
 }
-
 export const writeUrgent = (dir, record) => writeJson(urgentPath(dir, record.head), record);
-
 /** Appends a gate row to the rows of `head` (a row of the same name is replaced). */
 export function recordRow(dir, head, row) {
-  const file = rowsPath(dir, head);
-  const rows = (readJson(file) ?? []).filter((known) => known?.name !== row.name);
-  writeJson(file, [...rows, row]);
+    const file = rowsPath(dir, head);
+    const rows = (readJson(file) ?? []).filter((known) => known?.name !== row.name);
+    writeJson(file, [...rows, row]);
 }
-
 /** The recorded green row of `head` whose name and command match and whose log still has the recorded sha256, or null. */
 export function greenRow(dir, head, name, command) {
-  const rows = readJson(rowsPath(dir, head)) ?? [];
-  const row = rows.find((known) => known?.name === name && known.command === command && known.pass === true);
-  return row && row.log && fileSha256(row.log) === row.logSha256 ? row : null;
+    const rows = readJson(rowsPath(dir, head)) ?? [];
+    const row = rows.find((known) => known?.name === name && known.command === command && known.pass === true);
+    return row && row.log && fileSha256(row.log) === row.logSha256 ? row : null;
 }

package/release/sonar-quality-gate.d.mts

@@ -0,0 +1,18 @@
+import type { VerbContext } from './index.mjs';
+/**
+ * The quality-gate verdict of the analysis the scanner just uploaded from `cwd`: `{ pass, detail, conditions? }`. `token` is the
+ * scanner's token, `host` the declared server. `ctx.fetch`, `ctx.now` and `ctx.sleep` are the seams; `wait` bounds the poll.
+ */
+export declare function sonarQualityGate(ctx: VerbContext, { cwd, host, token, wait }: {
+    cwd: string;
+    host: string;
+    token: string;
+    wait?: {
+        deadline: number;
+        interval: number;
+    };
+}): Promise<{
+    pass: boolean;
+    detail: string;
+    conditions?: string[];
+}>;

package/release/sonar-quality-gate.mjs

@@ -6,7 +6,6 @@
 // read failure (a network error or an HTTP 5xx) is retried with a bounded backoff inside the same wait before it is unreadable.
 import fs from 'node:fs';
 import path from 'node:path';
-
 const SONAR_GATE_FAILED = 'RELEASE_SONAR_GATE_FAILED';
 const SONAR_GATE_TIMEOUT = 'RELEASE_SONAR_GATE_TIMEOUT';
 const SONAR_GATE_UNREADABLE = 'RELEASE_SONAR_GATE_UNREADABLE';
@@ -14,80 +13,89 @@ const REPORT_TASK = path.join('.scannerwork', 'report-task.txt');
 const DONE = new Set(['SUCCESS', 'FAILED', 'CANCELED']);
 /** The bound of one compute-engine wait and the pause between polls (milliseconds). */
 const QUALITY_GATE_WAIT = Object.freeze({ deadline: 600_000, interval: 5_000 });
-
 /** The `key=value` lines of the scanner's report-task.txt under `cwd`, or null when the scanner wrote none. */
 function reportTask(cwd) {
-  let text;
-  try { text = fs.readFileSync(path.join(cwd, REPORT_TASK), 'utf8'); } catch { return null; }
-  return Object.fromEntries(text.split(/\r?\n/u).map((line) => line.split('=')).filter(([key, ...rest]) => key && rest.length).map(([key, ...rest]) => [key.trim(), rest.join('=').trim()]));
+    let text;
+    try {
+        text = fs.readFileSync(path.join(cwd, REPORT_TASK), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    return Object.fromEntries(text.split(/\r?\n/u).map((line) => line.split('=')).filter(([key, ...rest]) => key && rest.length).map(([key, ...rest]) => [key.trim(), rest.join('=').trim()]));
 }
-
 /** The bound of a transient read failure: attempts per request and the first pause, doubled after each retry (milliseconds). */
 const TRANSIENT_RETRY = Object.freeze({ attempts: 5, firstPause: 2_000 });
-
 /** One authenticated JSON GET; a failed request or a non-JSON body throws. A network error or an HTTP 5xx is marked transient. */
 async function getJsonOnce(ctx, url, token) {
-  let response;
-  try {
-    response = await ctx.fetch(url, { headers: { Authorization: `Basic ${Buffer.from(`${token}:`).toString('base64')}` }, signal: AbortSignal.timeout(30_000) });
-  } catch (error) {
-    throw Object.assign(new Error(`${String(error?.message ?? error)} (${url.split('?')[0]})`), { transient: true });
-  }
-  if (!response.ok) throw Object.assign(new Error(`HTTP ${response.status} from ${url.split('?')[0]}`), { transient: response.status >= 500 });
-  return response.json();
+    let response;
+    try {
+        response = await ctx.fetch(url, { headers: { Authorization: `Basic ${Buffer.from(`${token}:`).toString('base64')}` }, signal: AbortSignal.timeout(30_000) });
+    }
+    catch (error) {
+        throw Object.assign(new Error(`${String(error?.message ?? error)} (${url.split('?')[0]})`), { transient: true });
+    }
+    if (!response.ok)
+        throw Object.assign(new Error(`HTTP ${response.status} from ${url.split('?')[0]}`), { transient: response.status >= 500 });
+    return response.json();
 }
-
 /**
  * getJsonOnce, retried only when the failure is transient (a network error or an HTTP 5xx): at most TRANSIENT_RETRY.attempts
  * tries, pausing 2 s, 4 s, 8 s, ... between them, and never past `deadline`. A 4xx (401 and 403 included) and an unreadable body
  * throw at once; the last transient failure throws as itself, so a retry never turns an unreadable answer into a verdict.
  */
 async function getJson(ctx, url, token, { sleep, deadline }) {
-  for (let attempt = 1, pause = TRANSIENT_RETRY.firstPause; ; attempt += 1, pause *= 2) {
-    try { return await getJsonOnce(ctx, url, token); }
-    catch (error) {
-      if (!error.transient || attempt >= TRANSIENT_RETRY.attempts || ctx.now() + pause > deadline) throw error;
-      await sleep(pause);
+    for (let attempt = 1, pause = TRANSIENT_RETRY.firstPause;; attempt += 1, pause *= 2) {
+        try {
+            return await getJsonOnce(ctx, url, token);
+        }
+        catch (error) {
+            if (!error.transient || attempt >= TRANSIENT_RETRY.attempts || ctx.now() + pause > deadline)
+                throw error;
+            await sleep(pause);
+        }
     }
-  }
 }
-
 /** The failed conditions of a quality gate answer, as `metric comparator threshold (actual value)` lines. */
 const failedConditions = (status) => (status?.conditions ?? []).filter((condition) => condition.status === 'ERROR')
-  .map((condition) => `${condition.metricKey} ${condition.comparator ?? ''} ${condition.errorThreshold ?? ''} (actual ${condition.actualValue ?? '?'})`.replace(/\s+/gu, ' '));
-
+    .map((condition) => `${condition.metricKey} ${condition.comparator ?? ''} ${condition.errorThreshold ?? ''} (actual ${condition.actualValue ?? '?'})`.replace(/\s+/gu, ' '));
 /**
  * The quality-gate verdict of the analysis the scanner just uploaded from `cwd`: `{ pass, detail, conditions? }`. `token` is the
  * scanner's token, `host` the declared server. `ctx.fetch`, `ctx.now` and `ctx.sleep` are the seams; `wait` bounds the poll.
  */
 export async function sonarQualityGate(ctx, { cwd, host, token, wait = QUALITY_GATE_WAIT }) {
-  const task = reportTask(cwd);
-  if (!task?.ceTaskId) return { pass: false, detail: `${SONAR_GATE_UNREADABLE}: the scanner wrote no ${REPORT_TASK.replaceAll('\\', '/')} with a ceTaskId` };
-  const server = String(task.serverUrl || host).replace(/\/$/u, '');
-  const sleep = ctx.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
-  const deadline = ctx.now() + wait.deadline;
-  const retry = { sleep, deadline };
-  let analysisId = null;
-  try {
-    for (;;) {
-      const state = (await getJson(ctx, `${server}/api/ce/task?id=${encodeURIComponent(task.ceTaskId)}`, token, retry))?.task;
-      if (DONE.has(state?.status)) {
-        if (state.status !== 'SUCCESS') return { pass: false, detail: `${SONAR_GATE_FAILED}: compute-engine task ${task.ceTaskId} ended ${state.status}${state.errorMessage ? `: ${state.errorMessage}` : ''}` };
-        analysisId = state.analysisId;
-        break;
-      }
-      if (ctx.now() >= deadline) return { pass: false, detail: `${SONAR_GATE_TIMEOUT}: compute-engine task ${task.ceTaskId} is still ${state?.status ?? 'unknown'} after ${Math.round(wait.deadline / 1000)}s` };
-      await sleep(wait.interval);
+    const task = reportTask(cwd);
+    if (!task?.ceTaskId)
+        return { pass: false, detail: `${SONAR_GATE_UNREADABLE}: the scanner wrote no ${REPORT_TASK.replaceAll('\\', '/')} with a ceTaskId` };
+    const server = String(task.serverUrl || host).replace(/\/$/u, '');
+    const sleep = ctx.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const deadline = ctx.now() + wait.deadline;
+    const retry = { sleep, deadline };
+    let analysisId = null;
+    try {
+        for (;;) {
+            const state = (await getJson(ctx, `${server}/api/ce/task?id=${encodeURIComponent(task.ceTaskId)}`, token, retry))?.task;
+            if (DONE.has(state?.status)) {
+                if (state.status !== 'SUCCESS')
+                    return { pass: false, detail: `${SONAR_GATE_FAILED}: compute-engine task ${task.ceTaskId} ended ${state.status}${state.errorMessage ? `: ${state.errorMessage}` : ''}` };
+                analysisId = state.analysisId;
+                break;
+            }
+            if (ctx.now() >= deadline)
+                return { pass: false, detail: `${SONAR_GATE_TIMEOUT}: compute-engine task ${task.ceTaskId} is still ${state?.status ?? 'unknown'} after ${Math.round(wait.deadline / 1000)}s` };
+            await sleep(wait.interval);
+        }
+        const query = analysisId ? `analysisId=${encodeURIComponent(analysisId)}` : `projectKey=${encodeURIComponent(task.projectKey ?? '')}`;
+        const status = (await getJson(ctx, `${server}/api/qualitygates/project_status?${query}`, token, retry))?.projectStatus;
+        if (status?.status === 'OK')
+            return { pass: true, detail: 'exit 0, quality gate OK' };
+        if (status?.status === 'ERROR') {
+            const conditions = failedConditions(status);
+            return { pass: false, detail: `${SONAR_GATE_FAILED}: quality gate ERROR (${conditions.join('; ') || 'no condition listed'})${task.dashboardUrl ? ` ${task.dashboardUrl}` : ''}`, conditions };
+        }
+        return { pass: false, detail: `${SONAR_GATE_UNREADABLE}: quality gate status ${status?.status ?? 'missing'}` };
     }
-    const query = analysisId ? `analysisId=${encodeURIComponent(analysisId)}` : `projectKey=${encodeURIComponent(task.projectKey ?? '')}`;
-    const status = (await getJson(ctx, `${server}/api/qualitygates/project_status?${query}`, token, retry))?.projectStatus;
-    if (status?.status === 'OK') return { pass: true, detail: 'exit 0, quality gate OK' };
-    if (status?.status === 'ERROR') {
-      const conditions = failedConditions(status);
-      return { pass: false, detail: `${SONAR_GATE_FAILED}: quality gate ERROR (${conditions.join('; ') || 'no condition listed'})${task.dashboardUrl ? ` ${task.dashboardUrl}` : ''}`, conditions };
+    catch (error) {
+        return { pass: false, detail: `${SONAR_GATE_UNREADABLE}: ${String(error?.message ?? error)}` };
     }
-    return { pass: false, detail: `${SONAR_GATE_UNREADABLE}: quality gate status ${status?.status ?? 'missing'}` };
-  } catch (error) {
-    return { pass: false, detail: `${SONAR_GATE_UNREADABLE}: ${String(error?.message ?? error)}` };
-  }
 }

package/release/urgent.d.mts

@@ -0,0 +1,20 @@
+import type { ReleaseConfig } from './gate.mjs';
+import type { VerbContext, VerbResult } from './index.mjs';
+/**
+ * The fast local checks of an urgent release, by gate name, in the order they run: what can break production, the types and the build
+ * (owner ruling urgent-typecheck-build, 2026-10-30). App check, lint and the tests wait for the back-fill (`release gate --backfill`).
+ */
+export declare const URGENT_CHECKS: readonly string[];
+/**
+ * `starci app release push --urgent`. options: { execute, remote, reason, role, platform }. Dry run prints the checks, the tag and the push it would
+ * make; --execute runs them, tags, pushes atomically and writes the urgent record. A red check is RELEASE_URGENT_CHECK_RED: nothing tagged, nothing pushed.
+ */
+export declare function releaseUrgentPush(ctx: VerbContext, config: ReleaseConfig, options?: {
+    execute?: boolean | undefined;
+    remote?: string | boolean | undefined;
+    reason?: string | boolean | undefined;
+    role?: string | undefined;
+    platform?: string;
+}): Promise<VerbResult & {
+    lines: string[];
+}>;

package/release/urgent.mjs

@@ -12,101 +12,103 @@ import { failure, refusal } from '../stack/errors.mjs';
 import { assertUnmoved, git, inspect, releaseDir, runGate, summaryOf } from './gate.mjs';
 import { assertNames, branchRefs, probe, tagRefs } from './push.mjs';
 import { URGENT_RULING, URGENT_SCHEMA, greenRow, recordRow, writeUrgent } from './records.mjs';
-
 /**
  * The fast local checks of an urgent release, by gate name, in the order they run: what can break production, the types and the build
  * (owner ruling urgent-typecheck-build, 2026-10-30). App check, lint and the tests wait for the back-fill (`release gate --backfill`).
  */
 export const URGENT_CHECKS = Object.freeze(['typecheck', 'build', 'build-be', 'build-fe']);
 const REASON_MAX = 500;
-
 /** The reason, one line of plain text; an urgent release without one is refused. */
 function reasonOf(value) {
-  const reason = String(value ?? '').replaceAll(/\s+/gu, ' ').trim();
-  if (reason === '') throw refusal('RELEASE_URGENT_REASON_MISSING', 'an urgent release says why: --reason "<text>"');
-  if (reason.length > REASON_MAX) throw refusal('RELEASE_URGENT_REASON_MISSING', `--reason is one line of at most ${REASON_MAX} characters`);
-  return reason;
+    const reason = String(value ?? '').replaceAll(/\s+/gu, ' ').trim();
+    if (reason === '')
+        throw refusal('RELEASE_URGENT_REASON_MISSING', 'an urgent release says why: --reason "<text>"');
+    if (reason.length > REASON_MAX)
+        throw refusal('RELEASE_URGENT_REASON_MISSING', `--reason is one line of at most ${REASON_MAX} characters`);
+    return reason;
 }
-
-/** The urgent checks this app declares, from its release gates, in URGENT_CHECKS order. */
 function urgentGates(config) {
-  const declared = URGENT_CHECKS.map((name) => config.gates.find((gate) => gate.name === name)).filter(Boolean);
-  if (declared.length === 0) throw refusal('RELEASE_URGENT_NO_CHECKS', `the release gates declare none of ${URGENT_CHECKS.join(', ')}: an urgent release still runs its fast local checks`);
-  return declared.map((gate) => ({ name: gate.name, gate, note: null }));
+    const declared = URGENT_CHECKS.map((name) => config.gates.find((gate) => gate.name === name)).filter((gate) => Boolean(gate));
+    if (declared.length === 0)
+        throw refusal('RELEASE_URGENT_NO_CHECKS', `the release gates declare none of ${URGENT_CHECKS.join(', ')}: an urgent release still runs its fast local checks`);
+    return declared.map((gate) => ({ name: gate.name, gate, note: null }));
 }
-
 /** Runs (or reuses) each check in order and stops at the first red one. Returns the rows of the record. */
 function runChecks(ctx, checks, { common, head, dir, platform }) {
-  fs.mkdirSync(dir, { recursive: true });
-  const rows = [];
-  for (const check of checks) {
-    if (!check.gate) {
-      rows.push({ name: check.name, command: null, pass: true, reused: false, detail: check.note, log: null, logSha256: null });
-      continue;
+    fs.mkdirSync(dir, { recursive: true });
+    const rows = [];
+    for (const check of checks) {
+        if (!check.gate) {
+            rows.push({ name: check.name, command: null, pass: true, reused: false, detail: check.note, log: null, logSha256: null });
+            continue;
+        }
+        const command = check.gate.command.join(' ');
+        const reused = greenRow(common, head, check.name, command);
+        if (reused) {
+            rows.push({ ...reused, reused: true, ...(check.note ? { note: check.note } : {}) });
+            continue;
+        }
+        const row = runGate(ctx, check.gate, { dir, platform, credentialNames: [] });
+        recordRow(common, head, row);
+        rows.push({ ...row, reused: false, ...(check.note ? { note: check.note } : {}) });
+        if (!row.pass)
+            break;
     }
-    const command = check.gate.command.join(' ');
-    const reused = greenRow(common, head, check.name, command);
-    if (reused) {
-      rows.push({ ...reused, reused: true, ...(check.note ? { note: check.note } : {}) });
-      continue;
-    }
-    const row = runGate(ctx, check.gate, { dir, platform, credentialNames: [] });
-    recordRow(common, head, row);
-    rows.push({ ...row, reused: false, ...(check.note ? { note: check.note } : {}) });
-    if (!row.pass) break;
-  }
-  return rows;
+    return rows;
 }
-
 const checkLine = (row) => (row.command === null ? `SKIP ${row.name} (${row.detail})` : `${row.reused ? 'REUSED ' : ''}${summaryOf(row)}`);
-
 function planOf(checks) {
-  return ['urgent checks (each must pass; a green row recorded for HEAD with the same command and log is reused):',
-    ...checks.map((check) => `  ${check.name.padEnd(10)} ${check.gate ? check.gate.command.join(' ') : '(nothing to run)'}${check.note ? `  [${check.note}]` : ''}`)];
+    return ['urgent checks (each must pass; a green row recorded for HEAD with the same command and log is reused):',
+        ...checks.map((check) => `  ${check.name.padEnd(10)} ${check.gate ? check.gate.command.join(' ') : '(nothing to run)'}${check.note ? `  [${check.note}]` : ''}`)];
 }
-
 /**
  * `starci app release push --urgent`. options: { execute, remote, reason, role, platform }. Dry run prints the checks, the tag and the push it would
  * make; --execute runs them, tags, pushes atomically and writes the urgent record. A red check is RELEASE_URGENT_CHECK_RED: nothing tagged, nothing pushed.
  */
 export async function releaseUrgentPush(ctx, config, options = {}) {
-  const reason = reasonOf(options.reason);
-  if (options.lintBaseline !== undefined) throw refusal('RELEASE_URGENT_LINT_BASELINE_RETIRED', 'an urgent release no longer lints (owner ruling urgent-typecheck-build): lint runs in the back-fill, so --lint-baseline has nothing to judge');
-  const role = options.role ?? 'unset';
-  const remote = options.remote ?? 'origin';
-  const branch = config.defaultBranch;
-  assertNames(remote, branch);
-  const facts = inspect(ctx, config, {});
-  const { head, chosen } = facts;
-  const common = releaseDir(ctx);
-  const dir = path.join(common, head.slice(0, 12));
-  const checks = urgentGates(config);
-  const out = [...facts.out, `urgent         ${URGENT_RULING}`, `reason         ${reason}`, `role           ${role}`, ...planOf(checks)];
-  const data = { head, tag: chosen.tag, remote, branch, urgent: true, reason, role, checks: [], pushed: false };
-  if (facts.red.length > 0) return { ok: false, lines: [...out, ...facts.red.map((item) => `RED: ${item}`), 'nothing run, nothing pushed.'], data: { ...data, red: facts.red } };
-  const red = [];
-  const refs = [...branchRefs(ctx, { head, remote, branch }, red).refs, ...(chosen.state === 'on-head' ? tagRefs(ctx, { remote, tag: chosen.tag }, red) : [`refs/tags/${chosen.tag}`])];
-  out.push(`plan           git tag -a ${chosen.tag}${chosen.state === 'on-head' ? ' (already on HEAD)' : ''}, then git push --atomic ${remote} ${refs.join(' ') || '(nothing)'}; no candidate CI`);
-  if (red.length > 0) return { ok: false, lines: [...out, ...red.map((item) => `RED: ${item}`), 'nothing run, nothing pushed.'], data: { ...data, red } };
-  if (options.execute !== true) return { ok: true, lines: [...out, 'dry run: no check run, nothing tagged or pushed. ready; re-run with --execute.'], data };
-  const rows = runChecks(ctx, checks, { common, head, dir, platform: options.platform ?? process.platform });
-  data.checks = rows;
-  out.push(...rows.map(checkLine));
-  const failed = rows.find((row) => !row.pass);
-  if (failed) throw failure('RELEASE_URGENT_CHECK_RED', `${failed.name} is red (${failed.detail}; log ${failed.log}): nothing tagged, nothing pushed`);
-  assertUnmoved(ctx, head);
-  if (chosen.state !== 'on-head') git(ctx, ['tag', '-a', chosen.tag, '-m', `URGENT release ${chosen.tag} on ${head.slice(0, 12)} by ${role}: ${reason} (fast local checks only; back-fill: starci app release gate --backfill ${chosen.tag})`, head]);
-  if (refs.length > 0) {
-    const hook = probe(ctx, remote, refs, red);
-    out.push(...hook.lines);
-    if (red.length > 0) return { ok: false, lines: [...out, ...red.map((item) => `RED: ${item}`), `nothing pushed; ${chosen.tag} stays local.`], data };
-    const run = git(ctx, ['push', '--atomic', remote, ...refs], { allowFail: true });
-    if (run.code !== 0) return { ok: false, lines: [...out, `push failed: ${firstLine(run.stderr)}; ${chosen.tag} stays local.`], data };
-  }
-  const record = {
-    schema: URGENT_SCHEMA, head, tag: chosen.tag, createdAt: new Date(ctx.now()).toISOString(), producedBy: 'starci app release push --urgent',
-    role, reason, ruling: URGENT_RULING, remote, branch, refs, pushed: true, checks: rows, backfill: null,
-  };
-  writeUrgent(common, record);
-  return { ok: true, lines: [...out, `pushed to ${remote}: ${refs.join(' ') || '(already there)'}`, `URGENT record written: ${path.join(common, `${head}.urgent.json`)}`, `back-fill later: starci app release gate --backfill ${chosen.tag} --execute (in a clean checkout of ${chosen.tag})`], data: { ...data, pushed: true, record: path.join(common, `${head}.urgent.json`) } };
+    const reason = reasonOf(options.reason);
+    const role = options.role ?? 'unset';
+    const remote = (options.remote ?? 'origin');
+    const branch = config.defaultBranch;
+    assertNames(remote, branch);
+    const facts = inspect(ctx, config, {});
+    const { head, chosen } = facts;
+    const common = releaseDir(ctx);
+    const dir = path.join(common, head.slice(0, 12));
+    const checks = urgentGates(config);
+    const out = [...facts.out, `urgent         ${URGENT_RULING}`, `reason         ${reason}`, `role           ${role}`, ...planOf(checks)];
+    const data = { head, tag: chosen.tag, remote, branch, urgent: true, reason, role, checks: [], pushed: false };
+    if (facts.red.length > 0)
+        return { ok: false, lines: [...out, ...facts.red.map((item) => `RED: ${item}`), 'nothing run, nothing pushed.'], data: { ...data, red: facts.red } };
+    const red = [];
+    const refs = [...branchRefs(ctx, { head, remote, branch }, red).refs, ...(chosen.state === 'on-head' ? tagRefs(ctx, { remote, tag: chosen.tag }, red) : [`refs/tags/${chosen.tag}`])];
+    out.push(`plan           git tag -a ${chosen.tag}${chosen.state === 'on-head' ? ' (already on HEAD)' : ''}, then git push --atomic ${remote} ${refs.join(' ') || '(nothing)'}; no candidate CI`);
+    if (red.length > 0)
+        return { ok: false, lines: [...out, ...red.map((item) => `RED: ${item}`), 'nothing run, nothing pushed.'], data: { ...data, red } };
+    if (options.execute !== true)
+        return { ok: true, lines: [...out, 'dry run: no check run, nothing tagged or pushed. ready; re-run with --execute.'], data };
+    const rows = runChecks(ctx, checks, { common, head, dir, platform: options.platform ?? process.platform });
+    data.checks = rows;
+    out.push(...rows.map(checkLine));
+    const failed = rows.find((row) => !row.pass);
+    if (failed)
+        throw failure('RELEASE_URGENT_CHECK_RED', `${failed.name} is red (${failed.detail}; log ${failed.log}): nothing tagged, nothing pushed`);
+    assertUnmoved(ctx, head);
+    if (chosen.state !== 'on-head')
+        git(ctx, ['tag', '-a', chosen.tag, '-m', `URGENT release ${chosen.tag} on ${head.slice(0, 12)} by ${role}: ${reason} (fast local checks only; back-fill: starci app release gate --backfill ${chosen.tag})`, head]);
+    if (refs.length > 0) {
+        const hook = probe(ctx, remote, refs, red);
+        out.push(...hook.lines);
+        if (red.length > 0)
+            return { ok: false, lines: [...out, ...red.map((item) => `RED: ${item}`), `nothing pushed; ${chosen.tag} stays local.`], data };
+        const run = git(ctx, ['push', '--atomic', remote, ...refs], { allowFail: true });
+        if (run.code !== 0)
+            return { ok: false, lines: [...out, `push failed: ${firstLine(run.stderr)}; ${chosen.tag} stays local.`], data };
+    }
+    const record = {
+        schema: URGENT_SCHEMA, head, tag: chosen.tag, createdAt: new Date(ctx.now()).toISOString(), producedBy: 'starci app release push --urgent',
+        role, reason, ruling: URGENT_RULING, remote, branch, refs, pushed: true, checks: rows, backfill: null,
+    };
+    writeUrgent(common, record);
+    return { ok: true, lines: [...out, `pushed to ${remote}: ${refs.join(' ') || '(already there)'}`, `URGENT record written: ${path.join(common, `${head}.urgent.json`)}`, `back-fill later: starci app release gate --backfill ${chosen.tag} --execute (in a clean checkout of ${chosen.tag})`], data: { ...data, pushed: true, record: path.join(common, `${head}.urgent.json`) } };
 }

package/report/order.d.mts

@@ -0,0 +1 @@
+export declare const byCodeUnit: (a: unknown, b: unknown) => number;

package/report/sonar.d.mts

@@ -0,0 +1,73 @@
+/** A Sonar rule of the import document. */
+export interface SonarRule {
+    id: string;
+    name: string;
+    description: string;
+    engineId: string;
+    cleanCodeAttribute: string;
+    impacts: {
+        softwareQuality: string;
+        severity: string;
+    }[];
+}
+/** Where an issue is: the file, the message and, when known, its lines. */
+export interface PrimaryLocation {
+    message: string;
+    filePath: string;
+    textRange?: {
+        startLine: number;
+        endLine: number;
+    };
+}
+/** One issue of the import document. */
+export interface SonarIssue {
+    ruleId: string;
+    effortMinutes: number;
+    primaryLocation: PrimaryLocation;
+}
+/** The Generic Issue Import document: { rules, issues }. */
+export interface SonarDocument {
+    rules: SonarRule[];
+    issues: SonarIssue[];
+}
+/** The placement inputs: the sonar.sources roots and the tracked files. */
+interface Placing {
+    sourceRoots?: readonly string[];
+    tracked?: readonly string[];
+}
+/** One finding of `starci app check` as the report reads it. */
+interface CheckFinding {
+    level: string;
+    code: string;
+    title?: string;
+    titleVi?: string;
+    whyVi?: string;
+    nextStepVi?: string;
+    path?: string;
+    message: string;
+    line?: number;
+}
+type LinterResult = any;
+/** One document of several (the starci-hfs, eslint and stylelint documents of one app lint): rules by id, issues in the one sort order. */
+export declare function mergeReports(reports: readonly SonarDocument[]): SonarDocument;
+/**
+ * The Generic Issue Import document of a check's findings (the `findings` of checkRepository, each with the catalog's
+ * `title`, `titleVi`, `whyVi` and `nextStepVi`). `sourceRoots` and `tracked` place a finding that lies outside the indexed
+ * sources (see placement); without them every finding keeps its own path.
+ */
+export declare function sonarReport(findings: readonly CheckFinding[], { sourceRoots, tracked }?: Placing): SonarDocument;
+/**
+ * A linter's json results (`eslint -f json`: [{ filePath, messages: [{ ruleId, line, endLine, message }] }]; `stylelint
+ * --formatter json`: [{ source, warnings: [{ line, endLine, rule, text }] }]) as a Generic Issue Import document. `root` is
+ * the directory paths are made relative to (the repository root, where the scan runs); a file outside it is skipped.
+ * `sourceRoots` and `tracked` place a finding on a file Sonar does not index (see placement). A parse error or an invalid
+ * option is a finding the linter reports without a rule name; it is imported under the rule `eslint-error` / `stylelint-error`.
+ */
+export declare function linterReport(kind: string, results: readonly LinterResult[], { root, sourceRoots, tracked }: Placing & {
+    root: string;
+}): SonarDocument;
+/** The `sonar.sources` roots of a sonar-project.properties text (empty when the file does not name them). */
+export declare function sourceRootsOf(propertiesText: unknown): string[];
+/** Write a report as JSON (2-space, LF, trailing newline), creating the directory. */
+export declare function writeReport(file: string, report: SonarDocument): void;
+export {};