Merge branch 'dev' into feat/feasibility-check

# Conflicts:
#	pyproject.toml

Author: Samoed

.ci/compute_matrix.py

@@ -0,0 +1,139 @@
+# ruff: noqa: INP001
+# .ci/ is a top-level script directory invoked by GitHub Actions, not a
+# Python package, so no __init__.py here (mirrors .ci/warm_hf_cache.py).
+"""Decide test matrix scope and emit it to ``GITHUB_OUTPUT``.
+
+Full matrix runs on push to ``dev`` and on PRs labeled ``full-ci``.
+Otherwise (default PR commits) only ubuntu-latest + Python 3.14 runs.
+On ``workflow_dispatch`` (the manual coverage run) a single
+ubuntu-latest + ``DISPATCH_PYTHON`` combo runs: coverage is the union of
+lines exercised, so it is OS/Python-independent and one combo keeps the
+manual job cheap.
+
+Inputs come from environment variables:
+
+* ``EVENT_NAME`` - the GitHub event name (``push`` / ``pull_request`` /
+  ``workflow_dispatch``).
+* ``LABELS_JSON`` - ``toJSON(github.event.pull_request.labels.*.name)``
+  from the workflow; ``null`` / missing on non-PR events.
+* ``DISPATCH_PYTHON`` - Python version for the ``workflow_dispatch`` combo;
+  falls back to ``DISPATCH_DEFAULT_PYTHON`` when unset/empty.
+* ``GITHUB_OUTPUT`` - file the runner reads to pick up step outputs.
+
+The script writes ``matrix``, ``warm_os`` and ``full`` to that output
+file and mirrors them to the log for debuggability.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+
+FULL_MATRIX = {
+    "os": ["ubuntu-latest"],
+    "python-version": ["3.10", "3.11", "3.12", "3.13", "3.14"],
+    "include": [{"os": "windows-latest", "python-version": "3.10"}],
+}
+
+MINIMAL_MATRIX = {
+    "os": ["ubuntu-latest"],
+    "python-version": ["3.14"],
+}
+
+FULL_CI_LABEL = "full-ci"
+
+DISPATCH_EVENT = "workflow_dispatch"
+DISPATCH_DEFAULT_PYTHON = "3.12"
+
+
+def dispatch_matrix(python_version: str) -> dict:
+    """Return the single-combo matrix for the manual coverage run."""
+    return {"os": ["ubuntu-latest"], "python-version": [python_version or DISPATCH_DEFAULT_PYTHON]}
+
+
+logger = logging.getLogger("compute_matrix")
+
+
+def collect_os_list(matrix: dict) -> list[str]:
+    """Return the unique runner OSes referenced by ``matrix`` (base + includes)."""
+    seen: list[str] = []
+    for entry in matrix.get("os", []):
+        if entry not in seen:
+            seen.append(entry)
+    for include in matrix.get("include", []):
+        entry = include.get("os")
+        if entry and entry not in seen:
+            seen.append(entry)
+    return seen
+
+
+def is_full(event_name: str, labels: list[str]) -> bool:
+    """Return True iff this run should fan out across the full OS/Python matrix."""
+    # Any push that reaches this workflow is a push to `dev` (ci.yaml pins
+    # on.push.branches: [dev]), so the branch is implied and not re-checked
+    # here. If more push branches are ever added there, revisit this.
+    if event_name == "push":
+        return True
+    return FULL_CI_LABEL in labels
+
+
+def parse_labels(raw: str) -> list[str]:
+    """Parse the ``LABELS_JSON`` env var into a list of label names.
+
+    Returns an empty list when the value is missing, ``"null"`` (the
+    ``toJSON`` rendering of a missing PR object), malformed, or not a
+    JSON array of strings.
+    """
+    if not raw:
+        return []
+    try:
+        decoded = json.loads(raw)
+    except json.JSONDecodeError:
+        return []
+    if not isinstance(decoded, list):
+        return []
+    return [item for item in decoded if isinstance(item, str)]
+
+
+def main() -> int:
+    """Compute matrix from env, log a summary, write outputs; return exit code."""
+    logging.basicConfig(level=logging.INFO, format="%(message)s", stream=sys.stderr)
+
+    event_name = os.environ.get("EVENT_NAME", "")
+    labels = parse_labels(os.environ.get("LABELS_JSON", ""))
+
+    if event_name == DISPATCH_EVENT:
+        full = False
+        matrix = dispatch_matrix(os.environ.get("DISPATCH_PYTHON", ""))
+    else:
+        full = is_full(event_name, labels)
+        matrix = FULL_MATRIX if full else MINIMAL_MATRIX
+    warm_os = collect_os_list(matrix)
+
+    payload = {
+        "matrix": json.dumps(matrix),
+        "warm_os": json.dumps(warm_os),
+        "full": "true" if full else "false",
+    }
+
+    logger.info("event_name=%s", event_name)
+    logger.info("labels=%s", labels)
+    logger.info("full=%s", full)
+    logger.info("matrix=%s", payload["matrix"])
+    logger.info("warm_os=%s", payload["warm_os"])
+
+    output_path = os.environ.get("GITHUB_OUTPUT")
+    if not output_path:
+        logger.error("GITHUB_OUTPUT is not set; cannot emit step outputs")
+        return 1
+    lines = "".join(f"{key}={value}\n" for key, value in payload.items())
+    with Path(output_path).open("a", encoding="utf-8") as fh:
+        fh.write(lines)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.ci/coverage_report.py

@@ -0,0 +1,76 @@
+# ruff: noqa: INP001
+# .ci/ is a top-level script directory invoked by GitHub Actions, not a
+# Python package, so no __init__.py here (mirrors .ci/compute_matrix.py).
+"""Combine per-group coverage data files and publish a combined report.
+
+The coverage run (``ci.yaml`` dispatched with ``coverage=true``) has every test
+job upload a ``.coverage.<group>`` data file as an artifact. This script runs in
+the ``coverage-report`` job after those artifacts are downloaded into the
+working directory. It combines them into one dataset, prints the table to the
+job log, writes ``coverage.xml`` + an HTML report (uploaded as an artifact), and
+appends a compact summary to ``GITHUB_STEP_SUMMARY`` so the total is visible in
+the Actions UI without opening the logs.
+
+Run via ``uv run --no-project --with 'coverage[toml]' python .ci/coverage_report.py``;
+coverage settings are read from ``[tool.coverage.*]`` in ``pyproject.toml``.
+
+The script also enforces a regression floor on the *combined* total
+(``MIN_TOTAL_COVERAGE``): a dispatch whose total drops below it fails this job.
+The threshold lives here rather than in ``[tool.coverage.report] fail_under``
+on purpose — pytest-cov reads that key, and each per-job ``--cov`` run measures
+only a slice of the package, so a config-level ``fail_under`` would fail every
+partial run. Enforcing here gates the combined total only.
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+import os
+import sys
+from pathlib import Path
+
+import coverage
+
+logger = logging.getLogger("coverage_report")
+
+# Minimum acceptable combined coverage (%). Bump this as coverage improves to
+# ratchet the floor up; keep it a few points below the current total so normal
+# churn doesn't trip it.
+MIN_TOTAL_COVERAGE = 85.0
+
+
+def main() -> int:
+    """Combine coverage data, emit reports, write the GitHub step summary, gate the total."""
+    logging.basicConfig(level=logging.INFO, format="%(message)s", stream=sys.stderr)
+
+    cov = coverage.Coverage()
+    cov.combine()  # merge the downloaded `.coverage.*` files into the data file
+    cov.load()
+
+    total = cov.report()  # full table (config `show_missing`) -> job log
+    cov.xml_report()
+    cov.html_report()
+
+    logger.info("Total coverage: %.2f%%", total)
+    passed = total >= MIN_TOTAL_COVERAGE
+
+    summary_path = os.environ.get("GITHUB_STEP_SUMMARY")
+    if summary_path:
+        compact = io.StringIO()
+        cov.report(file=compact, show_missing=False)
+        gate_icon = "✅" if passed else "❌"
+        gate_line = f"{gate_icon} Gate: {total:.2f}% vs {MIN_TOTAL_COVERAGE:.2f}% minimum\n"
+        body = f"### Test coverage: {total:.2f}%\n\n{gate_line}\n```\n{compact.getvalue()}```\n"
+        with Path(summary_path).open("a", encoding="utf-8") as fh:
+            fh.write(body)
+
+    if not passed:
+        logger.error("Coverage %.2f%% is below the required minimum of %.2f%%", total, MIN_TOTAL_COVERAGE)
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/workflows/build-docs.yaml

@@ -10,6 +10,10 @@ on:
   pull_request:
     branches:
       - dev
+    # `labeled` lets adding the `full-ci` label re-trigger the docs build on
+    # an open PR; ordinary PR commits skip it (see build-docs.if) to avoid the
+    # ~20 min `make test-docs` run on every push.
+    types: [opened, synchronize, reopened, labeled]
   workflow_dispatch:
 
 concurrency:
@@ -23,6 +27,14 @@ jobs:
   build-docs:
     name: Build Documentation
     runs-on: ubuntu-latest
+    # The docs build (~20 min) is gated behind `full-ci` on PRs: it still runs
+    # on every push to dev, on releases, and on manual dispatch, but on a PR it
+    # only runs when the `full-ci` label is present. build-docs is not a
+    # required check (only ruff/mypy/all-tests are), so skipping it on a regular
+    # PR does not block merge; docs breakage is caught on the push to dev.
+    if: >-
+      github.event_name != 'pull_request'
+      || contains(github.event.pull_request.labels.*.name, 'full-ci')
 
     steps:
       - name: Checkout code