@mindlace/chreode 0.0.0-stage → 0.2.0

package/dist/lock/machine-lock.js

@@ -0,0 +1,76 @@
+import os from 'node:os';
+import path from 'node:path';
+import lockfile from 'proper-lockfile';
+// Steps hold gigabytes. Several agents in parallel worktrees running a suite at once swap
+// the machine to death and produce spurious failures, and the contended resource is the
+// machine, not the repo, so every chreode repo on the box shares ONE lock.
+//
+// A live holder refreshes the lock mtime every UPDATE; a holder that dies stops refreshing,
+// so the lock goes stale after STALE and the next waiter steals it.
+export const LOCK_STALE_MS = 30_000;
+export const LOCK_UPDATE_MS = 10_000;
+export const LOCK_POLL_MS = 2_000;
+export const LOCK_MAX_WAIT_MS = 60 * 60_000;
+/** Poll-until-free around a one-shot lock. All I/O injected so the retry/log/timeout logic
+ *  is testable without the filesystem or real timers. */
+export function createRetryingLock(deps) {
+    return {
+        async acquire() {
+            const deadline = deps.now() + deps.maxWaitMs;
+            let logged = false;
+            for (;;) {
+                try {
+                    return await deps.tryLock();
+                }
+                catch (err) {
+                    if (err.code !== 'ELOCKED')
+                        throw err;
+                    if (!logged) {
+                        deps.log(`[chreode] another run holds the ${deps.label} lock; waiting…`);
+                        logged = true;
+                    }
+                    if (deps.now() >= deadline) {
+                        const hint = deps.hint ? ` ${deps.hint}` : '';
+                        throw new Error(`[chreode] timed out after ${Math.round(deps.maxWaitMs / 60_000)}m waiting for ` +
+                            `the ${deps.label} lock (${deps.lockPath}).${hint}`, { cause: err });
+                    }
+                    await deps.sleep(deps.pollMs);
+                }
+            }
+        }
+    };
+}
+/** proper-lockfile at a fixed path, with stale-steal. */
+export function fileLock(opts) {
+    return createRetryingLock({
+        tryLock: () => lockfile.lock(opts.lockPath, {
+            realpath: false, // the target need not exist; the lock is the `${lockPath}.lock` dir
+            stale: opts.staleMs ?? LOCK_STALE_MS,
+            update: opts.updateMs ?? LOCK_UPDATE_MS,
+            retries: 0, // we own the retry loop so we can log once and bound the wait
+            // The default handler throws from a timer: a stalled mtime refresh (laptop sleep) would crash
+            // chreode uncaught and orphan the detached step group. Log and carry on instead.
+            onCompromised: (err) => console.error(`[chreode] lock compromised: ${err.message}`)
+        }),
+        label: opts.label,
+        lockPath: opts.lockPath,
+        pollMs: opts.pollMs ?? LOCK_POLL_MS,
+        maxWaitMs: opts.maxWaitMs ?? LOCK_MAX_WAIT_MS,
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        log: opts.log ?? ((msg) => console.log(msg)),
+        hint: opts.hint
+    });
+}
+/** `CHREODE_LOCK_PATH` exists for test isolation: chreode's own suite runs `chreode signoff`
+ *  while an outer signoff holds the real lock. */
+export function defaultLockPath(env = process.env) {
+    return env.CHREODE_LOCK_PATH || path.join(os.tmpdir(), 'chreode-signoff.lock');
+}
+export function signoffLock(env = process.env) {
+    return fileLock({
+        label: 'signoff',
+        lockPath: defaultLockPath(env),
+        hint: 'The holder is another chreode signoff on this machine (any repo). Do not kill it; wait it out.'
+    });
+}

package/dist/reporters/options.d.ts

@@ -0,0 +1,17 @@
+import { type FlakeEvent } from '../flakes/log.js';
+export interface FlakeReporterOptions {
+    /** Issue-title bucket: fixed, or derived from the runner project name. */
+    kind?: string | ((project: string) => string);
+    /** Record only these runner projects (default: all). */
+    projects?: string[];
+    /** Where events go (default: appended to the flake log). A seam for tests. */
+    append?: (event: FlakeEvent) => void;
+}
+export declare function resolveKind(kind: FlakeReporterOptions['kind'], project: string, fallback: string): string;
+export declare function wants(projects: readonly string[] | undefined, project: string): boolean;
+/** The sha under test when running under signoff. */
+export declare function headSha(env?: NodeJS.ProcessEnv): {
+    sha?: string;
+};
+/** Resolved at write time, so CHREODE_FLAKE_LOG set by signoff is honoured. */
+export declare function defaultAppend(event: FlakeEvent): void;

package/dist/reporters/options.js

@@ -0,0 +1,18 @@
+import { appendFlakeEvent, flakeLogPath } from '../flakes/log.js';
+export function resolveKind(kind, project, fallback) {
+    if (typeof kind === 'function')
+        return kind(project);
+    return kind ?? fallback;
+}
+export function wants(projects, project) {
+    return projects === undefined || projects.includes(project);
+}
+/** The sha under test when running under signoff. */
+export function headSha(env = process.env) {
+    const sha = env.CHREODE_HEAD;
+    return sha ? { sha } : {};
+}
+/** Resolved at write time, so CHREODE_FLAKE_LOG set by signoff is honoured. */
+export function defaultAppend(event) {
+    appendFlakeEvent(event, flakeLogPath());
+}

package/dist/reporters/playwright.d.ts

@@ -0,0 +1,15 @@
+import type { Reporter, TestCase, TestResult } from 'playwright/types/testReporter';
+import { type FlakeReporterOptions } from './options.js';
+/**
+ * Records every test that failed (or timed out) and then passed on a retry. Playwright loads
+ * reporters by module specifier, hence the default export. Imports Playwright's types only.
+ */
+export default class PlaywrightFlakeReporter implements Reporter {
+    private readonly options;
+    private readonly append;
+    /** The first failed attempt of each test that has not passed yet. */
+    private readonly failed;
+    constructor(options?: FlakeReporterOptions);
+    onTestEnd(test: TestCase, result: TestResult): void;
+    printsToStdio(): boolean;
+}

package/dist/reporters/playwright.js

@@ -0,0 +1,47 @@
+import { repoRelative, truncateError } from '../flakes/log.js';
+import { defaultAppend, headSha, resolveKind, wants } from './options.js';
+/**
+ * Records every test that failed (or timed out) and then passed on a retry. Playwright loads
+ * reporters by module specifier, hence the default export. Imports Playwright's types only.
+ */
+export default class PlaywrightFlakeReporter {
+    options;
+    append;
+    /** The first failed attempt of each test that has not passed yet. */
+    failed = new Map();
+    constructor(options = {}) {
+        this.options = options;
+        this.append = options.append ?? defaultAppend;
+    }
+    onTestEnd(test, result) {
+        if (result.status === 'failed' || result.status === 'timedOut') {
+            if (!this.failed.has(test.id))
+                this.failed.set(test.id, result);
+            return;
+        }
+        const first = this.failed.get(test.id);
+        if (result.status !== 'passed' || result.retry === 0 || first === undefined)
+            return;
+        this.failed.delete(test.id);
+        // ['', project, file, ...describes, title]
+        const titlePath = test.titlePath();
+        const project = titlePath[1] ?? '';
+        if (!wants(this.options.projects, project))
+            return;
+        const trace = first.attachments.find((a) => a.name === 'trace')?.path;
+        this.append({
+            kind: resolveKind(this.options.kind, project, 'e2e'),
+            runner: 'playwright',
+            project,
+            file: repoRelative(test.location.file),
+            title: titlePath.slice(3).join(' › '),
+            firstAttemptError: truncateError(first.error?.message),
+            ...(trace ? { tracePath: trace } : {}),
+            ...headSha(),
+            at: new Date().toISOString()
+        });
+    }
+    printsToStdio() {
+        return false;
+    }
+}

package/dist/reporters/vitest.d.ts

@@ -0,0 +1,15 @@
+import type { Reporter, TestModule } from 'vitest/node';
+import { type FlakeReporterOptions } from './options.js';
+/**
+ * Records every test that passed after at least one retry. vitest reporters are a root-level
+ * option, so instantiate this in the root config's `reporters`; it sees every project and
+ * filters with `projects`. Imports vitest's types only.
+ */
+export declare class VitestFlakeReporter implements Reporter {
+    private readonly options;
+    private readonly append;
+    constructor(options?: FlakeReporterOptions);
+    onTestRunEnd(testModules: ReadonlyArray<TestModule>): void;
+    private walk;
+}
+export default VitestFlakeReporter;

package/dist/reporters/vitest.js

@@ -0,0 +1,47 @@
+import { repoRelative, truncateError } from '../flakes/log.js';
+import { defaultAppend, headSha, resolveKind, wants } from './options.js';
+/**
+ * Records every test that passed after at least one retry. vitest reporters are a root-level
+ * option, so instantiate this in the root config's `reporters`; it sees every project and
+ * filters with `projects`. Imports vitest's types only.
+ */
+export class VitestFlakeReporter {
+    options;
+    append;
+    constructor(options = {}) {
+        this.options = options;
+        this.append = options.append ?? defaultAppend;
+    }
+    onTestRunEnd(testModules) {
+        for (const testModule of testModules) {
+            const project = testModule.project.name;
+            if (!wants(this.options.projects, project))
+                continue;
+            const where = { project, file: repoRelative(testModule.moduleId) };
+            this.walk(testModule.children.array(), [], where);
+        }
+    }
+    walk(entities, titles, where) {
+        for (const entity of entities) {
+            if (entity.type === 'suite') {
+                this.walk(entity.children.array(), [...titles, entity.name], where);
+                continue;
+            }
+            const result = entity.result();
+            if (result.state !== 'passed' || (entity.diagnostic()?.retryCount ?? 0) === 0)
+                continue;
+            this.append({
+                kind: resolveKind(this.options.kind, where.project, where.project || 'unit'),
+                runner: 'vitest',
+                project: where.project,
+                file: where.file,
+                title: [...titles, entity.name].join(' › '),
+                // A test that passed on retry still reports the errors of its failed attempts.
+                firstAttemptError: truncateError(result.errors?.[0]?.message),
+                ...headSha(),
+                at: new Date().toISOString()
+            });
+        }
+    }
+}
+export default VitestFlakeReporter;

package/dist/run/exec.d.ts

@@ -0,0 +1,8 @@
+/** Run a program (no shell) and return its stdout. Throws on non-zero exit; the error
+ *  message carries the program's stderr. */
+export type Exec = (file: string, args: readonly string[]) => string;
+export declare const defaultExec: Exec;
+/** Run a shell command with inherited stdio (for long, chatty commands). */
+export type Run = (command: string, env?: NodeJS.ProcessEnv) => void;
+export declare const defaultRun: Run;
+export declare function lines(out: string): string[];

package/dist/run/exec.js

@@ -0,0 +1,15 @@
+import { execFileSync, execSync } from 'node:child_process';
+export const defaultExec = (file, args) => execFileSync(file, [...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: 64 * 1024 * 1024
+});
+export const defaultRun = (command, env) => {
+    execSync(command, { stdio: 'inherit', env: env ?? process.env });
+};
+export function lines(out) {
+    return out
+        .split('\n')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}

package/dist/run/stderr.d.ts

@@ -0,0 +1,22 @@
+import type { AllowlistEntry } from '../config/types.js';
+export declare function stripAnsi(s: string): string;
+/** Classify captured stderr line by line: blank and allowlisted lines are benign,
+ *  everything else is returned ANSI-stripped. */
+export declare function policeStderr(buffer: string, allowlist: readonly AllowlistEntry[]): {
+    offendingLines: string[];
+};
+export type PolicedOutcome = {
+    kind: 'pass';
+} | {
+    kind: 'fail-exit';
+    rawStderr: string;
+} | {
+    kind: 'fail-stderr';
+    offendingLines: string[];
+};
+/** A non-zero/null exit is a real failure (surface everything). A clean exit with
+ *  non-allowlisted stderr is a policy failure (surface just the offending lines). */
+export declare function decidePolicedOutcome(result: {
+    code: number | null;
+    stderr?: string;
+}, allowlist: readonly AllowlistEntry[]): PolicedOutcome;

package/dist/run/stderr.js

@@ -0,0 +1,30 @@
+// ANSI SGR color codes must not defeat allowlist matching. The escape character is built at
+// runtime so no control character appears in source (keeps no-control-regex quiet).
+const ANSI_SGR = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g');
+export function stripAnsi(s) {
+    return s.replace(ANSI_SGR, '');
+}
+/** Classify captured stderr line by line: blank and allowlisted lines are benign,
+ *  everything else is returned ANSI-stripped. */
+export function policeStderr(buffer, allowlist) {
+    const offendingLines = buffer
+        .split(/\r?\n/)
+        .map(stripAnsi)
+        .filter((line) => line.trim() !== '')
+        .filter((line) => !allowlist.some((entry) => {
+        entry.pattern.lastIndex = 0;
+        return entry.pattern.test(line);
+    }));
+    return { offendingLines };
+}
+/** A non-zero/null exit is a real failure (surface everything). A clean exit with
+ *  non-allowlisted stderr is a policy failure (surface just the offending lines). */
+export function decidePolicedOutcome(result, allowlist) {
+    const buffer = result.stderr ?? '';
+    if (result.code !== 0)
+        return { kind: 'fail-exit', rawStderr: buffer };
+    const { offendingLines } = policeStderr(buffer, allowlist);
+    if (offendingLines.length > 0)
+        return { kind: 'fail-stderr', offendingLines };
+    return { kind: 'pass' };
+}

package/dist/run/step.d.ts

@@ -0,0 +1,55 @@
+import type { AllowlistEntry } from '../config/types.js';
+import type { MachineLock } from '../lock/machine-lock.js';
+import type { PlannedStep } from '../signoff/plan.js';
+export interface RunResult {
+    /** Exit code, or null when killed by a signal. */
+    code: number | null;
+    timedOut: boolean;
+    interrupted: boolean;
+    /** Present only when captureStderr was set. */
+    stderr?: string;
+}
+export interface SignalSource {
+    on(event: 'SIGINT' | 'SIGTERM', fn: () => void): unknown;
+    off(event: 'SIGINT' | 'SIGTERM', fn: () => void): unknown;
+}
+export interface RunOptions {
+    /** stdout stays live; stderr is piped, buffered and returned. */
+    captureStderr?: boolean;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    /** Where SIGINT/SIGTERM arrive; defaults to the process. Injectable for tests. */
+    signals?: SignalSource;
+}
+/** After forwarding SIGINT/SIGTERM, how long a step gets to exit before its group is SIGKILLed. */
+export declare const INTERRUPT_GRACE_MS = 3000;
+/**
+ * Run a shell command with a hard wall-clock timeout. The command runs in its OWN process
+ * group (detached) so a timeout can SIGKILL the whole tree, not just the wrapping shell.
+ * Being in its own group, it no longer receives the terminal's Ctrl-C, so SIGINT/SIGTERM
+ * delivered to us are forwarded to the group. Never rejects.
+ */
+export declare function runWithTimeout(cmd: string, timeoutMs: number, opts?: RunOptions): Promise<RunResult>;
+export declare class StepFailure extends Error {
+    readonly label: string;
+    constructor(label: string, message: string);
+}
+export declare function timeoutMessage(label: string, timeoutMs: number): string;
+export interface StepRunOptions {
+    allowStderr: boolean;
+    allowlist: readonly AllowlistEntry[];
+    env?: NodeJS.ProcessEnv;
+    log?: (m: string) => void;
+    error?: (m: string) => void;
+    writeStderr?: (s: string) => void;
+    runImpl?: (cmd: string, timeoutMs: number, opts: RunOptions) => Promise<RunResult>;
+}
+/** How a step passed: 'allowed-stderr' means it would have failed stderr policing but for
+ *  --allow-stderr, which makes the run partial. */
+export type StepOutcome = 'passed' | 'allowed-stderr';
+/** Run one planned step. Every failure throws StepFailure so the caller's `finally`
+ *  releases the lock before the run exits. */
+export declare function runStep(step: PlannedStep, opts: StepRunOptions): Promise<StepOutcome>;
+/** Run the plan holding the machine lock; an empty plan touches no lock. The lock is
+ *  released on every exit path. Returns the labels whose stderr --allow-stderr waived. */
+export declare function runSteps(steps: readonly PlannedStep[], lock: MachineLock, run: (step: PlannedStep) => Promise<StepOutcome>): Promise<string[]>;

package/dist/run/step.js

@@ -0,0 +1,182 @@
+import { spawn } from 'node:child_process';
+import { decidePolicedOutcome } from './stderr.js';
+/** After exit, how long to wait for a captured stderr pipe to drain. A grandchild that
+ *  inherited the pipe can hold it open; this bounds the wait. */
+const STDERR_DRAIN_MS = 2_000;
+/** After forwarding SIGINT/SIGTERM, how long a step gets to exit before its group is SIGKILLed. */
+export const INTERRUPT_GRACE_MS = 3_000;
+/**
+ * Run a shell command with a hard wall-clock timeout. The command runs in its OWN process
+ * group (detached) so a timeout can SIGKILL the whole tree, not just the wrapping shell.
+ * Being in its own group, it no longer receives the terminal's Ctrl-C, so SIGINT/SIGTERM
+ * delivered to us are forwarded to the group. Never rejects.
+ */
+export function runWithTimeout(cmd, timeoutMs, opts = {}) {
+    const capture = opts.captureStderr ?? false;
+    const signals = opts.signals ?? process;
+    return new Promise((resolve) => {
+        const child = spawn(cmd, {
+            shell: true,
+            stdio: capture ? ['inherit', 'inherit', 'pipe'] : 'inherit',
+            detached: true,
+            env: opts.env ?? process.env,
+            cwd: opts.cwd
+        });
+        let stderrBuf = '';
+        let stderrEnded = !capture || child.stderr === null;
+        let exitCode;
+        let timedOut = false;
+        let interrupted = false;
+        let settled = false;
+        const killGroup = (signal) => {
+            try {
+                if (child.pid !== undefined)
+                    process.kill(-child.pid, signal);
+            }
+            catch {
+                // Group already gone.
+            }
+        };
+        let graceTimer;
+        const onSignal = () => {
+            if (interrupted) {
+                // A second Ctrl-C means "now".
+                killGroup('SIGKILL');
+                return;
+            }
+            interrupted = true;
+            killGroup('SIGTERM');
+            graceTimer = setTimeout(() => killGroup('SIGKILL'), INTERRUPT_GRACE_MS);
+            graceTimer.unref();
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killGroup('SIGKILL');
+        }, timeoutMs);
+        signals.on('SIGINT', onSignal);
+        signals.on('SIGTERM', onSignal);
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            clearTimeout(graceTimer);
+            // Reap survivors of the leader's exit (e.g. TERM-ignoring grandchildren).
+            if (interrupted)
+                killGroup('SIGKILL');
+            signals.off('SIGINT', onSignal);
+            signals.off('SIGTERM', onSignal);
+            resolve({ code, timedOut, interrupted, stderr: capture ? stderrBuf : undefined });
+        };
+        if (capture && child.stderr) {
+            // setEncoding decodes through a StringDecoder, so a multi-byte character split across
+            // chunks is not corrupted.
+            child.stderr.setEncoding('utf8');
+            child.stderr.on('data', (chunk) => {
+                stderrBuf += chunk;
+            });
+            child.stderr.on('end', () => {
+                stderrEnded = true;
+                if (exitCode !== undefined)
+                    finish(exitCode);
+            });
+        }
+        child.on('exit', (code) => {
+            exitCode = code;
+            if (stderrEnded)
+                finish(code);
+            else
+                setTimeout(() => finish(code), STDERR_DRAIN_MS).unref();
+        });
+        child.on('error', () => finish(1));
+    });
+}
+export class StepFailure extends Error {
+    label;
+    constructor(label, message) {
+        super(message);
+        this.label = label;
+        this.name = 'StepFailure';
+    }
+}
+function formatDuration(ms) {
+    return ms < 60_000 ? `${Math.round(ms / 1000)}s` : `${Math.round(ms / 60_000)}m`;
+}
+export function timeoutMessage(label, timeoutMs) {
+    return (`\n[chreode] TIMED OUT at: ${label} after ${formatDuration(timeoutMs)}. Suspect a ` +
+        `contending process or a genuinely slow machine. Killed the step's process tree.`);
+}
+/** Run one planned step. Every failure throws StepFailure so the caller's `finally`
+ *  releases the lock before the run exits. */
+export async function runStep(step, opts) {
+    const log = opts.log ?? ((m) => console.log(m));
+    const error = opts.error ?? ((m) => console.error(m));
+    const writeStderr = opts.writeStderr ?? ((s) => void process.stderr.write(s));
+    const runImpl = opts.runImpl ?? runWithTimeout;
+    log(`\n[chreode] ${step.label}: ${step.command}`);
+    const r = await runImpl(step.command, step.timeoutMs, {
+        captureStderr: step.policeStderr,
+        env: { ...(opts.env ?? process.env), CHREODE_SIGNOFF: '1' }
+    });
+    if (r.timedOut) {
+        if (r.stderr)
+            writeStderr(r.stderr);
+        error(timeoutMessage(step.label, step.timeoutMs));
+        throw new StepFailure(step.label, `${step.label} timed out`);
+    }
+    if (r.interrupted) {
+        if (r.stderr)
+            writeStderr(r.stderr);
+        error(`\n[chreode] INTERRUPTED at: ${step.label}`);
+        throw new StepFailure(step.label, `${step.label} interrupted`);
+    }
+    if (!step.policeStderr) {
+        if (r.code !== 0) {
+            error(`\n[chreode] FAILED at: ${step.label} (exit ${r.code})`);
+            throw new StepFailure(step.label, `${step.label} failed`);
+        }
+        return 'passed';
+    }
+    const outcome = decidePolicedOutcome({ code: r.code, stderr: r.stderr }, opts.allowlist);
+    if (outcome.kind === 'fail-exit') {
+        if (outcome.rawStderr)
+            writeStderr(outcome.rawStderr);
+        error(`\n[chreode] FAILED at: ${step.label} (exit ${r.code})`);
+        throw new StepFailure(step.label, `${step.label} failed`);
+    }
+    if (outcome.kind === 'fail-stderr') {
+        if (opts.allowStderr) {
+            error(`\n[chreode] ${step.label} wrote unexpected stderr, allowed by --allow-stderr:`);
+            for (const line of outcome.offendingLines)
+                writeStderr(`${line}\n`);
+            return 'allowed-stderr';
+        }
+        error(`\n[chreode] FAILED at: ${step.label}: it exited 0 but wrote unexpected stderr.\n` +
+            `[chreode] A passing step that logs errors is still a failure: fix it at the source.\n` +
+            `[chreode] Allowlisting genuinely benign noise is a reviewed change to stderrAllowlist\n` +
+            `[chreode] in chreode.config.ts, with a reason. --allow-stderr bypasses for one run.\n` +
+            `[chreode] Offending lines:`);
+        for (const line of outcome.offendingLines)
+            writeStderr(`${line}\n`);
+        throw new StepFailure(step.label, `${step.label} wrote unexpected stderr`);
+    }
+    return 'passed';
+}
+/** Run the plan holding the machine lock; an empty plan touches no lock. The lock is
+ *  released on every exit path. Returns the labels whose stderr --allow-stderr waived. */
+export async function runSteps(steps, lock, run) {
+    if (steps.length === 0)
+        return [];
+    const release = await lock.acquire();
+    const allowed = [];
+    try {
+        for (const step of steps) {
+            if ((await run(step)) === 'allowed-stderr')
+                allowed.push(step.label);
+        }
+        return allowed;
+    }
+    finally {
+        await release();
+    }
+}

package/dist/signoff/plan.d.ts

@@ -0,0 +1,50 @@
+import type { Matcher, ResolvedConfig, ResolvedStep, RuleConfig } from '../config/types.js';
+export declare class PlanError extends Error {
+    constructor(message: string);
+}
+export interface PlanInput {
+    paths: readonly string[];
+    full: boolean;
+    skip: readonly string[];
+    base: string;
+    head: string;
+    isWorktree: boolean;
+}
+export interface PlannedStep {
+    label: string;
+    command: string;
+    policeStderr: boolean;
+    timeoutMs: number;
+}
+export type SkipReason = {
+    kind: 'not-triggered';
+} | {
+    kind: 'if-false';
+} | {
+    kind: 'skip-flag';
+} | {
+    kind: 'superseded';
+    by: string;
+};
+export interface Plan {
+    triggers: string[];
+    /** Changed paths no rule matched; each one fired every trigger. */
+    unmatched: string[];
+    steps: PlannedStep[];
+    skipped: {
+        label: string;
+        reason: SkipReason;
+    }[];
+    /** Steps that would have run but for --skip: these go in the status description. */
+    skippedByFlag: string[];
+}
+export declare function matchesAny(path: string, matchers: Matcher | Matcher[]): boolean;
+export declare function matchRule(path: string, rules: readonly RuleConfig[]): RuleConfig | null;
+export declare function allTriggers(steps: readonly ResolvedStep[]): string[];
+/** Rules can only make a run smaller by matching: an unmatched path fires everything. */
+export declare function fireTriggers(paths: readonly string[], rules: readonly RuleConfig[], steps: readonly ResolvedStep[]): {
+    triggers: string[];
+    unmatched: string[];
+};
+export declare function planSignoff(config: ResolvedConfig, input: PlanInput): Plan;
+export declare function describeSkip(reason: SkipReason): string;