Expose scan references in JSON reports

[John-David Dalton (jdalton)]

LLM Description written by Codex:GPT-6

---

JSON consumers can identify a comparison and open its original full-scan reports without parsing URLs or display text.

• Adds five nullable fields: diff_scan_id, old_scan_id, new_scan_id, old_scan_url, and new_scan_url.
• Preserves the nine existing fields and documents canonical URLs versus display links.

Why?

Automation needs stable scan references even when comparison output falls back to a full scan. Missing references remain null.

Builds on #399 in the #396 → #398 → #399 stack.

Validation

32 focused tests and scoped Ruff passed, including real Core/SDK requests against the approved local Socket API fixture. Source review found no blockers. No package published.

Public Changelog

Add comparison and full-scan references to standard Socket JSON reports.

---

Note

Low Risk
Additive JSON fields and documentation only; existing consumers keep prior keys and semantics, with nulls when references are unavailable.

Overview
Standard Socket JSON (--enable-json) now exposes comparison and full-scan identity so automation can link results without parsing URLs.

build_socket_json_report adds five nullable top-level fields copied from the Diff / ReportReferences layer: diff_scan_id, old_scan_id, new_scan_id, old_scan_url, and new_scan_url. Existing keys (full_scan_id, diff_url, report_url, alerts, metadata) are unchanged; full_scan_id still means the new full-scan ID (not the comparison ID). Missing references serialize as JSON null (fallback comparisons, full-only scans, no-run sentinels). new_scan_url is documented as the canonical scan URL, distinct from report_url (display link, e.g. license-detail query params). CLI reference documents this; FOSSA compatibility output is explicitly out of scope.

Tests cover unit serialization (null vs populated, no URL inference) and Core/integration paths for diff, full scan, and no-change runs.

^{Reviewed by Cursor Bugbot for commit 8193af4. Configure here.}