canary-test-cli 5.15.0 → 6.0.0

package/bin/canary.js

@@ -6,35 +6,40 @@ const path = require('node:path');
 const fs = require('node:fs');
 const { isTsCommand, route } = require('../dist/router.js');
 
-function getBinaryPath(platform) {
-  const name = platform === 'win32' ? 'canary.exe' : 'canary';
-  return path.join(__dirname, name);
+/**
+ * Absolute path to the bundled TypeScript engine's runnable entry
+ * (`dist/engine/cli.js`, generated by scripts/build-engine.mjs). Runs under the
+ * current `node` via `execFileSync(process.execPath, [enginePath, ...])`.
+ */
+function getEnginePath() {
+  return path.join(__dirname, '..', 'dist', 'engine', 'cli.js');
 }
 
 /**
- * Forward a command to the bundled Python binary. Returns the exit code
- * (0 on success, the binary's status on failure, 1 when the binary is missing).
+ * Forward a command to the bundled TypeScript engine. Returns the exit code
+ * (0 on success, the engine's status on failure, 1 when the engine is missing).
  * Dependencies are injectable for testing.
  */
-function forwardToBinary(
+function forwardToEngine(
   argv,
   {
     execFile = execFileSync,
     existsSync = fs.existsSync,
-    platform = process.platform,
+    execPath = process.execPath,
     stderr = process.stderr,
   } = {},
 ) {
-  const binaryPath = getBinaryPath(platform);
-  if (!existsSync(binaryPath)) {
+  const enginePath = getEnginePath();
+  if (!existsSync(enginePath)) {
     stderr.write(
-      `canary binary not found at ${binaryPath}.\n` +
-        `Try reinstalling: npm install -g canary-test-cli\n`,
+      `canary engine not found at ${enginePath}.\n` +
+        `The package looks incomplete; try reinstalling: npm install -g canary-test-cli\n`,
     );
     return 1;
   }
   try {
-    execFile(binaryPath, argv, { stdio: 'inherit' });
+    // Inherit stdio AND cwd so the engine operates on the user's project.
+    execFile(execPath, [enginePath, ...argv], { stdio: 'inherit' });
     return 0;
   } catch (err) {
     return err.status ?? 1;
@@ -43,14 +48,14 @@ function forwardToBinary(
 
 /**
  * Dispatch one invocation: TS-handled commands (e.g. `overlay`, `doctor`) go to
- * the router; everything else forwards verbatim to the Python binary. Returns
+ * the router; everything else forwards verbatim to the bundled engine. Returns
  * the process exit code, or a Promise of one for async commands (`doctor`).
  */
 function run(argv, deps = {}) {
   if (isTsCommand(argv)) {
     return route(argv, deps) ?? 0;
   }
-  return forwardToBinary(argv, deps);
+  return forwardToEngine(argv, deps);
 }
 
 function main() {
@@ -60,5 +65,5 @@ function main() {
   );
 }
 
-module.exports = { getBinaryPath, forwardToBinary, run };
+module.exports = { getEnginePath, forwardToEngine, run };
 if (require.main === module) main();

package/dist/doctor-manifest.d.ts

@@ -0,0 +1,94 @@
+import type { CheckResult } from './doctor.js';
+export declare const CHECK_TYPES: readonly ["file-exists", "url-reachable", "command-succeeds"];
+export type CheckType = (typeof CHECK_TYPES)[number];
+/** A single validated check from an overlay's `doctor.json`. */
+export interface ManifestCheck {
+    id: string;
+    type: CheckType;
+    /** Shown under the check line when it fails. */
+    remedy: string;
+    /**
+     * Free-form audience tags (#319 B). A check with none runs for every
+     * audience; otherwise it runs only when `--audience <tag>` matches one.
+     * Declared as `audience:` in doctor.json (legacy alias: `persona:`).
+     *
+     * NB: unrelated to harness's persona system (`run_persona` /
+     * `generate_persona_artifacts`). This is a canary-local check-grouping tag;
+     * the field was renamed off "persona" to end that collision.
+     */
+    audience?: string[];
+    /** `file-exists`: path relative to the overlay clone. */
+    path?: string;
+    /** `url-reachable`: the URL to probe. */
+    url?: string;
+    /** `command-succeeds`: argv array run (no shell) in the clone dir. */
+    command?: string[];
+}
+/** Result of loading a manifest: either its checks, or a single failing check. */
+export type ManifestLoad = {
+    ok: true;
+    checks: ManifestCheck[];
+} | {
+    ok: false;
+    failure: CheckResult;
+};
+/** Path to an overlay's manifest. */
+export declare function manifestPath(cloneDir: string): string;
+/**
+ * Stable fingerprint of a manifest's `command-succeeds` checks — the (id,
+ * command) pairs, sorted by id. Returns null when there are no such checks
+ * (nothing to gate). Consent is re-requested when this value changes.
+ */
+export declare function commandSucceedsHash(checks: ManifestCheck[]): string | null;
+/**
+ * Load and validate `<clone>/.canary/doctor.json`. A missing file is not an
+ * error (no checks). A malformed file or an invalid check degrades to a single
+ * failing check ({@link ManifestLoad} `ok: false`) — never a throw.
+ */
+export declare function loadManifest(cloneDir: string): ManifestLoad;
+/**
+ * The distinct audience tags declared across a set of checks, in first-seen
+ * order and de-duplicated case-insensitively (original casing preserved for
+ * display). This is the discoverable audience *vocabulary* — the engine ships
+ * none of its own, so it is derived entirely from overlay manifests. Used to
+ * tell a user which `--audience` values actually mean something (issue #294).
+ */
+export declare function collectAudiences(checks: ManifestCheck[]): string[];
+/**
+ * Keep checks that should run for `audience`: a null audience runs everything;
+ * otherwise keep checks with no audience plus those whose audience list
+ * contains the tag (case-insensitive).
+ */
+export declare function filterByAudience(checks: ManifestCheck[], audience: string | null): ManifestCheck[];
+/** Default per-check timeout for url and command checks. */
+export declare const DEFAULT_CHECK_TIMEOUT_MS = 10000;
+/** Probe a URL for reachability (injectable). Resolves true on a 2xx/3xx. */
+export type UrlProbe = (url: string, timeoutMs: number) => Promise<boolean>;
+/** Run a command (injectable). `ok` = exit 0; `timedOut` = killed at the timeout. */
+export type CommandRunner = (command: string[], cwd: string, timeoutMs: number, extraEnv?: NodeJS.ProcessEnv) => {
+    ok: boolean;
+    timedOut: boolean;
+    detail?: string;
+};
+/** Context for executing checks against one overlay clone. */
+export interface RunContext {
+    cloneDir: string;
+    /**
+     * Directory `canary doctor` was invoked from (the consuming repo root).
+     * Exposed to `command-succeeds` checks as `CANARY_INVOCATION_DIR` so a check
+     * can anchor to consuming-repo runtime artifacts instead of the overlay
+     * clone, which is always the cwd (#378).
+     */
+    invocationDir?: string;
+    /** Whether this overlay's `command-succeeds` checks may execute. */
+    consentGranted: boolean;
+    timeoutMs?: number;
+    probeUrl?: UrlProbe;
+    runCommand?: CommandRunner;
+}
+/**
+ * Execute one validated check against its overlay clone, under a bounded
+ * timeout. `command-succeeds` is skipped (not failed) unless consent is
+ * granted. Never throws.
+ */
+export declare function runCheck(check: ManifestCheck, ctx: RunContext): Promise<CheckResult>;

package/dist/doctor.d.ts

@@ -0,0 +1,67 @@
+import type { CommandDeps } from './overlay-commands.js';
+import { type CommandRunner, type UrlProbe } from './doctor-manifest.js';
+/** Outcome of a single doctor check. */
+export type CheckStatus = 'pass' | 'fail' | 'skip' | 'info';
+/** A single doctor check result, rendered as one output line. */
+export interface CheckResult {
+    /** Stable identifier (engine check id, or the manifest check's `id`). */
+    id: string;
+    status: CheckStatus;
+    /** Human-readable label for the check line. */
+    label: string;
+    /** Shown indented under the line when the check does not pass. */
+    remedy?: string;
+}
+/** Dependencies for `doctor`, injectable for tests (real ones by default). */
+export interface DoctorDeps extends CommandDeps {
+    /** Current working directory (for project `.canary/` and `.mcp.json`). */
+    cwd?: string;
+    currentVersion?: string;
+    getLatestVersion?: () => Promise<string | null>;
+    probeUrl?: UrlProbe;
+    runCommand?: CommandRunner;
+    timeoutMs?: number;
+}
+/**
+ * The `canary doctor --json` machine contract (issue #318). Canary-owned and
+ * intentionally distinct from `harness doctor --json`: only `allPassed` matches
+ * harness's top-level shape; per-check fields (`id`/`label`/`remedy`/`group`)
+ * and the `skip` status tier are canary's own. `version` guards the contract so
+ * consumers can detect a breaking change.
+ */
+export interface JsonReportCheck {
+    /** Stable check identifier (engine check id, or the manifest check's `id`). */
+    id: string;
+    status: CheckStatus;
+    label: string;
+    /** Present only when the check did not pass. */
+    remedy?: string;
+    /** The section the check belongs to, e.g. `"Engine"` or `"Overlay: acme"`. */
+    group: string;
+}
+export interface JsonReport {
+    version: 1;
+    checks: JsonReportCheck[];
+    /** True iff no check failed — mirrors `harness doctor --json`'s one shared field. */
+    allPassed: boolean;
+    /** Non-fatal advisories (e.g. an unknown `--audience`); empty when none. */
+    warnings: string[];
+}
+/** `--json` requests machine output on stdout instead of the human report. */
+export declare function parseJsonFlag(args: readonly string[]): boolean;
+/**
+ * Fail-loud hint for an unrecognized `--audience` value (issue #294). Returns
+ * null when there is nothing to say — no audience was passed, or the passed
+ * audience is part of the known vocabulary. Otherwise returns a one-line,
+ * actionable message: the engine ships no audience vocabulary, so this lists
+ * the tags overlays actually declared (or says none are defined) instead of
+ * silently running only the audience-less checks and leaving the user to
+ * guess why their filter matched nothing.
+ */
+export declare function unknownAudienceHint(audience: string | null, known: readonly string[]): string | null;
+/**
+ * Run `canary doctor`. Returns a process exit code: 0 when every check passed
+ * or was skipped/info, non-zero when any check failed. A malformed manifest for
+ * one overlay never blocks engine checks or other overlays.
+ */
+export declare function runDoctor(args: readonly string[], deps?: DoctorDeps): Promise<number>;

package/dist/engine/analysis/cli.js

@@ -0,0 +1,270 @@
+/**
+ * CLI subcommands for `canary analyze` -- faithful port of
+ * `agent/analysis/cli.py` (the `analyze_app` Typer sub-app), wired to the
+ * already-ported analysis engine + report builders (`engine.ts`, `reports.ts`,
+ * `rows.ts`) and the local NDJSON history store.
+ *
+ * Follows the guardian CLI conventions (see `../cli-common.ts`): a
+ * {@link createAnalyzeCommand} factory wired to an injectable {@link AnalyzeDeps},
+ * and `normalizeUsageExit` on every command so usage errors exit 2. No command
+ * raises a business exit -- every analyze subcommand returns 0 (matching Python).
+ *
+ * Python->TS fidelity notes:
+ *   - `json.dumps(x, indent=2)` -> {@link jsonIndent2} (byte-exact + ensure_ascii).
+ *   - The report builders are byte-exact ports (Markdown), so the human-readable
+ *     paths match the oracle exactly.
+ *   - INTENTIONAL DEVIATION: the TS analysis engine (`engine.ts`) operates on the
+ *     LOCAL NDJSON store only -- the JS Supabase SDK is async and the engine's
+ *     query surface is synchronous. `--db-url` is still accepted (faithful CLI
+ *     surface) but the TS port always reads the local store, exactly as the
+ *     Python `isinstance(store, LocalHistoryStore)` read-path does for the
+ *     spikes/common-failures commands. No Python analyze test exercises a remote
+ *     store.
+ *   - `area-health` accepts `--json` but ignores it -- faithful to the Python
+ *     command, which never branches on `output_json`.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Command, Option } from 'commander';
+import { jsonIndent2, normalizeUsageExit } from '../cli-common.js';
+import { AnalysisEngine } from './engine.js';
+import { buildAreaHealthReport, buildCommonFailuresReport, buildFlakyReport, buildRegressionCandidatesReport, buildSpikesReport, } from './reports.js';
+import { NdjsonHistoryStore } from '../history/ndjson-store.js';
+const DEFAULT_HISTORY_PATH = 'test-results/reports/history-v2.jsonl';
+/** Process-backed defaults for production. */
+export function defaultAnalyzeDeps() {
+    const err = (s) => {
+        process.stderr.write(`${s}\n`);
+    };
+    return {
+        out: (s) => process.stdout.write(`${s}\n`),
+        err,
+        env: process.env,
+        // The ported analysis engine's query surface is synchronous, so it cannot
+        // drive the async Supabase store; analyze reads local NDJSON only. Python
+        // honors --db-url / CANARY_HISTORY_DB_URL via make_store, so warn (to stderr,
+        // not stdout -- keeps --json clean) rather than SILENTLY reading a different
+        // data source. Full remote support is deferred with the async engine port.
+        makeStore: (dbUrl) => {
+            if (dbUrl) {
+                err('note: --db-url is ignored by analyze; it reads local NDJSON only.');
+            }
+            return new NdjsonHistoryStore(DEFAULT_HISTORY_PATH);
+        },
+    };
+}
+function writeArtifacts(artifacts, output) {
+    mkdirSync(output, { recursive: true });
+    for (const [name, content] of Object.entries(artifacts)) {
+        writeFileSync(join(output, name), content, 'utf-8');
+    }
+}
+function flakyCmd(opts, deps) {
+    const store = deps.makeStore(opts.dbUrl);
+    const rows = store.queryFlaky(opts.window, opts.suite ?? null, opts.minRate);
+    if (opts.json) {
+        deps.out(jsonIndent2(rows));
+    }
+    else {
+        deps.out(buildFlakyReport(rows, opts.window, opts.minRate));
+    }
+}
+function spikesCmd(opts, deps) {
+    const store = deps.makeStore(opts.dbUrl);
+    const rows = [];
+    for (const r of store.readAll()) {
+        if (opts.since && (r.timestamp ?? '') < opts.since)
+            continue;
+        rows.push({
+            suite: r.suite ?? '',
+            timestamp: r.timestamp ?? '',
+            passed: r.passed ?? 0,
+            failed: r.failed ?? 0,
+            flaky: r.flaky ?? 0,
+            total: r.total ?? 0,
+        });
+    }
+    if (opts.json) {
+        deps.out(jsonIndent2(rows));
+    }
+    else {
+        deps.out(buildSpikesReport(rows, opts.delta));
+    }
+}
+function areaHealthCmd(opts, deps) {
+    // Faithful to Python: always builds from an empty row set and never branches
+    // on --json.
+    deps.out(buildAreaHealthReport([], opts.weeks));
+}
+function commonFailuresCmd(opts, deps) {
+    const store = deps.makeStore(opts.dbUrl);
+    const rows = [];
+    for (const record of store.readAll()) {
+        if (opts.since && (record.timestamp ?? '') < opts.since)
+            continue;
+        for (const t of record.tests ?? []) {
+            if ((t.status === 'failed' || t.status === 'flaky') && t.error_text) {
+                rows.push({
+                    test_name: t.test_name,
+                    suite: record.suite ?? '',
+                    failure_category: t.failure_category ?? 'other',
+                    error_text: t.error_text ?? '',
+                    run_count: 1,
+                });
+            }
+        }
+    }
+    if (opts.json) {
+        deps.out(jsonIndent2(rows));
+    }
+    else {
+        deps.out(buildCommonFailuresReport(rows, opts.minSuites));
+    }
+}
+function regressionCandidatesCmd(opts, deps) {
+    const engine = new AnalysisEngine(deps.makeStore(opts.dbUrl));
+    const candidates = engine.detectRegressionCandidates(null, opts.minGreen, opts.recentFailures);
+    if (opts.json) {
+        deps.out(jsonIndent2(candidates));
+    }
+    else {
+        deps.out(buildRegressionCandidatesReport(candidates));
+    }
+}
+function digestCmd(opts, deps) {
+    const engine = new AnalysisEngine(deps.makeStore(opts.dbUrl));
+    const result = engine.run({
+        window: opts.window,
+        delta: opts.delta,
+        weeks: opts.weeks,
+        minSuites: opts.minSuites,
+        suite: opts.suite ?? null,
+    });
+    writeArtifacts(result.artifacts, opts.output);
+    if (opts.json) {
+        deps.out(jsonIndent2({
+            flaky_count: result.flaky.length,
+            spike_count: result.spikes.length,
+            regression_count: result.regressionCandidates.length,
+        }));
+    }
+    else if (opts.slack) {
+        printSlack(result.flaky.length, result.regressionCandidates.length, deps);
+    }
+    else {
+        deps.out(result.digestMd);
+        deps.out(`\nArtifacts written to ${opts.output}/`);
+    }
+}
+function printSlack(flakyCount, regCount, deps) {
+    // U+2022 bullet, U+2265 >=.
+    const lines = [
+        '*Fleet Health Digest*',
+        `\u{2022} Flakeys \u{2265} 10%: ${flakyCount}`,
+        `\u{2022} Regression candidates: ${regCount}`,
+    ];
+    deps.out(lines.join('\n'));
+}
+// --- assembly ----------------------------------------------------------------
+/** Build a fresh `analyze` command wired to `depsInit`. */
+export function createAnalyzeCommand(depsInit = {}) {
+    const deps = { ...defaultAnalyzeDeps(), ...depsInit };
+    const program = new Command('analyze');
+    program
+        .description('Cross-suite fleet health analysis.')
+        .exitOverride(normalizeUsageExit);
+    program
+        .command('flaky')
+        .description('Fleet-wide flake leaderboard.')
+        .addOption(new Option('-w, --window <n>')
+        .default(30)
+        .argParser((v) => Number.parseInt(v, 10)))
+        .option('-s, --suite <suite>')
+        .addOption(new Option('--min-rate <pct>')
+        .default(10.0)
+        .argParser((v) => Number.parseFloat(v)))
+        .addOption(new Option('--db-url <url>').env('CANARY_HISTORY_DB_URL'))
+        .option('--json')
+        .action((opts) => {
+        flakyCmd(opts, deps);
+    });
+    program
+        .command('spikes')
+        .description('Recent failure spikes across suites.')
+        .option('--since <date>', 'ISO date filter, e.g. 2026-06-01')
+        .addOption(new Option('--delta <pp>')
+        .default(20.0)
+        .argParser((v) => Number.parseFloat(v)))
+        .addOption(new Option('--db-url <url>').env('CANARY_HISTORY_DB_URL'))
+        .option('--json')
+        .action((opts) => {
+        spikesCmd(opts, deps);
+    });
+    program
+        .command('area-health')
+        .description('Area degradation trends over time.')
+        .addOption(new Option('--weeks <n>')
+        .default(4)
+        .argParser((v) => Number.parseInt(v, 10)))
+        .addOption(new Option('--db-url <url>').env('CANARY_HISTORY_DB_URL'))
+        .option('--json')
+        .action((opts) => {
+        areaHealthCmd(opts, deps);
+    });
+    program
+        .command('common-failures')
+        .description('Cross-suite failure fingerprinting.')
+        .option('--since <date>')
+        .addOption(new Option('--min-suites <n>')
+        .default(2)
+        .argParser((v) => Number.parseInt(v, 10)))
+        .addOption(new Option('--db-url <url>').env('CANARY_HISTORY_DB_URL'))
+        .option('--json')
+        .action((opts) => {
+        commonFailuresCmd(opts, deps);
+    });
+    program
+        .command('regression-candidates')
+        .description('Tests newly and consistently broken after a green streak.')
+        .addOption(new Option('--min-green <n>')
+        .default(5)
+        .argParser((v) => Number.parseInt(v, 10)))
+        .addOption(new Option('--recent-failures <n>')
+        .default(3)
+        .argParser((v) => Number.parseInt(v, 10)))
+        .addOption(new Option('--db-url <url>').env('CANARY_HISTORY_DB_URL'))
+        .option('--json')
+        .action((opts) => {
+        regressionCandidatesCmd(opts, deps);
+    });
+    program
+        .command('digest')
+        .description('Combined digest of all five report types.')
+        .addOption(new Option('--window <n>')
+        .default(30)
+        .argParser((v) => Number.parseInt(v, 10)))
+        .addOption(new Option('--delta <pp>')
+        .default(20.0)
+        .argParser((v) => Number.parseFloat(v)))
+        .addOption(new Option('--weeks <n>')
+        .default(4)
+        .argParser((v) => Number.parseInt(v, 10)))
+        .addOption(new Option('--min-suites <n>')
+        .default(2)
+        .argParser((v) => Number.parseInt(v, 10)))
+        .option('--suite <suite>')
+        .addOption(new Option('--output <dir>').default('test-results/analysis'))
+        .option('--json')
+        .option('--slack')
+        .addOption(new Option('--db-url <url>').env('CANARY_HISTORY_DB_URL'))
+        .action((opts) => {
+        digestCmd(opts, deps);
+    });
+    for (const sub of program.commands) {
+        sub.exitOverride(normalizeUsageExit);
+    }
+    return program;
+}
+/** The production `analyze` command (process-backed defaults). */
+export const analyzeCommand = createAnalyzeCommand();
+//# sourceMappingURL=cli.js.map

package/dist/engine/analysis/engine.js

@@ -0,0 +1,146 @@
+/**
+ * AnalysisEngine — queries the history store and runs all report types.
+ *
+ * Faithful TS port of `agent/analysis/engine.py`. Thin coordinator: calls the
+ * store's query methods, passes results to the pure builders in reports.ts, and
+ * returns structured data plus Markdown artifacts.
+ *
+ * Fidelity note: as in Python, `areaHealth` is intentionally never populated by
+ * `run()` (the Python engine initialises `area_rows = []` and never appends), so
+ * the area-health artifact always renders the empty-data message.
+ */
+import { buildAreaHealthReport, buildCommonFailuresReport, buildDigest, buildFlakyReport, buildRegressionCandidatesReport, buildSpikesReport, } from './reports.js';
+import { detectRegressions } from '../history/detector.js';
+import { def } from '../util/coalesce.js';
+function isReadable(store) {
+    return typeof store.readAll === 'function';
+}
+function isFailureWithError(t) {
+    return ((t.status === 'failed' || t.status === 'flaky') && Boolean(t.error_text));
+}
+function toCommonFailureRow(record, t) {
+    return {
+        test_name: t.test_name,
+        suite: def(record.suite, ''),
+        failure_category: def(t.failure_category, 'other'),
+        error_text: t.error_text,
+    };
+}
+export class AnalysisEngine {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    run(opts = {}) {
+        const window = opts.window ?? 30;
+        const delta = opts.delta ?? 20.0;
+        const weeks = opts.weeks ?? 4;
+        const minSuites = opts.minSuites ?? 2;
+        const minFlakeRate = opts.minFlakeRate ?? 10.0;
+        const minGreen = opts.minGreen ?? 5;
+        const recentFailures = opts.recentFailures ?? 3;
+        const suite = opts.suite ?? null;
+        const flaky = this.store.queryFlaky(window, suite, minFlakeRate);
+        const suitesToQuery = suite ? [suite] : this.discoverSuites();
+        const spikesRows = [];
+        for (const s of suitesToQuery) {
+            const summary = this.store.querySummary(s, window * 2);
+            for (const row of def(summary.runs, [])) {
+                // query_summary rows omit suite; the spikes builder groups by it, so
+                // tag each pooled row with the suite it came from (matches Python).
+                spikesRows.push({
+                    suite: s,
+                    timestamp: row.timestamp,
+                    total: row.total,
+                    failed: row.failed,
+                    flaky: row.flaky,
+                });
+            }
+        }
+        // Faithful to Python: area rows are never populated by run().
+        const areaRows = [];
+        const commonRows = this.queryCommonFailures(suite);
+        const regressionCandidates = this.detectRegressionCandidates(suite, minGreen, recentFailures);
+        const digest = buildDigest({
+            flaky,
+            spikes: spikesRows,
+            areaHealth: areaRows,
+            commonFailures: commonRows,
+            regressionCandidates,
+            window,
+            delta,
+            weeks,
+            minSuites,
+        });
+        const artifacts = {
+            'flaky.md': buildFlakyReport(flaky, window, minFlakeRate),
+            'spikes.md': buildSpikesReport(spikesRows, delta),
+            'area-health.md': buildAreaHealthReport(areaRows, weeks),
+            'common-failures.md': buildCommonFailuresReport(commonRows, minSuites),
+            'regression-candidates.md': buildRegressionCandidatesReport(regressionCandidates),
+            'digest.md': digest,
+        };
+        return {
+            flaky,
+            spikes: spikesRows,
+            areaHealth: areaRows,
+            commonFailures: commonRows,
+            regressionCandidates,
+            digestMd: digest,
+            artifacts,
+        };
+    }
+    discoverSuites() {
+        if (!isReadable(this.store))
+            return [];
+        const suites = new Set();
+        for (const r of this.store.readAll()) {
+            if (r.suite)
+                suites.add(r.suite);
+        }
+        return [...suites];
+    }
+    queryCommonFailures(suite) {
+        if (!isReadable(this.store))
+            return [];
+        const rows = [];
+        for (const record of this.store.readAll()) {
+            if (suite && record.suite !== suite)
+                continue;
+            for (const t of def(record.tests, [])) {
+                if (isFailureWithError(t))
+                    rows.push(toCommonFailureRow(record, t));
+            }
+        }
+        return rows;
+    }
+    detectRegressionCandidates(suite, minGreen, recentFailures) {
+        if (!isReadable(this.store))
+            return [];
+        const testNames = new Set();
+        for (const record of this.store.readAll()) {
+            if (suite && record.suite !== suite)
+                continue;
+            for (const t of def(record.tests, []))
+                testNames.add(t.test_name);
+        }
+        const candidates = [];
+        for (const name of testNames) {
+            const timeline = this.store.queryTimeline(name);
+            const result = detectRegressions(timeline, minGreen, recentFailures);
+            if (result.is_regression) {
+                candidates.push({
+                    test_name: name,
+                    suite: timeline.length > 0 ? timeline[0].suite : '',
+                    area: null,
+                    green_streak: result.green_streak,
+                    ...(result.first_failure_commit
+                        ? { first_failure_commit: result.first_failure_commit }
+                        : {}),
+                });
+            }
+        }
+        return candidates;
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/engine/analysis/rows.js

@@ -0,0 +1,9 @@
+/**
+ * Row shapes consumed by the report builders.
+ *
+ * These mirror the pre-fetched query rows that the Python `reports.py` builders
+ * receive from the history store — one shape per report. Ported field-for-field
+ * so the TS builders produce identical output (see the parity harness).
+ */
+export {};
+//# sourceMappingURL=rows.js.map