unflake 0.6.1__tar.gz

unflake-0.6.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unflake Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

unflake-0.6.1/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: unflake
+Version: 0.6.1
+Summary: Green CI without the rerun ritual — detect, score, and quarantine flaky tests
+License: MIT
+Project-URL: Homepage, https://github.com/YOUR-USER/unflake
+Project-URL: Issues, https://github.com/YOUR-USER/unflake/issues
+Keywords: testing,flaky-tests,ci,qa,agent-skills
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Unflake 🟢
+
+[![CI](https://github.com/YOUR-USER/unflake/actions/workflows/ci.yml/badge.svg)](https://github.com/YOUR-USER/unflake/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/YOUR-USER/unflake/badge)](https://scorecard.dev/viewer/?uri=github.com/YOUR-USER/unflake)
+[![PyPI](https://img.shields.io/pypi/v/unflake.svg)](https://pypi.org/project/unflake/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Green CI without the "just rerun it" ritual.**
+
+![Unflake 60-second demo](assets/terminal-demo.svg)
+
+CI is red. You rerun. It's green. You merge, trusting nothing. Unflake hunts the flake instead: static scan in milliseconds, FlakeScore across repeated runs, regression-vs-flake verdicts, and quarantine configs that keep the build green *without deleting a single test*.
+
+![scan → run → calm](assets/pipeline.svg)
+
+```bash
+pip install unflake
+unflake scan tests/                                  # 1. smells, instantly
+unflake run --runs 3 --runner pytest -- pytest tests/ -q   # 2. collect + score
+unflake quarantine run1.xml run2.xml --framework pytest    # 3. quarantine, don't delete
+unflake init --framework pytest --write              # 4. seeded RNG scaffold (prevention)
+```
+
+JS-first repo? Same tool, no Python packaging — just Python itself (3.9+):
+
+```bash
+npx unflake-ci scan tests/
+npx unflake-ci run --runs 3 --runner vitest -- npx vitest run tests/
+```
+
+Proven on real suites: 3,676 tests × 5 runs across attrs/click/tqdm → FlakeScore 100,
+0 false quarantines ([study](benchmarks/BENCH.md)).
+
+No install handy? `bash demo.sh` runs the whole loop on fixtures in 60 seconds.
+
+> ⭐ If flaky tests have ever paged you, star this — it helps other devs find it.
+
+## Before / after
+
+```python
+# before: the 3am pager
+def test_checkout():
+    time.sleep(5)                       # pray the server is up
+    assert requests.get(API).ok         # real network in a unit test
+```
+
+```bash
+$ unflake scan tests/
+  WARNING [FLK001] tests/test_shop.py:4 — time.sleep() in tests makes timing-dependent flakes
+           fix: Replace with polling (wait_for / waitFor / eventually) with a timeout, or freeze time.
+  WARNING [FLK004] tests/test_shop.py:5 — Real network calls in tests fail without mocks ...
+```
+
+```bash
+$ unflake run --runs 3 -- pytest tests/ -q
+FlakeScore: 50.0/100 (2 flaky of 4 tests)
+  FLAKY test_cart::test_checkout (2P/1F over 3 runs)
+  FLAKY test_cart::test_discount (2P/1F over 3 runs)
+```
+
+```bash
+$ unflake quarantine run1.xml run2.xml --framework pytest
+pytest -k "not test_checkout and not test_discount"   # gating run stays green
+pytest -k "test_checkout or test_discount"            # nightly run still reports
+```
+
+Quarantine preserves signal; deletion hides it. Every quarantined test still runs — it just can't fail the build. **Regressions are never quarantined**: green-then-red-forever is a real failure — fix it.
+
+## Flaky or regression? Unflake knows the difference
+
+Pass result files oldest → newest and Unflake separates three fates:
+
+| Verdict | Meaning | Action |
+|---|---|---|
+| `FLAKY` | mixed outcomes, no clean break | quarantine + fix root cause |
+| `REGRESSION` | green until run N, red ever since | fix now — never quarantine |
+| `NEW` / stable | seen once / always green / always red | more runs / ship it / real bug |
+
+Two runs can only suggest a flake; calling a regression needs ≥3. One run proves nothing — `unflake run` exists so there's no excuse.
+
+## Why not the others?
+
+| | Unflake | Heavy flake platforms |
+|---|---|---|
+| Install | zero-dep, stdlib only, `pip install unflake` | OTel collectors, dashboards, SaaS |
+| Input | JUnit XML from **any** framework (pytest ✅, Vitest ✅, Playwright ✅, Jest ✅ e2e — plus generic `--junit-flag`, Go, JUnit…) | per-framework reporters/plugins |
+| First value | `scan` in milliseconds, no execution | needs history ingestion |
+| Verdicts | flaky vs regression vs new, change-point included | usually just a score |
+| Philosophy | quarantine, never delete | often auto-skip-and-forget |
+| Agent-native | `SKILL.md` + harness adapters day one | docs page, if you're lucky |
+
+## Works with your harness
+
+Claude Code · Codex · Copilot · Cursor · Gemini · Pi · OpenCode · Windsurf · Cline · Qoder — plus a GitHub Action (`action.yml`, SARIF → code scanning) and a pre-commit hook. Details: [`docs/ADAPTERS.md`](docs/ADAPTERS.md). The skill lives at [`skills/unflake/SKILL.md`](skills/unflake/SKILL.md).
+
+10 rules today, incl. the JS classics: `cy.wait(ms)` (FLK009) and `waitForTimeout` (FLK010).
+Precision features: localhost-aware severities, string-literal awareness (Python),
+`--exclude` globs, and SARIF rule metadata for code scanning.
+
+## Benchmarks (honest, reproducible)
+
+Fixtures + real pytest e2e + a real-repo scan (`psf/requests`: 120 findings in ~0.1s — with the noise documented, not hidden). Method, numbers, and known limitations: [`benchmarks/BENCH.md`](benchmarks/BENCH.md). If a number doesn't reproduce, that's a bug — file it.
+
+## Contributing — built for drive-by PRs
+
+- 🧪 New FLK rule = one regex + one test (`good first issue`)
+- 🔌 New harness adapter or quarantine emitter = one file + one test
+- 🌱 `unflake init` for your framework = one snippet
+- 🌍 Translations welcome (`README.<lang>.md`)
+- Full loop: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+
+## Roadmap
+
+- [x] v0.1 — scan / analyze / quarantine, SARIF, 4 frameworks, skill + adapters
+- [x] v0.2 — `run` collector, regression-vs-flake verdicts, `init` scaffolder, FLK009/FLK010, pre-commit + GitHub Action, `pip install unflake`
+- [x] v0.3 — `--runner` presets, per-run logs, real-pytest e2e in CI, launch kit (`demo.sh`, templates, `LAUNCH.md`), real-repo validation
+- [x] v0.4 — precision (localhost-aware FLK004, literal-awareness), `--exclude`, SARIF rules, safe `-k` quoting, CI matrix 3.10–3.14
+- [x] v0.5 — `unflake-ci` npx wrapper (verified pack→install→run), `--runner vitest` verified e2e
+- [x] v0.6 — `--runner` playwright + jest verified e2e, real-repo study (3,676 tests, 0 false quarantines)
+- [ ] Recall study v2 on suites with known flakes (specificity proven; recall needs wild flakes)
+- [ ] JS/TS string-literal awareness + variable-host local-server detection (see BENCH.md)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

unflake-0.6.1/README.md

@@ -0,0 +1,125 @@
+# Unflake 🟢
+
+[![CI](https://github.com/YOUR-USER/unflake/actions/workflows/ci.yml/badge.svg)](https://github.com/YOUR-USER/unflake/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/YOUR-USER/unflake/badge)](https://scorecard.dev/viewer/?uri=github.com/YOUR-USER/unflake)
+[![PyPI](https://img.shields.io/pypi/v/unflake.svg)](https://pypi.org/project/unflake/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Green CI without the "just rerun it" ritual.**
+
+![Unflake 60-second demo](assets/terminal-demo.svg)
+
+CI is red. You rerun. It's green. You merge, trusting nothing. Unflake hunts the flake instead: static scan in milliseconds, FlakeScore across repeated runs, regression-vs-flake verdicts, and quarantine configs that keep the build green *without deleting a single test*.
+
+![scan → run → calm](assets/pipeline.svg)
+
+```bash
+pip install unflake
+unflake scan tests/                                  # 1. smells, instantly
+unflake run --runs 3 --runner pytest -- pytest tests/ -q   # 2. collect + score
+unflake quarantine run1.xml run2.xml --framework pytest    # 3. quarantine, don't delete
+unflake init --framework pytest --write              # 4. seeded RNG scaffold (prevention)
+```
+
+JS-first repo? Same tool, no Python packaging — just Python itself (3.9+):
+
+```bash
+npx unflake-ci scan tests/
+npx unflake-ci run --runs 3 --runner vitest -- npx vitest run tests/
+```
+
+Proven on real suites: 3,676 tests × 5 runs across attrs/click/tqdm → FlakeScore 100,
+0 false quarantines ([study](benchmarks/BENCH.md)).
+
+No install handy? `bash demo.sh` runs the whole loop on fixtures in 60 seconds.
+
+> ⭐ If flaky tests have ever paged you, star this — it helps other devs find it.
+
+## Before / after
+
+```python
+# before: the 3am pager
+def test_checkout():
+    time.sleep(5)                       # pray the server is up
+    assert requests.get(API).ok         # real network in a unit test
+```
+
+```bash
+$ unflake scan tests/
+  WARNING [FLK001] tests/test_shop.py:4 — time.sleep() in tests makes timing-dependent flakes
+           fix: Replace with polling (wait_for / waitFor / eventually) with a timeout, or freeze time.
+  WARNING [FLK004] tests/test_shop.py:5 — Real network calls in tests fail without mocks ...
+```
+
+```bash
+$ unflake run --runs 3 -- pytest tests/ -q
+FlakeScore: 50.0/100 (2 flaky of 4 tests)
+  FLAKY test_cart::test_checkout (2P/1F over 3 runs)
+  FLAKY test_cart::test_discount (2P/1F over 3 runs)
+```
+
+```bash
+$ unflake quarantine run1.xml run2.xml --framework pytest
+pytest -k "not test_checkout and not test_discount"   # gating run stays green
+pytest -k "test_checkout or test_discount"            # nightly run still reports
+```
+
+Quarantine preserves signal; deletion hides it. Every quarantined test still runs — it just can't fail the build. **Regressions are never quarantined**: green-then-red-forever is a real failure — fix it.
+
+## Flaky or regression? Unflake knows the difference
+
+Pass result files oldest → newest and Unflake separates three fates:
+
+| Verdict | Meaning | Action |
+|---|---|---|
+| `FLAKY` | mixed outcomes, no clean break | quarantine + fix root cause |
+| `REGRESSION` | green until run N, red ever since | fix now — never quarantine |
+| `NEW` / stable | seen once / always green / always red | more runs / ship it / real bug |
+
+Two runs can only suggest a flake; calling a regression needs ≥3. One run proves nothing — `unflake run` exists so there's no excuse.
+
+## Why not the others?
+
+| | Unflake | Heavy flake platforms |
+|---|---|---|
+| Install | zero-dep, stdlib only, `pip install unflake` | OTel collectors, dashboards, SaaS |
+| Input | JUnit XML from **any** framework (pytest ✅, Vitest ✅, Playwright ✅, Jest ✅ e2e — plus generic `--junit-flag`, Go, JUnit…) | per-framework reporters/plugins |
+| First value | `scan` in milliseconds, no execution | needs history ingestion |
+| Verdicts | flaky vs regression vs new, change-point included | usually just a score |
+| Philosophy | quarantine, never delete | often auto-skip-and-forget |
+| Agent-native | `SKILL.md` + harness adapters day one | docs page, if you're lucky |
+
+## Works with your harness
+
+Claude Code · Codex · Copilot · Cursor · Gemini · Pi · OpenCode · Windsurf · Cline · Qoder — plus a GitHub Action (`action.yml`, SARIF → code scanning) and a pre-commit hook. Details: [`docs/ADAPTERS.md`](docs/ADAPTERS.md). The skill lives at [`skills/unflake/SKILL.md`](skills/unflake/SKILL.md).
+
+10 rules today, incl. the JS classics: `cy.wait(ms)` (FLK009) and `waitForTimeout` (FLK010).
+Precision features: localhost-aware severities, string-literal awareness (Python),
+`--exclude` globs, and SARIF rule metadata for code scanning.
+
+## Benchmarks (honest, reproducible)
+
+Fixtures + real pytest e2e + a real-repo scan (`psf/requests`: 120 findings in ~0.1s — with the noise documented, not hidden). Method, numbers, and known limitations: [`benchmarks/BENCH.md`](benchmarks/BENCH.md). If a number doesn't reproduce, that's a bug — file it.
+
+## Contributing — built for drive-by PRs
+
+- 🧪 New FLK rule = one regex + one test (`good first issue`)
+- 🔌 New harness adapter or quarantine emitter = one file + one test
+- 🌱 `unflake init` for your framework = one snippet
+- 🌍 Translations welcome (`README.<lang>.md`)
+- Full loop: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+
+## Roadmap
+
+- [x] v0.1 — scan / analyze / quarantine, SARIF, 4 frameworks, skill + adapters
+- [x] v0.2 — `run` collector, regression-vs-flake verdicts, `init` scaffolder, FLK009/FLK010, pre-commit + GitHub Action, `pip install unflake`
+- [x] v0.3 — `--runner` presets, per-run logs, real-pytest e2e in CI, launch kit (`demo.sh`, templates, `LAUNCH.md`), real-repo validation
+- [x] v0.4 — precision (localhost-aware FLK004, literal-awareness), `--exclude`, SARIF rules, safe `-k` quoting, CI matrix 3.10–3.14
+- [x] v0.5 — `unflake-ci` npx wrapper (verified pack→install→run), `--runner vitest` verified e2e
+- [x] v0.6 — `--runner` playwright + jest verified e2e, real-repo study (3,676 tests, 0 false quarantines)
+- [ ] Recall study v2 on suites with known flakes (specificity proven; recall needs wild flakes)
+- [ ] JS/TS string-literal awareness + variable-host local-server detection (see BENCH.md)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

unflake-0.6.1/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "unflake"
+version = "0.6.1"
+description = "Green CI without the rerun ritual — detect, score, and quarantine flaky tests"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["testing", "flaky-tests", "ci", "qa", "agent-skills"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Testing",
+]
+
+[project.scripts]
+unflake = "unflake.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/YOUR-USER/unflake"
+Issues = "https://github.com/YOUR-USER/unflake/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

unflake-0.6.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

unflake-0.6.1/src/unflake/__init__.py

@@ -0,0 +1,3 @@
+"""Unflake: detect, score, and quarantine flaky tests. Stdlib only."""
+
+__version__ = "0.6.1"

unflake-0.6.1/src/unflake/__main__.py

@@ -0,0 +1,14 @@
+"""Entry point. Works as `python -m unflake` AND as `python path/to/__main__.py`
+(the latter is how the npx wrapper invokes the vendored core)."""
+
+try:
+    from .cli import main
+except ImportError:  # pragma: no cover - path-invoked fallback
+    import os
+    import sys
+
+    sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    from unflake.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

unflake-0.6.1/src/unflake/cli.py

@@ -0,0 +1,214 @@
+"""`unflake` CLI. Stdlib only. Exit codes: 0 clean, 1 findings, 2 usage."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .ingest import load_runs
+from .patterns import SEVERITIES, Finding, scan_path
+from .quarantine import FRAMEWORKS, emit
+from .report import (
+    format_analyze_text,
+    format_sarif,
+    format_scan_json,
+    format_scan_text,
+)
+from .runner import collect
+from .scaffold import FRAMEWORKS as SCAFFOLD_FRAMEWORKS
+from .scaffold import init_framework
+from .score import score_runs
+
+ORDER = {"error": 0, "warning": 1, "info": 2}
+
+
+def _meets_threshold(f: Finding, fail_on: str) -> bool:
+    return ORDER[f.severity] <= ORDER[fail_on]
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    findings: list[Finding] = []
+    for target in args.targets:
+        try:
+            findings.extend(scan_path(target, exclude=args.exclude))
+        except ValueError as exc:
+            print(f"unflake: error: {exc}", file=sys.stderr)
+            return 2
+    if args.format == "json":
+        print(format_scan_json(findings))
+    elif args.format == "sarif":
+        print(format_sarif(findings))
+    else:
+        print(format_scan_text(findings))
+    bad = [f for f in findings if _meets_threshold(f, args.fail_on)]
+    return 1 if bad else 0
+
+
+def _print_suite(suite, fmt: str) -> None:
+    if fmt == "json":
+        print(json.dumps(suite.to_dict(), indent=2))
+    elif fmt == "sarif":
+        print(format_sarif([], suite))
+    else:
+        print(format_analyze_text(suite))
+
+
+def _analyze_gate(suite, fail_on: str) -> int:
+    if fail_on == "never":
+        return 0
+    if fail_on == "flaky":
+        return 1 if (suite.flaky_count or suite.regression_count) else 0
+    return 0
+
+
+def _quarantine_note(suite, framework: str | None) -> None:
+    if not framework:
+        return
+    flaky_ids = [t.id for t in suite.tests if t.verdict == "flaky"]
+    if not flaky_ids:
+        return
+    print()
+    print(emit(framework, flaky_ids))
+
+
+def cmd_analyze(args: argparse.Namespace) -> int:
+    try:
+        runs = load_runs(args.results)
+    except ValueError as exc:
+        print(f"unflake: error: {exc}", file=sys.stderr)
+        return 2
+    if len(runs) < 2:
+        print("unflake: warning: only 1 run given — flakiness needs >= 2 runs "
+              "of the same suite to compare.", file=sys.stderr)
+    suite = score_runs(runs)
+    _print_suite(suite, args.format)
+    return _analyze_gate(suite, args.fail_on)
+
+
+def cmd_quarantine(args: argparse.Namespace) -> int:
+    try:
+        runs = load_runs(args.results)
+    except ValueError as exc:
+        print(f"unflake: error: {exc}", file=sys.stderr)
+        return 2
+    suite = score_runs(runs)
+    regressions = [t.id for t in suite.tests if t.verdict == "regression"]
+    if regressions:
+        print("# unflake quarantine: NOT quarantining regressions "
+              "(real failures — fix them):", file=sys.stderr)
+        for rid in regressions:
+            print(f"#  - {rid}", file=sys.stderr)
+    flaky_ids = [t.id for t in suite.tests if t.verdict == "flaky"]
+    if not flaky_ids:
+        print("# unflake quarantine: no flaky tests — nothing to quarantine.")
+        return 0
+    try:
+        print(emit(args.framework, flaky_ids))
+    except ValueError as exc:
+        print(f"unflake: error: {exc}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    if args.runs < 2:
+        print("unflake: error: --runs must be >= 2 (one run proves nothing)",
+              file=sys.stderr)
+        return 2
+    cmd = list(args.test_command or [])
+    if cmd[:1] == ["--"]:
+        cmd = cmd[1:]  # argparse.REMAINDER keeps the separator
+    if not cmd:
+        print("unflake: error: no test command given after `--`", file=sys.stderr)
+        return 2
+    try:
+        files = collect(
+            cmd, runs=args.runs, out_dir=args.out_dir,
+            junit_flag=args.junit_flag, runner=args.runner, timeout=args.timeout,
+            progress=lambda m: print(f"unflake: {m}", file=sys.stderr),
+        )
+    except ValueError as exc:
+        print(f"unflake: error: {exc}", file=sys.stderr)
+        return 2
+    print(f"unflake: collected {len(files)} run(s) in {args.out_dir}", file=sys.stderr)
+    suite = score_runs(load_runs(files))
+    _print_suite(suite, args.format)
+    _quarantine_note(suite, args.quarantine)
+    return _analyze_gate(suite, args.fail_on)
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    try:
+        print(init_framework(args.framework, root=args.root, write=args.write))
+    except ValueError as exc:
+        print(f"unflake: error: {exc}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="unflake",
+        description="Green CI without the rerun ritual — detect, score, quarantine flaky tests.",
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("scan", help="Static scan for flake anti-patterns (no test execution).")
+    s.add_argument("targets", nargs="+", help="File(s) or directorie(s) to scan.")
+    s.add_argument("--exclude", action="append", default=[],
+                   help="Extra path-part glob to skip (repeatable; "
+                        "defaults already skip .git, node_modules, venvs, build dirs).")
+    s.add_argument("--format", choices=["text", "json", "sarif"], default="text")
+    s.add_argument("--fail-on", choices=list(SEVERITIES), default="warning",
+                   help="Exit 1 if any finding at/above this severity (default: warning).")
+    s.set_defaults(func=cmd_scan)
+
+    a = sub.add_parser("analyze", help="Score flakiness across >=2 result files (JUnit XML or JSON).")
+    a.add_argument("results", nargs="+", help="Result files from repeated runs, oldest first.")
+    a.add_argument("--format", choices=["text", "json", "sarif"], default="text")
+    a.add_argument("--fail-on", choices=["flaky", "never"], default="never",
+                   help="'flaky' exits 1 on flaky tests OR regressions.")
+    a.set_defaults(func=cmd_analyze)
+
+    q = sub.add_parser("quarantine", help="Emit quarantine config for flaky tests (never deletes).")
+    q.add_argument("results", nargs="+", help="Result files from repeated runs, oldest first.")
+    q.add_argument("--framework", choices=list(FRAMEWORKS), required=True)
+    q.set_defaults(func=cmd_quarantine)
+
+    r = sub.add_parser("run", help="Run your test command N times, then score (collects JUnit when possible).")
+    r.add_argument("--runs", type=int, default=3, help="Repeat count, >= 2 (default: 3).")
+    r.add_argument("--out-dir", default=".unflake/runs", help="Where per-run files land.")
+    r.add_argument("--junit-flag", default=None,
+                   help="Flag your runner uses for JUnit output, e.g. '--junitxml=' "
+                        "(auto-detected for pytest; omit for exit-code-only mode).")
+    r.add_argument("--runner", default=None,
+                   help="Verified runner preset (pytest, vitest, playwright, jest). "
+                        "Others: use --junit-flag.")
+    r.add_argument("--timeout", type=float, default=None, help="Per-run timeout in seconds.")
+    r.add_argument("--format", choices=["text", "json", "sarif"], default="text")
+    r.add_argument("--fail-on", choices=["flaky", "never"], default="flaky")
+    r.add_argument("--quarantine", choices=list(FRAMEWORKS), default=None,
+                   help="Also emit a quarantine snippet for this framework.")
+    r.add_argument("test_command", nargs=argparse.REMAINDER,
+                   help="Test command after `--`, e.g. `-- pytest tests/ -q`.")
+    r.set_defaults(func=cmd_run)
+
+    i = sub.add_parser("init", help="Scaffold seeded-RNG / frozen-time helpers for a framework.")
+    i.add_argument("--framework", choices=list(SCAFFOLD_FRAMEWORKS), required=True)
+    i.add_argument("--root", default=".", help="Project root to write into.")
+    i.add_argument("--write", action="store_true",
+                   help="Write files (idempotent). Without it, print to stdout.")
+    i.set_defaults(func=cmd_init)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

unflake-0.6.1/src/unflake/ingest.py

@@ -0,0 +1,95 @@
+"""Ingest test results from JUnit XML and generic JSON result files.
+
+Universal input: anything that can emit JUnit XML works
+(pytest --junitxml, jest-junit, vitest --reporter=junit, Playwright,
+JUnit/Gradle, go-junit-report, ...). No framework SDK required.
+"""
+
+from __future__ import annotations
+
+import json
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+PASS = "passed"
+FAIL = "failed"
+SKIP = "skipped"
+
+
+def _test_id(classname: str, name: str, filepath: str = "") -> str:
+    if classname:
+        return f"{classname}::{name}"
+    if filepath:
+        return f"{filepath}::{name}"
+    return name
+
+
+def parse_junit_xml(path: str | Path) -> dict[str, str]:
+    """Parse one JUnit XML file -> {test_id: status}."""
+    path = Path(path)
+    try:
+        tree = ET.parse(path)
+    except ET.ParseError as exc:
+        raise ValueError(f"{path}: not valid XML ({exc})") from exc
+    root = tree.getroot()
+    results: dict[str, str] = {}
+    suites = [root] if root.tag == "testsuite" else root.findall("testsuite")
+    if not suites and root.tag != "testsuite":
+        raise ValueError(f"{path}: no <testsuite> found, is this JUnit XML?")
+    for suite in suites:
+        for case in suite.iter("testcase"):
+            name = case.get("name", "unknown")
+            classname = case.get("classname", "") or ""
+            filepath = case.get("file", "") or ""
+            tid = _test_id(classname, name, filepath)
+            if case.find("failure") is not None or case.find("error") is not None:
+                status = FAIL
+            elif case.find("skipped") is not None:
+                status = SKIP
+            else:
+                status = PASS
+            results[tid] = status
+    return results
+
+
+def parse_generic_json(path: str | Path) -> dict[str, str]:
+    """Parse {"tests": [{"id": ..., "status": "passed|failed|skipped"}]}."""
+    path = Path(path)
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{path}: not valid JSON ({exc})") from exc
+    items = data.get("tests", data if isinstance(data, list) else [])
+    results: dict[str, str] = {}
+    for item in items:
+        tid = str(item.get("id", item.get("name", "unknown")))
+        status = str(item.get("status", item.get("outcome", PASS))).lower()
+        if status in {"failure", "fail", "failed", "error"}:
+            status = FAIL
+        elif status in {"skip", "skipped", "xskip"}:
+            status = SKIP
+        else:
+            status = PASS
+        results[tid] = status
+    return results
+
+
+def parse_file(path: str | Path) -> dict[str, str]:
+    """Auto-detect format by extension/content -> {test_id: status}."""
+    path = Path(path)
+    if not path.exists():
+        raise ValueError(f"{path}: file not found")
+    if path.suffix.lower() == ".json":
+        return parse_generic_json(path)
+    head = path.read_bytes()[:2000].lstrip()
+    if head.startswith(b"{") or head.startswith(b"["):
+        return parse_generic_json(path)
+    return parse_junit_xml(path)
+
+
+def load_runs(paths: list[str | Path]) -> list[dict[str, str]]:
+    """Load N result files (e.g. N repeated runs of the same suite)."""
+    runs = []
+    for p in paths:
+        runs.append(parse_file(p))
+    return runs