document baseline overrides, merge-base workflow, Buildlkite-specific guidance

Signed-off-by: lelia <2418071+lelia@users.noreply.github.com>

Author: lelia

README.md

@@ -42,6 +42,26 @@ socketcli --target-path .
 socketcli --enable-gitlab-security --gitlab-security-file gl-dependency-scanning-report.json
 ```
 
+### PR scan diffed against the merge base
+
+By default, PR scans are diffed against the repository's latest head scan. To diff against
+the exact commit your PR branched from instead, pass the merge base as the baseline:
+
+```bash
+BASE_SHA=$(git merge-base origin/main HEAD)
+socketcli --pr-number 123 --base-commit-sha "$BASE_SHA"
+```
+
+> **Requirement:** `--base-commit-sha` only works if Socket already has a full scan for that
+> exact commit. In practice this means your CI must run `socketcli` on **every commit that
+> lands on your default branch** — not just some of them. If merges can land without a scan
+> (skipped/canceled builds, `[skip ci]`, path-filtered pipelines), the PR scan will fail with
+> exit code 3 rather than silently diff against the wrong baseline. See
+> [`docs/cli-reference.md`](https://github.com/SocketDev/socket-python-cli/blob/main/docs/cli-reference.md)
+> for the full requirements and a backfill pattern that makes PR jobs self-sufficient.
+
+A specific full scan ID also works: `--base-scan-id <id>`.
+
 ## SARIF use cases
 
 ### Full-scope reachable SARIF (grouped alerts)
@@ -204,8 +224,10 @@ Minimal pattern:
 | `3`  | Infrastructure or API error (timeout, network failure, unexpected error) |
 
 `--exit-code-on-api-error <N>` remaps the infrastructure-error code (`3`) to any
-value — e.g. a Buildkite `soft_fail` code, or `0` to swallow infra errors. Exit
-`3` is a Socket convention, not an industry standard.
+value — e.g. a Buildkite
+[`soft_fail`](https://buildkite.com/docs/pipelines/configure/step-types/command-step)
+code, or `0` to swallow infra errors. Exit `3` is a Socket convention, not an
+industry standard.
 
 ### How these options interact
 

docs/ci-cd.md

@@ -81,6 +81,54 @@ steps:
       SOCKET_SECURITY_API_TOKEN: "${SOCKET_SECURITY_API_TOKEN}"
 ```
 
+#### Merge-base baselines in Buildkite (dynamic pipelines)
+
+Notes for using `--base-commit-sha` (see the
+[merge-base note in the CLI reference](cli-reference.md#pull-request-and-commit))
+when your steps are emitted by a
+[dynamic pipeline](https://buildkite.com/docs/pipelines/configure/dynamic-pipelines)
+generator rather than a static YAML file:
+
+- **Compute the merge base at generation time, not step time.** The generator runs
+  with a full checkout; step agents may have shallow or fresh clones where
+  `git merge-base` fails or needs an extra fetch. Resolve it once in the generator and
+  bake it into the emitted step's `env`. Diff against the PR's *target* branch, which
+  isn't always the default branch (see Buildkite's
+  [environment variables](https://buildkite.com/docs/pipelines/configure/environment-variables)):
+
+  ```shell
+  TARGET="${BUILDKITE_PULL_REQUEST_BASE_BRANCH:-$BUILDKITE_PIPELINE_DEFAULT_BRANCH}"
+  BASE_SHA=$(git merge-base "origin/${TARGET}" HEAD)
+  ```
+
+- **Emit the backfill step conditionally from the generator.** The generator is the
+  natural place for the "does a baseline scan exist?" check
+  (`GET /orgs/{org}/full-scans?repo=<repo>&commit_hash=$BASE_SHA&per_page=1`): only
+  emit the baseline-scan step when it returns nothing. The emitted pipeline then shows
+  in the UI whether a backfill will run.
+
+- **Keep the backfill inside one command step.** The checkout-base → scan →
+  checkout-PR sequence must not be split across steps — steps can land on different
+  agents with different checkouts. Prefer
+  [`git worktree`](https://git-scm.com/docs/git-worktree) over mutating the step's
+  checkout: `git worktree add /tmp/socket-base "$BASE_SHA"` then
+  `socketcli --target-path /tmp/socket-base --branch "$TARGET" --disable-blocking`.
+
+- **Soft-fail infra errors, not findings.** A missing baseline (or any API error)
+  exits with code 3 (`--exit-code-on-api-error` to change it); real findings exit 1.
+  [`soft_fail: [{exit_status: 3}]`](https://buildkite.com/docs/pipelines/configure/step-types/command-step)
+  on the PR scan step keeps infra errors from blocking merges while security findings
+  still do.
+
+- **["Cancel intermediate builds"](https://buildkite.com/docs/pipelines/configure/canceling-builds#cancel-running-intermediate-builds)
+  on the default branch is the main source of baseline gaps.** Canceled builds never
+  scan their commit, so merge-base lookups for PRs based on those commits fail. The
+  conditional backfill step above is the remedy; there is no per-step exemption from
+  build cancellation in Buildkite. If you need strict scan-once semantics for
+  concurrent backfills of the same merge base, serialize the backfill step with a
+  [concurrency group](https://buildkite.com/docs/pipelines/configure/workflows/controlling-concurrency)
+  keyed on the merge-base SHA.
+
 ### GitLab CI
 
 ```yaml

docs/cli-reference.md

@@ -146,6 +146,7 @@ This will simultaneously generate:
 socketcli [-h] [--api-token API_TOKEN] [--repo REPO] [--workspace WORKSPACE] [--repo-is-public] [--branch BRANCH] [--integration {api,github,gitlab,azure,bitbucket}]
           [--config <path>]
           [--owner OWNER] [--pr-number PR_NUMBER] [--commit-message COMMIT_MESSAGE] [--commit-sha COMMIT_SHA] [--committers [COMMITTERS ...]]
+          [--base-scan-id BASE_SCAN_ID | --base-commit-sha BASE_COMMIT_SHA]
           [--target-path TARGET_PATH] [--sbom-file SBOM_FILE] [--license-file-name LICENSE_FILE_NAME] [--save-submitted-files-list SAVE_SUBMITTED_FILES_LIST]
           [--save-manifest-tar SAVE_MANIFEST_TAR] [--files FILES] [--sub-path SUB_PATH] [--workspace-name WORKSPACE_NAME]
           [--excluded-ecosystems EXCLUDED_ECOSYSTEMS] [--exclude-paths EXCLUDE_PATHS] [--include-dirs INCLUDE_DIRS] [--default-branch] [--pending-head] [--generate-license] [--enable-debug]
@@ -191,6 +192,39 @@ If you don't want to provide the Socket API Token every time then you can use th
 | `--pr-number`      | False    | "0"     | Pull request number                            |
 | `--commit-message` | False    | *auto*  | Commit message (auto-detected from git)       |
 | `--commit-sha`     | False    | *auto*  | Commit SHA (auto-detected from git)           |
+| `--base-scan-id`   | False    |         | Full scan ID to diff against, overriding the repository's head scan as the baseline. Mutually exclusive with `--base-commit-sha` |
+| `--base-commit-sha`| False    |         | Commit SHA to diff against, overriding the repository's head scan as the baseline. The most recent full scan for that commit is used; the CLI errors (exit code 3, or `--exit-code-on-api-error`) if no scan exists for it. Mutually exclusive with `--base-scan-id` |
+
+> **Diffing against the merge base** — by default, PR scans are diffed against the repository's *latest* head scan, which may include newer default-branch commits than your PR branched from. To diff against the exact commit your PR is based on, compute the merge base and pass it as the baseline:
+>
+> ```shell
+> BASE_SHA=$(git merge-base origin/main HEAD)
+> socketcli --pr-number 123 --base-commit-sha "$BASE_SHA"
+> ```
+>
+> **Requirement: a full scan must already exist for the merge-base commit.** `--base-commit-sha` does not create a scan of that commit; it looks up an existing one. That lookup only succeeds if your CI runs `socketcli` on **every commit that lands on your default branch** — every merge and direct push, not just periodic or latest-only scans. Common ways commits slip through without a scan:
+>
+> - CI settings that cancel or skip intermediate builds when newer commits land (e.g. Buildkite's ["cancel intermediate builds"](https://buildkite.com/docs/pipelines/configure/canceling-builds#cancel-running-intermediate-builds))
+> - `[skip ci]` commits, path-filtered pipelines, or failed/canceled scan steps
+> - merge-base commits that predate your Socket rollout
+>
+> If no scan exists for the commit, the CLI **fails** (exit code 3, or your `--exit-code-on-api-error` value; exit 0 with `--disable-blocking`) instead of silently falling back to the head scan — a wrong baseline would misreport which alerts the PR introduces. Don't adopt this flag without default-branch scan coverage in place; you'll fail PR builds on lookup misses.
+>
+> **Backfill pattern** — if your default-branch coverage has gaps, the PR job can create the missing baseline itself before scanning:
+>
+> ```shell
+> BASE_SHA=$(git merge-base origin/main HEAD)
+> # Create the baseline only if Socket doesn't have one for this commit yet
+> # (check: GET /orgs/{org}/full-scans?repo=<repo>&commit_hash=$BASE_SHA&per_page=1)
+> git checkout "$BASE_SHA"
+> socketcli --branch main --disable-blocking
+> git checkout -
+> socketcli --pr-number 123 --base-commit-sha "$BASE_SHA"
+> ```
+>
+> Run the baseline step with `--disable-blocking` (findings on the default branch must not fail the PR job) and an explicit `--branch`, since branch auto-detection is unreliable at a detached HEAD.
+>
+> Buildkite users with dynamically generated pipelines: see [Merge-base baselines in Buildkite](ci-cd.md#merge-base-baselines-in-buildkite-dynamic-pipelines) for generation-time vs. step-time guidance.
 
 #### Path and File
 | Parameter                   | Required | Default               | Description                                                                                                                                                                      |