flakeradar 0.1.0

package/dist/report/terminal.d.ts

@@ -0,0 +1,4 @@
+import type { AnalysisReport } from "../types.js";
+/** Render the full report as colored text for a terminal. */
+export declare function renderTerminal(report: AnalysisReport): string;
+//# sourceMappingURL=terminal.d.ts.map

package/dist/report/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/report/terminal.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAe,MAAM,aAAa,CAAC;AAa/D,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CA2C7D"}

package/dist/report/terminal.js

@@ -0,0 +1,101 @@
+import { causeLabel } from "../analysis/classify.js";
+import { color } from "../color.js";
+const pct = (n) => `${Math.round(n * 100)}%`;
+function ratio(v) {
+    return `${v.failures}/${v.passes + v.failures}`;
+}
+function shorten(s, max) {
+    if (s.length <= max)
+        return s;
+    return `${s.slice(0, max - 1)}…`;
+}
+/** Render the full report as colored text for a terminal. */
+export function renderTerminal(report) {
+    const { summary, flaky, alwaysFailing } = report;
+    const lines = [];
+    lines.push(color.bold(color.cyan("flakeradar")) + color.dim(" — flakiness report"));
+    lines.push("");
+    const greenColor = summary.greenRunRate >= 0.9 ? color.green : summary.greenRunRate >= 0.5 ? color.yellow : color.red;
+    lines.push([
+        `${color.dim("Runs analyzed:")} ${color.bold(String(summary.totalRuns))}`,
+        `${color.dim("Green runs:")} ${greenColor(pct(summary.greenRunRate))}`,
+        `${color.dim("Crashed:")} ${summary.crashedRuns > 0 ? color.red(String(summary.crashedRuns)) : "0"}`,
+    ].join("   "));
+    lines.push([
+        `${color.dim("Unique tests:")} ${summary.uniqueTests}`,
+        `${color.dim("Flaky:")} ${summary.flakyCount > 0 ? color.yellow(String(summary.flakyCount)) : color.green("0")}`,
+        `${color.dim("Always-failing:")} ${summary.alwaysFailCount > 0 ? color.red(String(summary.alwaysFailCount)) : "0"}`,
+    ].join("   "));
+    lines.push("");
+    if (flaky.length === 0) {
+        lines.push(color.green("✔ No flaky tests detected. ") + color.dim("Every test was consistent across all runs."));
+    }
+    else {
+        lines.push(color.bold(`Flaky tests (ranked, worst first):`));
+        lines.push(renderFlakyTable(flaky));
+        lines.push("");
+        lines.push(renderTopDetail(flaky[0]));
+    }
+    if (alwaysFailing.length > 0) {
+        lines.push("");
+        lines.push(color.bold(color.red("Always-failing")) + color.dim(" (broken every run — likely a real bug, not flakiness):"));
+        for (const v of alwaysFailing.slice(0, 10)) {
+            lines.push(`  ${color.red("✗")} ${shorten(v.id, 70)}  ${color.dim(`(${v.failures}/${v.failures} failed)`)}`);
+        }
+        if (alwaysFailing.length > 10)
+            lines.push(color.dim(`  …and ${alwaysFailing.length - 10} more`));
+    }
+    return lines.join("\n");
+}
+function renderFlakyTable(flaky) {
+    const header = ["#", "Test", "Fails", "Rate", "Flips", "Likely cause", "Conf"];
+    const rows = flaky.map((v, i) => [
+        String(i + 1),
+        shorten(v.id, 48),
+        ratio(v),
+        pct(v.failureRate),
+        String(v.flips),
+        v.cause ? causeLabel(v.cause.category) : "-",
+        v.cause ? pct(v.cause.confidence) : "-",
+    ]);
+    const widths = header.map((h, col) => Math.max(h.length, ...rows.map((r) => r[col].length)));
+    const sep = "  ";
+    const fmtRow = (cells, colorize, v) => cells
+        .map((c, col) => {
+        const padded = col === 1 || col === 5 ? c.padEnd(widths[col]) : c.padStart(widths[col]);
+        if (colorize && v)
+            return colorize(v, col, padded);
+        return padded;
+    })
+        .join(sep);
+    const out = [];
+    out.push(color.dim(fmtRow(header)));
+    flaky.forEach((v, i) => {
+        out.push(fmtRow(rows[i], (verdict, col, text) => {
+            if (col === 3) {
+                // failure rate
+                return verdict.failureRate >= 0.5 ? color.red(text) : color.yellow(text);
+            }
+            if (col === 5)
+                return color.magenta(text);
+            return text;
+        }, v));
+    });
+    return out.join("\n");
+}
+function renderTopDetail(top) {
+    const lines = [];
+    lines.push(color.bold("Top offender: ") + color.yellow(top.id));
+    if (top.cause) {
+        lines.push(`  ${color.dim("likely:")} ${color.magenta(causeLabel(top.cause.category))} ${color.dim(`(${pct(top.cause.confidence)} confident)`)}`);
+        lines.push(`  ${color.dim("→")} ${top.cause.hint}`);
+    }
+    if (top.sampleMessages.length > 0) {
+        lines.push(`  ${color.dim("sample failures:")}`);
+        for (const m of top.sampleMessages) {
+            lines.push(`    ${color.red("•")} ${color.dim(shorten(m, 100))}`);
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=terminal.js.map

package/dist/report/terminal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.js","sourceRoot":"","sources":["../../src/report/terminal.ts"],"names":[],"mappings":"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"}

package/dist/runner/runner.d.ts

@@ -0,0 +1,45 @@
+import type { Run } from "../types.js";
+declare const OUT_TOKEN = "{out}";
+export interface ProgressInfo {
+    index: number;
+    total: number;
+    passed: number;
+    failed: number;
+    crashed: boolean;
+    durationMs: number;
+}
+export interface RunnerOptions {
+    /** Command argv (everything after `--`). */
+    command: string[];
+    /** How many times to execute the command. */
+    runs: number;
+    /**
+     * Glob for the JUnit XML the command writes each run. Ignored when the
+     * command contains the `{out}` token.
+     */
+    reportGlob?: string;
+    /** Directory used for `{out}` per-run report files. */
+    outputDir: string;
+    /** Keep running remaining iterations even if one crashes. */
+    keepGoing: boolean;
+    cwd?: string;
+    onProgress?: (info: ProgressInfo) => void;
+    /**
+     * Called after each run with all runs so far. Return `true` to stop early
+     * (used by `--stop-on-first-flaky`).
+     */
+    afterRun?: (runs: Run[]) => boolean;
+}
+/** Execute the whole run loop and return the collected runs. */
+export declare function executeRuns(opts: RunnerOptions): Promise<Run[]>;
+/**
+ * Quote a single argument so a shell re-parses it as one token. We receive
+ * already-split argv (the user's shell split it), so we must re-quote args
+ * that contain spaces/metacharacters — otherwise `pytest -k "a or b"` breaks
+ * under cmd.exe on Windows.
+ */
+export declare function quoteArg(arg: string): string;
+/** Join argv into a single shell command line with proper quoting. */
+export declare function buildCommandLine(argv: string[]): string;
+export { OUT_TOKEN };
+//# sourceMappingURL=runner.d.ts.map

package/dist/runner/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/runner/runner.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,GAAG,EAAc,MAAM,aAAa,CAAC;AAGnD,QAAA,MAAM,SAAS,UAAU,CAAC;AAE1B,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,SAAS,EAAE,OAAO,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC;CACrC;AASD,gEAAgE;AAChE,wBAAsB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAyCrE;AAqCD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI5C;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAEvD;AAuCD,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/runner/runner.js

@@ -0,0 +1,125 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { parseJUnitXml } from "../junit/parser.js";
+import { glob } from "../util/glob.js";
+const OUT_TOKEN = "{out}";
+/** Execute the whole run loop and return the collected runs. */
+export async function executeRuns(opts) {
+    const usesToken = opts.command.some((a) => a.includes(OUT_TOKEN));
+    if (usesToken) {
+        fs.mkdirSync(opts.outputDir, { recursive: true });
+    }
+    const runs = [];
+    for (let i = 0; i < opts.runs; i++) {
+        const index = i + 1;
+        const outFile = path.join(opts.outputDir, `run-${index}.xml`);
+        // Prepare command for this iteration.
+        const argv = usesToken
+            ? opts.command.map((a) => a.split(OUT_TOKEN).join(outFile))
+            : opts.command;
+        // Clear stale report so we only read this run's output.
+        if (usesToken)
+            safeUnlink(outFile);
+        const exec = await runOnce(argv, opts.cwd);
+        const results = collectResults({ usesToken, outFile, reportGlob: opts.reportGlob, cwd: opts.cwd });
+        const passed = results.filter((r) => r.status === "passed").length;
+        const failed = results.filter((r) => r.status === "failed" || r.status === "error").length;
+        const noReport = results.length === 0;
+        const crashed = noReport && (exec.exitCode !== 0 || exec.signal !== null);
+        const note = buildNote(noReport, exec);
+        runs.push({ label: `run ${index}`, results, crashed, note });
+        opts.onProgress?.({ index, total: opts.runs, passed, failed, crashed, durationMs: exec.durationMs });
+        if (crashed && !opts.keepGoing) {
+            break;
+        }
+        if (opts.afterRun?.(runs)) {
+            break;
+        }
+    }
+    return runs;
+}
+function buildNote(noReport, exec) {
+    if (!noReport)
+        return undefined;
+    if (exec.exitCode !== 0 || exec.signal !== null) {
+        const reason = exec.signal ? `signal ${exec.signal}` : `exit code ${exec.exitCode}`;
+        const tail = exec.stderrTail ? ` — ${exec.stderrTail}` : "";
+        return `no JUnit report produced; command ended with ${reason}${tail}`;
+    }
+    return "command succeeded but produced no JUnit report (check --report path or the {out} token)";
+}
+function collectResults(args) {
+    const files = [];
+    if (args.usesToken) {
+        if (fs.existsSync(args.outFile))
+            files.push(args.outFile);
+    }
+    else if (args.reportGlob) {
+        files.push(...glob(args.reportGlob, args.cwd));
+    }
+    const results = [];
+    for (const file of files) {
+        try {
+            const xml = fs.readFileSync(file, "utf8");
+            results.push(...parseJUnitXml(xml, file));
+        }
+        catch {
+            // Unreadable file — skip; a crashed run will be flagged separately.
+        }
+    }
+    return results;
+}
+/**
+ * Quote a single argument so a shell re-parses it as one token. We receive
+ * already-split argv (the user's shell split it), so we must re-quote args
+ * that contain spaces/metacharacters — otherwise `pytest -k "a or b"` breaks
+ * under cmd.exe on Windows.
+ */
+export function quoteArg(arg) {
+    if (arg.length === 0)
+        return '""';
+    if (/^[A-Za-z0-9_@%+=:,./\\-]+$/.test(arg))
+        return arg;
+    return `"${arg.replace(/"/g, '\\"')}"`;
+}
+/** Join argv into a single shell command line with proper quoting. */
+export function buildCommandLine(argv) {
+    return argv.map(quoteArg).join(" ");
+}
+function runOnce(argv, cwd) {
+    const start = Date.now();
+    return new Promise((resolve) => {
+        const child = spawn(buildCommandLine(argv), {
+            cwd,
+            shell: true,
+            stdio: ["ignore", "ignore", "pipe"],
+        });
+        let stderr = "";
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString();
+            if (stderr.length > 4000)
+                stderr = stderr.slice(-4000);
+        });
+        child.on("error", () => {
+            resolve({ exitCode: 127, signal: null, stderrTail: lastLine(stderr) || "failed to spawn command", durationMs: Date.now() - start });
+        });
+        child.on("close", (code, signal) => {
+            resolve({ exitCode: code, signal, stderrTail: lastLine(stderr), durationMs: Date.now() - start });
+        });
+    });
+}
+function lastLine(text) {
+    const lines = text.split(/\r?\n/).map((l) => l.trim()).filter((l) => l.length > 0);
+    return lines.length > 0 ? lines[lines.length - 1] : "";
+}
+function safeUnlink(p) {
+    try {
+        fs.unlinkSync(p);
+    }
+    catch {
+        /* ignore */
+    }
+}
+export { OUT_TOKEN };
+//# sourceMappingURL=runner.js.map

package/dist/runner/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/runner/runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEvC,MAAM,SAAS,GAAG,OAAO,CAAC;AAyC1B,gEAAgE;AAChE,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAmB;IACnD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;IAClE,IAAI,SAAS,EAAE,CAAC;QACd,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,MAAM,IAAI,GAAU,EAAE,CAAC;IACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC;QACpB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,KAAK,MAAM,CAAC,CAAC;QAE9D,sCAAsC;QACtC,MAAM,IAAI,GAAG,SAAS;YACpB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC3D,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;QAEjB,wDAAwD;QACxD,IAAI,SAAS;YAAE,UAAU,CAAC,OAAO,CAAC,CAAC;QAEnC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3C,MAAM,OAAO,GAAG,cAAc,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAEnG,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,MAAM,CAAC;QACnE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,MAAM,CAAC;QAE3F,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC;QACtC,MAAM,OAAO,GAAG,QAAQ,IAAI,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC;QAC1E,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAEvC,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAE7D,IAAI,CAAC,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QAErG,IAAI,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YAC/B,MAAM;QACR,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,MAAM;QACR,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,SAAS,CAAC,QAAiB,EAAE,IAAgB;IACpD,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChC,IAAI,IAAI,CAAC,QAAQ,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,aAAa,IAAI,CAAC,QAAQ,EAAE,CAAC;QACpF,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,OAAO,gDAAgD,MAAM,GAAG,IAAI,EAAE,CAAC;IACzE,CAAC;IACD,OAAO,yFAAyF,CAAC;AACnG,CAAC;AAED,SAAS,cAAc,CAAC,IAKvB;IACC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACnB,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5D,CAAC;SAAM,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC1C,OAAO,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,oEAAoE;QACtE,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,4BAA4B,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IACvD,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC;AACzC,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,gBAAgB,CAAC,IAAc;IAC7C,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,OAAO,CAAC,IAAc,EAAE,GAAY;IAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,KAAK,GAAG,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE;YAC1C,GAAG;YACH,KAAK,EAAE,IAAI;YACX,KAAK,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC;SACpC,CAAC,CAAC;QAEH,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YACzC,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YAC3B,IAAI,MAAM,CAAC,MAAM,GAAG,IAAI;gBAAE,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;QACzD,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACrB,OAAO,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,yBAAyB,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;QACtI,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;YACjC,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;QACpG,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACnF,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC1D,CAAC;AAED,SAAS,UAAU,CAAC,CAAS;IAC3B,IAAI,CAAC;QACH,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,YAAY;IACd,CAAC;AACH,CAAC;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,87 @@
+/** Normalized outcome of a single test case within a single run. */
+export type TestStatus = "passed" | "failed" | "error" | "skipped";
+/** A single test case result parsed from one JUnit XML report. */
+export interface TestResult {
+    /** Stable identity across runs: `classname::name` (or just `name`). */
+    id: string;
+    name: string;
+    classname: string;
+    status: TestStatus;
+    /** Duration in milliseconds, if reported. */
+    durationMs: number | null;
+    /** Short failure/error message, if any. */
+    message: string | null;
+    /** Full failure/error body (stack trace / assertion detail), if any. */
+    details: string | null;
+}
+/**
+ * One "run" of a suite: the collection of test results produced by a single
+ * execution (or a single ingested report file/directory).
+ */
+export interface Run {
+    /** Human-friendly label, e.g. "run 3" or a file path. */
+    label: string;
+    results: TestResult[];
+    /**
+     * True when the run itself failed to produce parseable results
+     * (e.g. the test command crashed before writing a report).
+     */
+    crashed: boolean;
+    /** Optional note explaining a crash or anomaly. */
+    note?: string;
+}
+/** A single observed failure sample used for root-cause classification. */
+export interface FailureSample {
+    message: string | null;
+    details: string | null;
+}
+/** Root-cause category assigned by the heuristic classifier. */
+export type CauseCategory = "timing" | "concurrency" | "resource" | "external" | "order-dependency" | "randomness" | "unknown";
+export interface CauseGuess {
+    category: CauseCategory;
+    /** 0..1 rough confidence in the guess. */
+    confidence: number;
+    /** One-line human-readable hint about the likely cause and what to check. */
+    hint: string;
+}
+/** Aggregated verdict for a single test across all runs. */
+export interface TestVerdict {
+    id: string;
+    name: string;
+    classname: string;
+    runsSeen: number;
+    passes: number;
+    failures: number;
+    skips: number;
+    /** failures / (passes + failures); NaN-safe (0 when no non-skip runs). */
+    failureRate: number;
+    /** Number of pass<->fail transitions across the ordered runs (ignoring skips). */
+    flips: number;
+    /** True when the test both passed and failed at least once. */
+    flaky: boolean;
+    /** True when every non-skip run failed. */
+    alwaysFails: boolean;
+    /** Ranking score; higher = more worth investigating. */
+    score: number;
+    cause: CauseGuess | null;
+    /** Up to a few representative failure messages. */
+    sampleMessages: string[];
+}
+export interface SuiteSummary {
+    totalRuns: number;
+    crashedRuns: number;
+    uniqueTests: number;
+    flakyCount: number;
+    alwaysFailCount: number;
+    alwaysPassCount: number;
+    /** Fraction of runs with zero failures (a "green" run). */
+    greenRunRate: number;
+}
+export interface AnalysisReport {
+    summary: SuiteSummary;
+    /** Flaky tests, ranked by score (desc). */
+    flaky: TestVerdict[];
+    /** Consistently failing tests (not flaky, but broken). */
+    alwaysFailing: TestVerdict[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAEnE,kEAAkE;AAClE,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,2CAA2C;IAC3C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wEAAwE;IACxE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,GAAG;IAClB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,gEAAgE;AAChE,MAAM,MAAM,aAAa,GACrB,QAAQ,GACR,aAAa,GACb,UAAU,GACV,UAAU,GACV,kBAAkB,GAClB,YAAY,GACZ,SAAS,CAAC;AAEd,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,aAAa,CAAC;IACxB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,KAAK,EAAE,OAAO,CAAC;IACf,2CAA2C;IAC3C,WAAW,EAAE,OAAO,CAAC;IACrB,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,mDAAmD;IACnD,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,YAAY,CAAC;IACtB,2CAA2C;IAC3C,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,0DAA0D;IAC1D,aAAa,EAAE,WAAW,EAAE,CAAC;CAC9B"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/util/args.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tiny zero-dependency argument parser. Supports `--flag`, `--key value`,
+ * `--key=value`, short aliases, and a `--` separator whose remainder is
+ * returned verbatim (used to capture the user's test command).
+ */
+export interface ArgSpec {
+    /** Long names of boolean flags (no value). */
+    bools?: string[];
+    /** Long names of flags that take a value. */
+    values?: string[];
+    /** Map of short/alternate name -> canonical long name. */
+    aliases?: Record<string, string>;
+}
+export interface ParsedArgs {
+    bools: Set<string>;
+    values: Map<string, string>;
+    positionals: string[];
+    /** Tokens after a literal `--`, unparsed. */
+    rest: string[];
+    errors: string[];
+}
+export declare function parseArgs(argv: string[], spec: ArgSpec): ParsedArgs;
+//# sourceMappingURL=args.d.ts.map

package/dist/util/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/util/args.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,OAAO;IACtB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,UAAU,CAwEnE"}

package/dist/util/args.js

@@ -0,0 +1,83 @@
+/**
+ * Tiny zero-dependency argument parser. Supports `--flag`, `--key value`,
+ * `--key=value`, short aliases, and a `--` separator whose remainder is
+ * returned verbatim (used to capture the user's test command).
+ */
+export function parseArgs(argv, spec) {
+    const bools = new Set();
+    const values = new Map();
+    const positionals = [];
+    const errors = [];
+    let rest = [];
+    const boolSet = new Set(spec.bools ?? []);
+    const valueSet = new Set(spec.values ?? []);
+    const aliases = spec.aliases ?? {};
+    const canonical = (name) => aliases[name] ?? name;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--") {
+            rest = argv.slice(i + 1);
+            break;
+        }
+        if (token.startsWith("--")) {
+            const eq = token.indexOf("=");
+            const rawName = eq === -1 ? token.slice(2) : token.slice(2, eq);
+            const name = canonical(rawName);
+            if (boolSet.has(name)) {
+                bools.add(name);
+            }
+            else if (valueSet.has(name)) {
+                if (eq !== -1) {
+                    values.set(name, token.slice(eq + 1));
+                }
+                else if (i + 1 < argv.length) {
+                    values.set(name, argv[++i]);
+                }
+                else {
+                    errors.push(`missing value for --${rawName}`);
+                }
+            }
+            else {
+                errors.push(`unknown option --${rawName}`);
+            }
+            continue;
+        }
+        if (token.startsWith("-") && token.length > 1 && !isNegativeNumber(token)) {
+            const eq = token.indexOf("=");
+            const rawName = eq === -1 ? token.slice(1, 2) : token.slice(1, eq);
+            const name = canonical(rawName);
+            // Allow `-n5` compact form for value flags.
+            const inlineValue = eq === -1 ? token.slice(2) : token.slice(eq + 1);
+            if (boolSet.has(name)) {
+                bools.add(name);
+                // Support stacked bool shorts like -ab
+                for (const ch of token.slice(2)) {
+                    const n = canonical(ch);
+                    if (boolSet.has(n))
+                        bools.add(n);
+                }
+            }
+            else if (valueSet.has(name)) {
+                if (inlineValue) {
+                    values.set(name, inlineValue);
+                }
+                else if (i + 1 < argv.length) {
+                    values.set(name, argv[++i]);
+                }
+                else {
+                    errors.push(`missing value for -${rawName}`);
+                }
+            }
+            else {
+                errors.push(`unknown option -${rawName}`);
+            }
+            continue;
+        }
+        positionals.push(token);
+    }
+    return { bools, values, positionals, rest, errors };
+}
+function isNegativeNumber(token) {
+    return /^-\d/.test(token);
+}
+//# sourceMappingURL=args.js.map

package/dist/util/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/util/args.ts"],"names":[],"mappings":"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"}

package/dist/util/glob.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Minimal, dependency-free glob supporting `**`, `*`, and `?`. Needed because
+ * shells (especially on Windows) don't expand globs for us, and both `analyze`
+ * and `run` accept glob patterns for JUnit report locations.
+ *
+ * Returns absolute file paths, sorted and de-duplicated.
+ */
+export declare function glob(pattern: string, cwd?: string): string[];
+/** Expand many patterns and merge results (de-duplicated). */
+export declare function globMany(patterns: string[], cwd?: string): string[];
+//# sourceMappingURL=glob.d.ts.map

package/dist/util/glob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/util/glob.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,SAAgB,GAAG,MAAM,EAAE,CAwBnE;AAED,8DAA8D;AAC9D,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,SAAgB,GAAG,MAAM,EAAE,CAM1E"}

package/dist/util/glob.js

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Minimal, dependency-free glob supporting `**`, `*`, and `?`. Needed because
+ * shells (especially on Windows) don't expand globs for us, and both `analyze`
+ * and `run` accept glob patterns for JUnit report locations.
+ *
+ * Returns absolute file paths, sorted and de-duplicated.
+ */
+export function glob(pattern, cwd = process.cwd()) {
+    const norm = pattern.replace(/\\/g, "/");
+    const parts = norm.split("/");
+    const baseParts = [];
+    let i = 0;
+    for (; i < parts.length; i++) {
+        if (hasMagic(parts[i]))
+            break;
+        baseParts.push(parts[i]);
+    }
+    const globParts = parts.slice(i).filter((s) => s.length > 0);
+    if (globParts.length === 0) {
+        const resolved = path.resolve(cwd, norm);
+        return isFile(resolved) ? [resolved] : [];
+    }
+    const isAbsolute = norm.startsWith("/") || /^[A-Za-z]:\//.test(norm);
+    const baseJoined = baseParts.join("/");
+    const baseDir = isAbsolute ? baseJoined || "/" : path.resolve(cwd, baseJoined || ".");
+    const out = new Set();
+    walk(baseDir, globParts, out);
+    return [...out].sort();
+}
+/** Expand many patterns and merge results (de-duplicated). */
+export function globMany(patterns, cwd = process.cwd()) {
+    const set = new Set();
+    for (const pat of patterns) {
+        for (const file of glob(pat, cwd))
+            set.add(file);
+    }
+    return [...set].sort();
+}
+function hasMagic(segment) {
+    return /[*?[]/.test(segment);
+}
+function segmentToRegex(seg) {
+    let re = "^";
+    for (const ch of seg) {
+        if (ch === "*")
+            re += "[^/]*";
+        else if (ch === "?")
+            re += "[^/]";
+        else
+            re += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    re += "$";
+    return new RegExp(re);
+}
+function walk(dir, segs, out) {
+    if (segs.length === 0) {
+        if (isFile(dir))
+            out.add(dir);
+        return;
+    }
+    const [seg, ...rest] = segs;
+    if (seg === "**") {
+        // `**` matches zero path segments...
+        walk(dir, rest, out);
+        // ...or one-or-more: recurse into each subdirectory, keeping `**`.
+        for (const entry of readDir(dir)) {
+            if (entry.isDirectory())
+                walk(path.join(dir, entry.name), segs, out);
+        }
+        return;
+    }
+    const re = segmentToRegex(seg);
+    for (const entry of readDir(dir)) {
+        if (!re.test(entry.name))
+            continue;
+        const full = path.join(dir, entry.name);
+        if (rest.length === 0) {
+            if (entry.isFile())
+                out.add(full);
+        }
+        else if (entry.isDirectory()) {
+            walk(full, rest, out);
+        }
+    }
+}
+function readDir(dir) {
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+function isFile(p) {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=glob.js.map