Improve `scripts/pr_file_map.py` observability and output metadata

@@ -5,12 +5,19 @@ Lists all open pull requests in the current directory's git repo (via `gh`) and, for each file touched by any open PR, which PR number(s) touch it. -Output is GitHub-flavored Markdown: a sorted list of files that currently+Output is GitHub-flavored Markdown that includes this script's path, the+current UTC datetime, and summary counts for open PRs, file entries, and+existing/missing files. It then renders a sorted list of files that currently exist in the working directory, each with its modifying PR numbers, followed by a separate section for files referenced by open PRs but that do not exist in the working directory (e.g. deleted, renamed, or on a branch not checked out locally). +Run status is also written to stderr with:+  - Number of PRs from `get_open_prs()`+  - Number of files from `get_pr_files()`+  - Number of existing and missing files+ Requirements: gh (GitHub CLI), authenticated (`gh auth login`)  Usage:@@ -19,11 +26,12 @@ """  import json-import os import shutil import subprocess import sys from collections import defaultdict+from datetime import UTC, datetime+from pathlib import Path   def run_gh(args: list[str]) -> str:@@ -73,36 +81,52 @@ def main() -> None:     check_gh_auth()      prs = get_open_prs()-    if not prs:-        print("No open pull requests found.")-        return+    pr_count = len(prs)+    print(f"PR count from get_open_prs(): {pr_count}", file=sys.stderr)      file_to_prs: dict[str, list[int]] = defaultdict(list)+    file_count = 0      for pr in prs:         pr_number = pr["number"]-        for path in get_pr_files(pr_number):+        pr_files = get_pr_files(pr_number)+        file_count += len(pr_files)+        for path in pr_files:             file_to_prs[path].append(pr_number)+    print(f"File count from get_pr_files(): {file_count}", file=sys.stderr)      existing: dict[str, list[int]] = {}     missing: dict[str, list[int]] = {}      for path, pr_numbers in file_to_prs.items():-        target = existing if os.path.exists(path) else missing+        target = existing if Path(path).exists() else missing         target[path] = sorted(set(pr_numbers))+    existing_count = len(existing)+    missing_count = len(missing)+    print(+        f"Existing files: {existing_count}, Missing files: {missing_count}",+        file=sys.stderr,+    )      # --- Render GitHub-flavored Markdown ---     print("# Open Pull Request File Map\n")+    print(f"- Script: `{Path(__file__).resolve()}`")+    print(f"- Generated (UTC): `{datetime.now(UTC).isoformat()}`")+    print(f"- Number of PRs: `{pr_count}`")+    print(f"- Number of files: `{file_count}`")+    if pr_count == 0:+        print("No open pull requests found.")+        return -    print("## Existing files\n")+    print(f"## `{existing_count}` existing files\n")     if existing:         for path in sorted(existing):             pr_list = " ".join(f"#{n}" for n in existing[path])             print(f"- `{path}`: {pr_list}")     else:         print("_None._") -    print("\n## Files not present in the working directory\n")+    print(f"\n## `{missing_count}` files not present in the working directory\n")     if missing:         for path in sorted(missing):             pr_list = " ".join(f"#{n}" for n in missing[path])