Merge pull request #193 from genomoncology/add-python-docs-pr-ci-gate

ci: add contracts job to PR CI and make test-contracts local target

Author: imaurer

.github/workflows/ci.yml

@@ -28,3 +28,32 @@ jobs:
       - run: cargo fmt --check
       - run: cargo clippy -- -D warnings
       - run: cargo test
+
+  contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cache protoc
+        uses: actions/cache@v4
+        with:
+          path: ${{ runner.tool_cache }}/protoc
+          key: protoc-${{ runner.os }}-${{ runner.arch }}-v28.3
+
+      - uses: arduino/setup-protoc@v3
+        continue-on-error: true
+        with:
+          version: "28.3"
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - uses: astral-sh/setup-uv@v4
+
+      - run: uv sync --extra dev
+      - run: uv run pytest tests/ -v --mcp-cmd "biomcp serve"
+      - run: uv run mkdocs build --strict

Makefile

@@ -1,11 +1,16 @@
-.PHONY: build test check run clean spec validate-skills
+.PHONY: build test check run clean spec validate-skills test-contracts
 
 build:
 	cargo build --release
 
 test:
 	cargo test
 
+test-contracts:
+	uv sync --extra dev
+	uv run pytest tests/ -v --mcp-cmd "biomcp serve"
+	uv run mkdocs build --strict
+
 check:
 	cargo clippy -- -D warnings
 	cargo fmt --check

RUN.md

@@ -78,6 +78,26 @@ Owned routes:
 | `ONCOKB_TOKEN` | Canonical OncoKB production token |
 | `ALPHAGENOME_API_KEY` | Required for AlphaGenome variant prediction |
 
+## Pre-Merge Checks
+
+Run the Rust gate locally:
+
+```bash
+make check
+make test
+```
+
+Run the Python/docs contract gate (same as PR CI `contracts` job):
+
+```bash
+make test-contracts
+```
+
+`make test-contracts` runs `uv sync --extra dev`, `pytest tests/`, and
+`mkdocs build --strict` - the same steps that PR CI and release validation
+require. Use this to catch docs-contract and Python regressions before
+pushing.
+
 ## Smoke Checks
 
 ```bash

analysis/technical/overview.md

@@ -81,8 +81,10 @@ share one limiter budget and one Streamable HTTP `/mcp` surface.
 2. Commit and push to `main`
 3. Cut a GitHub release with a semver tag
 4. GitHub Actions validates and publishes:
-   - CI (`.github/workflows/ci.yml`) runs `cargo fmt --check`,
-     `cargo clippy -- -D warnings`, and `cargo test`.
+   - CI (`.github/workflows/ci.yml`) runs two parallel jobs: `check`
+     (`cargo fmt --check`, `cargo clippy -- -D warnings`, `cargo test`) and
+     `contracts` (`uv sync --extra dev`, `uv run pytest tests/ -v --mcp-cmd "biomcp serve"`,
+     `uv run mkdocs build --strict`).
    - Release validation runs the Rust checks again, then
      `uv run pytest tests/ -v --mcp-cmd "biomcp serve"` and
      `uv run mkdocs build --strict`.
@@ -100,7 +102,7 @@ BioMCP has three verification layers:
 
 ### 1. GitHub Workflows
 
-CI (`.github/workflows/ci.yml`) runs `cargo fmt --check`, `cargo clippy -- -D warnings`, and `cargo test`.
+CI (`.github/workflows/ci.yml`) runs two parallel jobs: `check` (`cargo fmt --check`, `cargo clippy -- -D warnings`, `cargo test`) and `contracts` (`uv sync --extra dev`, `uv run pytest tests/ -v --mcp-cmd "biomcp serve"`, `uv run mkdocs build --strict`).
 Contract smoke checks run in `.github/workflows/contracts.yml` on a schedule
 and by manual dispatch via `bash scripts/contract-smoke.sh`.
 release validation runs `pytest tests/` and `mkdocs build --strict` after the

tests/test_upstream_planning_analysis_docs.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import os
+import re
 from pathlib import Path
 
 import pytest
@@ -21,6 +22,20 @@ def _read_planning(path: str) -> str:
     return (_planning_root() / path).read_text(encoding="utf-8")
 
 
+def _workflow_job_block(workflow: str, job_name: str) -> str:
+    match = re.search(
+        rf"^  {re.escape(job_name)}:\n(.*?)(?=^  [A-Za-z0-9_-]+:\n|\Z)",
+        workflow,
+        flags=re.MULTILINE | re.DOTALL,
+    )
+    assert match is not None, f"missing workflow job {job_name}"
+    return match.group(1)
+
+
+def _workflow_run_steps(job_block: str) -> list[str]:
+    return re.findall(r"^\s+- run: (.+)$", job_block, flags=re.MULTILINE)
+
+
 def test_planning_contract_uses_repo_fixture_fallback_by_default(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
@@ -112,7 +127,9 @@ def test_technical_and_ux_docs_match_current_cli_and_workflow_contracts() -> Non
     technical = _read_repo("analysis/technical/overview.md")
     ux = _read_repo("analysis/ux/cli-reference.md")
 
-    assert "CI (`.github/workflows/ci.yml`) runs `cargo fmt --check`, `cargo clippy -- -D warnings`, and `cargo test`." in technical
+    assert "CI (`.github/workflows/ci.yml`) runs two parallel jobs" in technical
+    assert "`check` (`cargo fmt --check`, `cargo clippy -- -D warnings`, `cargo test`)" in technical
+    assert '`contracts` (`uv sync --extra dev`, `uv run pytest tests/ -v --mcp-cmd "biomcp serve"`, `uv run mkdocs build --strict`)' in technical
     assert "The spec suite is repo-local executable documentation; no GitHub workflow currently runs `make spec`." in technical
     assert "Contract smoke checks run in `.github/workflows/contracts.yml`" in technical
     assert "release validation runs `pytest tests/` and `mkdocs build --strict`" in technical
@@ -136,6 +153,31 @@ def test_technical_and_ux_docs_match_current_cli_and_workflow_contracts() -> Non
     assert "biomcp serve-sse             → removed compatibility command; use `biomcp serve-http`" in ux
 
 
+def test_pull_request_contract_gate_matches_release_validation() -> None:
+    ci = _read_repo(".github/workflows/ci.yml")
+    release = _read_repo(".github/workflows/release.yml")
+    contracts_smoke = _read_repo(".github/workflows/contracts.yml")
+    expected_contract_runs = [
+        "uv sync --extra dev",
+        'uv run pytest tests/ -v --mcp-cmd "biomcp serve"',
+        "uv run mkdocs build --strict",
+    ]
+
+    ci_contracts = _workflow_job_block(ci, "contracts")
+    release_validate = _workflow_job_block(release, "validate")
+
+    assert 'python-version: "3.12"' in ci_contracts
+    assert 'python-version: "3.12"' in release_validate
+    assert _workflow_run_steps(ci_contracts) == expected_contract_runs
+    assert _workflow_run_steps(release_validate)[-3:] == expected_contract_runs
+
+    assert "name: Contract Smoke Tests" in contracts_smoke
+    assert 'cron: "0 6 * * *"' in contracts_smoke
+    assert "workflow_dispatch:" in contracts_smoke
+    assert "continue-on-error: true" in contracts_smoke
+    assert "- run: bash scripts/contract-smoke.sh" in contracts_smoke
+
+
 def test_runtime_contract_docs_and_scripts_align_on_release_target() -> None:
     staging_demo = _read_repo("analysis/technical/staging-demo.md")
     runbook = _read_repo("RUN.md")
@@ -172,6 +214,7 @@ def test_runtime_contract_docs_and_scripts_align_on_release_target() -> None:
     assert "tests/test_mcp_http_surface.py" in runbook
     assert "tests/test_mcp_http_transport.py" in runbook
     assert "make spec" in runbook
+    assert "make test-contracts" in runbook
     assert "docs/user-guide/cli-reference.md" in runbook
     assert "docs/reference/mcp-server.md" in runbook