ci: add slow e2e validation

Author: ayhammouda

.github/INTEGRATION-TEST.md

@@ -16,6 +16,10 @@ Release-specific sign-off still lives in [`.github/RELEASE.md`](RELEASE.md).
   - `uv run mcp-server-python-docs build-index --versions 3.12,3.13`
 - Doctor passes:
   - `uv run mcp-server-python-docs doctor`
+- Slow E2E workflow passes when preparing a release:
+  - GitHub Actions: `Slow E2E`
+  - Expected: Python 3.13 and 3.14 jobs both complete `build-index`, `doctor`,
+    and `validate-corpus` from an installed wheel
 - If `uv` is not on `PATH`, use `python -m uv ...` instead
 
 ## Test 1: MCP Inspector quick loop
@@ -116,6 +120,24 @@ locked.
 - [ ] Follow the README from scratch
   - Expected: a new user can get to a working client configuration without using `.planning/`
 
+## Test 5: Slow E2E workflow
+
+Run this before a release and after changes to ingestion, publishing, packaging,
+or supported Python versions.
+
+### Checks
+
+- [ ] Start the `Slow E2E` workflow from GitHub Actions
+  - Expected: both Python 3.13 and Python 3.14 jobs start
+- [ ] Confirm each job installs the built wheel into a clean virtual environment
+  - Expected: the command path is the installed `mcp-server-python-docs`, not editable source
+- [ ] Confirm `build-index --versions 3.12,3.13` passes
+  - Expected: both versions produce content, not symbol-only fallback
+- [ ] Confirm `doctor` and `validate-corpus` pass
+  - Expected: corpus smoke checks include requested versions and the default version
+- [ ] Inspect uploaded logs if a job fails
+  - Expected: Sphinx/build logs are available as workflow artifacts
+
 ## Evidence log
 
 | Test | Pass/Fail | Tester | Date | Notes |
@@ -124,3 +146,4 @@ locked.
 | Claude Desktop | | | | |
 | Cursor | | | | |
 | Fresh install | | | | |
+| Slow E2E workflow | | | | |

.github/RELEASE.md

@@ -144,6 +144,11 @@ Complete these steps in order. Each step has a checkbox -- do not skip ahead.
   uvx mcp-server-python-docs doctor
   # All checks should PASS
   ```
+- [ ] Slow E2E workflow passes:
+  - Run GitHub Actions workflow `Slow E2E`
+  - Confirm Python 3.13 and Python 3.14 jobs both pass
+  - Confirm each job installs the built wheel, runs
+    `build-index --versions 3.12,3.13`, `doctor`, and `validate-corpus`
 - [ ] Claude Desktop test with published package:
   Configure `mcpServers` with `uvx mcp-server-python-docs` and verify
   "what is asyncio.TaskGroup" returns a correct hit
@@ -153,6 +158,7 @@ Complete these steps in order. Each step has a checkbox -- do not skip ahead.
 - [ ] GitHub Release exists with attached artifacts
 - [ ] PyPI page shows 0.1.0 with attestation
 - [ ] README install instructions verified end-to-end
+- [ ] Slow E2E workflow passed for the release candidate
 - [ ] Tag v0.1.0 exists in git
 
 **Release date**: _______________

.github/workflows/e2e.yml

@@ -0,0 +1,58 @@
+name: Slow E2E
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "17 4 * * 1"
+
+jobs:
+  installed-build-index:
+    name: Installed build-index (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+
+    env:
+      HOME: ${{ runner.temp }}/mcp-python-docs-home
+      XDG_CACHE_HOME: ${{ runner.temp }}/mcp-python-docs-cache
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Build package
+        run: uv build
+
+      - name: Install wheel in clean virtual environment
+        run: |
+          uv run --python ${{ matrix.python-version }} python -m venv .e2e-venv
+          .e2e-venv/bin/python -m pip install --upgrade pip
+          .e2e-venv/bin/python -m pip install dist/*.whl
+          .e2e-venv/bin/mcp-server-python-docs --version
+
+      - name: Build and validate full docs index
+        run: |
+          set -o pipefail
+          .e2e-venv/bin/mcp-server-python-docs build-index --versions 3.12,3.13 \
+            2>&1 | tee "${RUNNER_TEMP}/build-index-${{ matrix.python-version }}.log"
+          .e2e-venv/bin/mcp-server-python-docs doctor
+          .e2e-venv/bin/mcp-server-python-docs validate-corpus
+
+      - name: Upload E2E logs and cache artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-python-${{ matrix.python-version }}
+          path: |
+            ${{ runner.temp }}/build-index-${{ matrix.python-version }}.log
+            ${{ runner.temp }}/mcp-python-docs-cache
+          retention-days: 7

src/mcp_server_python_docs/__main__.py

@@ -122,11 +122,15 @@ def build_index(versions: str, skip_content: bool) -> None:
 
     from mcp_server_python_docs.ingestion.inventory import ingest_inventory
     from mcp_server_python_docs.ingestion.publish import (
+        _version_sort_key,
         generate_build_path,
+        parse_expected_versions,
         publish_index,
     )
     from mcp_server_python_docs.ingestion.sphinx_json import (
+        build_sphinx_json_command,
         ingest_sphinx_json_dir,
+        make_sphinx_json_env,
         populate_synonyms,
         rebuild_fts_indexes,
         write_json_build_requirements,
@@ -144,7 +148,7 @@ def build_index(versions: str, skip_content: bool) -> None:
         "3.13": {"tag": "v3.13.12", "sphinx_pin": "sphinx<9.0.0"},
     }
 
-    version_list = [v.strip() for v in versions.split(",") if v.strip()]
+    version_list = parse_expected_versions(versions)
     if not version_list:
         logger.error("No valid versions specified. Example: --versions 3.13")
         raise SystemExit(1)
@@ -159,8 +163,7 @@ def build_index(versions: str, skip_content: bool) -> None:
             raise SystemExit(1)
 
     # Determine default version: highest version number (MVER-02)
-    sorted_versions = sorted(version_list, key=lambda v: [int(x) for x in v.split(".")])
-    default_version = sorted_versions[-1]
+    default_version = max(version_list, key=_version_sort_key)
 
     # Build into a timestamped artifact, not directly to index.db (PUBL-01)
     build_db_path = generate_build_path()
@@ -259,25 +262,15 @@ def build_index(versions: str, skip_content: bool) -> None:
                     json_out = os.path.join(doc_dir, "build", "json")
                     sphinx_compat_dir = Path(clone_dir) / "_sphinx_json_compat"
                     write_sphinx_json_sitecustomize(sphinx_compat_dir)
-                    sphinx_env = os.environ.copy()
-                    sphinx_env["PYTHONPATH"] = (
-                        str(sphinx_compat_dir)
-                        if not sphinx_env.get("PYTHONPATH")
-                        else f"{sphinx_compat_dir}{os.pathsep}{sphinx_env['PYTHONPATH']}"
-                    )
+                    sphinx_env = make_sphinx_json_env(sphinx_compat_dir)
 
                     logger.info(
                         "Running sphinx-build -b json for Python %s "
                         "(this may take 3-8 minutes)...",
                         version,
                     )
                     result = subprocess.run(
-                        [
-                            sphinx_build, "-b", "json",
-                            "-D", "html_theme=classic",
-                            "-j", "auto",
-                            doc_dir, json_out,
-                        ],
+                        build_sphinx_json_command(sphinx_build, doc_dir, json_out),
                         capture_output=True,
                         text=True,
                         cwd=doc_dir,
@@ -375,7 +368,10 @@ def validate_corpus(db_path: str | None) -> None:
     """
     from pathlib import Path
 
-    from mcp_server_python_docs.ingestion.publish import run_smoke_tests
+    from mcp_server_python_docs.ingestion.publish import (
+        parse_expected_versions,
+        run_smoke_tests,
+    )
     from mcp_server_python_docs.storage.db import get_index_path, get_readonly_connection
 
     if db_path is not None:
@@ -392,20 +388,28 @@ def validate_corpus(db_path: str | None) -> None:
 
     # Auto-detect symbol-only builds from the last published ingestion run
     require_content = True
+    expected_versions: list[str] | None = None
     try:
         ro_conn = get_readonly_connection(target)
         row = ro_conn.execute(
-            "SELECT notes FROM ingestion_runs "
+            "SELECT version, notes FROM ingestion_runs "
             "WHERE status = 'published' ORDER BY id DESC LIMIT 1"
         ).fetchone()
         ro_conn.close()
-        if row and row[0] and "build_mode=symbol_only" in row[0]:
+        if row and row[0]:
+            expected_versions = parse_expected_versions(row[0])
+        if row and row[1] and "build_mode=symbol_only" in row[1]:
             require_content = False
             logger.info("Detected symbol-only build — skipping content checks")
-    except Exception:
-        pass  # If we can't read the metadata, default to full validation
-
-    passed, messages = run_smoke_tests(target, require_content=require_content)
+    except Exception as e:
+        # If we can't read the metadata, default to full validation
+        logger.debug("Could not read ingestion_runs metadata: %s", e)
+
+    passed, messages = run_smoke_tests(
+        target,
+        require_content=require_content,
+        expected_versions=expected_versions,
+    )
 
     for msg in messages:
         if msg.startswith("OK:"):