fix: keep PR walkthrough links canonical (#3438)

scripts/pr-walkthrough-pr-body

@@ -14,6 +14,7 @@ END_MARKER = "<!-- kandev-pr-walkthrough-end -->"
 SHA_PATTERN = re.compile(r"^[0-9a-f]{40}$")
 PUBLIC_SHA_LENGTH = 12
 UNCHANGED = 3
+NO_WALKTHROUGH = 4
 
 
 def parse_args() -> argparse.Namespace:
@@ -23,6 +24,11 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("--url", required=True)
     parser.add_argument("--pr-number", type=int, required=True)
     parser.add_argument("--head-sha", required=True)
+    parser.add_argument(
+        "--require-existing",
+        action="store_true",
+        help="return a no-op when the PR body has no owned walkthrough block",
+    )
     return parser.parse_args()
 
 
@@ -93,6 +99,12 @@ def main() -> int:
     try:
         validate_url(args.url, args.pr_number, args.head_sha)
         body = load_pr(args.github_response, args.pr_number)
+        if (
+            args.require_existing
+            and START_MARKER not in body
+            and END_MARKER not in body
+        ):
+            return NO_WALKTHROUGH
         updated = update_body(body, args.url)
         if updated == body:
             return UNCHANGED

scripts/pr-walkthrough-pr-body.test.py

@@ -16,6 +16,7 @@ SHORT_HEAD_SHA = HEAD_SHA[:12]
 URL = f"https://walkthrough.kandev.ai/pr/{PR_NUMBER}/{SHORT_HEAD_SHA}.html"
 START = "<!-- kandev-pr-walkthrough-start -->"
 END = "<!-- kandev-pr-walkthrough-end -->"
+NO_WALKTHROUGH = 4
 
 
 class PRWalkthroughPRBodyTest(unittest.TestCase):
@@ -26,6 +27,7 @@ class PRWalkthroughPRBodyTest(unittest.TestCase):
         url: str = URL,
         response_number: int = PR_NUMBER,
         response_sha: str = HEAD_SHA,
+        require_existing: bool = False,
     ) -> tuple[subprocess.CompletedProcess[str], Path, tempfile.TemporaryDirectory[str]]:
         temp_dir = tempfile.TemporaryDirectory()
         root = Path(temp_dir.name)
@@ -41,21 +43,24 @@ class PRWalkthroughPRBodyTest(unittest.TestCase):
             ),
             encoding="utf-8",
         )
+        command = [
+            "python3",
+            str(SCRIPT),
+            "--github-response",
+            str(response),
+            "--output",
+            str(output),
+            "--url",
+            url,
+            "--pr-number",
+            str(PR_NUMBER),
+            "--head-sha",
+            HEAD_SHA,
+        ]
+        if require_existing:
+            command.append("--require-existing")
         result = subprocess.run(
-            [
-                "python3",
-                str(SCRIPT),
-                "--github-response",
-                str(response),
-                "--output",
-                str(output),
-                "--url",
-                url,
-                "--pr-number",
-                str(PR_NUMBER),
-                "--head-sha",
-                HEAD_SHA,
-            ],
+            command,
             cwd=REPO_ROOT,
             capture_output=True,
             text=True,
@@ -88,7 +93,7 @@ class PRWalkthroughPRBodyTest(unittest.TestCase):
             f"> **PR walkthrough:** [Open the visual walkthrough]({old_url})\n"
             f"{END}\n\nContributor content"
         )
-        result, output, temp_dir = self.run_updater(original)
+        result, output, temp_dir = self.run_updater(original, require_existing=True)
         self.addCleanup(temp_dir.cleanup)
 
         self.assertEqual(result.returncode, 0, result.stderr)
@@ -99,6 +104,15 @@ class PRWalkthroughPRBodyTest(unittest.TestCase):
         self.assertNotIn(old_url, updated)
         self.assertTrue(updated.endswith("\n\nContributor content"))
 
+    def test_reconciliation_without_an_owned_block_is_a_no_op(self) -> None:
+        result, output, temp_dir = self.run_updater(
+            "Contributor content", require_existing=True
+        )
+        self.addCleanup(temp_dir.cleanup)
+
+        self.assertEqual(result.returncode, NO_WALKTHROUGH, result.stderr)
+        self.assertFalse(output.exists())
+
     def test_reports_an_unchanged_body_without_writing_a_payload(self) -> None:
         original = (
             f"{START}\n> [!TIP]\n"
@@ -159,7 +173,7 @@ class PRWalkthroughPRBodyTest(unittest.TestCase):
             f"{START}\none\n{END}\n{START}\ntwo\n{END}",
         ):
             with self.subTest(body=body):
-                result, output, temp_dir = self.run_updater(body)
+                result, output, temp_dir = self.run_updater(body, require_existing=True)
                 self.addCleanup(temp_dir.cleanup)
                 self.assertNotEqual(result.returncode, 0)
                 self.assertFalse(output.exists())