test: guard the deployment contract for entrypoint count and bundle contents

Author: codebybilal18

.github/workflows/ci.yml

@@ -54,16 +54,26 @@ jobs:
           pip install -r requirements-dev.txt
 
       - name: Lint
-        run: ruff check app scripts tests
+        run: ruff check app api scripts tests
 
       - name: Format check
-        run: ruff format --check app scripts tests
+        run: ruff format --check app api scripts tests
 
       - name: Verify the Vercel bundle stays importable without local extras
         # Guards the actual deployment contract: if anything in the import graph
         # starts requiring torch, Vercel breaks at runtime, not at build time.
         run: python -c "from app.main import create_app; create_app()"
 
+      - name: Verify the serverless entrypoint loads
+        # Executed the way Vercel does it — from another directory, with the
+        # repo root not already on sys.path.
+        run: cd /tmp && python -c "
+          import importlib.util;
+          spec = importlib.util.spec_from_file_location('e', '$GITHUB_WORKSPACE/api/index.py');
+          m = importlib.util.module_from_spec(spec);
+          spec.loader.exec_module(m);
+          print('entrypoint ok:', len(m.app.routes), 'routes')"
+
       - name: Migrate
         run: alembic upgrade head
 

requirements-dev.txt

@@ -12,3 +12,5 @@ pytest==8.3.4
 pytest-asyncio==0.25.0
 anyio==4.7.0
 ruff==0.16.0
+# Used by the deployment-contract test to evaluate .vercelignore patterns.
+pathspec==0.12.1

tests/test_deployment_contract.py

@@ -0,0 +1,118 @@
+"""Guards on how the app is packaged for deployment.
+
+Both of these encode bugs that reached production. Neither was visible to any
+other test, and both presented as an opaque `FUNCTION_INVOCATION_FAILED` with a
+build that reported success.
+"""
+
+from __future__ import annotations
+
+import ast
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def module_level_asgi_apps() -> list[str]:
+    """Files assigning a module-level `app`, which is what Vercel's FastAPI
+    preset scans for when choosing an entrypoint."""
+    found: list[str] = []
+    for path in list(ROOT.glob("app/**/*.py")) + list(ROOT.glob("api/**/*.py")):
+        tree = ast.parse(path.read_text())
+        for node in tree.body:  # module level only
+            targets = (
+                node.targets
+                if isinstance(node, ast.Assign)
+                else [node.target]
+                if isinstance(node, ast.AnnAssign)
+                else []
+            )
+            if any(isinstance(t, ast.Name) and t.id == "app" for t in targets):
+                found.append(str(path.relative_to(ROOT)))
+    return sorted(found)
+
+
+def test_there_is_exactly_one_asgi_entrypoint():
+    """Two module-level `app` instances meant Vercel's preset built
+    `app/main.py` as the function while dependencies were installed for the
+    entrypoint declared in vercel.json. The deployed function had no fastapi and
+    died at cold start.
+
+    Anything needing an instance should use the factory:
+    `uvicorn app.main:create_app --factory`.
+    """
+    apps = module_level_asgi_apps()
+    assert apps == ["api/index.py"], (
+        f"expected exactly one ASGI entrypoint at api/index.py, found {apps}. "
+        "A second one makes the deployed entrypoint ambiguous."
+    )
+
+
+def test_vercelignore_patterns_are_anchored():
+    """.vercelignore uses gitignore semantics, so an unanchored directory name
+    matches at every depth. `evals/` once stripped `app/evals/` — a package the
+    request path imports — out of the bundle.
+    """
+    unanchored = [
+        line
+        for raw in (ROOT / ".vercelignore").read_text().splitlines()
+        if (line := raw.strip()) and not line.startswith(("#", "/", "!"))
+    ]
+    assert not unanchored, (
+        f"unanchored .vercelignore patterns match at every depth: {unanchored}. "
+        "Prefix each with '/' so it only matches at the repo root."
+    )
+
+
+def test_nothing_the_runtime_imports_is_excluded_from_the_bundle():
+    pathspec = pytest.importorskip("pathspec", reason="pathspec not installed")
+
+    lines = [
+        line
+        for raw in (ROOT / ".vercelignore").read_text().splitlines()
+        if (line := raw.strip()) and not line.startswith("#")
+    ]
+    spec = pathspec.PathSpec.from_lines("gitwildmatch", lines)
+
+    tracked = subprocess.run(
+        ["git", "ls-files"], cwd=ROOT, capture_output=True, text=True, check=True
+    ).stdout.split()
+
+    # Everything under app/ and api/ is runtime code, plus the two non-Python
+    # assets that are easy to lose because nothing imports them by path.
+    required = [
+        f
+        for f in tracked
+        if f.startswith(("app/", "api/"))
+        or f in ("requirements.txt", "vercel.json", ".python-version")
+    ]
+    excluded = [f for f in required if spec.match_file(f)]
+
+    assert not excluded, f"runtime files excluded from the Vercel bundle: {excluded}"
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="posix path assumptions")
+def test_the_entrypoint_loads_without_the_repo_root_on_syspath():
+    """Vercel executes api/index.py from another directory. If the sys.path
+    bootstrap in that file regresses, `app` becomes unimportable in production
+    while every local run still works."""
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-c",
+            "import importlib.util,sys;"
+            f"spec=importlib.util.spec_from_file_location('e', r'{ROOT / 'api' / 'index.py'}');"
+            "m=importlib.util.module_from_spec(spec);"
+            "spec.loader.exec_module(m);"
+            "print(len(m.app.routes))",
+        ],
+        cwd="/tmp",
+        capture_output=True,
+        text=True,
+    )
+    assert result.returncode == 0, result.stderr
+    assert int(result.stdout.strip()) > 0