flakehound 0.1.0__tar.gz

flakehound-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Private working context (never pushed)
+PROJECT_CONTEXT.md
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tool caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# flakehound run artifacts
+.flakehound/runs/
+
+# Secrets / local env (never commit)
+.env
+.env.*
+
+# OS / editors
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# Demo output
+demo/report.json
+
+# flakehound output files
+demo/report.md

flakehound-0.1.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to flakehound are listed here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
+project uses [Semantic Versioning](https://semver.org/) (pre-1.0: minor versions may break things).
+
+## [0.1.0] - 2026-11-10
+
+First release. Python + pytest.
+
+### Detection
+- `flakehound run`: runs the suite many times in parallel with shuffled order and varied
+  `random` seed and `PYTHONHASHSEED`; failure rates with 95% confidence intervals.
+- Tests that fail every run are rechecked alone before being called broken.
+- Probe runs find **time bombs** (UTC+14, UTC−12, just before midnight, last day of the
+  month, New Year's Eve, Feb 29) and **racy tests** (main-thread sleeps 20× shorter;
+  thread-switch stress).
+
+### Diagnosis (every verdict backed by real runs)
+- Order dependency: isolation with the failing runs' exact seeds, polluter or
+  state-setter search (correlation fast path + parallel delta debugging), and the
+  **leaked state** named (module globals, object/class attributes, env vars, cwd,
+  `sys.path`, project files, logging).
+- Randomness vs set/dict ordering (hash seed), told apart by swapping one seed at a time.
+- Timezone and date/clock time bombs.
+- Sleep used as a wait, pinned to the exact `sleep()` line; race conditions.
+- Rule-based fix suggestions; repro commands that are run for real and marked *verified*.
+
+### Output and CI
+- Terminal report, JSON report (schema v3), Markdown report (`--markdown`), and the
+  GitHub Actions job summary.
+- `--fail-on` to choose what fails a build.
+- Quarantine: `.flakehound/quarantine.toml` + pytest plugin (non-strict xfail or skip)
+  + `flakehound quarantine list|add|remove` with diff and confirmation.
+- Works with projects that use pytest-xdist (`-n auto` in addopts).
+
+### Security and cost
+- Fully offline, no telemetry, secrets redacted from every report.
+- No shell commands; every child process tree is cleaned up on timeout or Ctrl+C.
+- Runtime dependencies: pytest, rich, and tomli on Python 3.10 only.
+
+### Known limitations
+- `asyncio.sleep` is not shortened by the timing probes.
+- State hidden in fixtures, databases or external services is not visible to the leak
+  detector (the report says so instead of guessing).
+- Thread stress needs the race to happen around a Python function call.
+
+[0.1.0]: https://github.com/urumb/flakehound/releases/tag/v0.1.0

flakehound-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Noel Jacob Antony
+
+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.

flakehound-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.5
+Name: flakehound
+Version: 0.1.0
+Summary: Find flaky tests and prove why they're flaky. Free, local, private.
+Project-URL: Homepage, https://github.com/urumb/flakehound
+Project-URL: Issues, https://github.com/urumb/flakehound/issues
+Project-URL: Security, https://github.com/urumb/flakehound/security/policy
+Project-URL: Changelog, https://github.com/urumb/flakehound/blob/main/CHANGELOG.md
+Author: Noel Jacob Antony
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ci,flaky,flaky-tests,pytest,test-order,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: pytest>=7.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli>=1.1; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# flakehound
+
+[![PyPI](https://img.shields.io/pypi/v/flakehound.svg)](https://pypi.org/project/flakehound/)
+[![Python](https://img.shields.io/pypi/pyversions/flakehound.svg)](https://pypi.org/project/flakehound/)
+[![CI](https://github.com/urumb/flakehound/actions/workflows/ci.yml/badge.svg)](https://github.com/urumb/flakehound/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/urumb/flakehound/actions/workflows/codeql.yml/badge.svg)](https://github.com/urumb/flakehound/actions/workflows/codeql.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/urumb/flakehound/blob/main/LICENSE)
+
+**Find flaky tests and prove *why* they're flaky.**
+
+Flaky tests pass sometimes and fail sometimes with no code change. Most tools just retry
+them, which hides the problem. flakehound runs your pytest suite under deliberately hostile
+conditions, finds the tests that flip, and tells you the cause, with evidence from real runs
+and a command that reproduces it. It also finds problems that haven't bitten you *yet*.
+
+![flakehound output on the demo project](https://raw.githubusercontent.com/urumb/flakehound/main/docs/demo.svg)
+
+- 🆓 **Free forever.** No accounts, no servers, no paid services.
+- 🔒 **Local and private.** Offline, no telemetry, secrets redacted from every report.
+- 🧪 **Evidence, not guesses.** Every verdict comes from runs that prove it, and every repro
+  command is run for real before it's marked *verified*.
+
+## What it finds
+
+| Problem | Example | What flakehound tells you |
+|---|---|---|
+| **Order dependency** | a test leaves an item in a shared cart | the polluter test and the leaked state: `shop.cart: [] → ['apple']` |
+| **Needs another test** | a test only passes after a setup-like test ran | the test it secretly depends on |
+| **Randomness** | `assert random.random() < 0.8` | the failing seed, and a repro that replays it |
+| **Set/dict ordering** | comparing `",".join(a_set)` to a string | that `PYTHONHASHSEED` is the cause |
+| **Time bombs** | breaks on the last day of the month, on Feb 29, in another timezone | the exact date/timezone, *before* it happens |
+| **Sleep used as a wait** | `sleep(0.06)` then assert a thread finished | the exact `sleep()` line that will fail on a slow CI machine |
+| **Race conditions** | unlocked read-modify-write from threads | that it fails when threads interleave |
+
+## Quickstart
+
+```bash
+pip install flakehound
+cd your-project
+flakehound run
+```
+
+That's it: no config. Try it on the included [demo project](https://github.com/urumb/flakehound/tree/main/demo) to see every kind of
+problem. The same results as a Markdown report: [docs/example-report.md](https://github.com/urumb/flakehound/blob/main/docs/example-report.md).
+
+> ⚠️ flakehound **runs your test suite** (many times). Only run it on code you trust.
+
+### Options
+
+| Option | Meaning |
+|---|---|
+| `-n, --runs N` | How many times to run the suite (default 10) |
+| `-j, --workers N` | Parallel runs (default: CPU cores − 1, max 8) |
+| `--seed N` | Replay an earlier session exactly |
+| `--json PATH` | Also write a machine-readable report |
+| `--markdown PATH` | Also write a Markdown report (for PR comments) |
+| `--fail-on KINDS` | What makes exit code 1: `flaky`, `time-bomb`, `racy`, `broken`, `suspected`, `none` (default `flaky,time-bomb,racy`) |
+| `--no-diagnose` | Only detect flaky tests, don't explain them |
+| `--max-diagnose N` | Diagnose at most N flaky tests (default 20) |
+| `--no-probes` | Skip all probe runs (timezones, risky dates, timing) |
+| `--no-timing` | Skip only the timing probes |
+| `--no-step-summary` | Don't add the report to the GitHub Actions job summary |
+| `--timeout S` | Kill a single run after S seconds (default 600) |
+| `-- ARGS` | Anything after `--` goes straight to pytest |
+
+Exit codes: `0` no problems, `1` problems found (by default only flaky tests and *confirmed*
+time bombs or racy tests fail a build), `2` usage or collection error.
+
+## In CI
+
+Hunting runs your suite many times, so run it on a schedule rather than on every push:
+
+```yaml
+# .github/workflows/flakehound.yml
+on:
+  schedule: [{ cron: "0 3 * * *" }]   # nightly
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  hunt:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with: { persist-credentials: false }
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with: { python-version: "3.12" }
+      - run: pip install -e . flakehound
+      - run: flakehound run --json flakehound.json
+```
+
+In GitHub Actions the Markdown report appears on the run's summary page automatically.
+
+## Quarantine
+
+Found a flaky test you can't fix today? Quarantine it so it stops failing the build, without
+hiding it:
+
+```bash
+flakehound quarantine add tests/test_cart.py::test_cart_starts_empty --reason "polluted by test_add_item"
+flakehound quarantine add --from-report flakehound.json    # everything flakehound found
+flakehound quarantine list
+flakehound quarantine remove tests/test_cart.py::test_cart_starts_empty
+```
+
+- The list is one file, `.flakehound/quarantine.toml`: commit it, review it, revert it.
+  flakehound never edits your test files.
+- Every change shows a diff and asks first (`--yes` skips the prompt).
+- pytest still runs quarantined tests as non-strict `xfail` (or `skip`), so you see `XPASS`
+  once one is fixed. Disable for one run with `pytest -p no:flakehound-quarantine`. The
+  plugin does nothing when the file doesn't exist.
+- `flakehound run` ignores the quarantine, so quarantined tests keep being hunted.
+
+## How it works
+
+flakehound changes **one factor at a time**, like a science experiment:
+
+1. **Shake.** Run the whole suite many times in parallel, each with a different test order,
+   `random` seed and `PYTHONHASHSEED`, all recorded. Tests that both pass and fail are
+   flaky; tests that always fail are rechecked, then reported as broken.
+2. **Isolate.** Run each flaky test alone with the *exact seeds* of the runs where it
+   failed. Only the order changed, so if it now passes, order is proven to be the cause.
+3. **Find the culprit.** Try the tests whose position best correlates with the failure,
+   then shrink the preceding tests with delta debugging, in parallel batches.
+4. **Name the leaked state.** Snapshot global state before and after the culprit: module
+   variables, object and class attributes, environment variables (secret values are never
+   shown), working directory, `sys.path`, project files and logging config.
+5. **Seeds.** For flaky tests that aren't about order, swap *one* seed at a time between a
+   failing and a passing run: the one that flips the result is the cause. If identical
+   seeds still give different results, the test is nondeterministic.
+6. **Time bomb probes.** Runs with the baseline's exact order and seeds, but in UTC+14,
+   UTC−12, just before midnight, on the last day of the month, on New Year's Eve and on
+   Feb 29. The clock is *shifted*, not frozen, so code that waits on time still works.
+7. **Timing probes.** One run where every `sleep()` on the test's main thread is 20×
+   shorter (background work keeps its real speed, like a slow machine), and one where
+   threads switch far more often. Then one `sleep()` call site at a time, to find the line.
+8. **Confirm and verify.** Findings are re-run, and each printed repro command is run for
+   real; it's marked *verified* only if it fails exactly as printed.
+
+Repro commands that replay a seed, clock or timing stress use flakehound's pytest plugin
+(`-p flakehound.adapters.pytest.plugin`), so they need flakehound installed. That plugin
+never loads into your normal pytest runs on its own.
+
+## How it compares
+
+| Tool | Retries | Detects | Explains why | Free & local |
+|---|---|---|---|---|
+| pytest-rerunfailures, flaky | ✅ | ❌ | ❌ | ✅ |
+| pytest-randomly | ❌ | order/seed issues show up | ❌ | ✅ |
+| detect-test-pollution | ❌ | ❌ | the polluter test (you drive it) | ✅ |
+| Trunk, BuildPulse, Datadog | ✅ | from CI history | little | ❌ paid / uploads data |
+| **flakehound** | ❌ (on purpose) | ✅ + time bombs + racy tests | polluter, leaked state, seed, date, timezone, `sleep()` line, race | ✅ |
+
+## Limitations
+
+- Python + pytest only, for now.
+- `asyncio.sleep` is not shortened by the timing probes.
+- State hidden in fixtures, databases or external services can't be seen by the leak
+  detector; the report says so instead of guessing.
+- Thread stress exposes races that happen around Python function calls.
+- Hunting takes many runs of your suite: use `-n`, `-j` and `--max-diagnose` on large suites.
+
+## Roadmap
+
+- GitHub Actions history mode: find flaky tests from past CI runs without running anything
+- A ready-made GitHub Action
+- Adapters for Jest/Vitest, Go test and JUnit
+- Optional AI explanations (local models via Ollama, or your own key; never required)
+
+See [CHANGELOG.md](https://github.com/urumb/flakehound/blob/main/CHANGELOG.md) for what's in each release.
+
+## Contributing and security
+
+Contributions are welcome: see [CONTRIBUTING.md](https://github.com/urumb/flakehound/blob/main/CONTRIBUTING.md). To report a
+vulnerability privately, see [SECURITY.md](https://github.com/urumb/flakehound/blob/main/SECURITY.md).
+
+## License
+
+MIT

flakehound-0.1.0/README.md

@@ -0,0 +1,179 @@
+# flakehound
+
+[![PyPI](https://img.shields.io/pypi/v/flakehound.svg)](https://pypi.org/project/flakehound/)
+[![Python](https://img.shields.io/pypi/pyversions/flakehound.svg)](https://pypi.org/project/flakehound/)
+[![CI](https://github.com/urumb/flakehound/actions/workflows/ci.yml/badge.svg)](https://github.com/urumb/flakehound/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/urumb/flakehound/actions/workflows/codeql.yml/badge.svg)](https://github.com/urumb/flakehound/actions/workflows/codeql.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/urumb/flakehound/blob/main/LICENSE)
+
+**Find flaky tests and prove *why* they're flaky.**
+
+Flaky tests pass sometimes and fail sometimes with no code change. Most tools just retry
+them, which hides the problem. flakehound runs your pytest suite under deliberately hostile
+conditions, finds the tests that flip, and tells you the cause, with evidence from real runs
+and a command that reproduces it. It also finds problems that haven't bitten you *yet*.
+
+![flakehound output on the demo project](https://raw.githubusercontent.com/urumb/flakehound/main/docs/demo.svg)
+
+- 🆓 **Free forever.** No accounts, no servers, no paid services.
+- 🔒 **Local and private.** Offline, no telemetry, secrets redacted from every report.
+- 🧪 **Evidence, not guesses.** Every verdict comes from runs that prove it, and every repro
+  command is run for real before it's marked *verified*.
+
+## What it finds
+
+| Problem | Example | What flakehound tells you |
+|---|---|---|
+| **Order dependency** | a test leaves an item in a shared cart | the polluter test and the leaked state: `shop.cart: [] → ['apple']` |
+| **Needs another test** | a test only passes after a setup-like test ran | the test it secretly depends on |
+| **Randomness** | `assert random.random() < 0.8` | the failing seed, and a repro that replays it |
+| **Set/dict ordering** | comparing `",".join(a_set)` to a string | that `PYTHONHASHSEED` is the cause |
+| **Time bombs** | breaks on the last day of the month, on Feb 29, in another timezone | the exact date/timezone, *before* it happens |
+| **Sleep used as a wait** | `sleep(0.06)` then assert a thread finished | the exact `sleep()` line that will fail on a slow CI machine |
+| **Race conditions** | unlocked read-modify-write from threads | that it fails when threads interleave |
+
+## Quickstart
+
+```bash
+pip install flakehound
+cd your-project
+flakehound run
+```
+
+That's it: no config. Try it on the included [demo project](https://github.com/urumb/flakehound/tree/main/demo) to see every kind of
+problem. The same results as a Markdown report: [docs/example-report.md](https://github.com/urumb/flakehound/blob/main/docs/example-report.md).
+
+> ⚠️ flakehound **runs your test suite** (many times). Only run it on code you trust.
+
+### Options
+
+| Option | Meaning |
+|---|---|
+| `-n, --runs N` | How many times to run the suite (default 10) |
+| `-j, --workers N` | Parallel runs (default: CPU cores − 1, max 8) |
+| `--seed N` | Replay an earlier session exactly |
+| `--json PATH` | Also write a machine-readable report |
+| `--markdown PATH` | Also write a Markdown report (for PR comments) |
+| `--fail-on KINDS` | What makes exit code 1: `flaky`, `time-bomb`, `racy`, `broken`, `suspected`, `none` (default `flaky,time-bomb,racy`) |
+| `--no-diagnose` | Only detect flaky tests, don't explain them |
+| `--max-diagnose N` | Diagnose at most N flaky tests (default 20) |
+| `--no-probes` | Skip all probe runs (timezones, risky dates, timing) |
+| `--no-timing` | Skip only the timing probes |
+| `--no-step-summary` | Don't add the report to the GitHub Actions job summary |
+| `--timeout S` | Kill a single run after S seconds (default 600) |
+| `-- ARGS` | Anything after `--` goes straight to pytest |
+
+Exit codes: `0` no problems, `1` problems found (by default only flaky tests and *confirmed*
+time bombs or racy tests fail a build), `2` usage or collection error.
+
+## In CI
+
+Hunting runs your suite many times, so run it on a schedule rather than on every push:
+
+```yaml
+# .github/workflows/flakehound.yml
+on:
+  schedule: [{ cron: "0 3 * * *" }]   # nightly
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  hunt:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with: { persist-credentials: false }
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with: { python-version: "3.12" }
+      - run: pip install -e . flakehound
+      - run: flakehound run --json flakehound.json
+```
+
+In GitHub Actions the Markdown report appears on the run's summary page automatically.
+
+## Quarantine
+
+Found a flaky test you can't fix today? Quarantine it so it stops failing the build, without
+hiding it:
+
+```bash
+flakehound quarantine add tests/test_cart.py::test_cart_starts_empty --reason "polluted by test_add_item"
+flakehound quarantine add --from-report flakehound.json    # everything flakehound found
+flakehound quarantine list
+flakehound quarantine remove tests/test_cart.py::test_cart_starts_empty
+```
+
+- The list is one file, `.flakehound/quarantine.toml`: commit it, review it, revert it.
+  flakehound never edits your test files.
+- Every change shows a diff and asks first (`--yes` skips the prompt).
+- pytest still runs quarantined tests as non-strict `xfail` (or `skip`), so you see `XPASS`
+  once one is fixed. Disable for one run with `pytest -p no:flakehound-quarantine`. The
+  plugin does nothing when the file doesn't exist.
+- `flakehound run` ignores the quarantine, so quarantined tests keep being hunted.
+
+## How it works
+
+flakehound changes **one factor at a time**, like a science experiment:
+
+1. **Shake.** Run the whole suite many times in parallel, each with a different test order,
+   `random` seed and `PYTHONHASHSEED`, all recorded. Tests that both pass and fail are
+   flaky; tests that always fail are rechecked, then reported as broken.
+2. **Isolate.** Run each flaky test alone with the *exact seeds* of the runs where it
+   failed. Only the order changed, so if it now passes, order is proven to be the cause.
+3. **Find the culprit.** Try the tests whose position best correlates with the failure,
+   then shrink the preceding tests with delta debugging, in parallel batches.
+4. **Name the leaked state.** Snapshot global state before and after the culprit: module
+   variables, object and class attributes, environment variables (secret values are never
+   shown), working directory, `sys.path`, project files and logging config.
+5. **Seeds.** For flaky tests that aren't about order, swap *one* seed at a time between a
+   failing and a passing run: the one that flips the result is the cause. If identical
+   seeds still give different results, the test is nondeterministic.
+6. **Time bomb probes.** Runs with the baseline's exact order and seeds, but in UTC+14,
+   UTC−12, just before midnight, on the last day of the month, on New Year's Eve and on
+   Feb 29. The clock is *shifted*, not frozen, so code that waits on time still works.
+7. **Timing probes.** One run where every `sleep()` on the test's main thread is 20×
+   shorter (background work keeps its real speed, like a slow machine), and one where
+   threads switch far more often. Then one `sleep()` call site at a time, to find the line.
+8. **Confirm and verify.** Findings are re-run, and each printed repro command is run for
+   real; it's marked *verified* only if it fails exactly as printed.
+
+Repro commands that replay a seed, clock or timing stress use flakehound's pytest plugin
+(`-p flakehound.adapters.pytest.plugin`), so they need flakehound installed. That plugin
+never loads into your normal pytest runs on its own.
+
+## How it compares
+
+| Tool | Retries | Detects | Explains why | Free & local |
+|---|---|---|---|---|
+| pytest-rerunfailures, flaky | ✅ | ❌ | ❌ | ✅ |
+| pytest-randomly | ❌ | order/seed issues show up | ❌ | ✅ |
+| detect-test-pollution | ❌ | ❌ | the polluter test (you drive it) | ✅ |
+| Trunk, BuildPulse, Datadog | ✅ | from CI history | little | ❌ paid / uploads data |
+| **flakehound** | ❌ (on purpose) | ✅ + time bombs + racy tests | polluter, leaked state, seed, date, timezone, `sleep()` line, race | ✅ |
+
+## Limitations
+
+- Python + pytest only, for now.
+- `asyncio.sleep` is not shortened by the timing probes.
+- State hidden in fixtures, databases or external services can't be seen by the leak
+  detector; the report says so instead of guessing.
+- Thread stress exposes races that happen around Python function calls.
+- Hunting takes many runs of your suite: use `-n`, `-j` and `--max-diagnose` on large suites.
+
+## Roadmap
+
+- GitHub Actions history mode: find flaky tests from past CI runs without running anything
+- A ready-made GitHub Action
+- Adapters for Jest/Vitest, Go test and JUnit
+- Optional AI explanations (local models via Ollama, or your own key; never required)
+
+See [CHANGELOG.md](https://github.com/urumb/flakehound/blob/main/CHANGELOG.md) for what's in each release.
+
+## Contributing and security
+
+Contributions are welcome: see [CONTRIBUTING.md](https://github.com/urumb/flakehound/blob/main/CONTRIBUTING.md). To report a
+vulnerability privately, see [SECURITY.md](https://github.com/urumb/flakehound/blob/main/SECURITY.md).
+
+## License
+
+MIT

flakehound-0.1.0/SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please **do not open a public issue** for security problems.
+
+Report privately through GitHub's
+[private vulnerability reporting](https://github.com/urumb/flakehound/security/advisories/new).
+You should get a response within 7 days. Please include steps to reproduce and the affected version.
+
+## Supported versions
+
+Only the latest release receives security fixes while the project is pre-1.0.
+
+## Security model
+
+- **flakehound runs your test suite, which is arbitrary code.** Only run it on code you trust.
+  Never point it at untrusted pull requests or repositories without a sandbox.
+- **Offline by default.** flakehound makes no network calls and collects no telemetry.
+  Features that need the network (such as future GitHub history mode or cloud AI) are opt-in.
+- **No secrets in output.** Reports never include environment variables; values that look like
+  tokens, keys or passwords are redacted.
+- **Safe subprocesses.** Tests run via argument lists, never `shell=True`. Child processes and
+  temporary files are cleaned up, even on Ctrl+C.
+- **Supply chain.** Minimal dependencies, releases published with PyPI Trusted Publishing
+  (no long-lived tokens), GitHub Actions pinned to commit SHAs with least-privilege permissions.

flakehound-0.1.0/demo/README.md

@@ -0,0 +1,17 @@
+# flakehound demo
+
+A tiny shop whose tests are flaky on purpose. Each file is one classic trap:
+
+| Test file | Trap |
+|---|---|
+| `tests/test_cart.py` | Order dependency: `test_add_item` leaves an item in the shared cart |
+| `tests/test_currency.py` | Order dependency: `test_euro_store` leaks the `SHOP_CURRENCY` env var |
+| `tests/test_inventory.py` | Needs another test: `test_apples_in_stock` only passes after `test_restock_apples` |
+| `tests/test_discount.py` | Unseeded randomness |
+| `tests/test_tags.py` | Set iteration order depends on `PYTHONHASHSEED` |
+| `tests/test_upload.py` | Timing: `sleep()` used to wait for a background thread |
+| `tests/test_wallet.py` | Race condition: unlocked read-modify-write from several threads |
+| `tests/test_dates.py` | Time bombs: mixes local time and UTC, breaks on the last day of the month and on Feb 29 |
+| `tests/test_math.py` | Stable tests, for contrast |
+
+Run `flakehound run` in this folder.

flakehound-0.1.0/demo/tests/test_cart.py

@@ -0,0 +1,11 @@
+import shop
+
+
+def test_cart_starts_empty():
+    # Passes in the default order, fails whenever test_add_item ran first.
+    assert shop.cart == []
+
+
+def test_add_item():
+    shop.add_item("apple")  # never cleaned up: leaks into later tests
+    assert "apple" in shop.cart

flakehound-0.1.0/demo/tests/test_currency.py

@@ -0,0 +1,12 @@
+import os
+
+import shop
+
+
+def test_prices_default_to_usd():
+    assert shop.currency() == "USD"
+
+
+def test_euro_store():
+    os.environ["SHOP_CURRENCY"] = "EUR"  # bug: never restored (use monkeypatch.setenv)
+    assert shop.currency() == "EUR"

flakehound-0.1.0/demo/tests/test_dates.py

@@ -0,0 +1,18 @@
+from datetime import date, datetime, timedelta, timezone
+
+
+def test_order_date_matches_utc():
+    # Bug: mixes local time and UTC. Fails wherever the local date differs from
+    # the UTC date (e.g. a CI machine in another timezone, or late evenings).
+    assert datetime.now().date() == datetime.now(timezone.utc).date()
+
+
+def test_coupon_valid_until_tomorrow():
+    # Bug: assumes tomorrow is in the same month. False on the last day of every month.
+    assert (date.today() + timedelta(days=1)).month == date.today().month
+
+
+def test_anniversary_next_year():
+    today = date.today()
+    # Bug: Feb 29 plus one year does not exist -> ValueError on leap days.
+    assert today.replace(year=today.year + 1) > today

flakehound-0.1.0/demo/tests/test_discount.py

@@ -0,0 +1,5 @@
+import shop
+
+
+def test_lucky_discount_is_small():
+    assert shop.lucky_discount() < 0.8  # fails about 20% of the time

flakehound-0.1.0/demo/tests/test_inventory.py

@@ -0,0 +1,11 @@
+import shop
+
+
+def test_restock_apples():
+    shop.Inventory.restock("apple", 5)
+    assert shop.Inventory.stock["apple"] >= 5
+
+
+def test_apples_in_stock():
+    # Bug: silently relies on test_restock_apples having run first.
+    assert shop.Inventory.stock.get("apple", 0) > 0

flakehound-0.1.0/demo/tests/test_math.py

@@ -0,0 +1,9 @@
+import shop
+
+
+def test_single_tag_renders():
+    assert shop.render_tags({"python"}) == "python"
+
+
+def test_addition():
+    assert 1 + 1 == 2

flakehound-0.1.0/demo/tests/test_tags.py

@@ -0,0 +1,6 @@
+import shop
+
+
+def test_tags_render_alphabetically():
+    # Bug: sets have no defined order. Passes only for some hash seeds.
+    assert shop.render_tags({"flaky", "pytest", "python"}) == "flaky,pytest,python"

flakehound-0.1.0/demo/tests/test_upload.py

@@ -0,0 +1,10 @@
+import time
+
+import shop
+
+
+def test_upload_finishes():
+    up = shop.Uploader()
+    up.start()
+    time.sleep(0.06)  # "should be long enough" (it isn't on a busy machine)
+    assert up.done

flakehound-0.1.0/demo/tests/test_wallet.py

@@ -0,0 +1,21 @@
+import threading
+
+import shop
+
+
+def test_concurrent_top_ups():
+    wallet = shop.Wallet()
+    start = threading.Barrier(4)  # all four "users" pay at the same moment
+
+    def worker():
+        start.wait()
+        for _ in range(2000):
+            wallet.top_up(1)
+
+    threads = [threading.Thread(target=worker) for _ in range(4)]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+    # Bug: top_up is not thread-safe. Passes almost always, until threads interleave.
+    assert wallet.balance == 8000