feat: merge the PR-comment browser + editor CTAs into one line

brovatten · claude · brovatten · commit f8b3b03d4d7f · 2026-06-14T00:31:35.000+02:00
Replace the two stacked CTA lines (a '🌐 Explore … in your browser →' line and a separate 'See this … in your editor: Open in VS Code →' line) with a single sentence: 'Explore this PR's architecture in your browser or VS Code.' The browser link only joins when webview_ready (head analysis committed, non-fork PR); 'your' rides with the browser entry alone so it still reads right when only the editor link is present ('… in VS Code'). Multiple editors render with an Oxford 'or' ('browser, VS Code, or Cursor'). The ⚠️ health banner and the proxy-only 'Get the extension' line stay separate. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
diff --git a/scripts/build_cta.py b/scripts/build_cta.py
@@ -1,16 +1,18 @@
 """Build the call-to-action footer appended to the architecture-diff PR comment.
 
-The footer drives to the VS Code/Cursor **extension** with an editor link, and a
-warning banner when real health findings exist. With a click proxy (``cta_base``)
-the links route through it (owner/repo/pr tracked) and can deep-link into the
-editor (the proxy redirects to a ``vscode:``/``cursor:`` URL) plus a separate
-"install the extension" link. Without a proxy GitHub's comment sanitizer strips
-custom ``vscode:``/``cursor:`` schemes — a deep link would render as dead text —
-so the editor link points at the extension's plain-https listing instead (VS Code
-Marketplace, Cursor via Open VSX), which is the only clickable option. A no-install
-hosted-webview ("explore in browser") line is added when ``webview_ready`` — i.e. the
-head ``analysis.json`` was committed to the PR branch and this isn't a fork PR — so
-the webview can fetch a committed analysis at the head SHA (see docs/COMMIT_STRATEGY.md).
+The body is a single line — "Explore this PR's architecture in your browser or
+VS Code" — that merges the hosted-webview link with the editor link(s), preceded by
+a warning banner when real health findings exist. The "browser" link (a no-install
+hosted webview) is included only when ``webview_ready`` — i.e. the head
+``analysis.json`` was committed to the PR branch and this isn't a fork PR — so the
+webview can fetch a committed analysis at the head SHA (see docs/COMMIT_STRATEGY.md);
+otherwise the line is just the editor link(s). With a click proxy (``cta_base``) the
+editor link routes through it (owner/repo/pr tracked) and deep-links into the editor
+(the proxy redirects to a ``vscode:``/``cursor:`` URL), and a separate "install the
+extension" link is appended. Without a proxy GitHub's comment sanitizer strips custom
+``vscode:``/``cursor:`` schemes — a deep link would render as dead text — so the editor
+link points at the extension's plain-https listing instead (VS Code Marketplace, Cursor
+via Open VSX), which is the only clickable option.
 
 Editor coverage is deliberately limited to **VS Code and Cursor**. Per the 2025
 Stack Overflow Developer Survey (https://survey.stackoverflow.co/2025/technology/),
@@ -59,22 +61,31 @@ def detect_editors(repo_path: Path) -> list[str]:
 }
 
 
-def build_webview_link(webview_base: str, owner: str, repo: str, head_sha: str, base_sha: str) -> str | None:
-    """Return the markdown "explore in browser" line, or None if not buildable.
+def webview_url(webview_base: str, owner: str, repo: str, head_sha: str, base_sha: str) -> str | None:
+    """Return the hosted-webview deep-link URL for this PR's head-vs-base diff, or None.
 
-    Deep-links the hosted webview straight to this PR's head-vs-base architecture
-    diff: ``?repo=owner/repo&ref=<head_sha>&compare=<base_sha>``. Pinned to exact
-    SHAs so the committed ``analysis.json`` the webview fetches matches this run. For
-    a private repo the webview itself sends the viewer through GitHub sign-in and then
-    loads the same diff. Returns None when the base/head pieces aren't all present.
+    Deep-links straight to the diff: ``?repo=owner/repo&ref=<head_sha>&compare=<base_sha>``.
+    Pinned to exact SHAs so the committed ``analysis.json`` the webview fetches matches
+    this run. For a private repo the webview itself sends the viewer through GitHub
+    sign-in and then loads the same diff. Returns None when the base/head pieces aren't
+    all present.
     """
     if not (webview_base and owner and repo and head_sha):
         return None
     base = webview_base.rstrip("/")
     params = {"repo": f"{owner}/{repo}", "ref": head_sha}
     if base_sha:
         params["compare"] = base_sha
-    return f"🌐 [**Explore this PR’s architecture in your browser →**]({base}/?{urlencode(params)})"
+    return f"{base}/?{urlencode(params)}"
+
+
+def _join_or(items: list[str]) -> str:
+    """Join with commas and a trailing 'or': 'a' / 'a or b' / 'a, b, or c'."""
+    if len(items) <= 1:
+        return items[0] if items else ""
+    if len(items) == 2:
+        return f"{items[0]} or {items[1]}"
+    return ", ".join(items[:-1]) + f", or {items[-1]}"
 
 
 def build_cta(
@@ -108,11 +119,6 @@ def build_cta(
         noun = "issue" if issues == 1 else "issues"
         parts.append(f"⚠️ **{issues} architecture {noun} found** — open CodeBoarding to explore them.")
 
-    if webview_ready:
-        webview_line = build_webview_link(webview_base, owner, repo, head_sha, base_sha)
-        if webview_line:
-            parts.append(webview_line)
-
     editors = detect_editors(repo_path)
     if cta_base:
         base = cta_base.rstrip("/")
@@ -126,8 +132,18 @@ def link(path: str, **extra: str) -> str:
         editor_href = {e: _EDITOR_MARKETPLACE[e] for e in editors}
         extension_href = None
 
-    editor_links = " · ".join(f"[**Open in {_EDITOR_LABEL[e]} →**]({editor_href[e]})" for e in editors)
-    parts.append(f"See this architecture in your editor: {editor_links}")
+    # One line that merges the hosted-webview "browser" link — only when
+    # ``webview_ready`` (the head analysis was committed and this isn't a fork PR) —
+    # with the editor link(s), which always render. "your" rides with the browser
+    # entry alone, so the sentence reads naturally with or without it:
+    # "in your browser or VS Code" / "in VS Code".
+    targets: list[str] = []
+    if webview_ready:
+        wv = webview_url(webview_base, owner, repo, head_sha, base_sha)
+        if wv:
+            targets.append(f"your [**browser**]({wv})")
+    targets += [f"[**{_EDITOR_LABEL[e]}**]({editor_href[e]})" for e in editors]
+    parts.append(f"Explore this PR’s architecture in {_join_or(targets)}.")
     if extension_href:
         parts.append(f"💡 New to CodeBoarding? [**Get the extension →**]({extension_href})")
 
diff --git a/tests/test_build_cta.py b/tests/test_build_cta.py
@@ -35,15 +35,15 @@ def test_no_proxy_links_editor_to_https_listing_no_get_extension(self):
         out = bc.build_cta("", "o", "r", "1", repo_with(".cursor"), issues=3)
         self.assertIn("3 architecture issues found", out)
         # Cursor -> Open VSX https listing. A cursor: scheme would be stripped by GitHub.
-        self.assertIn("[**Open in Cursor →**](https://open-vsx.org/extension/CodeBoarding/codeboarding)", out)
+        self.assertIn("[**Cursor**](https://open-vsx.org/extension/CodeBoarding/codeboarding)", out)
         self.assertNotIn("cursor:extension", out)
         self.assertNotIn("Get the extension", out)  # dropped without a proxy
-        self.assertNotIn("Open in VS Code", out)  # cursor-only repo
+        self.assertNotIn("VS Code", out)  # cursor-only repo
 
     def test_no_proxy_vscode_marketplace_https_no_banner_at_zero(self):
         out = bc.build_cta("", "o", "r", "1", repo_with())  # neither dir, no issues
         self.assertIn(
-            "[**Open in VS Code →**](https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding)",
+            "[**VS Code**](https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding)",
             out,
         )
         self.assertNotIn("vscode:extension", out)  # custom scheme stripped by GitHub
@@ -53,22 +53,21 @@ def test_no_proxy_vscode_marketplace_https_no_banner_at_zero(self):
     def test_links_banner_and_cursor_only(self):
         out = bc.build_cta("https://x.dev/", "Org", "Repo", "9", repo_with(".cursor"), issues=2)
         self.assertIn("2 architecture issues found", out)
-        self.assertNotIn("use-workspace", out)  # webview/browser tier deferred — extension-direct
         self.assertIn("open-in-editor?owner=Org&repo=Repo&pr=9&editor=cursor", out)
-        self.assertIn("use-marketplace?owner=Org&repo=Repo&pr=9", out)
-        self.assertNotIn("Open in VS Code", out)  # cursor-only repo
+        self.assertIn("use-marketplace?owner=Org&repo=Repo&pr=9", out)  # proxy "Get the extension"
+        self.assertNotIn("VS Code", out)  # cursor-only repo
 
     def test_no_banner_when_zero_issues_and_default_vscode(self):
         out = bc.build_cta("https://x.dev", "o", "r", "1", repo_with(), issues=0)
         self.assertNotIn("architecture issue", out)
-        self.assertIn("Open in VS Code", out)
-        self.assertNotIn("Open in Cursor", out)
+        self.assertIn("VS Code", out)
+        self.assertNotIn("Cursor", out)
 
     def test_both_editors_singular_issue(self):
         out = bc.build_cta("https://x.dev", "o", "r", "1", repo_with(".vscode", ".cursor"), issues=1)
         self.assertIn("1 architecture issue found", out)  # singular
-        self.assertIn("Open in VS Code", out)
-        self.assertIn("Open in Cursor", out)
+        self.assertIn("VS Code", out)
+        self.assertIn("Cursor", out)
 
     def test_trailing_slash_in_base_is_normalized(self):
         a = bc.build_cta("https://x.dev/", "o", "r", "1", repo_with())
@@ -77,26 +76,27 @@ def test_trailing_slash_in_base_is_normalized(self):
         self.assertEqual(a, b)
 
 
-class TestWebviewLink(unittest.TestCase):
+class TestWebviewUrl(unittest.TestCase):
     WV = "https://app.codeboarding.org"
 
-    def test_link_built_with_head_ref_and_compare_base(self):
-        link = bc.build_webview_link(self.WV, "Org", "Repo", "headsha", "basesha")
-        self.assertIn("https://app.codeboarding.org/?", link)
-        self.assertIn("repo=Org%2FRepo", link)
-        self.assertIn("ref=headsha", link)
-        self.assertIn("compare=basesha", link)
+    def test_url_built_with_head_ref_and_compare_base(self):
+        url = bc.webview_url(self.WV, "Org", "Repo", "headsha", "basesha")
+        self.assertIn("https://app.codeboarding.org/?", url)
+        self.assertIn("repo=Org%2FRepo", url)
+        self.assertIn("ref=headsha", url)
+        self.assertIn("compare=basesha", url)
+        self.assertFalse(url.startswith("🌐"))  # a bare URL now, not a markdown line
 
-    def test_link_omits_compare_when_no_base(self):
-        link = bc.build_webview_link(self.WV, "o", "r", "headsha", "")
-        self.assertIn("ref=headsha", link)
-        self.assertNotIn("compare=", link)
+    def test_url_omits_compare_when_no_base(self):
+        url = bc.webview_url(self.WV, "o", "r", "headsha", "")
+        self.assertIn("ref=headsha", url)
+        self.assertNotIn("compare=", url)
 
-    def test_link_none_without_head_sha_or_base(self):
-        self.assertIsNone(bc.build_webview_link(self.WV, "o", "r", "", "basesha"))
-        self.assertIsNone(bc.build_webview_link("", "o", "r", "headsha", "basesha"))
+    def test_url_none_without_head_sha_or_base(self):
+        self.assertIsNone(bc.webview_url(self.WV, "o", "r", "", "basesha"))
+        self.assertIsNone(bc.webview_url("", "o", "r", "headsha", "basesha"))
 
-    def test_cta_emits_webview_line_when_ready(self):
+    def test_cta_includes_browser_link_when_ready(self):
         out = bc.build_cta(
             "",
             "Org",
@@ -110,10 +110,12 @@ def test_cta_emits_webview_line_when_ready(self):
             webview_ready=True,
         )
         self.assertIn("Explore this PR", out)
+        self.assertIn("your [**browser**](", out)
         self.assertIn("ref=headsha", out)
         self.assertIn("compare=basesha", out)
+        self.assertIn("VS Code", out)  # editor merged into the same line
 
-    def test_cta_omits_webview_line_when_not_ready(self):
+    def test_cta_omits_browser_link_when_not_ready(self):
         # Fork PR / head analysis not committed -> webview can't fetch at head SHA.
         out = bc.build_cta(
             "",
@@ -127,11 +129,12 @@ def test_cta_omits_webview_line_when_not_ready(self):
             base_sha="basesha",
             webview_ready=False,
         )
-        self.assertNotIn("Explore this PR", out)
-        # Editor CTA is still present regardless.
-        self.assertIn("Open in VS Code", out)
+        self.assertNotIn("ref=headsha", out)  # no browser link
+        self.assertNotIn("[**browser**]", out)
+        self.assertIn("Explore this PR", out)  # the line is still there, editor-only
+        self.assertIn("VS Code", out)
 
-    def test_cta_omits_webview_line_when_ready_but_no_base_url(self):
+    def test_cta_omits_browser_link_when_ready_but_no_base_url(self):
         out = bc.build_cta(
             "",
             "Org",
@@ -144,7 +147,45 @@ def test_cta_omits_webview_line_when_ready_but_no_base_url(self):
             base_sha="basesha",
             webview_ready=True,
         )
-        self.assertNotIn("Explore this PR", out)
+        self.assertNotIn("[**browser**]", out)
+        self.assertNotIn("ref=headsha", out)
+
+
+class TestJoinOr(unittest.TestCase):
+    def test_join_shapes(self):
+        self.assertEqual(bc._join_or(["a"]), "a")
+        self.assertEqual(bc._join_or(["a", "b"]), "a or b")
+        self.assertEqual(bc._join_or(["a", "b", "c"]), "a, b, or c")
+
+
+class TestMergedExploreLine(unittest.TestCase):
+    WV = "https://app.codeboarding.org"
+
+    def _ready(self, repo, cta=""):
+        return bc.build_cta(
+            cta, "o", "r", "1", repo, webview_base=self.WV, head_sha="h", base_sha="b", webview_ready=True
+        )
+
+    def test_browser_and_single_editor_joined_with_or(self):
+        out = self._ready(repo_with())  # default VS Code
+        self.assertIn("in your [**browser**](", out)
+        self.assertIn(") or [**VS Code**](", out)  # browser <or> editor on one line
+
+    def test_editor_only_has_no_your_and_no_browser(self):
+        out = bc.build_cta("", "o", "r", "1", repo_with())  # no webview
+        self.assertIn("architecture in [**VS Code**](", out)  # "in <editor>" with no "your"
+        self.assertNotIn("browser", out)
+
+    def test_browser_and_two_editors_use_oxford_or(self):
+        out = self._ready(repo_with(".vscode", ".cursor"))
+        self.assertIn("your [**browser**](", out)
+        self.assertIn(", or [**Cursor**](", out)  # 3 targets -> ", or" before the last
+
+    def test_two_editors_no_browser_joined_with_or(self):
+        out = bc.build_cta("", "o", "r", "1", repo_with(".vscode", ".cursor"))
+        self.assertIn(" or [**Cursor**](", out)
+        self.assertNotIn(", or [**Cursor**]", out)  # 2 targets -> plain "or", no Oxford comma
+        self.assertNotIn("browser", out)
 
 
 if __name__ == "__main__":
