Run python doctest against scripts

Taskfile.yml

@@ -321,7 +321,7 @@ tasks:
       - "! git grep -lF databricks.com -- '*uv.lock' '*.py.lock'"
 
   checks:
-    desc: Run quick checks (tidy, whitespace, links, deadcode, changelog, lockfiles)
+    desc: Run quick checks (tidy, whitespace, links, deadcode, changelog, lockfiles, doctests)
     # Sequential: `tidy` rewrites go.mod/go.sum and any future tidy work
     # touching more paths should not race with whitespace/link scanners.
     cmds:
@@ -331,6 +331,7 @@ tasks:
       - task: deadcode
       - task: check-changelog
       - task: check-lockfiles
+      - task: test-doctest
 
   install-pythons:
     desc: Install Python 3.9-3.13 via uv
@@ -514,6 +515,22 @@ tasks:
           --packages ./... \
           -- -timeout=${LOCAL_TIMEOUT:-60m}
 
+  test-doctest:
+    desc: Run doctests in first-party Python scripts
+    # `python -m doctest` imports every file it is given, so all these scripts
+    # must stay import-safe (no module-level side effects — keep real work under
+    # `if __name__ == "__main__"`). Globbed so new doctests are picked up
+    # automatically. --with pyyaml: generate_resources.py imports it; extend if
+    # another script grows a third-party import. -p ">=3.12": manual interpreter
+    # floor matching what most of these scripts target in their PEP 723 metadata;
+    # uv does not read that metadata here since the files are arguments to
+    # `python -m doctest`, not scripts uv runs.
+    sources:
+      - tools/*.py
+      - bundle/direct/tools/*.py
+    cmds:
+      - 'uv run -p ">=3.12" --no-project --with pyyaml python -m doctest tools/*.py bundle/direct/tools/*.py'
+
   test-acc:
     desc: Run acceptance tests
     # Sources mirror `build` (acceptance_test.go builds the CLI in-process via BuildCLI)

tools/gh_report.py

@@ -27,11 +27,6 @@
 DIRECTORY = Path(__file__).parent
 PARSE_SCRIPT = DIRECTORY / "gh_parse.py"
 
-try:
-    PARSE_SCRIPT = PARSE_SCRIPT.relative_to(os.getcwd())
-except Exception:
-    pass  # keep absolute
-
 
 def run(cmd, shell=False):
     sys.stderr.write("+ " + " ".join(cmd) + "\n")
@@ -279,7 +274,13 @@ def main():
 
     target_dir = download_run_id(args.run, repo, rm=args.rm)
     print(flush=True)
-    cmd = [sys.executable, str(PARSE_SCRIPT)]
+    # Prefer a cwd-relative path so the logged command line stays readable.
+    parse_script = PARSE_SCRIPT
+    try:
+        parse_script = parse_script.relative_to(os.getcwd())
+    except Exception:
+        pass  # keep absolute
+    cmd = [sys.executable, str(parse_script)]
     if args.filter:
         cmd.extend(["--filter", args.filter])
     if args.filter_env: