Fix diff-scan poll so omit_license_details is honored

cached=true ignores omit_license_details per the Socket API, so poll for
readiness with the cached endpoint and re-fetch the lean payload without
cached when license details should be omitted (CE-224).

Author: cursoragent

socketsecurity/core/__init__.py

@@ -1337,6 +1337,11 @@ def get_diff_scan_artifacts(
         the backend computes, so the comparison survives network idle timeouts
         (CE-354). See the DIFF_SCAN_POLL_* constants for the polling policy.
 
+        When ``include_license_details`` is False (the default), a final fetch
+        without ``cached`` requests ``omit_license_details=true``. The API
+        ignores that flag on cached responses, so the lean payload has to come
+        from a separate non-cached get (CE-224).
+
         Requires an org token with the ``diff-scans:create``, ``diff-scans:list``
         and ``full-scans:list`` scopes; callers are expected to catch failures and
         fall back to the legacy streaming comparison.
@@ -1368,10 +1373,16 @@ def get_diff_scan_artifacts(
         # which case the create response already carries the artifacts.
         artifacts_dict = diff_scan.get("artifacts")
 
-        poll_params = {
-            "cached": "true",
-            "omit_license_details": "false" if include_license_details else "true",
-        }
+        # Poll with cached=true for short bounded 202/200 responses (CE-354).
+        # The API ignores omit_license_details whenever cached=true — cached
+        # payloads always embed full license data — so readiness polling never
+        # requests it. When license details should be omitted (the default;
+        # CE-224), the lean payload is fetched separately below without cached.
+        poll_params = {"cached": "true"}
+        if not include_license_details:
+            # Keep the readiness response small so the ignored omit doesn't
+            # reintroduce large-response truncation while we wait for 200.
+            poll_params["omit_unchanged"] = "true"
         deadline = time.monotonic() + DIFF_SCAN_POLL_TIMEOUT_SECONDS
         interval = DIFF_SCAN_POLL_INITIAL_INTERVAL_SECONDS
         while artifacts_dict is None:
@@ -1404,6 +1415,21 @@ def get_diff_scan_artifacts(
             time.sleep(interval)
             interval = min(interval * DIFF_SCAN_POLL_BACKOFF_MULTIPLIER, DIFF_SCAN_POLL_MAX_INTERVAL_SECONDS)
 
+        # Cached results always include license details. Re-fetch once without
+        # cached so omit_license_details is honored and the diff stays lean.
+        if not include_license_details:
+            response = self.sdk.diffscans.get(
+                self.config.org_slug,
+                diff_scan_id,
+                params={"omit_license_details": "true"},
+            )
+            scan = response.get("diff_scan") or {}
+            if scan.get("artifacts") is None:
+                raise Exception(
+                    f"Error fetching diff scan {diff_scan_id}: unexpected response: {str(response)[:500]}"
+                )
+            artifacts_dict = scan["artifacts"]
+
         return DiffArtifacts.from_dict({
             key: artifacts_dict.get(key) or []
             for key in ("added", "removed", "unchanged", "replaced", "updated")

tests/core/test_diff_scan_polling.py

@@ -26,11 +26,14 @@ def no_sleep(mocker):
 def test_polls_until_diff_scan_ready(core, diff_scan_get_response, no_sleep):
     """202 processing responses are polled through until the 200 result arrives."""
     processing = {"status": "processing", "id": "diff-scan-123"}
-    core.sdk.diffscans.get.side_effect = [processing, processing, diff_scan_get_response]
+    # Final cached poll + lean omit_license_details re-fetch.
+    core.sdk.diffscans.get.side_effect = [
+        processing, processing, diff_scan_get_response, diff_scan_get_response
+    ]
 
     artifacts = core.get_diff_scan_artifacts("head", "new")
 
-    assert core.sdk.diffscans.get.call_count == 3
+    assert core.sdk.diffscans.get.call_count == 4
     assert no_sleep.call_count == 2  # slept between polls, never during them
     assert len(artifacts.added) > 0
 
@@ -40,7 +43,9 @@ def test_poll_interval_backs_off(core, diff_scan_get_response, no_sleep, monkeyp
     monkeypatch.setattr(core_module, "DIFF_SCAN_POLL_INITIAL_INTERVAL_SECONDS", 4.0)
     monkeypatch.setattr(core_module, "DIFF_SCAN_POLL_MAX_INTERVAL_SECONDS", 10.0)
     processing = {"status": "processing", "id": "diff-scan-123"}
-    core.sdk.diffscans.get.side_effect = [processing] * 4 + [diff_scan_get_response]
+    core.sdk.diffscans.get.side_effect = (
+        [processing] * 4 + [diff_scan_get_response, diff_scan_get_response]
+    )
 
     core.get_diff_scan_artifacts("head", "new")
 
@@ -50,11 +55,13 @@ def test_poll_interval_backs_off(core, diff_scan_get_response, no_sleep, monkeyp
 
 def test_transient_poll_error_is_retried(core, diff_scan_get_response, no_sleep):
     """A dropped poll doesn't abandon the flow - the diff keeps computing server-side."""
-    core.sdk.diffscans.get.side_effect = [APIConnectionError("reset"), diff_scan_get_response]
+    core.sdk.diffscans.get.side_effect = [
+        APIConnectionError("reset"), diff_scan_get_response, diff_scan_get_response
+    ]
 
     artifacts = core.get_diff_scan_artifacts("head", "new")
 
-    assert core.sdk.diffscans.get.call_count == 2
+    assert core.sdk.diffscans.get.call_count == 3
     assert len(artifacts.added) > 0
 
 
@@ -76,15 +83,45 @@ def test_poll_timeout_raises(core, no_sleep, monkeypatch):
 
 
 def test_duplicate_redirect_uses_embedded_artifacts(core, diff_scan_get_response):
-    """An on_duplicate redirect can return the computed diff scan straight away."""
+    """An on_duplicate redirect skips readiness polling; lean re-fetch still runs."""
     core.sdk.diffscans.create_from_ids.return_value = diff_scan_get_response
 
     artifacts = core.get_diff_scan_artifacts("head", "new")
 
-    core.sdk.diffscans.get.assert_not_called()
+    # Create already carried artifacts, so cached readiness polling is skipped,
+    # but omit_license_details still needs a non-cached get (cached ignores it).
+    core.sdk.diffscans.get.assert_called_once_with(
+        core.config.org_slug,
+        "diff-scan-123",
+        params={"omit_license_details": "true"},
+    )
     assert len(artifacts.added) > 0
 
 
+def test_lean_refetch_omits_license_details_without_cached(
+    core, diff_scan_get_response, no_sleep
+):
+    """omit_license_details is fetched without cached=true (API ignores it otherwise)."""
+    processing = {"status": "processing", "id": "diff-scan-123"}
+    core.sdk.diffscans.get.side_effect = [
+        processing, diff_scan_get_response, diff_scan_get_response
+    ]
+
+    core.get_diff_scan_artifacts("head", "new")
+
+    assert core.sdk.diffscans.get.call_args_list[0].kwargs["params"] == {
+        "cached": "true",
+        "omit_unchanged": "true",
+    }
+    assert core.sdk.diffscans.get.call_args_list[1].kwargs["params"] == {
+        "cached": "true",
+        "omit_unchanged": "true",
+    }
+    assert core.sdk.diffscans.get.call_args_list[2].kwargs["params"] == {
+        "omit_license_details": "true",
+    }
+
+
 def test_fallback_to_streaming_diff_on_failure(core):
     """If the diff-scans flow fails (e.g. token missing the diff-scans scopes),
     the comparison falls back to the legacy streaming diff transparently."""

tests/core/test_sdk_methods.py

@@ -239,12 +239,15 @@ def test_get_added_and_removed_packages(core):
     # include_license_details defaults to False: the diff path never consumes
     # embedded license data (license artifacts come from the PURL endpoint), so
     # requesting it only bloats the response and risks the truncation
-    # crash on large repos.
-    core.sdk.diffscans.get.assert_called_once_with(
-        core.config.org_slug,
-        "diff-scan-123",
-        params={"cached": "true", "omit_license_details": "true"},
-    )
+    # crash on large repos. cached=true ignores omit_license_details, so the
+    # poll checks readiness (optionally omitting unchanged to stay small) and
+    # a separate non-cached get fetches the lean payload.
+    get_calls = core.sdk.diffscans.get.call_args_list
+    assert len(get_calls) == 2
+    assert get_calls[0].args == (core.config.org_slug, "diff-scan-123")
+    assert get_calls[0].kwargs["params"] == {"cached": "true", "omit_unchanged": "true"}
+    assert get_calls[1].args == (core.config.org_slug, "diff-scan-123")
+    assert get_calls[1].kwargs["params"] == {"omit_license_details": "true"}
     core.sdk.fullscans.stream_diff.assert_not_called()
 
     # Verify the results
@@ -263,10 +266,12 @@ def test_get_added_and_removed_packages_license_override(core):
     """The include_license_details override seam still works when explicitly requested."""
     core.get_added_and_removed_packages("head", "new", include_license_details=True)
 
+    # When license details are wanted, the cached poll response is used directly
+    # — no lean re-fetch, and omit_license_details is not sent.
     core.sdk.diffscans.get.assert_called_once_with(
         core.config.org_slug,
         "diff-scan-123",
-        params={"cached": "true", "omit_license_details": "false"},
+        params={"cached": "true"},
     )
 
 def test_empty_alerts_preserved(core):