perf(diff): skip unchanged artifacts when no output reads them

Cached diff-scan responses embed every unchanged artifact at roughly 1 KB each. On
a large dependency tree that is nearly the whole response — measured at ~11 MB for
a tree with ~10k unchanged packages — downloaded, deserialised into Package objects
and then discarded on every pull request.

omit_unchanged is honored by the API (unlike omit_license_details, which cached
responses ignore), so request it whenever no enabled output reads that half of the
comparison. Verified against the live API through the SDK: 192 artifacts -> 57.

Every consumer is behind an opt-in flag, so the gate is centralised in
Core._requires_unchanged_artifacts with the reasoning recorded there:

- --strict-blocking blocks on pre-existing issues via diff.unchanged_alerts
- --enable-gitlab-security includes them in the dependency scanning report
- --generate-license enumerates diff.packages, which must list every dependency
- --legal-format fossa reports all currently-present issues

Diff.to_dict serialises them too but has no callers. When cli_config is absent the
caller is unknown, so the full payload is kept.

Tests parametrise over every flag in that list so a new reader of
diff.unchanged_alerts or diff.packages cannot be added without also updating the
gate. The completion log reports omit_unchanged so it is visible whether the
optimisation engaged on a given run.

Ref: CE-379

Author: lelia

CHANGELOG.md

@@ -22,6 +22,16 @@
   smaller local fallback pattern set. Manifest results from `--sub-path` routing
   are reused during scan creation.
 
+### Changed: scan comparisons no longer fetch unused artifacts
+
+- Scan comparisons now ask the API to omit unchanged artifacts unless an enabled
+  output actually reads them (`--strict-blocking`, `--enable-gitlab-security`,
+  `--generate-license`, or `--legal-format fossa`). Cached comparison responses
+  embed every unchanged artifact at roughly 1 KB each, so on a large dependency
+  tree this was most of the response — over 10 MB for a tree of ~10k unchanged
+  packages — downloaded and parsed on every pull request even when nothing read
+  it. Behavior is unchanged for any run that uses those outputs.
+
 ### Changed: scan comparison timing is easier to attribute
 
 - Lowered the diff-scan poll ceiling from 30s to 10s. A finished comparison is no

socketsecurity/core/__init__.py

@@ -1608,14 +1608,13 @@ def get_diff_scan_artifacts(
         #
         # Verified against the live API: passing omit_license_details alongside
         # cached=true leaves the license fields in the response, but omit_unchanged
-        # IS honored and drops the unchanged artifacts entirely (~1.1 KB each). Not
-        # sent here because unchanged artifacts are not only used by
-        # --strict-blocking: create_security_comment_gitlab and the FOSSA compat
-        # issue list both read diff.unchanged_alerts unconditionally, so omitting
-        # them would silently shrink those outputs. Gating it correctly across all
-        # three consumers is worth doing - on a tree with ~10k unchanged artifacts
-        # it is over 10 MB of response - but it needs its own change.
+        # IS honored and drops the unchanged artifacts entirely (~1.1 KB each), so
+        # it is requested whenever no enabled output reads them. See
+        # _requires_unchanged_artifacts.
         poll_params = {"cached": "true"}
+        omit_unchanged = not self._requires_unchanged_artifacts()
+        if omit_unchanged:
+            poll_params["omit_unchanged"] = "true"
         poll_start = time.monotonic()
         deadline = poll_start + DIFF_SCAN_POLL_TIMEOUT_SECONDS
         interval = DIFF_SCAN_POLL_INITIAL_INTERVAL_SECONDS
@@ -1648,7 +1647,8 @@ def get_diff_scan_artifacts(
                 log.info(
                     "Diff scan comparison ready in "
                     f"{time.monotonic() - poll_start:.2f}s: id={diff_scan_id}, "
-                    f"polls={polls}, wait_before_final_poll={last_interval:.0f}s"
+                    f"polls={polls}, wait_before_final_poll={last_interval:.0f}s, "
+                    f"omit_unchanged={str(omit_unchanged).lower()}"
                 )
                 break
             if time.monotonic() >= deadline:
@@ -1666,6 +1666,39 @@ def get_diff_scan_artifacts(
             for key in ("added", "removed", "unchanged", "replaced", "updated")
         })
 
+    def _requires_unchanged_artifacts(self) -> bool:
+        """Whether any enabled output reads the unchanged half of a comparison.
+
+        A cached diff-scan response embeds every unchanged artifact at roughly 1 KB
+        each, so on a large dependency tree they are almost the entire payload
+        (~11 MB for a tree of ~10k unchanged packages) even though most runs never
+        look at them. Every consumer is behind an opt-in flag:
+
+        - ``--strict-blocking`` reads ``diff.unchanged_alerts`` to block on
+          pre-existing issues (socketcli, output, alert_selection, slack plugin).
+        - ``--enable-gitlab-security`` includes them in the GitLab dependency
+          scanning report (Messages.create_security_comment_gitlab).
+        - ``--generate-license`` enumerates ``diff.packages``, which must list every
+          dependency, not just the changed ones.
+        - ``--legal-format fossa`` reports all currently-present issues, matching
+          FOSSA's point-in-time snapshot semantics.
+
+        ``Diff.to_dict`` also serializes them but has no callers. When cli_config is
+        absent the caller is unknown, so the full payload is kept.
+
+        Keep this in sync with those consumers; test_unchanged_artifacts_gating
+        pins the list.
+        """
+        config = self.cli_config
+        if config is None:
+            return True
+        return bool(
+            getattr(config, "strict_blocking", False)
+            or getattr(config, "enable_gitlab_security", False)
+            or getattr(config, "generate_license", False)
+            or getattr(config, "legal_format", "socket") == "fossa"
+        )
+
     def get_added_and_removed_packages(
             self,
             head_full_scan_id: str,

tests/core/test_diff_scan_polling.py

@@ -153,3 +153,65 @@ def test_max_poll_interval_bounds_dead_time_for_ci_budgets():
         core_module.DIFF_SCAN_POLL_INITIAL_INTERVAL_SECONDS
         <= core_module.DIFF_SCAN_POLL_MAX_INTERVAL_SECONDS
     )
+
+
+UNCHANGED_ARTIFACT_CONSUMERS = [
+    # flag name, value that makes the flag active
+    ("strict_blocking", True),
+    ("enable_gitlab_security", True),
+    ("generate_license", True),
+    ("legal_format", "fossa"),
+]
+
+
+@pytest.mark.parametrize(("flag", "value"), UNCHANGED_ARTIFACT_CONSUMERS)
+def test_unchanged_artifacts_gating(core, diff_scan_get_response, flag, value):
+    """Any output that reads unchanged artifacts must keep them in the response.
+
+    This pins the consumer list in Core._requires_unchanged_artifacts: adding a new
+    reader of diff.unchanged_alerts or diff.packages without adding it here (and to
+    that method) would silently ship an empty result to that output.
+    """
+    from types import SimpleNamespace
+
+    defaults = {name: (False if name != "legal_format" else "socket")
+                for name, _ in UNCHANGED_ARTIFACT_CONSUMERS}
+    core.cli_config = SimpleNamespace(**{**defaults, flag: value})
+    core.sdk.diffscans.get.side_effect = None
+    core.sdk.diffscans.get.return_value = diff_scan_get_response
+
+    core.get_diff_scan_artifacts("head", "new")
+
+    params = core.sdk.diffscans.get.call_args.kwargs["params"]
+    assert "omit_unchanged" not in params, f"{flag}={value} still needs unchanged artifacts"
+
+
+def test_unchanged_artifacts_omitted_when_no_output_reads_them(core, diff_scan_get_response):
+    """With no such flag set, the ~1 KB-per-artifact unchanged half is not fetched."""
+    from types import SimpleNamespace
+
+    core.cli_config = SimpleNamespace(
+        strict_blocking=False,
+        enable_gitlab_security=False,
+        generate_license=False,
+        legal_format="socket",
+    )
+    core.sdk.diffscans.get.side_effect = None
+    core.sdk.diffscans.get.return_value = diff_scan_get_response
+
+    core.get_diff_scan_artifacts("head", "new")
+
+    params = core.sdk.diffscans.get.call_args.kwargs["params"]
+    assert params["cached"] == "true"
+    assert params["omit_unchanged"] == "true"
+
+
+def test_unknown_caller_keeps_full_payload(core, diff_scan_get_response):
+    """cli_config is optional; without it, do not assume unchanged is unused."""
+    core.cli_config = None
+    core.sdk.diffscans.get.side_effect = None
+    core.sdk.diffscans.get.return_value = diff_scan_get_response
+
+    core.get_diff_scan_artifacts("head", "new")
+
+    assert "omit_unchanged" not in core.sdk.diffscans.get.call_args.kwargs["params"]