smoke-optimiser 0.1.0__tar.gz

smoke_optimiser-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.0.0
+
+      - name: Install just
+        uses: taiki-e/install-action@v2
+        with:
+          tool: just
+
+      - name: Install dependencies
+        run: uv sync
+
+      # Pre-commit logic is defined in the Justfile `precommit` target — do not add steps here.
+      - name: Validate project
+        run: just precommit

smoke_optimiser-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,72 @@
+name: release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      pr: ${{ steps.release.outputs.pr }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        env:
+          FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+        with:
+          release-type: python
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+  update-lockfile:
+    runs-on: ubuntu-latest
+    needs: release-please
+    if: ${{ needs.release-please.outputs.pr }}
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: release-please--branches--main
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.0.0
+
+      - name: Update lock file
+        run: uv lock
+
+      - name: Commit updated lock file
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add uv.lock
+          git diff --staged --quiet || git commit -m "chore: update uv.lock for version bump"
+          git push
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created }}
+    environment: pypi
+    permissions:
+      id-token: write  # Mandatory for Trusted Publishing
+    steps:
+      - uses: actions/checkout@v6
+        env:
+          FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.0.0
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

smoke_optimiser-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.coverage
+*.pyc
+.pytest_cache/
+.smoke_suite.json
+.smoke_profiling_data.json
+.smoke_outcomes.json
+.smoke_optimiser_coverage.json
+_smoke_hook.py
+.smoke_coveragerc
+.gstack/
+.jules/

smoke_optimiser-0.1.0/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+## 0.1.0 (2026-04-28)
+
+
+### Features
+
+* add --iterations argument to average test durations across multiple runs ([e85b02c](https://github.com/lawther/smoke-optimiser/commit/e85b02ce94a195bf8510a6d64e889da544fe6826))
+* add --src top-level argument for coverage target with conflict validation ([e6a1373](https://github.com/lawther/smoke-optimiser/commit/e6a13737aed3e1f96c6149036aed4ae3044e19dd))
+* add CLI argument parsing and config merging ([6b77dde](https://github.com/lawther/smoke-optimiser/commit/6b77dde50b42ffd71c5ed8a544f1eb6af439defa))
+* add config model with pyproject.toml loading ([e7f85a7](https://github.com/lawther/smoke-optimiser/commit/e7f85a7fa3eb1e629dba839770cbf1a76044abec))
+* add coverage JSON parser with streaming support ([1cad88f](https://github.com/lawther/smoke-optimiser/commit/1cad88f83c2d107ce2da481f2643548f254b45a3))
+* add full suite coverage metric to summary reports ([db6f218](https://github.com/lawther/smoke-optimiser/commit/db6f218420b748206ad377324f9a0af5d053552d))
+* add greedy set-cover optimiser ([0015142](https://github.com/lawther/smoke-optimiser/commit/00151429c2ef326384286c2dc3777a11465016c0))
+* add heuristic coverage target discovery with warning ([9ada322](https://github.com/lawther/smoke-optimiser/commit/9ada322039e51a8218e6020a507a1bde017cad51))
+* Add Justfile for development task automation ([6aa80bc](https://github.com/lawther/smoke-optimiser/commit/6aa80bc3d41f85f9aa0f74c2e8f7ab333a668666))
+* add machine environment capture ([b8ef0f9](https://github.com/lawther/smoke-optimiser/commit/b8ef0f92e58eecd0d52949a50a8e5343136919b7))
+* add optimiser data models ([4f6bbf4](https://github.com/lawther/smoke-optimiser/commit/4f6bbf4ae1a4a21dfe2fffac1496296eb445cc3b))
+* add optimiser filters (include/exclude/failing) ([5b8c049](https://github.com/lawther/smoke-optimiser/commit/5b8c0492686a08703caa7d73684cc2a7c7369f7d))
+* add plugin summary header showing smoke suite metadata ([7eabb0c](https://github.com/lawther/smoke-optimiser/commit/7eabb0cd806b58db89e40b6bec2619bfce8ea4d4))
+* add profiler data models ([0ece94c](https://github.com/lawther/smoke-optimiser/commit/0ece94cf4d93f7d39217d35d94522f030b902000))
+* add profiler runner (pytest + coverage orchestration) ([dd9b6ae](https://github.com/lawther/smoke-optimiser/commit/dd9b6ae3396afc471809dd52cfa7f097b1edb2d6))
+* add pytest plugin option registration and smoke suite loading ([44eee93](https://github.com/lawther/smoke-optimiser/commit/44eee93464936724cf79e2e2f19b941f82b6b0f6))
+* add report generation (JSON and human-readable) ([4f761b6](https://github.com/lawther/smoke-optimiser/commit/4f761b6ab4a690f20f616ef3d61b4a691a2de2a5))
+* add test collection filtering for --smoke ([f1ab66e](https://github.com/lawther/smoke-optimiser/commit/f1ab66edfdec290db8b83d6d4007bd610ce6de55))
+* allow matching include/exclude filters by test function name ([b85bcd0](https://github.com/lawther/smoke-optimiser/commit/b85bcd066c0d6936c67a7ef28f1d1c36cc9d6ce5))
+* enable direct installation of `smoke-optimiser`, update README instructions, and add MIT license. ([5c9c616](https://github.com/lawther/smoke-optimiser/commit/5c9c616a7133db88c7c43e8d4984ff7a1412f9cf))
+* support comma-separated patterns in include and exclude filters ([985f878](https://github.com/lawther/smoke-optimiser/commit/985f87886beb16fbea560176efcdc2c5c454d16e))
+* support file-level matching in include/exclude filters ([bb8f8db](https://github.com/lawther/smoke-optimiser/commit/bb8f8db337241952d085ccad221262357de24441))
+* warn user about unmatched include/exclude patterns during optimization ([41cabaa](https://github.com/lawther/smoke-optimiser/commit/41cabaa457526812a15f31275512637b895c2700))
+* wire CLI to profiler and optimiser phases ([d2a3534](https://github.com/lawther/smoke-optimiser/commit/d2a35345f87998db077e9a2aa40ab2a409b45433))
+
+
+### Bug Fixes
+
+* arbitrary file overwrite (Symlink Attack) ([7e97075](https://github.com/lawther/smoke-optimiser/commit/7e97075139f4ddf64493c73a3e2face57c013c9a))
+* capture heuristically discovered coverage target in repro command ([401f5d3](https://github.com/lawther/smoke-optimiser/commit/401f5d33a276e97d2d05289330b3dd434d749452))
+* Enhance CLI message consistency and add pluralisation ([20a7c56](https://github.com/lawther/smoke-optimiser/commit/20a7c56ed7a711e7cdc4ed1fc7519d4fe010d6be))
+* Fix B110 exception swallowing in config parser ([aa182f9](https://github.com/lawther/smoke-optimiser/commit/aa182f9e3d70e4e396914114423a0b7b6074a512))
+* insecure relative path generation in hook output ([ec54988](https://github.com/lawther/smoke-optimiser/commit/ec54988462fea499c9ccb79f041bdbc24c7269ae))
+* Predictable Temporary File Names in Project Root ([9ffdf7f](https://github.com/lawther/smoke-optimiser/commit/9ffdf7fc9866a8eb02b52bf4cdcd9e94a23be738))
+* prevent information disclosure on invalid profile data ([6d3dfac](https://github.com/lawther/smoke-optimiser/commit/6d3dface5ed0267593c668cf7af8297293a66717))
+* profiler hook loading and streaming parser robustness ([f8e7637](https://github.com/lawther/smoke-optimiser/commit/f8e7637cad0ec6540360b43305bd06361c46fb4c))
+* refactor Justfile for reliable error reporting and 4-space indentation ([4a588ba](https://github.com/lawther/smoke-optimiser/commit/4a588bafd273f784219d16a39ed23566cd9cc951))
+* refactor Justfile recipes for reliable error reporting and add linting ([8b96301](https://github.com/lawther/smoke-optimiser/commit/8b96301ef22b0b0b8420cb257ee500c87c7dda8f))
+* refactor precommit recipe for reliable error reporting ([67f2918](https://github.com/lawther/smoke-optimiser/commit/67f29189b9045ea0dc93a20b7e30e43d654a5833))
+* resolve conflicting coverage dynamic contexts and promote warnings to errors ([17a16dd](https://github.com/lawther/smoke-optimiser/commit/17a16ddd7c7b5d152ce92cdaf19f3e6124f545c7))
+* resolve partial executable paths using `shutil.which` ([d3619b5](https://github.com/lawther/smoke-optimiser/commit/d3619b58f5b8236ad23dbdb993fa0b0183f7ac62))
+* resolve ty check errors and enforce type safety in models ([c3579e9](https://github.com/lawther/smoke-optimiser/commit/c3579e9805726befd28b047cc9b41b778b243ed8))
+* suppress confusing coverage.py JSON report message in runner ([0d567e8](https://github.com/lawther/smoke-optimiser/commit/0d567e88054335afad192f7c8fe3c2d1dcbdfac5))
+
+
+### Performance Improvements
+
+* Lazy greedy evaluation for set cover ([b9a325c](https://github.com/lawther/smoke-optimiser/commit/b9a325c96c94e0063e9d7f18f6620e1e0b81fe42))
+* optimize equivalent group calculation by utilizing frozenset dictionary keys  ([57da5a8](https://github.com/lawther/smoke-optimiser/commit/57da5a8bd02ac49fb4f87d40d33964a536697230))
+* optimize greedy set cover selection algorithm in `optimise()` ([#4](https://github.com/lawther/smoke-optimiser/issues/4)) ([4318821](https://github.com/lawther/smoke-optimiser/commit/4318821fdab35abfa7c4bbf28421e1125792f6e3))
+* Optimize slow test ID parsing in coverage JSON ([4cfe127](https://github.com/lawther/smoke-optimiser/commit/4cfe1272940f518ad142fa15b184a988562d9dba))
+* pre-format branch strings in parser ([9cc27c8](https://github.com/lawther/smoke-optimiser/commit/9cc27c89e55836771a9643b91f2ed4e582ff2e3a))
+
+
+### Documentation
+
+* add comprehensive README with usage and argument documentation ([3666db3](https://github.com/lawther/smoke-optimiser/commit/3666db30c11014692917b63d9b69c26bd3bac8b3))
+* add readme, delete impl plans ([a412bf1](https://github.com/lawther/smoke-optimiser/commit/a412bf1f15fd936157fc4331b1b482d4688d64b8))
+* be super explicit about linting rules ([759fa77](https://github.com/lawther/smoke-optimiser/commit/759fa77a94a2c40873eb0e66220e90d4f8fe6253))
+* plan documents ([172ef92](https://github.com/lawther/smoke-optimiser/commit/172ef92b84a19df8edbc41d9b1755476f616c456))
+
+## Changelog

smoke_optimiser-0.1.0/Justfile

@@ -0,0 +1,82 @@
+# List available recipes
+default:
+    @just --list
+
+# Run all checks (lint, typecheck, test)
+check: lint typecheck test
+
+# Run linting and formatting
+lint:
+    uv run ruff format
+    uv run ruff check --fix
+
+# Format the code
+format:
+    uv run ruff format
+
+# Run type checks
+typecheck:
+    uv run ty check
+
+# Run tests
+test:
+    uv run pytest
+
+# Run tests with coverage
+test-cov:
+    uv run pytest --cov=smoke_optimiser
+
+# Run formatting, linting and tests (quiet on success, shows errors on failure)
+# This Justfile is the Single Source Of Truth (SSOT) for all pre-commit checks.
+precommit:
+    #!/usr/bin/env bash
+    echo "Running precommit checks..."
+    uv lock --check || { echo "❌ uv.lock is out of sync with pyproject.toml"; exit 1; }
+    tmpfile=$(mktemp)
+    trap 'rm -f "$tmpfile"' EXIT
+    (
+        set -e
+        just _lint-justfile
+        uv run ruff format
+        uv run ruff check --fix
+        git add $(git diff --cached --name-only)
+        uv run ty check
+        uv run pytest
+    ) > "$tmpfile" 2>&1
+    status=$?
+    if [ $status -ne 0 ]; then
+        cat "$tmpfile"
+        exit $status
+    fi
+    echo "✅ Precommit checks passed!"
+
+# [private] Ensure Justfile recipes don't use && chains (which suppress set -e)
+_lint-justfile:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    violations=$(awk '
+        /^[[:space:]]+#!/ { in_shebang = 1 }
+        /^[^[:space:]]/ && NF > 0 { in_shebang = 0 }
+        !in_shebang && /&&/ && !/^[[:space:]]*#/ { print NR": "$0 }
+    ' Justfile)
+    if [[ -n "$violations" ]]; then
+        echo "❌ Justfile recipes must not use && chains. Use separate lines for reliable error reporting."
+        echo "$violations"
+        exit 1
+    fi
+
+# Setup the development environment from a fresh clone
+setup-dev:
+    @uv sync
+    @just setup-git-hooks
+    @echo "✅ Development environment setup complete!"
+
+# Setup local git hooks
+setup-git-hooks:
+    @echo "Setting up local git hooks..."
+    @echo "#!/bin/sh" > .git/hooks/pre-commit
+    @echo "# This hook invokes the Justfile, which is the Single Source Of Truth for precommit logic." >> .git/hooks/pre-commit
+    @echo "# DO NOT add precommit logic here; add it to the 'precommit' recipe in the Justfile." >> .git/hooks/pre-commit
+    @echo "just precommit" >> .git/hooks/pre-commit
+    @chmod +x .git/hooks/pre-commit
+    @echo "✅ Git hooks set up!"

smoke_optimiser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mike Lawther
+
+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.

smoke_optimiser-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: smoke-optimiser
+Version: 0.1.0
+Summary: A Python CLI tool and pytest plugin to identify and run a minimal smoke test suite.
+Project-URL: Homepage, https://github.com/lawther/smoke-optimiser
+Project-URL: Repository, https://github.com/lawther/smoke-optimiser
+Project-URL: Bug Tracker, https://github.com/lawther/smoke-optimiser/issues
+Author-email: Mike Lawther <mike.lawther@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Mike Lawther
+        
+        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.
+License-File: LICENSE
+Keywords: coverage,optimisation,pytest,smoke-test,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Requires-Dist: coverage~=7.0
+Requires-Dist: ijson~=3.5
+Requires-Dist: pydantic~=2.0
+Requires-Dist: pytest-cov~=7.0
+Requires-Dist: pytest~=9.0
+Requires-Dist: typer~=0.9
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff~=0.15; extra == 'dev'
+Provides-Extra: machine
+Requires-Dist: psutil~=7.0; extra == 'machine'
+Description-Content-Type: text/markdown
+
+# smoke-optimiser
+
+`smoke-optimiser` is a tool and pytest plugin that analyses your test suite to produce a minimal **smoke suite** — a subset of tests that delivers maximum code coverage in minimum wall-clock time.
+
+It helps you find the "bang for buck" sweet spot: for example, achieving 80% of your total branch coverage in only 5% of the total runtime.
+
+## Installation
+
+Add `smoke-optimiser` as a development dependency in your project:
+
+```bash
+uv add --dev smoke-optimiser
+```
+
+Or with pip:
+
+```bash
+pip install smoke-optimiser
+```
+
+This will make the `smoke-optimiser` command available in your environment and register the pytest plugin automatically.
+
+## Quickstart
+
+1. **Generate the smoke suite**:
+   Run the optimiser in your project root. It will automatically detect your source code and profile your tests.
+   ```bash
+   uv run smoke-optimiser
+   ```
+
+2. **Run the smoke suite**:
+   Use the `--smoke` flag with pytest to run only the selected high-value tests.
+   ```bash
+   uv run pytest --smoke
+   ```
+
+## Common Usages
+
+### Custom Efficiency Targets
+By default, the tool tries to get maximum coverage within a 15-second time cap. You can tighten these bounds:
+```bash
+# Aim for 80% coverage, but stop if it takes longer than 5 seconds
+uv run smoke-optimiser --target-cov=80 --time-cap=5
+```
+
+### Stabilising Timing Data
+Test execution times can vary. Use `--iterations` to run the suite multiple times and average the results for a more stable smoke suite:
+```bash
+uv run smoke-optimiser --iterations=3
+```
+
+### Mandatory Inclusion/Exclusion
+Force certain tests (or markers) to be included or excluded from the smoke suite:
+```bash
+# Always include authentication tests, but exclude anything marked as 'slow'
+uv run smoke-optimiser --include="tests/test_auth.py" --exclude="@pytest.mark.slow"
+```
+*Multiple items can be separated by commas.*
+
+## Command-line Arguments
+
+### `smoke-optimiser` (Generator)
+
+| Argument | Description | Default |
+| :--- | :--- | :--- |
+| `--src` | The source directory or package to measure coverage for. | *Discovered* |
+| `--iterations` | Number of times to run profiling to average timing data. | `1` |
+| `--time-cap` | Maximum wall-clock runtime (seconds) of the smoke suite. | `15.0` |
+| `--target-cov` | Target % of the full suite's branch coverage to achieve. | `100.0` |
+| `--include` | Comma-separated list of tests, files, or markers to force include. | `[]` |
+| `--exclude` | Comma-separated list of tests, files, or markers to force exclude. | `[]` |
+| `--pytest-args` | Extra arguments forwarded to pytest during profiling. | `""` |
+| `--output-json` | Path for the generated smoke suite definition file. | `.smoke_suite.json` |
+| `--profile-only` | Run only the profiling phase and save intermediate data. | `False` |
+| `--optimise-only` | Run only the optimisation phase using existing profile data. | `False` |
+| `--allow-ordered` | Suppress warning when `pytest-randomly` is not installed. | `False` |
+
+### `pytest` (Plugin)
+
+| Argument | Description | Default |
+| :--- | :--- | :--- |
+| `--smoke` | Activates the plugin; filters collection to the smoke suite. | `False` |
+| `--smoke-file-path` | Path to the smoke suite JSON file to use. | `.smoke_suite.json` |
+
+## How it works
+
+1. **Profiling**: It runs your suite with `pytest-cov` and a custom hook to map every single branch execution to specific tests.
+2. **Analysis**: It calculates the "efficiency" of every test (New Branches Covered / Duration).
+3. **Greedy Selection**: It iteratively picks the most efficient test until your coverage target or time cap is reached.
+4. **Redundancy Reporting**: It identifies "Coverage-equivalent groups" — sets of tests that cover the exact same logic.

smoke_optimiser-0.1.0/README.md

@@ -0,0 +1,90 @@
+# smoke-optimiser
+
+`smoke-optimiser` is a tool and pytest plugin that analyses your test suite to produce a minimal **smoke suite** — a subset of tests that delivers maximum code coverage in minimum wall-clock time.
+
+It helps you find the "bang for buck" sweet spot: for example, achieving 80% of your total branch coverage in only 5% of the total runtime.
+
+## Installation
+
+Add `smoke-optimiser` as a development dependency in your project:
+
+```bash
+uv add --dev smoke-optimiser
+```
+
+Or with pip:
+
+```bash
+pip install smoke-optimiser
+```
+
+This will make the `smoke-optimiser` command available in your environment and register the pytest plugin automatically.
+
+## Quickstart
+
+1. **Generate the smoke suite**:
+   Run the optimiser in your project root. It will automatically detect your source code and profile your tests.
+   ```bash
+   uv run smoke-optimiser
+   ```
+
+2. **Run the smoke suite**:
+   Use the `--smoke` flag with pytest to run only the selected high-value tests.
+   ```bash
+   uv run pytest --smoke
+   ```
+
+## Common Usages
+
+### Custom Efficiency Targets
+By default, the tool tries to get maximum coverage within a 15-second time cap. You can tighten these bounds:
+```bash
+# Aim for 80% coverage, but stop if it takes longer than 5 seconds
+uv run smoke-optimiser --target-cov=80 --time-cap=5
+```
+
+### Stabilising Timing Data
+Test execution times can vary. Use `--iterations` to run the suite multiple times and average the results for a more stable smoke suite:
+```bash
+uv run smoke-optimiser --iterations=3
+```
+
+### Mandatory Inclusion/Exclusion
+Force certain tests (or markers) to be included or excluded from the smoke suite:
+```bash
+# Always include authentication tests, but exclude anything marked as 'slow'
+uv run smoke-optimiser --include="tests/test_auth.py" --exclude="@pytest.mark.slow"
+```
+*Multiple items can be separated by commas.*
+
+## Command-line Arguments
+
+### `smoke-optimiser` (Generator)
+
+| Argument | Description | Default |
+| :--- | :--- | :--- |
+| `--src` | The source directory or package to measure coverage for. | *Discovered* |
+| `--iterations` | Number of times to run profiling to average timing data. | `1` |
+| `--time-cap` | Maximum wall-clock runtime (seconds) of the smoke suite. | `15.0` |
+| `--target-cov` | Target % of the full suite's branch coverage to achieve. | `100.0` |
+| `--include` | Comma-separated list of tests, files, or markers to force include. | `[]` |
+| `--exclude` | Comma-separated list of tests, files, or markers to force exclude. | `[]` |
+| `--pytest-args` | Extra arguments forwarded to pytest during profiling. | `""` |
+| `--output-json` | Path for the generated smoke suite definition file. | `.smoke_suite.json` |
+| `--profile-only` | Run only the profiling phase and save intermediate data. | `False` |
+| `--optimise-only` | Run only the optimisation phase using existing profile data. | `False` |
+| `--allow-ordered` | Suppress warning when `pytest-randomly` is not installed. | `False` |
+
+### `pytest` (Plugin)
+
+| Argument | Description | Default |
+| :--- | :--- | :--- |
+| `--smoke` | Activates the plugin; filters collection to the smoke suite. | `False` |
+| `--smoke-file-path` | Path to the smoke suite JSON file to use. | `.smoke_suite.json` |
+
+## How it works
+
+1. **Profiling**: It runs your suite with `pytest-cov` and a custom hook to map every single branch execution to specific tests.
+2. **Analysis**: It calculates the "efficiency" of every test (New Branches Covered / Duration).
+3. **Greedy Selection**: It iteratively picks the most efficient test until your coverage target or time cap is reached.
+4. **Redundancy Reporting**: It identifies "Coverage-equivalent groups" — sets of tests that cover the exact same logic.

smoke_optimiser-0.1.0/pyproject.toml

@@ -0,0 +1,140 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "smoke-optimiser"
+version = "0.1.0"
+requires-python = ">=3.12"
+description = "A Python CLI tool and pytest plugin to identify and run a minimal smoke test suite."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Mike Lawther", email = "mike.lawther@gmail.com" }
+]
+keywords = ["pytest", "testing", "smoke-test", "coverage", "optimisation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "typer~=0.9",
+    "pydantic~=2.0",
+    "coverage~=7.0",
+    "pytest~=9.0",
+    "pytest-cov~=7.0",
+    "ijson~=3.5",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/lawther/smoke-optimiser"
+"Repository" = "https://github.com/lawther/smoke-optimiser"
+"Bug Tracker" = "https://github.com/lawther/smoke-optimiser/issues"
+
+[project.optional-dependencies]
+machine = ["psutil~=7.0"]
+dev = ["ruff~=0.15", "pytest"]
+
+[project.scripts]
+smoke-optimiser = "smoke_optimiser.__main__:main"
+
+[project.entry-points."pytest11"]
+smoke_optimiser = "smoke_optimiser.plugin"
+
+[tool.ruff]
+line-length = 120
+# these are explanation of the rules that are selected:
+# B: Basic checks
+# C4: Code complexity checks
+# D: Docstring checks
+# E: Error checks
+# F: Formatting checks
+# I: Import checks
+# S: Bandit checks
+# ICN: Import convention checks
+# PGH: Python grammar checks
+# PL: Pylint checks
+# RUF: Ruff checks
+# UP: Unused code checks
+# ANN: Type annotation checks
+# ASYNC: Async code checks
+# SIM: Simple checks
+# LOG: Logging checks
+lint.select = [
+  "B",
+  "C4",
+  "D",
+  "E",
+  "F",
+  "I",
+  "S",
+  "ICN",
+  "PGH",
+  "PL",
+  "RUF",
+  "UP",
+  "ANN",
+  "ASYNC",
+  "SIM",
+  "LOG",
+]
+lint.ignore = [
+  # pydocstyle
+  # D1: Missing docstring in public module
+  "D100",
+  # D2: Missing docstring in public package
+  "D104",
+  # D3: Missing docstring in public function
+  "D103",
+  # D4: Missing docstring in public package
+  "D107",
+  # D5: Missing docstring in public method
+  "D102",
+  # D6: Missing docstring in public class
+  "D101",
+  # D7: Missing docstring in __init__
+  "D107",
+  # pylint
+  # PLR09: Too many <...>
+  "PLR0912",
+  "PLR0913",
+  "PLR0915",
+]
+lint.per-file-ignores = { "tests/*" = ["S101"] }
+lint.pydocstyle.convention = "google"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+timeout = 10
+filterwarnings = [
+    "error::RuntimeWarning",
+    "error::pytest.PytestUnraisableExceptionWarning",
+    "error::pytest_cov.engine.CentralCovContextWarning",
+    "error::coverage.exceptions.CoverageWarning",
+]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/.claude",
+    "/CLAUDE.md",
+    "/GEMINI.md",
+    "/PRD-smoke-optimiser.md",
+    "/uv.lock",
+    "/tests",
+]
+
+[dependency-groups]
+dev = [
+    "psutil>=7.2.2",
+    "pytest-randomly~=4.0",
+    "pytest-timeout~=2.4",
+    "ruff>=0.15.4",
+    "ty>=0.0.25",
+]

smoke_optimiser-0.1.0/smoke_optimiser/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"