docs: rewrite branch comments for the reader, not the author

Sweep of every comment this branch adds, against the fourth-wall skill:

- A test docstring stated the scan type "(since 2.8.0)", which was already
  wrong after the renumber to 2.9.0 and would rot again on the next one. Version
  stamps in comments describe a debut rather than the behavior.
- Two docstrings narrated the failure the old parser produced instead of the
  invariant that makes rsplit correct. A scoped name carrying its own "@" is the
  whole reason; the traceback it used to raise is not.
- The "do NOT use on_duplicate=redirect" landmine was explained twice, in full,
  at both call sites. Kept at the 409 fallback, where the temptation to add it
  lives; the create site now just says what update does.
- A test section header justified its own design to a reviewer ("swapping the
  call back ... fails them"). Restated as what the test actually pins.
- "out of this branch" in the remote-URL regex reads as a git branch in this
  repo; it means the regex case.

642 passed, ruff clean.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: lelia

socketsecurity/core/__init__.py

@@ -1708,12 +1708,9 @@ def get_diff_scan_artifacts(
         if external_href:
             create_params["external_href"] = external_href
             # external_href is only honored while a diff scan is being created,
-            # so re-running a comparison over an already-compared scan pair
-            # would otherwise leave the Dashboard report with no link back to
-            # the pull request. on_duplicate=update applies the link to the
-            # existing resource and answers 200 with the same {"diff_scan": ...}
-            # envelope as a create. Notably it is not on_duplicate=redirect,
-            # whose 302 the SDK follows into a GET without cached=true.
+            # so a re-run over an already-compared scan pair needs
+            # on_duplicate=update to apply the link to the existing resource. It
+            # answers 200 with the same {"diff_scan": ...} envelope as a create.
             create_params["on_duplicate"] = "update"
         try:
             result = self.sdk.diffscans.create_from_ids(self.config.org_slug, create_params)
@@ -1723,14 +1720,13 @@ def get_diff_scan_artifacts(
             if error.status_code != 409:
                 raise
 
-            # Reached without on_duplicate=update (no pull request context to
-            # attach) and against deployments that predate it and still answer
-            # 409 regardless. Do not switch this to on_duplicate=redirect: the
-            # SDK follows that 302 automatically with a GET that lacks
-            # cached=true, which can leave the connection idle while an existing
-            # diff scan is still computing. Resolve the duplicate resource
-            # explicitly so every result fetch continues through the bounded
-            # cached polling path below.
+            # Reached when there is no pull request context to attach, and on
+            # deployments that answer 409 regardless. Do NOT switch this to
+            # on_duplicate=redirect: the SDK follows that 302 automatically with
+            # a GET that lacks cached=true, which can leave the connection idle
+            # while an existing diff scan is still computing. Resolve the
+            # duplicate explicitly so every result fetch continues through the
+            # bounded cached polling path below.
             existing = self.sdk.diffscans.list(
                 self.config.org_slug,
                 params={

socketsecurity/core/git_remote.py

@@ -10,7 +10,7 @@
 from urllib.parse import urlparse
 
 # git@host:owner/repo - the scp-like syntax urlparse cannot handle. The negative
-# lookahead keeps scheme-prefixed URLs (https://, ssh://) out of this branch.
+# lookahead keeps scheme-prefixed URLs (https://, ssh://) out of this case.
 _SCP_LIKE_REMOTE = re.compile(r"^(?:[^@/]+@)?([^:/]+):(?!//)(.+)$")
 
 

socketsecurity/core/scm_comments.py

@@ -164,8 +164,7 @@ def process_original_security_comment(
                 details, _ = package.split("](")
                 ecosystem, details = details.split("/", 1)
                 ecosystem = ecosystem.lstrip("[")
-                # Split from the right: a scoped name carries its own "@", so
-                # split("@") unpacks into three parts and raises.
+                # Split from the right: a scoped name carries its own "@".
                 pkg_name, pkg_version = details.rsplit("@", 1)
                 # ignore_all has to be checked outside the loop: an ignore-all
                 # comment produces no ignore_commands, so a loop-internal check

tests/core/test_full_scan_outputs.py

@@ -1,9 +1,8 @@
 """What a full scan has to carry for each enabled output.
 
 create_full_scan_with_report_url runs on every path with no baseline to compare
-against: API mode, and (since 2.8.0) SCM branch pipelines. Fetching the SBOM is
-the expensive part, so it is gated on the enabled outputs -- these pin which
-outputs need it.
+against: API mode and SCM branch pipelines. Fetching the SBOM is the expensive
+part, so it is gated on the enabled outputs -- these pin which outputs need it.
 """
 import pytest
 from socketdev.fullscans import FullScanParams

tests/unit/test_pr_comment_rendering.py

@@ -328,7 +328,7 @@ def test_ignore_all_collapses_to_the_no_alerts_body(self):
         assert "[View full report](https://socket.dev/report/legacy)" in new_body
 
     def test_scoped_package_row_does_not_raise(self):
-        """A scoped name carries its own "@", so split("@") unpacked into three."""
+        """A scoped name carries its own "@", so the split must come from the right."""
         security = _make_comment(SCOPED_LEGACY_COMMENT)
         comments = {"security": security, "ignore": []}
 

tests/unit/test_socketcli.py

@@ -80,8 +80,8 @@ def test_pr_context_provider_uses_integration_without_comment_adapter():
 #
 # Only a pull request or merge request event has a baseline, so every other
 # pipeline gets a full scan. These drive create_scm_scan against a recording
-# stub rather than asserting on the branch predicate, so swapping the call back
-# to create_new_diff fails them.
+# stub rather than asserting on a predicate, so they fail if the branch stops
+# reaching create_full_scan_with_report_url.
 # ---------------------------------------------------------------------------