spec status: cross-reference patches with stale specs

Patches in .evergreen/spec-patch/ reverse-apply after each sync to exclude
tests for unimplemented features. This change makes those relationships
visible throughout the output.

- Add _patch_dir_map(): builds {test_subdir: [ticket...]} reverse map from
  all active patch files, so we know which patches touch which spec dirs
- Annotate each stale spec with its patch ticket(s): 'dbx spec sync auth  🩹 PYTHON-5445'
- Add legend: '🩹 = has an active patch — re-run dbx spec patch apply after syncing'
- Update patch summary to show spec dirs each patch covers:
  '• PYTHON-5052 (14 file(s))  → unified-test-format'
- Update patch footer: 'After syncing any of the above spec dirs, run: dbx spec patch apply'
- Clarify verify step 2: 'Re-apply patches (removes unimplemented tests)'
- Restore accidentally-removed _list_patches() helper
- 2 new tests

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

Author: aclark4life

src/dbx_python_cli/commands/spec.py

@@ -74,8 +74,28 @@ def _list_patches(patch_dir: Path) -> list[Path]:
     return sorted(patch_dir.glob("*.patch"))
 
 
+def _patch_dir_map(patch_dir: Path) -> dict[str, list[str]]:
+    """Return {test_subdir: [ticket, ...]} for all active patches.
+
+    Reads each .patch file, extracts the ``test/<subdir>/`` paths from diff
+    headers, and builds a reverse map so callers can quickly find which
+    patches touch a given spec directory.
+    """
+    result: dict[str, list[str]] = {}
+    for patch_path in _list_patches(patch_dir):
+        ticket = patch_path.stem
+        for file_path in _parse_patch_files(patch_path):
+            parts = file_path.split("/")
+            if len(parts) >= 3 and parts[0] == "test":
+                subdir = parts[1]
+                result.setdefault(subdir, [])
+                if ticket not in result[subdir]:
+                    result[subdir].append(ticket)
+    return result
+
+
 def _show_patch_summary(driver_repo, verbose: bool = False) -> int:
-    """Print a summary of active patches. Returns the patch count."""
+    """Print a summary of active patches with the spec dirs each covers. Returns patch count."""
     patch_dir = _get_patch_dir(driver_repo)
     patches = _list_patches(patch_dir)
     if not patches:
@@ -84,13 +104,24 @@ def _show_patch_summary(driver_repo, verbose: bool = False) -> int:
     for p in patches:
         ticket = p.stem
         files = _parse_patch_files(p)
+        subdirs = sorted(
+            {
+                parts[1]
+                for f in files
+                for parts in [f.split("/")]
+                if len(parts) >= 3 and parts[0] == "test"
+            }
+        )
+        dirs_str = f"  → {', '.join(subdirs)}" if subdirs else ""
         if verbose:
-            typer.echo(f"  • {ticket} ({len(files)} file(s)):")
+            typer.echo(f"  • {ticket} ({len(files)} file(s)){dirs_str}:")
             for f in files:
                 typer.echo(f"      {f}")
         else:
-            typer.echo(f"  • {ticket} ({len(files)} file(s))")
-    typer.echo("\n  Run 'dbx spec patch apply' to apply them.")
+            typer.echo(f"  • {ticket} ({len(files)} file(s)){dirs_str}")
+    typer.echo(
+        "\n  ⚠  After syncing any of the above spec dirs, run: dbx spec patch apply"
+    )
     return len(patches)
 
 
@@ -602,14 +633,34 @@ def spec_status(
         else:
             up_to_date.append(spec_name)
 
+    # --- Build patch→dir map before output --------------------------------- #
+    patch_dir_lookup = _patch_dir_map(_get_patch_dir(driver_repo))
+    # reverse: spec_driver_dir → patch tickets that cover it
+    dir_to_patches: dict[str, list[str]] = patch_dir_lookup
+
+    # For each spec_name, collect the driver dirs it maps to
+    def _patches_for_spec(spec_name: str) -> list[str]:
+        tickets: list[str] = []
+        for _, driver_dir in spec_map.get(spec_name, []):
+            for t in dir_to_patches.get(driver_dir, []):
+                if t not in tickets:
+                    tickets.append(t)
+        return tickets
+
     # --- Output ------------------------------------------------------------ #
     if stale:
         typer.echo(f"  ❌ Still needs syncing ({len(stale)}):\n")
         for i, (name, reason) in enumerate(stale):
             is_last = i == len(stale) - 1
             prefix = "  └──" if is_last else "  ├──"
             reason_str = f"  [{reason}]" if verbose else ""
-            typer.echo(f"{prefix} dbx spec sync {name}{reason_str}")
+            tickets = _patches_for_spec(name)
+            patch_str = f"  🩹 {', '.join(tickets)}" if tickets else ""
+            typer.echo(f"{prefix} dbx spec sync {name}{reason_str}{patch_str}")
+        if any(_patches_for_spec(n) for n, _ in stale):
+            typer.echo(
+                "\n  🩹 = has an active patch — re-run 'dbx spec patch apply' after syncing"
+            )
     else:
         typer.echo("  ✅ All checked specs are up to date.")
 
@@ -634,7 +685,7 @@ def spec_status(
         typer.echo(f"        dbx spec sync {spec_names}")
         step += 1
     if patch_count:
-        typer.echo(f"     {step}. Re-apply patches after syncing:")
+        typer.echo(f"     {step}. Re-apply patches (removes unimplemented tests):")
         typer.echo("        dbx spec patch apply")
         step += 1
     if branch_dirs:

tests/test_spec_command.py

@@ -891,3 +891,66 @@ def test_spec_status_verify_section_no_stale(tmp_path):
         result = runner.invoke(app, ["spec", "status"])
     assert result.exit_code == 0
     assert "Nothing outstanding" in result.output
+
+
+def test_patch_dir_map(tmp_path):
+    """_patch_dir_map returns a dir→tickets reverse map from patch files."""
+    from dbx_python_cli.commands.spec import _patch_dir_map
+
+    patch_dir = tmp_path / "spec-patch"
+    patch_dir.mkdir()
+    (patch_dir / "PYTHON-1234.patch").write_text(
+        "diff --git a/test/crud/foo.json b/test/crud/foo.json\n"
+        "diff --git a/test/unified-test-format/bar.json b/test/unified-test-format/bar.json\n"
+    )
+    (patch_dir / "PYTHON-5678.patch").write_text(
+        "diff --git a/test/crud/baz.json b/test/crud/baz.json\n"
+    )
+
+    result = _patch_dir_map(patch_dir)
+
+    assert "crud" in result
+    assert "PYTHON-1234" in result["crud"]
+    assert "PYTHON-5678" in result["crud"]
+    assert "unified-test-format" in result
+    assert result["unified-test-format"] == ["PYTHON-1234"]
+
+
+def test_spec_status_annotates_patches(tmp_path):
+    """Stale specs that have an active patch should show the ticket."""
+    _, cfg = _make_status_repos(tmp_path, content_same=False)
+
+    # Add a patch covering the auth test dir
+    patch_dir = tmp_path / "repos" / "mongo-python-driver" / ".evergreen" / "spec-patch"
+    (patch_dir / "PYTHON-9999.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"
+        "+++ b/test/auth/auth.json\n"
+        "@@ -1 +1 @@\n"
+        "-old\n"
+        "+new\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-9999" in result.output
+    assert "🩹" in result.output