From c6dad9730e163cd2fbe37acf99493f5ab935d86c Mon Sep 17 00:00:00 2001
From: Jan Rose <jan.rose@databricks.com>
Date: Thu, 27 Aug 2026 17:18:12 +0200
Subject: [PATCH 1/4] Make gh_report side-effect free on import

---
 tools/gh_report.py | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/tools/gh_report.py b/tools/gh_report.py
index 41cab633281..455899529d4 100755
--- a/tools/gh_report.py
+++ b/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:

From 7b620d8f943ea0603bce950fc5cb7ee030fd2317 Mon Sep 17 00:00:00 2001
From: Jan Rose <jan.rose@databricks.com>
Date: Thu, 27 Aug 2026 17:18:28 +0200
Subject: [PATCH 2/4] Add test-doctest to run doctest on python scripts

---
 Taskfile.yml | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/Taskfile.yml b/Taskfile.yml
index 8ed24ad0f60..dc269324532 100644
--- a/Taskfile.yml
+++ b/Taskfile.yml
@@ -514,6 +514,20 @@ 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": three of these
+    # carry a PEP 723 `requires-python = ">=3.12"`.
+    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)

From e453d3d7f2f4656c42779dcca1802033635d61c3 Mon Sep 17 00:00:00 2001
From: Jan Rose <jan.rose@databricks.com>
Date: Thu, 27 Aug 2026 17:22:06 +0200
Subject: [PATCH 3/4] Run doctest on checks

---
 Taskfile.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Taskfile.yml b/Taskfile.yml
index dc269324532..e9aeb6df4c7 100644
--- a/Taskfile.yml
+++ b/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

From 7d8f8533e2fd9822e978e0b1f8ee3fb075357753 Mon Sep 17 00:00:00 2001
From: Jan Rose <jan.rose@databricks.com>
Date: Thu, 27 Aug 2026 17:29:11 +0200
Subject: [PATCH 4/4] Update comment

---
 Taskfile.yml | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Taskfile.yml b/Taskfile.yml
index e9aeb6df4c7..82858588dfc 100644
--- a/Taskfile.yml
+++ b/Taskfile.yml
@@ -521,8 +521,10 @@ tasks:
     # 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": three of these
-    # carry a PEP 723 `requires-python = ">=3.12"`.
+    # 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