From 47cdd907343cd1b402d5cee9f95ce9caed9b2c3c Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Wed, 4 Nov 2026 00:04:37 +0000 Subject: [PATCH 1/4] CI: publish the coverage numbers into the pull request's description Add scripts/publish_coverage_numbers_to_pr.py: after the tests and diff-cover steps on a pull request, read coverage.json and diff-cover.json, render one block between marker comments with the changed-lines figure and the whole-package figure, and replace that block in the pull request's description through the REST API, appending it when absent. The author's text outside the block is never touched. The pytest job gains pull-requests: write for that step; coverage.json joins the artifact. Nine mirror tests in triple form; mypy clean; the conventions check reports 0 breaches. The merge-commit half is a repository setting the owner flips: default merge message from the pull request's title and description. Co-Authored-By: Claude Fable 5.1 --- .github/workflows/tests.yml | 17 ++ CURRENT-STATUS.md | 2 +- devcapsule-src/noxfile.py | 1 + devcapsule-src/pyproject.toml | 2 +- .../scripts/publish_coverage_numbers_to_pr.py | 152 ++++++++++++++++++ .../test_publish_coverage_numbers_to_pr.py | 139 ++++++++++++++++ engineering-docs/development/unit-tests.md | 7 + .../2026-09-18-maintenance/CURRENT-STATUS.md | 25 ++- 8 files changed, 341 insertions(+), 4 deletions(-) create mode 100644 devcapsule-src/scripts/publish_coverage_numbers_to_pr.py create mode 100644 devcapsule-src/tests/unit/scripts/test_publish_coverage_numbers_to_pr.py diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index ca105a93..41a56871 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -112,6 +112,10 @@ jobs: needs: changes if: needs.changes.outputs.python == 'true' runs-on: ubuntu-24.04 + permissions: + contents: read + # The coverage numbers are written into the pull request's description. + pull-requests: write defaults: run: working-directory: devcapsule-src @@ -169,6 +173,18 @@ jobs: --format markdown:diff-cover.md,json:diff-cover.json python scripts/diff_coverage_annotations.py + # Both figures go into the PR description between marker comments, so + # a merge that takes the description as its message carries them too. + - name: Publish coverage numbers to the pull request + if: github.event_name == 'pull_request' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PR_NUMBER: ${{ github.event.pull_request.number }} + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + run: | + python -m coverage json -o coverage.json + python scripts/publish_coverage_numbers_to_pr.py + - name: Publish coverage summary if: ${{ always() && hashFiles('devcapsule-src/.coverage') != '' }} run: | @@ -185,6 +201,7 @@ jobs: name: python-coverage path: | devcapsule-src/coverage.xml + devcapsule-src/coverage.json devcapsule-src/htmlcov/ devcapsule-src/diff-cover.md devcapsule-src/diff-cover.json diff --git a/CURRENT-STATUS.md b/CURRENT-STATUS.md index 5990e590..14a60015 100644 --- a/CURRENT-STATUS.md +++ b/CURRENT-STATUS.md @@ -11,7 +11,7 @@ coordination branch. Detailed state belongs in each linked status file. |---|---|---|---|---|---| | `workflow-improvements` | 2026-08-09 | Improve the multiple-stream workflow from concrete dogfood findings during the recursive E2E cycle | active 2026-10-30; Pair Review Loop naming implemented and packaging verified for 0.3.0; mainline and release integration pending | `ws-workflow-improvements/v1` | [workstream status](engineering-docs/wip/2026-08-09-workflow-improvements/CURRENT-STATUS.md) | | `project-management` | 2026-08-09 | Maintain project-wide priorities, sequencing, dependencies, and lifecycle coordination | paused 2026-10-11 at owner direction; consent and forced configuration before RC work; remaining diagnostics/image scope and release cut decisions retained | `ws-project-management/coordination` | [workstream status](engineering-docs/wip/2026-08-09-project-management/CURRENT-STATUS.md) | -| `maintenance` | 2026-09-18 | Own the defects no open workstream covers, on `main` and on maintained release lines, and drive maintenance releases | active 2026-11-03; unit-test conventions slice, PR #335, awaits the owner's merge; 0.3.1 queue preserved | `ws-maintenance/test-conventions`; `ws-maintenance/0.3.1-preparation` carried into it; `release-0.3.0` closed and retained | [workstream status](engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md) | +| `maintenance` | 2026-09-18 | Own the defects no open workstream covers, on `main` and on maintained release lines, and drive maintenance releases | active 2026-11-04; #335 merged; coverage-numbers slice awaits the owner's merge; 0.3.1 queue preserved | `ws-maintenance/coverage-in-pr`; `ws-maintenance/test-conventions` merged through #335 and closed; `release-0.3.0` closed and retained | [workstream status](engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md) | | `component-upgrades` | 2026-09-21 | Deliver component distribution channels, developer-owned version sets and proven upgrade rollback; Codex first | paused 2026-10-02; consent design ruled (D-0011 to D-0013), 0.2.16 consent slice next; R-UPGRADE-002 follow-up retained | `ws-component-upgrades/v1` | [workstream status](engineering-docs/wip/2026-09-21-component-upgrades/CURRENT-STATUS.md) | | `sample-projects` | 2026-08-14 | Provide realistic sample projects as submodules that demonstrate ordinary adopter development inside DevCapsule | integrating 2026-10-22; AI Learning published; PR #252 reviewed and ready for human merge | `ws-sample-projects/ai-learning` | [workstream status](engineering-docs/wip/2026-08-14-sample-projects/CURRENT-STATUS.md) | | `contained-display` | 2026-08-19 | Own the capsule supervisor core (container entry process, supervised children, explicit session end, headless mode) and the capsule's own display environment, closing the host-session credential exposure — supervisor first, display as its first consumer | active; **the contained display shipped in v0.2.12 on 2026-09-14** (recipe-9 base, contained desktop by default, X11 passthrough behind `host-x11`); the X11 credential bug is resolved; remaining threads are records and follow-ups (reconnect, WSL2 opener, sample locks) | `ws-contained-display/display-transport` | [workstream status](engineering-docs/wip/2026-08-19-contained-display/CURRENT-STATUS.md) | diff --git a/devcapsule-src/noxfile.py b/devcapsule-src/noxfile.py index eca38273..743e2d4d 100644 --- a/devcapsule-src/noxfile.py +++ b/devcapsule-src/noxfile.py @@ -176,6 +176,7 @@ def run_typecheck(session: nox.Session) -> None: str(VERSION_SCRIPT), str(PROJECT_ROOT / "scripts" / "release-manifest.py"), str(PROJECT_ROOT / "scripts" / "validate_unittests_follow_conventions.py"), + str(PROJECT_ROOT / "scripts" / "publish_coverage_numbers_to_pr.py"), str(PROJECT_ROOT / "scripts" / "release-protocol.py"), str(PROJECT_ROOT / "scripts" / "prepare-promotion.py"), ) diff --git a/devcapsule-src/pyproject.toml b/devcapsule-src/pyproject.toml index fd007a5c..e468bdeb 100644 --- a/devcapsule-src/pyproject.toml +++ b/devcapsule-src/pyproject.toml @@ -107,7 +107,7 @@ skip_covered = true [tool.mypy] python_version = "3.12" -files = ["devcapsule", "tests", "noxfile.py", "scripts/bump-version.py", "scripts/release-manifest.py", "scripts/ci_gate.py", "scripts/diff_coverage_annotations.py", "scripts/validate_unittests_follow_conventions.py"] +files = ["devcapsule", "tests", "noxfile.py", "scripts/bump-version.py", "scripts/release-manifest.py", "scripts/ci_gate.py", "scripts/diff_coverage_annotations.py", "scripts/validate_unittests_follow_conventions.py", "scripts/publish_coverage_numbers_to_pr.py"] # Sample projects are independent submodules with their own dependencies. They # are checked by their own tooling, not by DevCapsule's gate. exclude = "(^|/)tests/resources/sample_projects/" diff --git a/devcapsule-src/scripts/publish_coverage_numbers_to_pr.py b/devcapsule-src/scripts/publish_coverage_numbers_to_pr.py new file mode 100644 index 00000000..1902f6ca --- /dev/null +++ b/devcapsule-src/scripts/publish_coverage_numbers_to_pr.py @@ -0,0 +1,152 @@ +"""Publish a pull request's coverage numbers into its description. + +Run from ``devcapsule-src`` after the tests and diff-cover steps, on a +``pull_request`` event only:: + + python -m coverage json -o coverage.json + python scripts/publish_coverage_numbers_to_pr.py + +The step reads ``coverage.json``, coverage.py's report of the whole +``devcapsule`` package, and ``diff-cover.json``, the report over the lines +the pull request changed. It renders one Markdown block between two marker +comments and replaces that block in the pull request's description, or +appends it when the description has none. The text outside the block is the +author's and is never touched. With the repository set to take the pull +request's description as the merge commit message, the numbers reach +``main``'s history unchanged. + +Environment: ``GITHUB_REPOSITORY``, ``PR_NUMBER``, ``GITHUB_TOKEN`` with +``pull-requests: write``, and ``RUN_URL`` for the link. No percentage fails +this step. A missing or malformed report, or a refused API call, does. +""" +from __future__ import annotations + +import argparse +import json +import os +import sys +import urllib.request +from collections.abc import Mapping +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +__all__ = ["Numbers", "read_numbers", "render", "upsert", "main"] + +BEGIN = "" +END = "" +"""The markers that bound the block; everything between them is replaced on each run.""" + +_API_VERSION = "2022-11-28" + + +@dataclass(frozen=True) +class Numbers: + """The two figures and what they are made of.""" + + overall_percent: float + """Statements of the ``devcapsule`` package covered, branch-aware as coverage.py reports it.""" + covered_statements: int + statements: int + diff_percent: int + """Changed measured lines covered, as diff-cover reports it.""" + diff_lines: int + """Changed lines the coverage report measures; test files and unmeasured lines are not among them.""" + diff_uncovered: int + + +def read_numbers(coverage: Mapping[str, Any], diff: Mapping[str, Any]) -> Numbers: + """The figures from coverage.py's JSON ``totals`` and diff-cover's JSON totals. + + Raises ``ValueError`` naming the first key a report lacks or mistypes. + """ + totals = coverage.get("totals") + if not isinstance(totals, Mapping): + raise ValueError("coverage.json: no 'totals' table") + try: + return Numbers( + overall_percent=float(totals["percent_covered"]), + covered_statements=int(totals["covered_lines"]), + statements=int(totals["num_statements"]), + diff_percent=int(diff["total_percent_covered"]), + diff_lines=int(diff["total_num_lines"]), + diff_uncovered=int(diff["total_num_violations"]), + ) + except KeyError as missing: + raise ValueError(f"report lacks {missing.args[0]!r}") from None + except (TypeError, ValueError) as wrong: + raise ValueError(f"report value is not a number: {wrong}") from None + + +def render(numbers: Numbers, run_url: str) -> str: + """The Markdown block, markers included, for one run.""" + return "\n".join([ + BEGIN, + f"### Test coverage, from [CI run]({run_url})", + "", + "| | |", + "|---|---|", + f"| Changed lines covered | **{numbers.diff_percent}%** " + f"({numbers.diff_lines - numbers.diff_uncovered} of {numbers.diff_lines} measured changed lines; " + f"{numbers.diff_uncovered} uncovered) |", + f"| Overall `devcapsule` | **{numbers.overall_percent:.1f}%** " + f"({numbers.covered_statements:,} of {numbers.statements:,} statements) |", + END, + ]) + + +def upsert(body: str | None, block: str) -> str: + """The description with the block replaced between the markers, or appended after a blank line.""" + text = body or "" + start = text.find(BEGIN) + end = text.find(END, start) + if start != -1 and end != -1: + return text[:start] + block + text[end + len(END):] + return block if not text.strip() else text.rstrip("\n") + "\n\n" + block + + +def _request(method: str, url: str, token: str, payload: Mapping[str, Any] | None = None) -> dict[str, Any]: + data = None if payload is None else json.dumps(payload).encode() + request = urllib.request.Request(url, data=data, method=method, headers={ + "Authorization": f"Bearer {token}", + "Accept": "application/vnd.github+json", + "X-GitHub-Api-Version": _API_VERSION, + "Content-Type": "application/json", + }) + with urllib.request.urlopen(request) as response: # noqa: S310 - the URL is api.github.com, built here + return json.load(response) + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__.split("\n\n", 1)[0]) + parser.add_argument("--coverage", type=Path, default=Path("coverage.json")) + parser.add_argument("--diff", type=Path, default=Path("diff-cover.json")) + arguments = parser.parse_args(argv) + try: + numbers = read_numbers( + json.loads(arguments.coverage.read_text(encoding="utf-8")), + json.loads(arguments.diff.read_text(encoding="utf-8")), + ) + repository, number, token = (os.environ[name] for name in ("GITHUB_REPOSITORY", "PR_NUMBER", "GITHUB_TOKEN")) + run_url = os.environ.get("RUN_URL", "") + except (OSError, ValueError, KeyError) as problem: + print(f"coverage numbers: {problem}", file=sys.stderr) + return 1 + block = render(numbers, run_url) + url = f"https://api.github.com/repos/{repository}/pulls/{number}" + current = _request("GET", url, token).get("body") + updated = upsert(current, block) + if updated == current: + print("coverage numbers: the description already carries this run's numbers") + return 0 + try: + _request("PATCH", url, token, {"body": updated}) + except OSError as refused: + print(f"coverage numbers: the API refused the update: {refused}", file=sys.stderr) + return 1 + print(f"coverage numbers: changed lines {numbers.diff_percent}%, overall {numbers.overall_percent:.1f}%, published to #{number}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/devcapsule-src/tests/unit/scripts/test_publish_coverage_numbers_to_pr.py b/devcapsule-src/tests/unit/scripts/test_publish_coverage_numbers_to_pr.py new file mode 100644 index 00000000..ea7d1aba --- /dev/null +++ b/devcapsule-src/tests/unit/scripts/test_publish_coverage_numbers_to_pr.py @@ -0,0 +1,139 @@ +"""Unit tests of ``scripts/publish_coverage_numbers_to_pr.py``: the figures, the block, the upsert, the step.""" +from __future__ import annotations + +import importlib.util +import json +import sys +from pathlib import Path +from typing import Any + +import pytest + +_SCRIPT = Path(__file__).resolve().parents[3] / "scripts" / "publish_coverage_numbers_to_pr.py" + + +def _load(path: Path) -> Any: + """The script as a module; registered in ``sys.modules`` so its dataclasses resolve their annotations.""" + spec = importlib.util.spec_from_file_location(path.stem, path) + assert spec and spec.loader + module = importlib.util.module_from_spec(spec) + sys.modules[spec.name] = module + spec.loader.exec_module(module) + return module + + +publish = _load(_SCRIPT) + +COVERAGE = {"totals": {"percent_covered": 82.456, "covered_lines": 16012, "num_statements": 19488}} +DIFF = {"total_percent_covered": 87, "total_num_lines": 150, "total_num_violations": 20} + + +def test_the_figures_are_read_from_both_reports() -> None: + """Precondition: coverage.py totals and diff-cover totals as their JSON gives them. + Action: read. Postcondition: the six figures, typed, with nothing derived yet.""" + numbers = publish.read_numbers(COVERAGE, DIFF) + assert numbers == publish.Numbers(82.456, 16012, 19488, 87, 150, 20) + + +@pytest.mark.parametrize("coverage,diff,missing", [ + ({}, DIFF, "'totals'"), + ({"totals": {"percent_covered": 1.0}}, DIFF, "'covered_lines'"), + (COVERAGE, {"total_percent_covered": 1}, "'total_num_lines'"), +]) +def test_a_report_lacking_a_figure_is_refused_by_name(coverage: dict, diff: dict, missing: str) -> None: + """Precondition: one report lacks a key. Action: read. Postcondition: ValueError names that key.""" + with pytest.raises(ValueError, match=missing): + publish.read_numbers(coverage, diff) + + +def test_the_block_carries_both_percentages_between_the_markers() -> None: + """Precondition: the figures and a run URL. Action: render. Postcondition: the block + starts and ends with the markers, links the run, and states 87% of changed lines + with 130 of 150 covered, and 82.5% overall with the statement counts.""" + block = publish.render(publish.Numbers(82.456, 16012, 19488, 87, 150, 20), "https://ci/run/1") + lines = block.splitlines() + assert lines[0] == publish.BEGIN and lines[-1] == publish.END + assert "[CI run](https://ci/run/1)" in block + assert "**87%** (130 of 150 measured changed lines; 20 uncovered)" in block + assert "**82.5%** (16,012 of 19,488 statements)" in block + + +def test_upsert_appends_the_block_after_the_authors_text() -> None: + """Precondition: a description without markers. Action: upsert. + Postcondition: the author's text is intact, one blank line, then the block.""" + block = f"{publish.BEGIN}\nnumbers\n{publish.END}" + assert publish.upsert("## Why\n\nBecause.\n", block) == f"## Why\n\nBecause.\n\n{block}" + + +def test_upsert_replaces_only_the_block_between_the_markers() -> None: + """Precondition: a description with an older block between text above and below. + Action: upsert the new block. Postcondition: the text above and below is byte for + byte what it was and the old block is gone.""" + old = f"{publish.BEGIN}\nold\n{publish.END}" + new = f"{publish.BEGIN}\nnew\n{publish.END}" + assert publish.upsert(f"above\n\n{old}\n\nbelow\n", new) == f"above\n\n{new}\n\nbelow\n" + + +def test_upsert_on_an_empty_description_is_the_block_alone() -> None: + """Precondition: the API returned no body. Action: upsert. Postcondition: the block alone.""" + block = f"{publish.BEGIN}\nnumbers\n{publish.END}" + assert publish.upsert(None, block) == block + + +def _reports(tmp_path: Path) -> list[str]: + (tmp_path / "coverage.json").write_text(json.dumps(COVERAGE)) + (tmp_path / "diff-cover.json").write_text(json.dumps(DIFF)) + return ["--coverage", str(tmp_path / "coverage.json"), "--diff", str(tmp_path / "diff-cover.json")] + + +def _environment(monkeypatch: pytest.MonkeyPatch) -> None: + for name, value in (("GITHUB_REPOSITORY", "o/r"), ("PR_NUMBER", "7"), ("GITHUB_TOKEN", "t"), ("RUN_URL", "https://ci/run/1")): + monkeypatch.setenv(name, value) + + +def test_main_reads_the_description_and_patches_it_with_the_block(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + """Precondition: both reports on disk, the environment set, a description without the block. + Action: run ``main`` with the API replaced by a recorder. Postcondition: one GET then one + PATCH of ``/repos/o/r/pulls/7`` whose body is the description plus the block; exit 0.""" + calls: list[tuple[str, str, dict | None]] = [] + + def api(method: str, url: str, token: str, payload: dict | None = None) -> dict: + calls.append((method, url, payload)) + return {"body": "The PR.\n"} if method == "GET" else {} + + monkeypatch.setattr(publish, "_request", api) + _environment(monkeypatch) + assert publish.main(_reports(tmp_path)) == 0 + assert [(m, u) for m, u, _ in calls] == [("GET", "https://api.github.com/repos/o/r/pulls/7"), + ("PATCH", "https://api.github.com/repos/o/r/pulls/7")] + body = calls[1][2]["body"] # type: ignore[index] + assert body.startswith("The PR.\n\n" + publish.BEGIN) and body.endswith(publish.END) + + +def test_main_does_not_patch_a_description_that_already_carries_this_block(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + """Precondition: the description already holds exactly this run's block. Action: run ``main``. + Postcondition: only the GET is made and the exit is 0.""" + block = publish.render(publish.read_numbers(COVERAGE, DIFF), "https://ci/run/1") + calls: list[str] = [] + + def api(method: str, url: str, token: str, payload: dict | None = None) -> dict: + calls.append(method) + return {"body": block} + + monkeypatch.setattr(publish, "_request", api) + _environment(monkeypatch) + assert publish.main(_reports(tmp_path)) == 0 + assert calls == ["GET"] + + +def test_main_fails_without_a_report_or_the_environment(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]) -> None: + """Precondition: the reports exist but the token is absent; then the reports are absent. + Action: run ``main`` twice. Postcondition: exit 1 each time with the cause on stderr, no API call.""" + monkeypatch.setattr(publish, "_request", lambda *a, **k: pytest.fail("no API call expected")) + _environment(monkeypatch) + monkeypatch.delenv("GITHUB_TOKEN") + assert publish.main(_reports(tmp_path)) == 1 + assert "GITHUB_TOKEN" in capsys.readouterr().err + monkeypatch.setenv("GITHUB_TOKEN", "t") + assert publish.main(["--coverage", str(tmp_path / "none.json"), "--diff", str(tmp_path / "diff-cover.json")]) == 1 + assert "none.json" in capsys.readouterr().err diff --git a/engineering-docs/development/unit-tests.md b/engineering-docs/development/unit-tests.md index be1afc81..9126e306 100644 --- a/engineering-docs/development/unit-tests.md +++ b/engineering-docs/development/unit-tests.md @@ -28,6 +28,13 @@ unit suite; the heavier suites are chosen by marker, never by accident. The `flaky` marker runs a test for visibility with a temporarily non-blocking result; the other markers belong to the heavier suites. +On a pull request the hosted workflow also writes both coverage figures, +changed lines covered and the whole package, into the pull request's +description between two marker comments, through +`scripts/publish_coverage_numbers_to_pr.py`; a merge that takes the +description as its message carries them into `main`'s history. The block is +replaced on every run and the author's text around it is never touched. + The hosted `tests.yml` workflow selects the existing serial unit suite when runtime, test, build or unclassified inputs change. It runs no Docker. Planning/status-only PRs skip heavy jobs; website inputs run the website's diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 56bec76e..07142010 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -4,7 +4,7 @@ Mnemonic: `maintenance` Start date: 2026-09-18 -State: active 2026-11-03; unit-test conventions slice delivered for the owner's merge; 0.3.1 queue preserved +State: active 2026-11-04; PR #335 merged at 650e2be3; coverage-numbers slice delivered for the owner's merge; 0.3.1 queue preserved Definition read: WORKFLOW.md@d2ccbbe43dfa, WORKFLOW-LOCAL.md@65501b3407db @@ -12,10 +12,31 @@ Integration target: `main` Delivery method: ordinary maintenance PRs to `main`; owner merges. No records-only PR. The 0.3.0 release is published; website production promotion remains owner-operated. -Branch association: `ws-maintenance/test-conventions`, from `ws-maintenance/0.3.1-preparation` merged with main b3f10b7d, carrying the 0.3.1 preparation records to main with this slice; `ws-maintenance/0.3.1-preparation` from main 31d44fa4; `release-0.3.0` closed after final publication and retained with its tags; `ws-maintenance/0.3.0-acceptance` merged through #332 and closed; earlier slice branches are historical +Branch association: `ws-maintenance/coverage-in-pr` from main 650e2be3; `ws-maintenance/test-conventions` merged through #335 and closed; `ws-maintenance/0.3.1-preparation` from main 31d44fa4; `release-0.3.0` closed after final publication and retained with its tags; `ws-maintenance/0.3.0-acceptance` merged through #332 and closed; earlier slice branches are historical Requirements: `R-PRODUCT-006`, `R-COMPAT-001`, `R-PRODUCT-002`, `R-CONSOLE-001` +## Coverage numbers in the pull request — 2026-11-04 + +The owner merged #335 at 650e2be3 and asked for the next slice from the +2026-11-03 question: the diff coverage and the overall coverage in the pull +request's summary, and later in the merge commit's detail. CI already +computed both, the overall figure into the job summary and diff-cover's +report into an artifact and annotations; nothing reached the pull request. + +Delivered on `ws-maintenance/coverage-in-pr` as a PR to `main`: +`scripts/publish_coverage_numbers_to_pr.py` reads `coverage.json` and +`diff-cover.json`, renders one block between `` +and ``, and replaces that block in the pull +request's description through the REST API, appending it when absent; the +author's text is never touched. The pytest job gains `pull-requests: write` +and runs the step on pull requests after diff coverage. Its tests are the +third mirror file, 9 cases in triple form. The merge commit part needs no +code: the owner sets the repository's default merge commit message to the +pull request's title and description, and the block travels into `main`'s +history as it stands at merge time. Until that setting is flipped, the +numbers are in the pull request only. + ## Unit-test conventions — 2026-11-03 The owner resumed from travel and ran `nox -s build` in the dogfood capsule: From 318248659e6f2d43966a2a56d02a7f9e715db864 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Wed, 4 Nov 2026 00:04:48 +0000 Subject: [PATCH 2/4] Record PR #336 in the maintenance status and the workstream list Co-Authored-By: Claude Fable 5.1 --- CURRENT-STATUS.md | 2 +- engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/CURRENT-STATUS.md b/CURRENT-STATUS.md index 14a60015..1b843315 100644 --- a/CURRENT-STATUS.md +++ b/CURRENT-STATUS.md @@ -11,7 +11,7 @@ coordination branch. Detailed state belongs in each linked status file. |---|---|---|---|---|---| | `workflow-improvements` | 2026-08-09 | Improve the multiple-stream workflow from concrete dogfood findings during the recursive E2E cycle | active 2026-10-30; Pair Review Loop naming implemented and packaging verified for 0.3.0; mainline and release integration pending | `ws-workflow-improvements/v1` | [workstream status](engineering-docs/wip/2026-08-09-workflow-improvements/CURRENT-STATUS.md) | | `project-management` | 2026-08-09 | Maintain project-wide priorities, sequencing, dependencies, and lifecycle coordination | paused 2026-10-11 at owner direction; consent and forced configuration before RC work; remaining diagnostics/image scope and release cut decisions retained | `ws-project-management/coordination` | [workstream status](engineering-docs/wip/2026-08-09-project-management/CURRENT-STATUS.md) | -| `maintenance` | 2026-09-18 | Own the defects no open workstream covers, on `main` and on maintained release lines, and drive maintenance releases | active 2026-11-04; #335 merged; coverage-numbers slice awaits the owner's merge; 0.3.1 queue preserved | `ws-maintenance/coverage-in-pr`; `ws-maintenance/test-conventions` merged through #335 and closed; `release-0.3.0` closed and retained | [workstream status](engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md) | +| `maintenance` | 2026-09-18 | Own the defects no open workstream covers, on `main` and on maintained release lines, and drive maintenance releases | active 2026-11-04; #335 merged; coverage-numbers slice, PR #336, awaits the owner's merge; 0.3.1 queue preserved | `ws-maintenance/coverage-in-pr`; `ws-maintenance/test-conventions` merged through #335 and closed; `release-0.3.0` closed and retained | [workstream status](engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md) | | `component-upgrades` | 2026-09-21 | Deliver component distribution channels, developer-owned version sets and proven upgrade rollback; Codex first | paused 2026-10-02; consent design ruled (D-0011 to D-0013), 0.2.16 consent slice next; R-UPGRADE-002 follow-up retained | `ws-component-upgrades/v1` | [workstream status](engineering-docs/wip/2026-09-21-component-upgrades/CURRENT-STATUS.md) | | `sample-projects` | 2026-08-14 | Provide realistic sample projects as submodules that demonstrate ordinary adopter development inside DevCapsule | integrating 2026-10-22; AI Learning published; PR #252 reviewed and ready for human merge | `ws-sample-projects/ai-learning` | [workstream status](engineering-docs/wip/2026-08-14-sample-projects/CURRENT-STATUS.md) | | `contained-display` | 2026-08-19 | Own the capsule supervisor core (container entry process, supervised children, explicit session end, headless mode) and the capsule's own display environment, closing the host-session credential exposure — supervisor first, display as its first consumer | active; **the contained display shipped in v0.2.12 on 2026-09-14** (recipe-9 base, contained desktop by default, X11 passthrough behind `host-x11`); the X11 credential bug is resolved; remaining threads are records and follow-ups (reconnect, WSL2 opener, sample locks) | `ws-contained-display/display-transport` | [workstream status](engineering-docs/wip/2026-08-19-contained-display/CURRENT-STATUS.md) | diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 07142010..d1aab2a3 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -24,7 +24,8 @@ request's summary, and later in the merge commit's detail. CI already computed both, the overall figure into the job summary and diff-cover's report into an artifact and annotations; nothing reached the pull request. -Delivered on `ws-maintenance/coverage-in-pr` as a PR to `main`: +Delivered on `ws-maintenance/coverage-in-pr` as +[PR #336](https://github.com/ccozianu/devcapsule/pull/336) to `main`: `scripts/publish_coverage_numbers_to_pr.py` reads `coverage.json` and `diff-cover.json`, renders one block between `` and ``, and replaces that block in the pull From 87bba34e55d9206540370648c77a99201ec95ad7 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Wed, 4 Nov 2026 00:12:00 +0000 Subject: [PATCH 3/4] CI: match the coverage block only on whole marker lines; say when no changed line is measured The first run on #336 spliced the block into the description's prose, which quoted the markers literally; a block is now matched only where each marker stands alone on its line, with a test for markers quoted in prose. The same run reported 100% of 0 changed lines on a change outside the devcapsule package; that case now reads "none measured". 13 mirror tests pass; mypy clean; the conventions check reports 0 breaches. Co-Authored-By: Claude Fable 5.1 --- .../scripts/publish_coverage_numbers_to_pr.py | 30 +++++++++++++------ .../test_publish_coverage_numbers_to_pr.py | 16 ++++++++++ 2 files changed, 37 insertions(+), 9 deletions(-) diff --git a/devcapsule-src/scripts/publish_coverage_numbers_to_pr.py b/devcapsule-src/scripts/publish_coverage_numbers_to_pr.py index 1902f6ca..6f7f07bf 100644 --- a/devcapsule-src/scripts/publish_coverage_numbers_to_pr.py +++ b/devcapsule-src/scripts/publish_coverage_numbers_to_pr.py @@ -24,6 +24,7 @@ import argparse import json import os +import re import sys import urllib.request from collections.abc import Mapping @@ -35,7 +36,9 @@ BEGIN = "" END = "" -"""The markers that bound the block; everything between them is replaced on each run.""" +"""The markers that bound the block; each stands alone on its line, so a marker quoted in prose is not a block.""" + +_BLOCK = re.compile(rf"^{re.escape(BEGIN)}\n.*?^{re.escape(END)}$", re.MULTILINE | re.DOTALL) _API_VERSION = "2022-11-28" @@ -86,22 +89,31 @@ def render(numbers: Numbers, run_url: str) -> str: "", "| | |", "|---|---|", - f"| Changed lines covered | **{numbers.diff_percent}%** " - f"({numbers.diff_lines - numbers.diff_uncovered} of {numbers.diff_lines} measured changed lines; " - f"{numbers.diff_uncovered} uncovered) |", + "| Changed lines covered | " + _changed_lines(numbers) + " |", f"| Overall `devcapsule` | **{numbers.overall_percent:.1f}%** " f"({numbers.covered_statements:,} of {numbers.statements:,} statements) |", END, ]) +def _changed_lines(numbers: Numbers) -> str: + """The changed-lines cell; a change outside the measured package says so instead of claiming 100% of nothing.""" + if numbers.diff_lines == 0: + return "none measured: the change touches no line of `devcapsule`" + return (f"**{numbers.diff_percent}%** ({numbers.diff_lines - numbers.diff_uncovered} of {numbers.diff_lines} " + f"measured changed lines; {numbers.diff_uncovered} uncovered)") + + def upsert(body: str | None, block: str) -> str: - """The description with the block replaced between the markers, or appended after a blank line.""" + """The description with its block replaced, or the block appended after a blank line. + + Only a block whose markers each stand alone on a line is replaced; the + markers quoted inside the author's prose are prose. + """ text = body or "" - start = text.find(BEGIN) - end = text.find(END, start) - if start != -1 and end != -1: - return text[:start] + block + text[end + len(END):] + found = _BLOCK.search(text) + if found: + return text[:found.start()] + block + text[found.end():] return block if not text.strip() else text.rstrip("\n") + "\n\n" + block diff --git a/devcapsule-src/tests/unit/scripts/test_publish_coverage_numbers_to_pr.py b/devcapsule-src/tests/unit/scripts/test_publish_coverage_numbers_to_pr.py index ea7d1aba..2a1961c2 100644 --- a/devcapsule-src/tests/unit/scripts/test_publish_coverage_numbers_to_pr.py +++ b/devcapsule-src/tests/unit/scripts/test_publish_coverage_numbers_to_pr.py @@ -74,6 +74,22 @@ def test_upsert_replaces_only_the_block_between_the_markers() -> None: assert publish.upsert(f"above\n\n{old}\n\nbelow\n", new) == f"above\n\n{new}\n\nbelow\n" +def test_markers_quoted_in_the_authors_prose_are_not_the_block() -> None: + """Precondition: a description that mentions both markers inside a sentence and has no block. + Action: upsert. Postcondition: the sentence is intact and the block is appended after it.""" + prose = f"It renders a block between `{publish.BEGIN}` and `{publish.END}` with the figures.\n" + block = f"{publish.BEGIN}\nnumbers\n{publish.END}" + assert publish.upsert(prose, block) == f"{prose}\n{block}" + + +def test_a_change_outside_the_measured_package_says_so_instead_of_a_percentage() -> None: + """Precondition: diff-cover measured no changed line. Action: render. + Postcondition: the changed-lines cell says none measured and names the package; no percent sign in it.""" + block = publish.render(publish.Numbers(82.456, 16012, 19488, 100, 0, 0), "https://ci/run/1") + cell = next(line for line in block.splitlines() if line.startswith("| Changed lines covered")) + assert "none measured: the change touches no line of `devcapsule`" in cell and "%" not in cell + + def test_upsert_on_an_empty_description_is_the_block_alone() -> None: """Precondition: the API returned no body. Action: upsert. Postcondition: the block alone.""" block = f"{publish.BEGIN}\nnumbers\n{publish.END}" From 2f0491bbef473fd89e25ebc815b997acea9e819e Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Wed, 4 Nov 2026 00:21:08 +0000 Subject: [PATCH 4/4] Record the merge-message setting under Integration Method The owner set the merge commit's title and message to the pull request's title and description on 2026-11-04; verified through the repository API. Co-Authored-By: Claude Fable 5.1 --- WORKFLOW-LOCAL.md | 5 ++++- .../wip/2026-09-18-maintenance/CURRENT-STATUS.md | 8 ++++++-- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/WORKFLOW-LOCAL.md b/WORKFLOW-LOCAL.md index 2ca37231..a0aac5e4 100644 --- a/WORKFLOW-LOCAL.md +++ b/WORKFLOW-LOCAL.md @@ -452,7 +452,10 @@ by merging `main` in. The hosting platform allows merge commits only. It deletes the head branch on merge. It refuses force pushes to `main` and deletion of `main`. The merge commit is the record of the branch: its second parent is the merged head and its message names the source branch. Delete a -merged branch. +merged branch. Owner setting, 2026-11-04: the merge commit's title is the +pull request's title and its message is the pull request's description, so +the description an agent writes, and the coverage block CI appends to it, +are the merge commit's detail as they stand at merge time. The earlier ruling that `ws-workflow-improvements/v1` rebases onto `main` is retired. That branch merges like the others. The engineering source is [merge strategy and commit identity](engineering-docs/implementation-notes/workflow/2026-08-17-merge-strategy-and-commit-identity.md). diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index d1aab2a3..d4d4ed18 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -35,8 +35,12 @@ and runs the step on pull requests after diff coverage. Its tests are the third mirror file, 9 cases in triple form. The merge commit part needs no code: the owner sets the repository's default merge commit message to the pull request's title and description, and the block travels into `main`'s -history as it stands at merge time. Until that setting is flipped, the -numbers are in the pull request only. +history as it stands at merge time. The owner set it from the command line +the same day; verified through the API: `merge_commit_title` PR_TITLE, +`merge_commit_message` PR_BODY. Recorded under *Integration Method* in +WORKFLOW-LOCAL.md. The first run on #336 spliced the block into prose that +quoted the markers and reported 100% of zero measured lines; both fixed at +87bba34e, the second run appended the block correctly. ## Unit-test conventions — 2026-11-03