spec status: flag patches whose source files no longer exist in specs repo

Add `_find_removable_patches()` helper that checks each active patch file
against the upstream specifications repo. A patch is flagged as removable
when all the driver-side test files it references no longer exist in the
specs source — meaning they've been deleted or renamed upstream and the
patch is no longer needed after the next sync.

`dbx spec status` now prints a 🗑 section listing any such patches with
suggested `rm` commands, and includes verbose mode support to show the
specific missing files.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: aclark4life

src/dbx_python_cli/commands/spec.py

@@ -484,6 +484,62 @@ def _branch_summary(repo_path: Path) -> tuple[list[str], int]:
     return [], 0
 
 
+def _find_removable_patches(
+    patch_dir: Path,
+    spec_map: dict[str, list[tuple[str, str]]],
+    specs_source: Path,
+) -> list[tuple[Path, list[str]]]:
+    """Return patches whose source files no longer exist in the specs repo.
+
+    For each patch, maps driver-side paths (``test/<driver_dst>/...``) back to
+    the corresponding specs-source paths using *spec_map*, then checks whether
+    any of those source files are still present.  A patch is considered
+    removable when **none** of its referenced source files exist upstream —
+    meaning after the next sync those files won't be copied in and there is
+    nothing left to patch out.
+
+    Returns a list of ``(patch_path, [missing_file, ...])`` tuples.
+    """
+    # Build reverse map: driver_dst -> specs_src (many-to-many, take first match)
+    driver_to_specs: dict[str, str] = {}
+    for mappings in spec_map.values():
+        for specs_src, driver_dst in mappings:
+            driver_to_specs.setdefault(driver_dst, specs_src)
+
+    removable: list[tuple[Path, list[str]]] = []
+    for patch_path in _list_patches(patch_dir):
+        patched_files = _parse_patch_files(patch_path)
+        if not patched_files:
+            continue
+
+        missing: list[str] = []
+        for file_path in patched_files:
+            parts = file_path.split("/")
+            if len(parts) < 3 or parts[0] != "test":
+                continue
+            driver_dst = parts[1]
+            rel_path = "/".join(parts[2:])
+            specs_src = driver_to_specs.get(driver_dst)
+            if specs_src is None:
+                # Can't resolve — treat as missing to be conservative
+                missing.append(file_path)
+                continue
+            src_file = specs_source / specs_src / rel_path
+            if not src_file.exists():
+                missing.append(file_path)
+
+        if missing and len(missing) == len(
+            [
+                f
+                for f in patched_files
+                if len(f.split("/")) >= 3 and f.split("/")[0] == "test"
+            ]
+        ):
+            removable.append((patch_path, missing))
+
+    return removable
+
+
 def _spec_is_stale(
     specs_source: Path,
     driver_test: Path,
@@ -700,6 +756,29 @@ def _patches_for_spec(spec_name: str) -> list[str]:
     # --- Patches ----------------------------------------------------------- #
     patch_count = _show_patch_summary(driver_repo, verbose)
 
+    # --- Removable patches ------------------------------------------------- #
+    removable = _find_removable_patches(
+        _get_patch_dir(driver_repo), spec_map, specs_source
+    )
+    if removable:
+        typer.echo(
+            f"\n  🗑  {len(removable)} patch(es) may be removable"
+            " (source files no longer exist in specs repo):\n"
+        )
+        for patch_path, missing_files in removable:
+            typer.echo(f"  • {patch_path.name}")
+            if verbose:
+                for f in missing_files:
+                    typer.echo(f"      {f}  [not found in specs]")
+        typer.echo(
+            "\n  ℹ  These patches target files that are no longer in the upstream specs."
+        )
+        typer.echo(
+            "     Review and remove them if the ticket has been resolved upstream:"
+        )
+        for patch_path, _ in removable:
+            typer.echo(f"     rm {patch_path}")
+
     # --- What to do next --------------------------------------------------- #
     typer.echo("\n  🔍 To verify locally:\n")
     step = 1

tests/test_spec_command.py

@@ -954,3 +954,81 @@ def test_spec_status_annotates_patches(tmp_path):
     assert result.exit_code == 0
     assert "PYTHON-9999" in result.output
     assert "🩹" in result.output
+
+
+def test_spec_status_shows_removable_patches(tmp_path):
+    """Patches whose source files no longer exist in specs should be flagged."""
+    _, cfg = _make_status_repos(tmp_path, content_same=True)
+
+    patch_dir = tmp_path / "repos" / "mongo-python-driver" / ".evergreen" / "spec-patch"
+    # This patch references a file that does NOT exist in the specs repo
+    (patch_dir / "PYTHON-GONE.patch").write_text(
+        "diff --git a/test/auth/deleted-test.json b/test/auth/deleted-test.json\n"
+        "index abc..def 100644\n"
+        "--- a/test/auth/deleted-test.json\n"
+        "+++ /dev/null\n"
+        "@@ -1 +0,0 @@\n"
+        "-{}\n"
+    )
+
+    with (
+        patch("dbx_python_cli.utils.repo.get_config_path", return_value=cfg),
+        patch(
+            "dbx_python_cli.commands.spec._get_current_branch",
+            return_value="spec-resync-test",
+        ),
+        patch(
+            "dbx_python_cli.commands.spec._find_recent_resync_commits",
+            return_value=["abc resyncing"],
+        ),
+        patch(
+            "dbx_python_cli.commands.spec._commit_relative_date",
+            return_value="1 day ago",
+        ),
+        patch("dbx_python_cli.commands.spec._commit_spec_dirs", return_value=[]),
+        patch("dbx_python_cli.commands.spec._branch_summary", return_value=([], 0)),
+    ):
+        result = runner.invoke(app, ["spec", "status"])
+
+    assert result.exit_code == 0
+    assert "PYTHON-GONE.patch" in result.output
+    assert "removable" in result.output.lower()
+
+
+def test_spec_status_no_removable_patches_when_files_exist(tmp_path):
+    """Patches whose source files still exist should NOT be flagged as removable."""
+    _, cfg = _make_status_repos(tmp_path, content_same=True)
+
+    patch_dir = tmp_path / "repos" / "mongo-python-driver" / ".evergreen" / "spec-patch"
+    # This patch references auth.json which DOES exist in the specs repo
+    (patch_dir / "PYTHON-KEEP.patch").write_text(
+        "diff --git a/test/auth/auth.json b/test/auth/auth.json\n"
+        "index abc..def 100644\n"
+        "--- a/test/auth/auth.json\n"
+        "+++ /dev/null\n"
+        "@@ -1 +0,0 @@\n"
+        '-{"spec": "auth"}\n'
+    )
+
+    with (
+        patch("dbx_python_cli.utils.repo.get_config_path", return_value=cfg),
+        patch(
+            "dbx_python_cli.commands.spec._get_current_branch",
+            return_value="spec-resync-test",
+        ),
+        patch(
+            "dbx_python_cli.commands.spec._find_recent_resync_commits",
+            return_value=["abc resyncing"],
+        ),
+        patch(
+            "dbx_python_cli.commands.spec._commit_relative_date",
+            return_value="1 day ago",
+        ),
+        patch("dbx_python_cli.commands.spec._commit_spec_dirs", return_value=[]),
+        patch("dbx_python_cli.commands.spec._branch_summary", return_value=([], 0)),
+    ):
+        result = runner.invoke(app, ["spec", "status"])
+
+    assert result.exit_code == 0
+    assert "may be removable" not in result.output
+    assert "PYTHON-KEEP.patch" not in result.output