Add --base-scan-id / --base-commit-sha flags for diffing against a chosen baseline

[lelia]

Summary

PR scans always diff against the repository's latest head scan, which on very active repositories can include default-branch changes the PR never branched from, thereby misattributing or masking alerts.

This adds two (mutually exclusive) flags that let CI pin the diff baseline to a specific scan or commit, most usefully the PR's merge base (git merge-base origin/main HEAD). Intended for teams whose default branch moves faster than their PRs and who scan every commit landing on it.

Adds

• --base-scan-id <id> to diff against a specific full scan ID
• --base-commit-sha <sha> to diff against the newest full scan for that commit
  • 💡 This flag is scoped to the same workspace and scan type as the new scan. It fails (exit 3 / --exit-code-on-api-error, or 0 with --disable-blocking) when no scan exists rather than silently falling back to the head scan.
• README docs with scan-coverage requirements, CLI usage refs (failure modes + backfill pattern), CI/CD guidance for Buildkite dynamic pipeline patterns
• Tests for flag parsing / mutual exclusion (both CLI and --config file scenarios) and all baseline-resolution paths

Changes

• Baseline resolution in create_new_diff now flows through a single resolve_base_full_scan_id() seam
• This behavior remains unchanged when neither flag (--base-scan-id / --base-commit-sha) is set

Fixes CE-304

[github-actions]

🚀 Preview package published!

Install with:

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple socketsecurity==2.5.0.dev1

Docker image: socketdev/cli:pr-261