benchmatrix 0.2.1__tar.gz

benchmatrix-0.2.1/.gitignore

@@ -0,0 +1,49 @@
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.pre-commit-cache/
+.mypy_cache/
+.pyright/
+.ipynb_checkpoints/
+
+# Virtual environments
+.nox/
+.venv/
+venv/
+env/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+site/
+
+# Test coverage and reports
+.coverage
+htmlcov/
+reports/
+
+# Environment and secrets
+.env
+.env.*
+!.env.example
+
+# OS/editor noise
+.DS_Store
+Thumbs.db
+
+# Node / npm
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.npm/
+
+# Notes
+TODO.md
+
+# Generated example benchmark output
+examples/benchmark_results/

benchmatrix-0.2.1/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to benchmatrix will be documented in this file.
+
+The project follows [Semantic Versioning](https://semver.org/), with the
+additional pre-1.0 compatibility expectations described in
+[the release policy](RELEASING.md).
+
+## Unreleased
+
+### Added
+
+### Changed
+
+## 0.2.1 - 2026-06-22
+
+### Changed
+
+* Fix release and release-verify workflow bugs preventing creation of PyPI
+  releases.
+
+## 0.2.0 - 2026-06-22
+
+### Added
+
+* Initial benchmark matrix utilities.
+* pytest-benchmark JSON parsing and display utilities.
+* Automated linting, typing, security, dependency, test, coverage, and package
+  validation for local development and pull requests, including scheduled
+  audits of locked dependencies for known vulnerabilities.
+* Pre-commit automation, secret scanning, Markdown linting, GitHub Actions
+  workflow linting, and repository text and binary file attributes.
+* MkDocs documentation site with strict builds, generated API reference pages,
+  and operational maintainer runbooks.
+* Reproducible CycloneDX SBOM generation for locked runtime dependencies.
+* uv-backed nox automation for supported-Python tests, quality checks, and
+  release artifact smoke testing.
+* GitHub pull request auto-labeling and labels-as-code configuration for
+  maintainers.
+* Dependabot automation for Python, Node, pre-commit, GitHub Actions, Docker,
+  and devcontainer dependency updates.
+* Repository settings-as-code plus external setup checklists for branch
+  protection, security features, Pages, environments, and PyPI publishing.
+* Focused Python dependency groups for test, lint, type, docs, security,
+  release, and automation tooling, with `dev` as the aggregate group.
+* Compatibility, lifecycle, security-fix, release-branch, and deprecation
+  policy documentation.
+* GitHub Actions CI/CD workflows for quality checks, multi-version and
+  cross-OS tests, docs deployment, PyPI Trusted Publishing, artifact
+  attestations, CodeQL, dependency review, OpenSSF Scorecard, and workflow
+  linting.
+* CI test and coverage report artifacts, documentation link checking, minimum-
+  dependency tests, and post-release PyPI installation verification.
+* Docker runtime and test images, local Docker targets, Docker-outside-of-Docker
+  devcontainer support, Dockerfile linting, GHCR publishing, image
+  SBOM/provenance, and critical-vulnerability image scanning.

benchmatrix-0.2.1/CITATION.cff

@@ -0,0 +1,24 @@
+cff-version: 1.2.0
+message: "If you use benchmatrix in your work, please cite it using this metadata."
+title: "benchmatrix"
+abstract: >-
+  Utilities for building pytest-benchmark benchmark matrices and parsing
+  pytest-benchmark JSON output.
+type: software
+authors:
+  - family-names: "Wallace"
+    given-names: "Ryan"
+    email: "ryancswallace@gmail.com"
+    alias: "ryancswallace"
+version: 0.2.1
+date-released: "2026-06-22"
+license: MIT
+repository-code: "https://github.com/ryancswallace/benchmatrix"
+url: "https://github.com/ryancswallace/benchmatrix"
+keywords:
+  - "python"
+  - "benchmarking"
+  - "benchmark"
+  - "performance"
+  - "pytest"
+  - "pytest-benchmark"

benchmatrix-0.2.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Code of conduct
+
+## Our commitment
+
+We are committed to making participation in the benchmatrix community a
+welcoming and harassment-free experience for everyone, regardless of
+background, identity, appearance, experience level, or ability.
+
+## Expected behavior
+
+Examples of behavior that contributes to a positive community include:
+
+* being respectful, constructive, and empathetic;
+* giving and accepting technical feedback gracefully;
+* focusing disagreement on ideas and outcomes rather than people;
+* taking responsibility for mistakes and learning from them.
+
+Unacceptable behavior includes harassment, discrimination, threats, sustained
+disruption, sexualized attention, deliberate intimidation, or publishing
+someone's private information without permission.
+
+## Enforcement
+
+Report conduct concerns privately to Ryan Wallace at
+<ryancswallace@gmail.com>. Reports will be reviewed promptly and handled as
+confidentially as practical. The maintainer may edit or remove contributions,
+temporarily or permanently restrict participation, or take other action
+appropriate to the circumstances.
+
+This policy applies in project spaces and when someone is publicly representing
+the project.

benchmatrix-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing to benchmatrix
+
+Thanks for considering a contribution.
+
+## Before you start
+
+For substantial changes, open an issue first so the problem and proposed
+direction can be discussed. Small fixes and documentation improvements can go
+directly to a pull request.
+
+By participating, you agree to follow the [code of conduct](CODE_OF_CONDUCT.md).
+Please report security vulnerabilities through the process in
+[SECURITY.md](SECURITY.md), not through a public issue.
+
+## Development
+
+benchmatrix requires Python 3.11 or newer and uses
+[uv](https://docs.astral.sh/uv/) for Python dependency management.
+
+Set up and verify the development environment:
+
+```bash
+make ready
+make hooks-install
+```
+
+Before submitting a change, run:
+
+```bash
+make format
+make check
+```
+
+For changes that may vary by interpreter or packaging environment, also run:
+
+```bash
+make test-matrix
+```
+
+This runs tests on Python 3.11 through 3.14 plus focused lint, type, dependency,
+security, and release-artifact smoke sessions.
+
+Documentation changes should pass `make docs`; API behavior changes should update
+docstrings so the generated API reference stays current.
+
+`make check` verifies the uv lockfile, Ruff formatting and linting, Markdown,
+the documentation site, GitHub Actions workflows, CSpell, secret scanning,
+Bandit, deptry, pip-audit, pytest and coverage, basedpyright, and built
+distributions, including CycloneDX SBOM generation. New behavior should include
+tests, and public APIs should include Google-style docstrings.
+
+The Git hooks run fast, file-oriented checks. Use `make precommit` to run every
+hook manually. Treat additions to `.secrets.baseline` as security-sensitive
+changes and review each detected value before updating the baseline.
+
+## Pull requests
+
+Keep each pull request focused on one coherent change. In the description:
+
+* explain the problem and the chosen approach;
+* identify any public API or compatibility impact;
+* include tests for behavior changes;
+* update documentation and `CHANGELOG.md` when users will notice the change.
+
+Maintainers may request changes before merging. Contributions are accepted
+under the project's [MIT License](LICENSE).

benchmatrix-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Wallace
+
+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 NON-INFRINGEMENT. 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.

benchmatrix-0.2.1/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: benchmatrix
+Version: 0.2.1
+Summary: A pytest-benchmark matrix, metadata, and JSON results layer.
+Project-URL: Homepage, https://github.com/ryancswallace/benchmatrix
+Project-URL: Changelog, https://github.com/ryancswallace/benchmatrix/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/ryancswallace/benchmatrix#readme
+Project-URL: Issues, https://github.com/ryancswallace/benchmatrix/issues
+Project-URL: Source, https://github.com/ryancswallace/benchmatrix
+Author-email: Ryan Wallace <ryancswallace@gmail.com>
+Maintainer-email: Ryan Wallace <ryancswallace@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: benchmark,benchmarking,performance,pytest,pytest-benchmark
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: <3.15,>=3.11
+Requires-Dist: pytest-benchmark>=5.2.3
+Requires-Dist: pytest>=9.1.1
+Description-Content-Type: text/markdown
+
+# benchmatrix
+
+[![CI](https://github.com/ryancswallace/benchmatrix/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ryancswallace/benchmatrix/actions/workflows/ci.yml)
+[![Documentation](https://github.com/ryancswallace/benchmatrix/actions/workflows/docs.yml/badge.svg?branch=main)](https://github.com/ryancswallace/benchmatrix/actions/workflows/docs.yml)
+[![Docker](https://github.com/ryancswallace/benchmatrix/actions/workflows/docker.yml/badge.svg?branch=main)](https://github.com/ryancswallace/benchmatrix/actions/workflows/docker.yml)
+[![CodeQL](https://github.com/ryancswallace/benchmatrix/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/ryancswallace/benchmatrix/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://github.com/ryancswallace/benchmatrix/actions/workflows/scorecard.yml/badge.svg?branch=main)](https://github.com/ryancswallace/benchmatrix/actions/workflows/scorecard.yml)
+[![Workflow lint](https://github.com/ryancswallace/benchmatrix/actions/workflows/workflow-lint.yml/badge.svg?branch=main)](https://github.com/ryancswallace/benchmatrix/actions/workflows/workflow-lint.yml)
+[![Python 3.11-3.14](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-3776AB?logo=python&logoColor=white)](https://github.com/ryancswallace/benchmatrix/blob/main/pyproject.toml)
+[![Typed with basedpyright](https://img.shields.io/badge/types-basedpyright-2f6fdd)](https://github.com/DetachHead/basedpyright)
+[![Linted with Ruff](https://img.shields.io/badge/lint-Ruff-46a2f1)](https://docs.astral.sh/ruff/)
+[![Coverage gate: 95%](https://img.shields.io/badge/coverage%20gate-%E2%89%A595%25-2e7d32)](https://github.com/ryancswallace/benchmatrix/blob/main/pyproject.toml)
+[![SBOM: CycloneDX 1.6](https://img.shields.io/badge/SBOM-CycloneDX%201.6-6f42c1)](https://cyclonedx.org/)
+
+**Benchmark matrices for Python projects that need performance data they can
+trust, compare, and parse.**
+
+benchmatrix sits on top of
+[pytest-benchmark](https://pytest-benchmark.readthedocs.io/) and adds the layer
+that benchmark suites usually grow by hand: implementation-by-case matrices,
+strict JSON-safe metadata, metric-aware result parsing, and concise display of
+saved benchmark runs.
+
+| Build repeatable suites | Keep metrics honest | Parse saved runs |
+| --- | --- | --- |
+| Generate pytest benchmark tests across implementations, cases, and metric views. | Separate latency, throughput, and local distribution comparisons instead of mixing unlike numbers. | Load benchmatrix-tagged pytest-benchmark JSON rows into structured Python objects. |
+
+## Quick Start
+
+Create a benchmark matrix from ordinary synchronous callables:
+
+```python
+from benchmatrix import BenchmarkCase, make_benchmark_test
+
+implementations = {
+    "builtin": sum,
+    "loop": lambda vs: sum(v for v in vs),
+}
+
+cases = [
+    BenchmarkCase.from_values(
+        "small",
+        list(range(100)),
+        work_units=100,
+        work_unit_name="items",
+    ),
+]
+
+test_sum_matrix = make_benchmark_test(implementations, cases)
+```
+
+Run it with pytest-benchmark and keep the machine-readable output:
+
+```bash
+uv run pytest tests/test_sum_benchmark.py --benchmark-json benchmark.json
+```
+
+Read the tagged rows back later:
+
+```python
+from benchmatrix import display_benchmark_rows, load_benchmark_json
+
+rows = load_benchmark_json("benchmark.json")
+display_benchmark_rows(rows)
+```
+
+## Why It Exists
+
+pytest-benchmark owns timing, calibration, statistics, terminal reporting, and
+JSON export. benchmatrix owns the repeatable structure around those timings.
+
+| Need | benchmatrix gives you |
+| --- | --- |
+| Compare multiple implementations | One generated pytest benchmark matrix instead of repeated parametrization code. |
+| Track what each timing means | JSON-safe invocation metadata with implementation, case, and metric identity. |
+| Report different metric views | Single-call latency, logical-work throughput, and local tail-latency summaries. |
+| Reuse benchmark output | Parsers and display helpers for pytest-benchmark JSON produced by benchmatrix tests. |
+
+benchmatrix is intentionally narrow: it benchmarks synchronous Python callables.
+It is not a load-testing framework, production latency monitor, or replacement
+for pytest-benchmark.
+
+## Install
+
+For local development from this repository:
+
+```bash
+make ready
+```
+
+To try the package from another project before the first PyPI release, install
+from GitHub:
+
+```bash
+uv add "benchmatrix @ git+https://github.com/ryancswallace/benchmatrix"
+```
+
+## Documentation
+
+| Start here | Use it for |
+| --- | --- |
+| [First benchmark](docs/tutorials/first-benchmark.md) | A complete first benchmark from test file to parsed JSON. |
+| [Create a benchmark matrix](docs/how-to/create-benchmark-matrix.md) | Cases, work units, fresh inputs, and synchronous target wrappers. |
+| [Parse benchmark results](docs/how-to/parse-results.md) | Loading and displaying benchmatrix-tagged pytest-benchmark JSON. |
+| [Performance model](docs/explanation/performance.md) | What the metrics mean and what they do not prove. |
+| [Configuration and automation](docs/reference/configuration.md) | Make targets, CI workflows, Docker checks, docs, and SBOM generation. |
+
+The MkDocs site builds in strict mode and generates API reference pages from the
+package docstrings.
+
+## Project Links
+
+* [Examples](examples/)
+* [Contributing](CONTRIBUTING.md)
+* [Changelog](CHANGELOG.md)
+* [Security policy](SECURITY.md)
+* [Release policy](RELEASING.md)
+* [Code of conduct](CODE_OF_CONDUCT.md)
+* [Citation metadata](CITATION.cff)
+
+## License
+
+benchmatrix is distributed under the [MIT License](LICENSE).

benchmatrix-0.2.1/README.md

@@ -0,0 +1,123 @@
+# benchmatrix
+
+[![CI](https://github.com/ryancswallace/benchmatrix/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ryancswallace/benchmatrix/actions/workflows/ci.yml)
+[![Documentation](https://github.com/ryancswallace/benchmatrix/actions/workflows/docs.yml/badge.svg?branch=main)](https://github.com/ryancswallace/benchmatrix/actions/workflows/docs.yml)
+[![Docker](https://github.com/ryancswallace/benchmatrix/actions/workflows/docker.yml/badge.svg?branch=main)](https://github.com/ryancswallace/benchmatrix/actions/workflows/docker.yml)
+[![CodeQL](https://github.com/ryancswallace/benchmatrix/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/ryancswallace/benchmatrix/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://github.com/ryancswallace/benchmatrix/actions/workflows/scorecard.yml/badge.svg?branch=main)](https://github.com/ryancswallace/benchmatrix/actions/workflows/scorecard.yml)
+[![Workflow lint](https://github.com/ryancswallace/benchmatrix/actions/workflows/workflow-lint.yml/badge.svg?branch=main)](https://github.com/ryancswallace/benchmatrix/actions/workflows/workflow-lint.yml)
+[![Python 3.11-3.14](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-3776AB?logo=python&logoColor=white)](https://github.com/ryancswallace/benchmatrix/blob/main/pyproject.toml)
+[![Typed with basedpyright](https://img.shields.io/badge/types-basedpyright-2f6fdd)](https://github.com/DetachHead/basedpyright)
+[![Linted with Ruff](https://img.shields.io/badge/lint-Ruff-46a2f1)](https://docs.astral.sh/ruff/)
+[![Coverage gate: 95%](https://img.shields.io/badge/coverage%20gate-%E2%89%A595%25-2e7d32)](https://github.com/ryancswallace/benchmatrix/blob/main/pyproject.toml)
+[![SBOM: CycloneDX 1.6](https://img.shields.io/badge/SBOM-CycloneDX%201.6-6f42c1)](https://cyclonedx.org/)
+
+**Benchmark matrices for Python projects that need performance data they can
+trust, compare, and parse.**
+
+benchmatrix sits on top of
+[pytest-benchmark](https://pytest-benchmark.readthedocs.io/) and adds the layer
+that benchmark suites usually grow by hand: implementation-by-case matrices,
+strict JSON-safe metadata, metric-aware result parsing, and concise display of
+saved benchmark runs.
+
+| Build repeatable suites | Keep metrics honest | Parse saved runs |
+| --- | --- | --- |
+| Generate pytest benchmark tests across implementations, cases, and metric views. | Separate latency, throughput, and local distribution comparisons instead of mixing unlike numbers. | Load benchmatrix-tagged pytest-benchmark JSON rows into structured Python objects. |
+
+## Quick Start
+
+Create a benchmark matrix from ordinary synchronous callables:
+
+```python
+from benchmatrix import BenchmarkCase, make_benchmark_test
+
+implementations = {
+    "builtin": sum,
+    "loop": lambda vs: sum(v for v in vs),
+}
+
+cases = [
+    BenchmarkCase.from_values(
+        "small",
+        list(range(100)),
+        work_units=100,
+        work_unit_name="items",
+    ),
+]
+
+test_sum_matrix = make_benchmark_test(implementations, cases)
+```
+
+Run it with pytest-benchmark and keep the machine-readable output:
+
+```bash
+uv run pytest tests/test_sum_benchmark.py --benchmark-json benchmark.json
+```
+
+Read the tagged rows back later:
+
+```python
+from benchmatrix import display_benchmark_rows, load_benchmark_json
+
+rows = load_benchmark_json("benchmark.json")
+display_benchmark_rows(rows)
+```
+
+## Why It Exists
+
+pytest-benchmark owns timing, calibration, statistics, terminal reporting, and
+JSON export. benchmatrix owns the repeatable structure around those timings.
+
+| Need | benchmatrix gives you |
+| --- | --- |
+| Compare multiple implementations | One generated pytest benchmark matrix instead of repeated parametrization code. |
+| Track what each timing means | JSON-safe invocation metadata with implementation, case, and metric identity. |
+| Report different metric views | Single-call latency, logical-work throughput, and local tail-latency summaries. |
+| Reuse benchmark output | Parsers and display helpers for pytest-benchmark JSON produced by benchmatrix tests. |
+
+benchmatrix is intentionally narrow: it benchmarks synchronous Python callables.
+It is not a load-testing framework, production latency monitor, or replacement
+for pytest-benchmark.
+
+## Install
+
+For local development from this repository:
+
+```bash
+make ready
+```
+
+To try the package from another project before the first PyPI release, install
+from GitHub:
+
+```bash
+uv add "benchmatrix @ git+https://github.com/ryancswallace/benchmatrix"
+```
+
+## Documentation
+
+| Start here | Use it for |
+| --- | --- |
+| [First benchmark](docs/tutorials/first-benchmark.md) | A complete first benchmark from test file to parsed JSON. |
+| [Create a benchmark matrix](docs/how-to/create-benchmark-matrix.md) | Cases, work units, fresh inputs, and synchronous target wrappers. |
+| [Parse benchmark results](docs/how-to/parse-results.md) | Loading and displaying benchmatrix-tagged pytest-benchmark JSON. |
+| [Performance model](docs/explanation/performance.md) | What the metrics mean and what they do not prove. |
+| [Configuration and automation](docs/reference/configuration.md) | Make targets, CI workflows, Docker checks, docs, and SBOM generation. |
+
+The MkDocs site builds in strict mode and generates API reference pages from the
+package docstrings.
+
+## Project Links
+
+* [Examples](examples/)
+* [Contributing](CONTRIBUTING.md)
+* [Changelog](CHANGELOG.md)
+* [Security policy](SECURITY.md)
+* [Release policy](RELEASING.md)
+* [Code of conduct](CODE_OF_CONDUCT.md)
+* [Citation metadata](CITATION.cff)
+
+## License
+
+benchmatrix is distributed under the [MIT License](LICENSE).

benchmatrix-0.2.1/RELEASING.md

@@ -0,0 +1,61 @@
+# Release policy
+
+benchmatrix uses [Semantic Versioning](https://semver.org/).
+
+## Compatibility
+
+While the project is pre-1.0:
+
+* patch releases contain compatible fixes and documentation improvements;
+* minor releases may introduce breaking API changes;
+* breaking changes should be called out clearly in the changelog.
+
+Starting with 1.0, incompatible public API changes require a major release.
+The supported public API is the set of names exported from
+`benchmatrix.__init__`. Private modules and names beginning with an underscore
+are not covered by the compatibility guarantee.
+
+Python version support may change in a minor release before 1.0 and in a major
+release after 1.0. Dropping a Python version will be documented in advance when
+practical.
+
+Release branches are not maintained as standing support branches. The active
+support branch is `main`; temporary release or security branches may be used for
+coordination and retired after release.
+
+## Release process
+
+Releases are prepared in a normal pull request and published by the GitHub
+Actions release workflow after a GitHub Release is published.
+
+1. Choose the next version from the changelog and compatibility policy.
+2. Update release metadata:
+
+   * set `project.version` in `pyproject.toml`;
+   * set `version` in `CITATION.cff`;
+   * add or update `date-released` in `CITATION.cff` once the release date is
+     known.
+
+3. Move user-visible `CHANGELOG.md` entries from `Unreleased` into a versioned
+   section such as `## 0.2.0 - 2026-06-20`, then leave a fresh `Unreleased`
+   section at the top.
+4. Run the release validation commands:
+
+   ```bash
+   make check-all
+   make build
+   ```
+
+5. Confirm `dist/` contains one source distribution, one wheel, and
+   `benchmatrix.cdx.json` for the intended version.
+6. Merge the release pull request after required checks pass.
+7. Create and push an annotated tag named `vX.Y.Z` for the release commit.
+8. Draft GitHub release notes from the changelog section for that version.
+9. Publish the GitHub Release. Publishing the release triggers
+   `.github/workflows/release.yml`, which rebuilds artifacts, attests them, and
+   publishes to PyPI through Trusted Publishing.
+10. Verify the package from PyPI in a clean environment.
+11. If any post-release fix is needed, prepare a new patch release. Do not
+    replace files for an already-published PyPI version.
+
+The detailed operational checklist lives in `docs/runbooks/release.md`.

benchmatrix-0.2.1/SECURITY.md

@@ -0,0 +1,30 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are provided for the latest released version of benchmatrix.
+Because the project is currently pre-1.0, fixes are not routinely backported to
+older minor versions.
+
+The active support branch is `main`. Temporary security release branches may be
+created for coordinated disclosure, but they are not maintained after the fix is
+released unless the release notes explicitly say otherwise.
+
+A backport to an older release may be considered when the issue is high impact,
+the patch is small and safe, the affected release still has meaningful user
+adoption, and the maintainer has capacity to validate and publish the backport.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a suspected vulnerability.
+
+Email Ryan Wallace at <ryancswallace@gmail.com> with:
+
+* the affected version;
+* steps to reproduce the issue;
+* the potential impact;
+* any suggested mitigation, if known.
+
+You should receive an acknowledgement within seven days. The maintainer will
+coordinate validation, remediation, and disclosure with the reporter. Please
+allow a reasonable period for a fix before publishing details.

benchmatrix-0.2.1/docs/_scripts/gen_api_reference.py

@@ -0,0 +1,34 @@
+"""Generate mkdocstrings API reference pages for benchmatrix modules."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+PACKAGE_ROOT = Path("src/benchmatrix")
+REFERENCE_ROOT = Path("reference/api")
+
+
+def _iter_public_modules() -> list[tuple[str, Path, Path]]:
+    """Return import path, source path, and generated docs path tuples."""
+    modules: list[tuple[str, Path, Path]] = []
+    for source_path in sorted(PACKAGE_ROOT.glob("*.py")):
+        if source_path.name.startswith("_") and source_path.name != "__init__.py":
+            continue
+
+        module_parts = source_path.relative_to("src").with_suffix("").parts
+        import_path = ".".join(part for part in module_parts if part != "__init__")
+        if source_path.name == "__init__.py":
+            docs_path = REFERENCE_ROOT / "index.md"
+        else:
+            docs_path = REFERENCE_ROOT / f"{source_path.stem}.md"
+        modules.append((import_path, source_path, docs_path))
+    return modules
+
+
+for module, source, docs_path in _iter_public_modules():
+    title = "benchmatrix" if module == "benchmatrix" else module.rsplit(".", 1)[-1].replace("_", " ").title()
+    with mkdocs_gen_files.open(docs_path, "w") as output:
+        output.write(f"# {title}\n\n")
+        output.write(f"::: {module}\n")
+
+    mkdocs_gen_files.set_edit_path(docs_path, source)

benchmatrix-0.2.1/docs/changelog.md

@@ -0,0 +1,13 @@
+# Changelog
+
+The repository changelog is the source of truth for release notes.
+
+For each user-visible change:
+
+1. add an entry under `Unreleased` in `CHANGELOG.md`;
+2. group the entry under the appropriate heading;
+3. mention compatibility or migration notes when behavior changes;
+4. move entries into a versioned section during release preparation.
+
+The project follows Semantic Versioning with the pre-1.0 expectations described
+in the release policy.