@mindlace/chreode 0.1.0 → 0.3.0

package/dist/config/validate.js

@@ -1,4 +1,4 @@
-import { DEFAULT_BASE_BRANCH, DEFAULT_STATUS_CONTEXT, DEFAULT_TIMEOUT_MS } from './types.js';
+import { DEFAULT_BASE_BRANCH, DEFAULT_BURN_IN_MAX_FILES, DEFAULT_BURN_IN_REPEATS, DEFAULT_STATUS_CONTEXT, DEFAULT_TIMEOUT_MS, resolveFlakes } from './types.js';
 export class ConfigError extends Error {
     problems;
     constructor(problems) {
@@ -11,10 +11,13 @@ const TOP_KEYS = new Set([
     'baseBranch',
     'statusContext',
     'rules',
+    'versionBumpTriggers',
     'steps',
     'afterMerge',
     'stderrAllowlist',
-    'protection'
+    'protection',
+    'flakes',
+    'burnIn'
 ]);
 const RULE_KEYS = new Set(['match', 'triggers']);
 const STEP_KEYS = new Set([
@@ -28,6 +31,10 @@ const STEP_KEYS = new Set([
 ]);
 const ALLOW_KEYS = new Set(['pattern', 'reason']);
 const PROTECTION_KEYS = new Set(['branch', 'repo']);
+const FLAKES_KEYS = new Set(['threshold', 'snoozeLabel', 'playbookUrl']);
+const BURN_IN_KEYS = new Set(['repeats', 'maxFiles', 'runners']);
+const RUNNER_KEYS = new Set(['name', 'match', 'ignore', 'command']);
+const MATCHER_PROBLEM = 'must be a glob string, a RegExp, or a non-empty array of them';
 /** Cross-realm safe: a config evaluated by jiti may not share this realm's RegExp. */
 export function isRegExp(v) {
     return Object.prototype.toString.call(v) === '[object RegExp]';
@@ -44,6 +51,12 @@ function isStringArray(v) {
 function isMatcher(v) {
     return isNonEmptyString(v) || isRegExp(v);
 }
+function isMatcherList(v) {
+    return Array.isArray(v) ? v.length > 0 && v.every(isMatcher) : isMatcher(v);
+}
+function isPositiveInteger(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v > 0;
+}
 function unknownKeys(obj, allowed, where, problems) {
     for (const key of Object.keys(obj)) {
         if (!allowed.has(key))
@@ -64,17 +77,23 @@ function validateRules(raw, problems) {
             return;
         }
         unknownKeys(rule, RULE_KEYS, where, problems);
-        const m = rule.match;
-        const ok = Array.isArray(m) ? m.length > 0 && m.every(isMatcher) : isMatcher(m);
-        if (!ok) {
-            problems.push(`${where}.match: must be a glob string, a RegExp, or a non-empty array of them`);
-        }
+        if (!isMatcherList(rule.match))
+            problems.push(`${where}.match: ${MATCHER_PROBLEM}`);
         if (!Array.isArray(rule.triggers) || !rule.triggers.every(isNonEmptyString)) {
             problems.push(`${where}.triggers: must be an array of trigger names ([] means "matched, run nothing")`);
         }
     });
     return raw;
 }
+function validateVersionBumpTriggers(raw, problems) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw) || !raw.every(isNonEmptyString)) {
+        problems.push('config.versionBumpTriggers: must be an array of trigger names ([] runs nothing)');
+        return [];
+    }
+    return raw;
+}
 function validateSteps(raw, problems) {
     if (!Array.isArray(raw)) {
         problems.push('config.steps: must be an array');
@@ -173,6 +192,67 @@ function validateProtection(raw, problems) {
     }
     return raw;
 }
+function validateFlakes(raw, problems) {
+    if (raw === undefined)
+        return null;
+    if (!isRecord(raw)) {
+        problems.push('config.flakes: must be an object ({} turns flake tracking on with the defaults)');
+        return null;
+    }
+    unknownKeys(raw, FLAKES_KEYS, 'flakes', problems);
+    if (raw.threshold !== undefined && !isPositiveInteger(raw.threshold)) {
+        problems.push('flakes.threshold: must be a positive integer');
+    }
+    for (const key of ['snoozeLabel', 'playbookUrl']) {
+        if (raw[key] !== undefined && !isNonEmptyString(raw[key])) {
+            problems.push(`flakes.${key}: must be a non-empty string`);
+        }
+    }
+    return resolveFlakes(raw);
+}
+function validateBurnIn(raw, problems) {
+    if (raw === undefined)
+        return null;
+    if (!isRecord(raw)) {
+        problems.push('config.burnIn: must be an object');
+        return null;
+    }
+    unknownKeys(raw, BURN_IN_KEYS, 'burnIn', problems);
+    for (const key of ['repeats', 'maxFiles']) {
+        if (raw[key] !== undefined && !isPositiveInteger(raw[key])) {
+            problems.push(`burnIn.${key}: must be a positive integer`);
+        }
+    }
+    const runners = raw.runners;
+    if (!Array.isArray(runners) || runners.length === 0) {
+        problems.push('burnIn.runners: must be a non-empty array');
+    }
+    else {
+        runners.forEach((runner, i) => {
+            const where = `burnIn.runners[${i}]`;
+            if (!isRecord(runner)) {
+                problems.push(`${where}: must be an object`);
+                return;
+            }
+            unknownKeys(runner, RUNNER_KEYS, where, problems);
+            if (!isNonEmptyString(runner.name))
+                problems.push(`${where}.name: must be a non-empty string`);
+            if (!isMatcherList(runner.match))
+                problems.push(`${where}.match: ${MATCHER_PROBLEM}`);
+            if (runner.ignore !== undefined && !isMatcherList(runner.ignore)) {
+                problems.push(`${where}.ignore: ${MATCHER_PROBLEM}`);
+            }
+            if (typeof runner.command !== 'function') {
+                problems.push(`${where}.command: must be a function (files, repeats) => string | string[]`);
+            }
+        });
+    }
+    return {
+        repeats: raw.repeats ?? DEFAULT_BURN_IN_REPEATS,
+        maxFiles: raw.maxFiles ?? DEFAULT_BURN_IN_MAX_FILES,
+        runners: Array.isArray(runners) ? runners : []
+    };
+}
 export function validateConfig(raw) {
     if (!isRecord(raw)) {
         throw new ConfigError([
@@ -187,18 +267,24 @@ export function validateConfig(raw) {
         }
     }
     const rules = validateRules(raw.rules, problems);
+    const versionBumpTriggers = validateVersionBumpTriggers(raw.versionBumpTriggers, problems);
     const steps = validateSteps(raw.steps, problems);
     const stderrAllowlist = validateAllowlist(raw.stderrAllowlist, problems);
     const protection = validateProtection(raw.protection, problems);
+    const flakes = validateFlakes(raw.flakes, problems);
+    const burnIn = validateBurnIn(raw.burnIn, problems);
     if (problems.length > 0)
         throw new ConfigError(problems);
     return {
         baseBranch: raw.baseBranch ?? DEFAULT_BASE_BRANCH,
         statusContext: raw.statusContext ?? DEFAULT_STATUS_CONTEXT,
         rules,
+        versionBumpTriggers,
         steps,
         afterMerge: raw.afterMerge ?? null,
         stderrAllowlist,
-        protection
+        protection,
+        flakes,
+        burnIn
     };
 }

package/dist/flakes/gh.d.ts

@@ -0,0 +1,5 @@
+import { type Exec } from '../run/exec.js';
+import { type FlakeLedgerDeps } from './ledger.js';
+/** The ledger's GitHub side over `gh`. Every call is argv (no shell), so test titles and
+ *  error text reach GitHub verbatim. */
+export declare function ghLedgerDeps(exec?: Exec): FlakeLedgerDeps;

package/dist/flakes/gh.js

@@ -0,0 +1,74 @@
+import { defaultExec, lines } from '../run/exec.js';
+import { FLAKE_LABEL, OCCURRENCE_MARKER } from './ledger.js';
+const LABEL_DESCRIPTION = 'A test that failed, then passed on retry (chreode)';
+const LABEL_COLOR = 'D93F0B';
+/** The ledger's GitHub side over `gh`. Every call is argv (no shell), so test titles and
+ *  error text reach GitHub verbatim. */
+export function ghLedgerDeps(exec = defaultExec) {
+    let labelReady = false;
+    const ensureLabel = () => {
+        if (labelReady)
+            return;
+        const labels = JSON.parse(exec('gh', ['label', 'list', '--limit', '1000', '--json', 'name']));
+        if (!labels.some((l) => l.name === FLAKE_LABEL)) {
+            exec('gh', [
+                'label',
+                'create',
+                FLAKE_LABEL,
+                '--description',
+                LABEL_DESCRIPTION,
+                '--color',
+                LABEL_COLOR
+            ]);
+        }
+        labelReady = true;
+    };
+    return {
+        listOpenFlakeIssues() {
+            // A label filter, not a title search: it does not depend on search-index lag.
+            const raw = JSON.parse(exec('gh', [
+                'issue',
+                'list',
+                '--label',
+                FLAKE_LABEL,
+                '--state',
+                'open',
+                '--limit',
+                '1000',
+                '--json',
+                'number,title,labels,url'
+            ]));
+            return raw.map((i) => ({
+                number: i.number,
+                title: i.title,
+                url: i.url,
+                labels: i.labels.map((l) => l.name)
+            }));
+        },
+        countOccurrenceComments(issue) {
+            const raw = JSON.parse(exec('gh', ['issue', 'view', String(issue), '--json', 'comments']));
+            return raw.comments.filter((c) => c.body.includes(OCCURRENCE_MARKER)).length;
+        },
+        createIssue(title, body) {
+            ensureLabel();
+            const out = exec('gh', [
+                'issue',
+                'create',
+                '--title',
+                title,
+                '--body',
+                body,
+                '--label',
+                FLAKE_LABEL
+            ]);
+            const url = lines(out).at(-1) ?? '';
+            const m = /\/issues\/(\d+)$/.exec(url);
+            if (!m)
+                throw new Error(`gh issue create printed no issue URL: ${out.trim()}`);
+            return { number: Number(m[1]), title, url, labels: [FLAKE_LABEL] };
+        },
+        commentIssue(issue, body) {
+            exec('gh', ['issue', 'comment', String(issue), '--body', body]);
+        }
+    };
+}

package/dist/flakes/ledger.d.ts

@@ -0,0 +1,53 @@
+import type { ResolvedFlakes } from '../config/types.js';
+import { type FlakeEvent } from './log.js';
+export declare const FLAKE_LABEL = "flake";
+export declare const OCCURRENCE_MARKER = "<!-- chreode:flake-occurrence -->";
+export declare const ISSUE_TITLE_MAX = 256;
+export interface RunContext {
+    branch: string;
+    sha: string;
+}
+export interface FlakeIssue {
+    number: number;
+    title: string;
+    url: string;
+    labels: string[];
+}
+/** The GitHub side, injected: see gh.ts for the real one. */
+export interface FlakeLedgerDeps {
+    /** Open issues labelled FLAKE_LABEL. */
+    listOpenFlakeIssues(): FlakeIssue[];
+    /** Comments on the issue that carry OCCURRENCE_MARKER. */
+    countOccurrenceComments(issue: number): number;
+    /** Creates an issue labelled FLAKE_LABEL. */
+    createIssue(title: string, body: string): FlakeIssue;
+    commentIssue(issue: number, body: string): void;
+}
+export interface LedgerEntry {
+    number: number;
+    title: string;
+    url: string;
+    /** Occurrences so far: 1 (the issue) + marker comments. */
+    count: number;
+}
+export interface LedgerResult {
+    filed: LedgerEntry[];
+    bumped: LedgerEntry[];
+    escalations: LedgerEntry[];
+}
+export declare function firstLine(err: unknown): string;
+/** A GitHub call failed partway: `partial` was recorded, `remaining` was not. */
+export declare class LedgerError extends Error {
+    readonly partial: LedgerResult;
+    readonly remaining: FlakeEvent[];
+    constructor(partial: LedgerResult, remaining: FlakeEvent[], cause: unknown);
+}
+export declare function issueTitle(event: FlakeEvent): string;
+export declare function issueBody(event: FlakeEvent, ctx: RunContext, config: ResolvedFlakes): string;
+export declare function occurrenceBody(event: FlakeEvent, ctx: RunContext): string;
+/**
+ * One open issue per flaking test (exact title match); each later sighting adds a marker
+ * comment. An issue at `threshold` occurrences without the snooze label is an escalation.
+ * Any GitHub failure throws LedgerError naming what was and was not recorded.
+ */
+export declare function processFlakeEvents(events: readonly FlakeEvent[], ctx: RunContext, config: ResolvedFlakes, deps: FlakeLedgerDeps): LedgerResult;

package/dist/flakes/ledger.js

@@ -0,0 +1,108 @@
+import { dedupeEvents } from './log.js';
+export const FLAKE_LABEL = 'flake';
+export const OCCURRENCE_MARKER = '<!-- chreode:flake-occurrence -->';
+export const ISSUE_TITLE_MAX = 256;
+export function firstLine(err) {
+    return (err instanceof Error ? err.message : String(err)).split('\n')[0] ?? '';
+}
+/** A GitHub call failed partway: `partial` was recorded, `remaining` was not. */
+export class LedgerError extends Error {
+    partial;
+    remaining;
+    constructor(partial, remaining, cause) {
+        super(firstLine(cause), { cause });
+        this.partial = partial;
+        this.remaining = remaining;
+        this.name = 'LedgerError';
+    }
+}
+export function issueTitle(event) {
+    return `flake(${event.kind}): ${event.file} › ${event.title}`.slice(0, ISSUE_TITLE_MAX).trimEnd();
+}
+function longestRun(text) {
+    return Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
+}
+/** Inline code span that survives backticks in `text`; keeps @mentions and #refs inert. */
+function codeSpan(text) {
+    const fence = '`'.repeat(longestRun(text) + 1);
+    const pad = text.startsWith('`') || text.endsWith('`') ? ' ' : '';
+    return `${fence}${pad}${text}${pad}${fence}`;
+}
+/** Fenced block whose fence is longer than any backtick run inside (minimum 3). */
+function codeFence(text) {
+    const fence = '`'.repeat(Math.max(3, longestRun(text) + 1));
+    return [fence, text, fence];
+}
+function details(event, ctx) {
+    const where = event.project === '' ? event.runner : `${event.runner}, project ${event.project}`;
+    return [
+        `- **Test:** ${codeSpan(`${event.file} › ${event.title}`)} (${where})`,
+        `- **Observed:** ${event.at} on \`${ctx.branch}\` @ ${event.sha ?? ctx.sha}`,
+        ...(event.tracePath ? [`- **First-attempt trace:** \`${event.tracePath}\``] : []),
+        '',
+        '**First-attempt error:**',
+        ...codeFence(event.firstAttemptError)
+    ].join('\n');
+}
+export function issueBody(event, ctx, config) {
+    return [
+        'Filed by chreode flake tracking: this test failed, then passed on retry.',
+        '',
+        details(event, ctx),
+        '',
+        `A flake is a bug, not noise. Diagnose it with the playbook: ${config.playbookUrl}`,
+        `At ${config.threshold} recorded occurrences it fails signoff until fixed; label this issue`,
+        `\`${config.snoozeLabel}\` to defer that deliberately.`
+    ].join('\n');
+}
+export function occurrenceBody(event, ctx) {
+    return [OCCURRENCE_MARKER, '', 'Flaked again.', '', details(event, ctx)].join('\n');
+}
+/**
+ * One open issue per flaking test (exact title match); each later sighting adds a marker
+ * comment. An issue at `threshold` occurrences without the snooze label is an escalation.
+ * Any GitHub failure throws LedgerError naming what was and was not recorded.
+ */
+export function processFlakeEvents(events, ctx, config, deps) {
+    const result = { filed: [], bumped: [], escalations: [] };
+    const unique = dedupeEvents(events);
+    if (unique.length === 0)
+        return result;
+    let open;
+    try {
+        open = [...deps.listOpenFlakeIssues()];
+    }
+    catch (err) {
+        throw new LedgerError(result, unique, err);
+    }
+    for (const [i, event] of unique.entries()) {
+        try {
+            const title = issueTitle(event);
+            const existing = open.find((candidate) => candidate.title === title);
+            let entry;
+            let labels;
+            if (existing === undefined) {
+                const created = deps.createIssue(title, issueBody(event, ctx, config));
+                // A later event whose title truncates to the same string bumps this issue.
+                open.push(created);
+                entry = { number: created.number, title, url: created.url, count: 1 };
+                labels = created.labels;
+                result.filed.push(entry);
+            }
+            else {
+                const prior = deps.countOccurrenceComments(existing.number);
+                deps.commentIssue(existing.number, occurrenceBody(event, ctx));
+                entry = { number: existing.number, title, url: existing.url, count: prior + 2 };
+                labels = existing.labels;
+                result.bumped.push(entry);
+            }
+            if (entry.count >= config.threshold && !labels.includes(config.snoozeLabel)) {
+                result.escalations.push(entry);
+            }
+        }
+        catch (err) {
+            throw new LedgerError(result, unique.slice(i), err);
+        }
+    }
+    return result;
+}

package/dist/flakes/log.d.ts

@@ -0,0 +1,39 @@
+/** One retried-then-passed test, as a reporter saw it. */
+export interface FlakeEvent {
+    /** Issue-title bucket, e.g. 'e2e', 'unit', 'client'. */
+    kind: string;
+    runner: 'playwright' | 'vitest';
+    /** Runner project name ('' if none). */
+    project: string;
+    /** Repo-relative, '/'-separated. */
+    file: string;
+    /** Describe chain joined with ' › '. */
+    title: string;
+    /** At most ERROR_LINE_CAP lines, ANSI-stripped. */
+    firstAttemptError: string;
+    /** Playwright trace of the failed attempt. */
+    tracePath?: string;
+    /** CHREODE_HEAD when run under signoff. */
+    sha?: string;
+    /** ISO timestamp. */
+    at: string;
+}
+/** Repo-relative. Not under test-results/: Playwright wipes its outputDir at start and would
+ *  delete events an earlier vitest step wrote. */
+export declare const FLAKE_LOG_FILE = ".chreode/flakes.jsonl";
+export declare const ERROR_LINE_CAP = 40;
+export declare function flakeLogPath(env?: NodeJS.ProcessEnv, cwd?: string): string;
+/** jsonl, append-only: sequential writer processes in one run never clobber each other. */
+export declare function appendFlakeEvent(event: FlakeEvent, logPath: string): void;
+export declare function readFlakeEvents(logPath: string): FlakeEvent[];
+export declare function clearFlakeLog(logPath: string): void;
+export declare function writeFlakeEvents(logPath: string, events: readonly FlakeEvent[]): void;
+export declare function flakeKey(event: FlakeEvent): string;
+/** One report per test per run: the same flake seen in two projects counts once. */
+export declare function dedupeEvents(events: readonly FlakeEvent[]): FlakeEvent[];
+export declare function truncateError(message: string | undefined): string;
+/** The nearest ancestor holding `.git`: a directory in a checkout, a file in a worktree. */
+export declare function findRepoRoot(start: string, exists?: (path: string) => boolean): string | null;
+/** Relative to the git root found from the file itself, so a runner started in a subpackage
+ *  still yields repo paths; '/'-separated. */
+export declare function repoRelative(file: string, cwd?: string, exists?: (path: string) => boolean): string;

package/dist/flakes/log.js

@@ -0,0 +1,89 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+import { stripAnsi } from '../run/stderr.js';
+/** Repo-relative. Not under test-results/: Playwright wipes its outputDir at start and would
+ *  delete events an earlier vitest step wrote. */
+export const FLAKE_LOG_FILE = '.chreode/flakes.jsonl';
+export const ERROR_LINE_CAP = 40;
+export function flakeLogPath(env = process.env, cwd = process.cwd()) {
+    const fromEnv = env.CHREODE_FLAKE_LOG;
+    return fromEnv !== undefined && fromEnv !== '' ? fromEnv : join(cwd, FLAKE_LOG_FILE);
+}
+/** jsonl, append-only: sequential writer processes in one run never clobber each other. */
+export function appendFlakeEvent(event, logPath) {
+    mkdirSync(dirname(logPath), { recursive: true });
+    appendFileSync(logPath, `${JSON.stringify(event)}\n`);
+}
+const REQUIRED = ['kind', 'runner', 'project', 'file', 'title', 'firstAttemptError', 'at'];
+function isFlakeEvent(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const record = v;
+    return REQUIRED.every((key) => typeof record[key] === 'string');
+}
+export function readFlakeEvents(logPath) {
+    if (!existsSync(logPath))
+        return [];
+    const events = [];
+    for (const line of readFileSync(logPath, 'utf8').split('\n')) {
+        if (line.trim() === '')
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (isFlakeEvent(parsed))
+                events.push(parsed);
+        }
+        catch {
+            // An interrupted write: skip it rather than fail the report.
+        }
+    }
+    return events;
+}
+export function clearFlakeLog(logPath) {
+    rmSync(logPath, { force: true });
+}
+export function writeFlakeEvents(logPath, events) {
+    if (events.length === 0) {
+        clearFlakeLog(logPath);
+        return;
+    }
+    mkdirSync(dirname(logPath), { recursive: true });
+    writeFileSync(logPath, events.map((e) => `${JSON.stringify(e)}\n`).join(''));
+}
+export function flakeKey(event) {
+    return `${event.kind}/${event.file}/${event.title}`;
+}
+/** One report per test per run: the same flake seen in two projects counts once. */
+export function dedupeEvents(events) {
+    const seen = new Set();
+    return events.filter((e) => {
+        const key = flakeKey(e);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+export function truncateError(message) {
+    if (message === undefined || message === '')
+        return '(first attempt error unavailable)';
+    return stripAnsi(message).split('\n').slice(0, ERROR_LINE_CAP).join('\n');
+}
+/** The nearest ancestor holding `.git`: a directory in a checkout, a file in a worktree. */
+export function findRepoRoot(start, exists = existsSync) {
+    let dir = start;
+    for (;;) {
+        if (exists(join(dir, '.git')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** Relative to the git root found from the file itself, so a runner started in a subpackage
+ *  still yields repo paths; '/'-separated. */
+export function repoRelative(file, cwd = process.cwd(), exists = existsSync) {
+    const root = findRepoRoot(dirname(file), exists) ?? cwd;
+    return relative(root, file).split(sep).join('/');
+}

package/dist/flakes/phase.d.ts

@@ -0,0 +1,34 @@
+import type { ResolvedFlakes } from '../config/types.js';
+import { type FlakeLedgerDeps, type LedgerEntry, type LedgerResult, type RunContext } from './ledger.js';
+export interface FlakePhaseInput {
+    logPath: string;
+    ctx: RunContext;
+    config: ResolvedFlakes;
+    ledger: FlakeLedgerDeps;
+    log: (m: string) => void;
+    warn: (m: string) => void;
+}
+export type FlakePhaseOutcome = {
+    kind: 'none';
+} | {
+    kind: 'reported';
+    result: LedgerResult;
+} | {
+    kind: 'gh-error';
+    message: string;
+    partial: LedgerResult;
+};
+/**
+ * Report the logged flakes to the ledger. Recorded events leave the log; on a GitHub failure
+ * the unrecorded ones stay for the next run (an outage must not block merging, and each event
+ * keeps its own sha and time). Escalations are returned, not acted on: the caller decides.
+ */
+export declare function runFlakePhase(input: FlakePhaseInput): FlakePhaseOutcome;
+/** The failure text for escalated flakes; each issue is listed once, at its highest count. */
+export declare function escalationMessage(escalations: readonly LedgerEntry[], config: ResolvedFlakes): string;
+/**
+ * The single place a phase outcome becomes a pass/fail decision: the failure message when any
+ * flake escalated (including ones recorded before a GitHub error), otherwise undefined.
+ * Signoff and `flake-report` both call this.
+ */
+export declare function escalationFailure(outcome: FlakePhaseOutcome, config: ResolvedFlakes): string | undefined;

package/dist/flakes/phase.js

@@ -0,0 +1,66 @@
+import { LedgerError, processFlakeEvents } from './ledger.js';
+import { clearFlakeLog, readFlakeEvents, writeFlakeEvents } from './log.js';
+function printResult(result, log) {
+    for (const f of result.filed)
+        log(`[chreode] flake filed: ${f.url} ${f.title}`);
+    for (const b of result.bumped) {
+        log(`[chreode] flake seen again (${b.count} occurrences): ${b.url} ${b.title}`);
+    }
+}
+/**
+ * Report the logged flakes to the ledger. Recorded events leave the log; on a GitHub failure
+ * the unrecorded ones stay for the next run (an outage must not block merging, and each event
+ * keeps its own sha and time). Escalations are returned, not acted on: the caller decides.
+ */
+export function runFlakePhase(input) {
+    const events = readFlakeEvents(input.logPath);
+    if (events.length === 0)
+        return { kind: 'none' };
+    input.log(`\n[chreode] flakes: ${events.length} retried-then-passed result(s) recorded`);
+    let result;
+    try {
+        result = processFlakeEvents(events, input.ctx, input.config, input.ledger);
+    }
+    catch (err) {
+        if (!(err instanceof LedgerError))
+            throw err;
+        printResult(err.partial, input.log);
+        writeFlakeEvents(input.logPath, err.remaining);
+        input.warn(`[chreode] flakes: a GitHub call failed (${err.message}); kept ` +
+            `${err.remaining.length} event(s) in ${input.logPath} for the next run`);
+        return { kind: 'gh-error', message: err.message, partial: err.partial };
+    }
+    clearFlakeLog(input.logPath);
+    printResult(result, input.log);
+    return { kind: 'reported', result };
+}
+function dedupeEscalations(escalations) {
+    const byIssue = new Map();
+    for (const e of escalations) {
+        const seen = byIssue.get(e.number);
+        if (!seen || e.count > seen.count)
+            byIssue.set(e.number, e);
+    }
+    return [...byIssue.values()];
+}
+/** The failure text for escalated flakes; each issue is listed once, at its highest count. */
+export function escalationMessage(escalations, config) {
+    const unique = dedupeEscalations(escalations);
+    return [
+        `\n[chreode] FAILED: ${unique.length} flake(s) reached ${config.threshold} occurrences:`,
+        ...unique.map((e) => `  ${e.url} (${e.count} occurrences) ${e.title}`),
+        `[chreode] Fix each one (playbook: ${config.playbookUrl}), or label its issue`,
+        `[chreode] ${config.snoozeLabel} to defer it deliberately.`
+    ].join('\n');
+}
+/**
+ * The single place a phase outcome becomes a pass/fail decision: the failure message when any
+ * flake escalated (including ones recorded before a GitHub error), otherwise undefined.
+ * Signoff and `flake-report` both call this.
+ */
+export function escalationFailure(outcome, config) {
+    if (outcome.kind === 'none')
+        return undefined;
+    const result = outcome.kind === 'reported' ? outcome.result : outcome.partial;
+    return result.escalations.length > 0 ? escalationMessage(result.escalations, config) : undefined;
+}

package/dist/flakes/report.d.ts

@@ -0,0 +1,14 @@
+import { type ResolvedConfig } from '../config/types.js';
+import { type Exec } from '../run/exec.js';
+import type { FlakeLedgerDeps } from './ledger.js';
+export interface FlakeReportDeps {
+    exec: Exec;
+    ledger: FlakeLedgerDeps;
+    logPath: string;
+    log: (m: string) => void;
+    warn: (m: string) => void;
+    error: (m: string) => void;
+}
+/** `chreode flake-report`: the signoff flake phase on its own, for hosted CI or by hand.
+ *  Without a `flakes` block it uses the defaults: running it is the opt-in. */
+export declare function runFlakeReport(config: ResolvedConfig, overrides?: Partial<FlakeReportDeps>): number;