@mindlace/chreode 0.0.0-stage → 0.2.0

package/dist/config/load.js

@@ -0,0 +1,13 @@
+import { existsSync } from 'node:fs';
+import { createJiti } from 'jiti';
+import { ConfigError, validateConfig } from './validate.js';
+export const CONFIG_FILE = 'chreode.config.ts';
+/** Load and validate a config file. jiti transpiles TypeScript on the fly, so consumers
+ *  need no build step and no tsx. */
+export async function loadConfig(file) {
+    if (!existsSync(file))
+        throw new ConfigError([`no config file at ${file}`]);
+    const jiti = createJiti(import.meta.url, { moduleCache: false, fsCache: false });
+    const mod = await jiti.import(file, { default: true });
+    return validateConfig(mod);
+}

package/dist/config/types.d.ts

@@ -0,0 +1,114 @@
+/** A path matcher: a picomatch glob (dotfiles match) or a RegExp tested against the
+ *  repo-relative POSIX path. */
+export type Matcher = string | RegExp;
+/** What a step's `run` function and `if` predicate see. */
+export interface StepContext {
+    base: string;
+    head: string;
+    paths: readonly string[];
+    triggers: readonly string[];
+    isWorktree: boolean;
+}
+/** First matching rule wins. `triggers: []` means "matched, nothing to run". */
+export interface RuleConfig {
+    match: Matcher | Matcher[];
+    triggers: string[];
+}
+export interface StepConfig {
+    /** Unique, no whitespace. Used by --skip, the note and the status description. */
+    label: string;
+    run: string | ((ctx: StepContext) => string);
+    /** Planned when any listed trigger fired. */
+    when: string[];
+    if?: (ctx: StepContext) => boolean;
+    /** Dropped when any listed step label is also going to run. */
+    supersededBy?: string[];
+    /** Capture stderr; a clean exit with non-allowlisted stderr fails the step. */
+    policeStderr?: boolean;
+    /** Hard wall-clock ceiling; the step's process group is SIGKILLed past it. */
+    timeoutMs?: number;
+}
+export interface AllowlistEntry {
+    /** A stderr line (ANSI-stripped) matching this pattern is benign. */
+    pattern: RegExp;
+    /** Why this noise is unavoidable. Required: allowlisting is a reviewed decision. */
+    reason: string;
+}
+export interface ProtectionConfig {
+    /** Shallow-merged over the default branch-protection payload. */
+    branch?: Record<string, unknown>;
+    /** Shallow-merged over the default repository merge settings. */
+    repo?: Record<string, unknown>;
+}
+/** Presence turns flake tracking on: retried-then-passed tests become GitHub issues. */
+export interface FlakesConfig {
+    /** Occurrences (the issue itself counts as one) at which an unsnoozed flake fails signoff. */
+    threshold?: number;
+    /** An issue carrying this label never escalates. */
+    snoozeLabel?: string;
+    /** Linked from every filed issue. */
+    playbookUrl?: string;
+}
+export interface BurnInRunner {
+    /** For output. */
+    name: string;
+    match: Matcher | Matcher[];
+    ignore?: Matcher | Matcher[];
+    /** A string runs once; an array runs each in sequence (for runners with no repeat flag). */
+    command: (files: string[], repeats: number) => string | string[];
+}
+export interface BurnInConfig {
+    repeats?: number;
+    /** Changed test files beyond this many are listed as skipped, never silently dropped. */
+    maxFiles?: number;
+    runners: BurnInRunner[];
+}
+export interface ResolvedFlakes {
+    threshold: number;
+    snoozeLabel: string;
+    playbookUrl: string;
+}
+export interface ResolvedBurnIn {
+    repeats: number;
+    maxFiles: number;
+    runners: BurnInRunner[];
+}
+export interface ChreodeConfig {
+    baseBranch?: string;
+    statusContext?: string;
+    rules?: RuleConfig[];
+    steps: StepConfig[];
+    /** Runs only when the merge of origin/<baseBranch> actually changed the branch. */
+    afterMerge?: string;
+    stderrAllowlist?: AllowlistEntry[];
+    protection?: ProtectionConfig;
+    flakes?: FlakesConfig;
+    burnIn?: BurnInConfig;
+}
+export interface ResolvedStep extends StepConfig {
+    supersededBy: string[];
+    policeStderr: boolean;
+    timeoutMs: number;
+}
+export interface ResolvedConfig {
+    baseBranch: string;
+    statusContext: string;
+    rules: RuleConfig[];
+    steps: ResolvedStep[];
+    afterMerge: string | null;
+    stderrAllowlist: AllowlistEntry[];
+    protection: ProtectionConfig;
+    flakes: ResolvedFlakes | null;
+    burnIn: ResolvedBurnIn | null;
+}
+export declare const DEFAULT_BASE_BRANCH = "main";
+export declare const DEFAULT_STATUS_CONTEXT = "chreode/signoff";
+export declare const DEFAULT_TIMEOUT_MS: number;
+export declare const DEFAULT_FLAKE_THRESHOLD = 3;
+export declare const DEFAULT_SNOOZE_LABEL = "flake-snoozed";
+export declare const DEFAULT_PLAYBOOK_URL = "https://github.com/mindlace/chreode/blob/main/docs/flakes.md";
+export declare const DEFAULT_BURN_IN_REPEATS = 5;
+export declare const DEFAULT_BURN_IN_MAX_FILES = 12;
+export declare function resolveFlakes(config: FlakesConfig): ResolvedFlakes;
+/** Identity helper so `chreode.config.ts` gets types. */
+export declare function defineConfig(config: ChreodeConfig): ChreodeConfig;

package/dist/config/types.js

@@ -0,0 +1,19 @@
+export const DEFAULT_BASE_BRANCH = 'main';
+export const DEFAULT_STATUS_CONTEXT = 'chreode/signoff';
+export const DEFAULT_TIMEOUT_MS = 10 * 60_000;
+export const DEFAULT_FLAKE_THRESHOLD = 3;
+export const DEFAULT_SNOOZE_LABEL = 'flake-snoozed';
+export const DEFAULT_PLAYBOOK_URL = 'https://github.com/mindlace/chreode/blob/main/docs/flakes.md';
+export const DEFAULT_BURN_IN_REPEATS = 5;
+export const DEFAULT_BURN_IN_MAX_FILES = 12;
+export function resolveFlakes(config) {
+    return {
+        threshold: config.threshold ?? DEFAULT_FLAKE_THRESHOLD,
+        snoozeLabel: config.snoozeLabel ?? DEFAULT_SNOOZE_LABEL,
+        playbookUrl: config.playbookUrl ?? DEFAULT_PLAYBOOK_URL
+    };
+}
+/** Identity helper so `chreode.config.ts` gets types. */
+export function defineConfig(config) {
+    return config;
+}

package/dist/config/validate.d.ts

@@ -0,0 +1,9 @@
+import { type ResolvedConfig } from './types.js';
+export declare class ConfigError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+/** Cross-realm safe: a config evaluated by jiti may not share this realm's RegExp. */
+export declare function isRegExp(v: unknown): v is RegExp;
+export declare function isRecord(v: unknown): v is Record<string, unknown>;
+export declare function validateConfig(raw: unknown): ResolvedConfig;

package/dist/config/validate.js

@@ -0,0 +1,278 @@
+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) {
+        super(`invalid chreode config:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+        this.problems = problems;
+        this.name = 'ConfigError';
+    }
+}
+const TOP_KEYS = new Set([
+    'baseBranch',
+    'statusContext',
+    'rules',
+    'steps',
+    'afterMerge',
+    'stderrAllowlist',
+    'protection',
+    'flakes',
+    'burnIn'
+]);
+const RULE_KEYS = new Set(['match', 'triggers']);
+const STEP_KEYS = new Set([
+    'label',
+    'run',
+    'when',
+    'if',
+    'supersededBy',
+    'policeStderr',
+    'timeoutMs'
+]);
+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]';
+}
+export function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v) && !isRegExp(v);
+}
+function isNonEmptyString(v) {
+    return typeof v === 'string' && v.length > 0;
+}
+function isStringArray(v) {
+    return Array.isArray(v) && v.every(isNonEmptyString);
+}
+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))
+            problems.push(`${where}: unknown key "${key}"`);
+    }
+}
+function validateRules(raw, problems) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        problems.push('config.rules: must be an array');
+        return [];
+    }
+    raw.forEach((rule, i) => {
+        const where = `rules[${i}]`;
+        if (!isRecord(rule)) {
+            problems.push(`${where}: must be an object`);
+            return;
+        }
+        unknownKeys(rule, RULE_KEYS, where, problems);
+        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 validateSteps(raw, problems) {
+    if (!Array.isArray(raw)) {
+        problems.push('config.steps: must be an array');
+        return [];
+    }
+    const labels = new Set();
+    const out = [];
+    raw.forEach((step, i) => {
+        const where = `steps[${i}]`;
+        if (!isRecord(step)) {
+            problems.push(`${where}: must be an object`);
+            return;
+        }
+        unknownKeys(step, STEP_KEYS, where, problems);
+        const label = step.label;
+        if (typeof label !== 'string' || !/^\S+$/.test(label)) {
+            problems.push(`${where}.label: must be non-empty with no whitespace`);
+        }
+        else if (labels.has(label)) {
+            problems.push(`${where}.label: duplicate label "${label}"`);
+        }
+        else {
+            labels.add(label);
+        }
+        if (!isNonEmptyString(step.run) && typeof step.run !== 'function') {
+            problems.push(`${where}.run: must be a non-empty string or a function`);
+        }
+        if (!isStringArray(step.when) || step.when.length === 0) {
+            problems.push(`${where}.when: must be a non-empty array of trigger names`);
+        }
+        if (step.if !== undefined && typeof step.if !== 'function') {
+            problems.push(`${where}.if: must be a function`);
+        }
+        if (step.supersededBy !== undefined && !isStringArray(step.supersededBy)) {
+            problems.push(`${where}.supersededBy: must be an array of step labels`);
+        }
+        if (step.policeStderr !== undefined && typeof step.policeStderr !== 'boolean') {
+            problems.push(`${where}.policeStderr: must be a boolean`);
+        }
+        const t = step.timeoutMs;
+        if (t !== undefined && (typeof t !== 'number' || !Number.isFinite(t) || t <= 0)) {
+            problems.push(`${where}.timeoutMs: must be a positive number`);
+        }
+        out.push({
+            ...step,
+            supersededBy: isStringArray(step.supersededBy) ? step.supersededBy : [],
+            policeStderr: step.policeStderr === true,
+            timeoutMs: typeof t === 'number' && t > 0 ? t : DEFAULT_TIMEOUT_MS
+        });
+    });
+    for (const step of out) {
+        for (const target of step.supersededBy) {
+            if (target === step.label) {
+                problems.push(`step "${step.label}": supersededBy names itself`);
+            }
+            else if (!labels.has(target)) {
+                problems.push(`step "${step.label}": supersededBy names unknown step "${target}"`);
+            }
+        }
+    }
+    return out;
+}
+function validateAllowlist(raw, problems) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        problems.push('config.stderrAllowlist: must be an array');
+        return [];
+    }
+    raw.forEach((entry, i) => {
+        const where = `stderrAllowlist[${i}]`;
+        if (!isRecord(entry)) {
+            problems.push(`${where}: must be an object`);
+            return;
+        }
+        unknownKeys(entry, ALLOW_KEYS, where, problems);
+        if (!isRegExp(entry.pattern))
+            problems.push(`${where}.pattern: must be a RegExp`);
+        if (!isNonEmptyString(entry.reason))
+            problems.push(`${where}.reason: must be a non-empty string`);
+    });
+    return raw;
+}
+function validateProtection(raw, problems) {
+    if (raw === undefined)
+        return {};
+    if (!isRecord(raw)) {
+        problems.push('config.protection: must be an object');
+        return {};
+    }
+    unknownKeys(raw, PROTECTION_KEYS, 'protection', problems);
+    for (const key of ['branch', 'repo']) {
+        if (raw[key] !== undefined && !isRecord(raw[key])) {
+            problems.push(`protection.${key}: must be an object`);
+        }
+    }
+    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([
+            'config must be an object (does chreode.config.ts `export default defineConfig({ ... })`?)'
+        ]);
+    }
+    const problems = [];
+    unknownKeys(raw, TOP_KEYS, 'config', problems);
+    for (const key of ['baseBranch', 'statusContext', 'afterMerge']) {
+        if (raw[key] !== undefined && !isNonEmptyString(raw[key])) {
+            problems.push(`config.${key}: must be a non-empty string`);
+        }
+    }
+    const rules = validateRules(raw.rules, 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,
+        steps,
+        afterMerge: raw.afterMerge ?? null,
+        stderrAllowlist,
+        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;
+}