Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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: |
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion CURRENT-STATUS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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, 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) |
Expand Down
5 changes: 4 additions & 1 deletion WORKFLOW-LOCAL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
1 change: 1 addition & 0 deletions devcapsule-src/noxfile.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"),
)
Expand Down
2 changes: 1 addition & 1 deletion devcapsule-src/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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/"
Expand Down
164 changes: 164 additions & 0 deletions devcapsule-src/scripts/publish_coverage_numbers_to_pr.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,164 @@
"""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 re
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 = "<!-- coverage-numbers:begin -->"
END = "<!-- coverage-numbers:end -->"
"""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"


@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})",
"",
"| | |",
"|---|---|",
"| 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 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 ""
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


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())
Loading
Loading