snapdrift 0.11.0 → 0.13.0

package/docs/contracts.md

@@ -159,6 +159,8 @@ The pull request drift bundle contains:
 
 ## Screenshot manifest shape
 
+Minimal legacy example (new local captures also write `captureProfile`):
+
 ```json
 {
   "generatedAt": "2024-01-01T00:00:00.000Z",
@@ -176,6 +178,75 @@ The pull request drift bundle contains:
 }
 ```
 
+### Local capture profile v2
+
+New local captures persist `captureProfile` with `schemaVersion: 2`. This version
+is independent of the outer manifest schema (which defaults to 1 when omitted)
+and comparison policy v1. The profile records:
+
+| Field | Local capture value |
+|:------|:--------------------|
+| `engine`, `engineVersion` | `{ "name": "snapdrift-local", "version": "<adapter-fs version>" }`; `engineVersion` equals `engine.version` |
+| `browser`, `browserRevision`, `playwrightVersion` | `chromium`, the running browser's `browser.version()` string, and the installed Playwright version |
+| `platform` | `name`, `architecture`, `release`, `version` from Node's OS APIs |
+| `locale`, `timezone` | `en-US`, `UTC` |
+| `settings.screenshot` | `fullPage: true`, `animations: "disabled"`, `caret: "hide"`, `scale: "device"`, `omitBackground: false`, `type: "png"` |
+| `settings.readiness` | `waitUntil: "load"`, `settleDelayMs: 300` |
+| `settings.context` | `isolation: "fresh-context-per-attempt"`, `colorScheme: "light"`, `reducedMotion: "no-preference"`, `forcedColors: "none"`, `javaScriptEnabled: true`, `serviceWorkers: "allow"` |
+| `settings.launch` | `headless: true`, `args: ["--disable-gpu"]` |
+
+These are persisted metadata, not new configuration knobs. Local v2 requires
+all listed fields with valid types/settings and matching engine version fields.
+Fonts are **not fingerprinted**: local capture does not populate the optional
+`fontsHash`, so a verified profile is not proof of identical installed fonts.
+Explicit `en-US` / `UTC` replaces environment-dependent defaults and may change
+localized text or dates; recapture affected baselines after upgrading.
+
+### Local compatibility before pixels
+
+Both manifests are validated after loading and before manifest entries are
+indexed and PNGs are resolved.
+Malformed manifests/profiles and unsupported profile schema versions (anything
+other than omitted, 1, or 2) throw before a comparison summary is generated;
+`report-only` does not suppress these input errors.
+
+- Two local v2 profiles must match exactly across the full profile, including
+  extra fields. Object key order is ignored; array order and values matter.
+  There is no version tolerance: adapter, Playwright, browser, or OS updates can
+  require a baseline refresh. The reason identifies the first differing field.
+- For each selected configured route id present in both manifests, both entries
+  must have the exact configured `path` and the same normalized viewport as the
+  config: width, height, device scale factor, mobile, and touch. Paths are not
+  URL-normalized; `baseUrl` and timestamps are not compared. Custom viewports use
+  scale 1, mobile false, touch false: 1440×900 equals `desktop`, but 390×844 does
+  not equal `mobile`. Missing entries retain their missing/error classification.
+- A profile or route-identity mismatch adds an `errors[]` item with
+  `status: "error"` and `code: "incompatible_capture"`. That route's PNGs are
+  not resolved, read, or pixel-compared, even if they would be byte-identical.
+  The summary is `incomplete`, not product drift. With compatible identity,
+  changed full-page raster dimensions remain normal union-canvas `changed[]`
+  signals, independent of threshold.
+- Missing profiles or profiles with omitted/v1 schema remain usable but
+  `unverified`, with a warning in `summary.message`; pixels can still be compared
+  after route checks. If both profiles provide `browser`, `browserRevision`,
+  `fontsHash`, `timezone`, or `locale`, a difference in any shared field is
+  incompatible. An explicit foreign `engine.name` on either side is incompatible
+  even when the other profile is absent. Legacy engine versions alone do not
+  establish verified compatibility.
+
+`summary.captureCompatibility` contains profile-level `status` (`verified`,
+`unverified`, or `incompatible`) and an optional `reason`. It is **not** an
+aggregate route status: profiles can be `verified` while route path/viewport
+checks produce `incompatible_capture` errors. Unverified alone does not make a
+run incomplete or fail enforcement.
+
+Refresh the baseline using the [existing CLI or baseline action](local-cli.md#refreshing-or-acknowledging-local-baselines)
+in the intended capture environment. For intentional nonblocking acknowledgement,
+set `diff.mode` to `report-only`: it preserves incompatibility errors and never
+overrides compatibility to compare pixels. `fail-on-incomplete` and `strict`
+fail on those errors; `fail-on-changes` does not fail on incompatibility alone
+but still fails if other comparable routes changed.
+
 ## Summary shape
 
 ```json
@@ -209,6 +280,7 @@ The pull request drift bundle contains:
 
 | Field | Type | Description |
 |:------|:-----|:------------|
+| `captureCompatibility` | `{ status, reason? }?` | Local profile-level compatibility: `verified`, `unverified`, or `incompatible`; route identity errors are separate |
 | `dashboardUrl` | `string?` | Snap dashboard URL for the run (set by `SnapProvider`; omitted by `LocalProvider`) |
 | `comparisonPolicy` | `{ "version": 1, "threshold": number }?` | Effective v1 comparison policy used by the local adapter (synthesized from `diff.threshold` when not configured) |
 
@@ -247,11 +319,12 @@ Additional missing-baseline fields: `baselineAvailable`, `currentResultsPath`.
 
 ## Drift semantics
 
-- Screenshots are matched by `id`
+- Screenshots are matched by `id`; local profile and configured path/normalized viewport compatibility are checked before pixels (see [Local compatibility before pixels](#local-compatibility-before-pixels))
 - Mismatch ratio is `different_pixels / total_pixels`
 - `diff.threshold` applies per screenshot
 - Missing captures are counted separately from drift signals
 - Comparison policy v1 `{ "version": 1, "threshold": number }` is always applied. When `diff.comparisonPolicy` is absent, SnapDrift synthesizes it from `diff.threshold`. Images are top-left aligned on a max-dimension union canvas with no scaling. Overlap pixels are compared, one-sided pixels count as changed (including transparent pixels), and empty union corners do not enter the denominator. Dimension changes land in `changed[]` with comparison metadata and a generated local diff image.
+- Local diff images are rendered with a semantic palette: orange = pixels that differ between baseline and current, green = pixels present only in the current capture (added), red = pixels present only in the baseline (removed). The palette is a rendering detail of `@snapdrift/compare-core` (`addedColor`/`removedColor`/`highlightColor` options); the frozen v1 comparison metrics are unaffected. Equal-dimension strict diffs (`generateDiffImage`) use orange for changed pixels and cannot contain added/removed pixels. Reports render a legend whenever a local diff image is embedded; summaries that carry only comparison metadata (Snap provider runs, which render diffs hosted-side) render no legend.
 - `dimensionChanges[]` remains part of the summary contract but is empty for local comparisons in v1. Strict same-dimension comparison (`compareBuffers`) remains available to direct `@snapdrift/compare-core`/`comparePngs` callers that pass no policy.
 - Threshold is applied after pixel aggregation. A mismatch exactly equal to the threshold is matched; a dimension change is still a changed signal independent of ratio.
 - `diff.mode` controls enforcement, not summary generation
@@ -260,7 +333,7 @@ Additional missing-baseline fields: `baselineAvailable`, `currentResultsPath`.
 
 | Mode | Stops the run when |
 |:-----|:-------------------|
-| `report-only` | Never |
+| `report-only` | Never from summary enforcement; validation/capture failures still fail |
 | `fail-on-changes` | `changedScreenshots > 0` |
 | `fail-on-incomplete` | Errors or missing captures occur; a completed v1 dimension comparison alone does not fail |
 | `strict` | Any drift or incomplete comparison appears |
@@ -297,7 +370,29 @@ dimensions.
 
 The comparator reports this condition with the stable error code
 `comparison_too_large` and includes the baseline, current, and union-canvas
-dimensions in the error message. Approximate maximum full-page CSS heights below
+dimensions in the error message. The ceiling that was exceeded is included too,
+since a caller may raise it per call.
+
+`32 × 1024 × 1024` is the *default* ceiling, not an algorithm property. The cost
+is dominated by the decoded images: both RGBA inputs (4 bytes per pixel each) are
+retained plus, when the diff image is rendered (the default), a union-sized diff
+canvas — at least ~12 bytes per union pixel when both inputs approach the union
+dimensions, before PNG decode/encode overhead. Measured end-to-end RSS on real
+full-page captures is ~32-35 bytes per union pixel (~1.16 GB at 33.8 M pixels,
+~3.37 GB at 103.9 M), so the default bounds a comparison to a process with a few
+GB of headroom.
+
+Direct `@snapdrift/compare-core` callers running in a larger memory envelope can
+pass `compareImages(..., { maxPixels })` to raise it for that call. **Size
+`maxPixels` against your own measured peak**, not against the byte-per-pixel
+arithmetic: PNG decode and encode overhead, GC, and concurrency all add to it. A
+missing, non-finite, or sub-1 `maxPixels` falls back to the default; fractions are
+floored (`16.9` becomes `16`). The sub-1 rule matters because a positive fraction
+such as `0.5` floors to `0`, which would otherwise reject every comparison.
+SnapDrift's own local and hosted paths keep the default, because the host process
+— not the image — decides how much memory is actually safe.
+
+Approximate maximum full-page CSS heights below
 assume that the raster width remains equal to the configured CSS width and that
 the document height scales by the same device scale factor:
 
@@ -327,6 +422,14 @@ that matches the product behavior. Do not resize or crop screenshots, or lower
 | Screenshot animations | `disabled` (Playwright finishes/cancels CSS animations before capture) |
 | Capture concurrency | 5 routes per viewport (overridable via `SNAPDRIFT_CAPTURE_CONCURRENCY`)|
 
+Local Playwright captures use a fresh browser context for every route attempt,
+including retries. Cookies and browser storage are not shared between routes,
+even when routes share a viewport or run serially. This also applies to Snap's
+local-capture hybrid, not to rendering performed by the hosted service. Viewport
+groups still run concurrently, with the configured limit applied per group.
+Previously leaked storage may have affected existing baselines; recapture them
+after upgrading if storage-dependent UI produces a one-time change.
+
 ## Local CLI directory layout
 
 When using the `snapdrift` CLI, outputs are written to `.snapdrift/` by default:
@@ -353,18 +456,16 @@ All three directories can be overridden with `--baseline-dir`, `--current-dir`,
 
 ### migrate-baselines
 
-Migrate baselines between local storage and Snap. Both directions require a `snap` block in `snapdrift.json` (or `--to local` for the `snap → local` direction, since the export call still talks to Snap first).
+Move baselines between local storage and Snap. Only the `snap → local` direction is supported; it requires a `snap` block in `snapdrift.json` (the export call talks to Snap).
 
-**Upload local baselines to Snap:**
+**Upload local baselines to Snap — not supported:**
 
 ```
-snapdrift migrate-baselines --to snap [--config <path>] [--baseline-dir <dir>]
+snapdrift migrate-baselines --to snap   # always fails
 ```
 
-- Reads `results.json`, `manifest.json`, and `screenshots/*.png` from the local baseline directory.
-- Uploads as the initial accepted baseline on Snap via `POST /v1/visual/projects/:id/baselines`.
-- Idempotent: if a baseline already exists for the same commit SHA (derived from `GITHUB_SHA` or `git rev-parse HEAD`), the upload is skipped.
-- Screenshots are base64-encoded in the request body; very large suites may want to migrate per-route.
+- The command exits with an error. Snap cannot accept a pre-built local baseline bundle: the screenshots it carries are never uploaded to Snap storage, and its manifest references local filenames rather than Snap object keys, so the call could only ever create a baseline with no pixels behind it. Snap rejects the request with `400 unsupported_baseline_body` (i2Dev-com/snap#653); the legacy `SnapProvider.migrateBaselineFromLocal()` path was removed in 0.7.0.
+- **Use `snapdrift baseline` instead** — with `provider: "snap"` it captures each route through Snap so the images actually land in storage, then publishes a baseline referencing the stored objects. Canonical hosted publication is CI-only (default-branch job); see [`snapdrift baseline`](local-cli.md#snapdrift-baseline).
 
 **Download Snap baselines to local:**
 
@@ -521,6 +622,50 @@ The wrapper actions (`actions/baseline`, `actions/pr-diff`) and the CLI both han
 request or response body is being bounded. It is not an additional public
 error class; callers should handle the exported error classes above.
 
+## Shared orchestration
+
+GitHub-facing request handling is shared between the wrapper and standalone
+actions through `lib/github-requests.mjs`. The github-script steps stay as thin
+adapters that load the module, inject `{ github, owner, repo, context }`-style
+inputs, and map the returned decision to step outputs:
+
+- `fetchPullRequestFiles` paginates `pulls.listFiles` (100 per page) and
+  validates each record's `filename` before any scope decision is made.
+- `resolveScopeDecision` is pure: renamed files contribute
+  `previous_filename`, paths are deduplicated, 3000+ records short-circuit to
+  running all routes (`changed_files_truncated`), and an empty list maps to
+  `no_changed_files`. Other reasons come from
+  `selectRoutesForChangedFiles`.
+- `resolvePullRequestScope` composes the above with the
+  explicit-route/force-run/missing-PR shortcuts and the
+  `snapdrift_scope_check_failed` fallback warning.
+- `upsertPullRequestReportComment` performs the marker-filtered, newest-first
+  comment upsert with duplicate deletion used by `actions/comment` and the
+  `actions/pr-diff` report step. The create-only "Capture Failed" /
+  "Baseline Lookup Failed" fallback body remains inline in `actions/pr-diff`.
+
+The baseline resolver keeps its own module (`lib/resolve-baseline-artifact.mjs`)
+because both actions already share it verbatim.
+
+### Capture artifact capabilities
+
+Providers now return `artifacts` on capture results, attached in the provider layer
+rather than adapter-fs:
+
+- `localScreenshots`: whether PNGs are available locally for pixel comparison.
+- `artifactsRoot`: the capture's `screenshotsRoot` for local and Snap hybrid
+  captures (`localScreenshots: true`); `undefined` for hosted remote captures
+  (`localScreenshots: false`), even though their metadata has a local path.
+
+`captureWithPolicy` prefers `result.artifacts` over provider-name/base-URL inference.
+For `diffWithPolicy`, pass the capture as `captureResult` or forward its `artifacts`.
+Precedence is the legacy `options.localScreenshots` boolean (if supplied), then
+`options.artifacts`, then `captureResult.artifacts`, then provider/config inference.
+The boolean overrides only `localScreenshots`; false clears `artifactsRoot`.
+Inference remains for legacy results without a descriptor when config is supplied.
+If no capability arguments, result descriptor, or config are supplied to
+`diffWithPolicy`, it preserves the legacy local-screenshots default without recapture.
+
 ## Primary entrypoints
 
 - `actions/baseline`
@@ -547,7 +692,7 @@ These are for custom orchestration only. Wrapper actions set them automatically.
 | `SNAPDRIFT_BASELINE_ARTIFACT_NAME` | `compare-results.mjs` | Baseline artifact label to embed in the report |
 | `SNAPDRIFT_BASELINE_SOURCE_SHA` | `compare-results.mjs` | Baseline source SHA to embed in the report |
 | `SNAPDRIFT_ENFORCE_OUTCOME` | `compare-results.mjs` | Set to `0` to disable enforcement in direct CLI usage |
-| `SNAPDRIFT_CAPTURE_CONCURRENCY` | `capture-routes.mjs` | Max concurrent route captures per viewport context (positive integer, default `5`). Set to `1` to restore serial behaviour for apps with shared session/auth state. |
+| `SNAPDRIFT_CAPTURE_CONCURRENCY` | `capture-routes.mjs` | Max concurrent route captures per viewport group (positive integer, default `5`). Each local attempt uses a fresh browser context. Set to `1` to serialize each group without sharing storage. |
 
 ## PR comment markdown shape
 

package/docs/integration-guide.md

@@ -46,7 +46,7 @@ SnapDrift owns route selection, capture, comparison, skipped-report generation,
 
 ```yaml
 - name: SnapDrift Baseline
-  uses: ranacseruet/snapdrift@v0.11.0
+  uses: ranacseruet/snapdrift@v0.13.0
   with:
     mode: baseline
     repo-config-path: .github/snapdrift.json
@@ -71,7 +71,7 @@ Then add SnapDrift after the app is running:
 
 ```yaml
 - name: SnapDrift Report
-  uses: ranacseruet/snapdrift@v0.11.0
+  uses: ranacseruet/snapdrift@v0.13.0
   with:
     mode: pr-diff
     github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -86,8 +86,8 @@ The wrappers remain published in their own right, and are equivalent to the disp
 
 | Entry point | Equivalent to |
 |-------------|---------------|
-| `ranacseruet/snapdrift@v0.11.0` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.11.0` |
-| `ranacseruet/snapdrift@v0.11.0` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.11.0` |
+| `ranacseruet/snapdrift@v0.13.0` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.13.0` |
+| `ranacseruet/snapdrift@v0.13.0` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.13.0` |
 
 Use the wrappers directly when you want to skip the dispatcher's input indirection, and the lower-level `capture`, `compare`, `scope`, `resolve-baseline`, `stage`, `comment`, and `enforce` actions when you need to orchestrate the stages yourself.
 
@@ -130,7 +130,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift@v0.11.0
+        uses: ranacseruet/snapdrift@v0.13.0
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -170,7 +170,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift@v0.11.0
+        uses: ranacseruet/snapdrift@v0.13.0
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -249,10 +249,11 @@ When `provider: "snap"` and `baseUrl` points to a local address (localhost, `127
 
 With the Snap provider, the PR comment includes a **"View in dashboard →"** link that points to `${apiUrl}/dashboard/visual/${projectId}/runs/${runId}`. The local provider omits the link.
 
-Migrating an existing local repo to the Snap provider is a one-shot CLI command:
+To adopt the hosted provider, seed the project with a hosted baseline. `migrate-baselines --to snap` is **not** the way to do it — Snap cannot accept a pre-built local baseline bundle, because the screenshots it carries are never uploaded to Snap storage and its manifest references local filenames rather than Snap object keys. Use `snapdrift baseline` with `provider: "snap"` instead: it captures each route through Snap so the pixels actually land in storage before the baseline manifest is published. Canonical hosted publication is CI-only — run it from your default-branch job, where GitHub Actions supplies the publication metadata automatically (other CI systems set `SNAPDRIFT_PUBLICATION_WORKFLOW_REF` and `SNAPDRIFT_PUBLICATION_SEQUENCE`); a plain local checkout fails before creating a hosted run.
 
 ```bash
-snapdrift migrate-baselines --to snap
+# In CI, on the default branch, with provider: "snap"
+snapdrift baseline
 ```
 
 Conversely, downloading a Snap baseline back to a local directory (useful for reproducible local debugging) is:
@@ -297,9 +298,6 @@ snapdrift capture
 # After making changes, compare and open the HTML report
 snapdrift diff --open
 
-# Migrate an established local baseline to the hosted Snap backend
-snapdrift migrate-baselines --to snap
-
 # Translate a snap/github-action workflow into snapdrift.json
 snapdrift init --from-snap-action .github/workflows/snap.yml
 ```

package/docs/local-cli.md

@@ -203,6 +203,61 @@ The `--open` flag opens the HTML report in your default browser when the diff is
 
 ---
 
+## Refreshing or acknowledging local baselines
+
+New local manifests record a [v2 capture profile](contracts.md#local-capture-profile-v2)
+with exact engine, Playwright/browser, OS, locale/timezone, and rendering settings.
+Manifests are validated after loading; then, before resolving PNGs, comparison
+checks the profiles and each selected route's id, exact configured path, and
+normalized viewport. A mismatch produces an
+`incompatible_capture` error and an `incomplete` summary, not a pixel drift
+signal. Matching profiles can still have route-identity errors:
+`summary.captureCompatibility.status` describes profiles only.
+
+To refresh, serve the intended accepted application state using the same capture
+environment and route config as future diffs. With `provider: "local"`, run:
+
+```bash
+snapdrift baseline --config .github/snapdrift.json --baseline-dir .snapdrift/baseline
+```
+
+This overwrites baseline metadata and captured screenshots; `snapdrift capture`
+with the same options is equivalent for the local provider. Capture all routes
+for a complete replacement, without `--routes` or `SNAPDRIFT_ROUTE_IDS` scoping.
+Then serve the candidate application state and run:
+
+```bash
+snapdrift diff --config .github/snapdrift.json --baseline-dir .snapdrift/baseline --open
+```
+
+In CI, run the existing default-branch baseline workflow using the root action's
+`mode: baseline` ([Quickstart](../README.md#quickstart)) or `actions/baseline`.
+Use the same upgraded SnapDrift/action revision and runner environment for
+baseline and PR captures, with artifact upload enabled; then rerun the PR diff.
+A baseline captured on a different OS is not interchangeable merely because
+both commands use Playwright.
+
+For intentional nonblocking acknowledgement, set `diff.mode` to `report-only`
+in the config and rerun `snapdrift diff --open`. This keeps the incompatibility
+errors visible and **never overrides compatibility to compare pixels**; there
+is no diff acceptance flag. `fail-on-incomplete` and `strict` fail on these
+errors; `fail-on-changes` fails only if other comparable routes changed. Once
+identity is compatible, a changed full-page PNG size is normal product drift,
+not incompatibility, and fails `fail-on-changes` / `strict` even below threshold.
+
+Legacy manifests with missing profiles or omitted/v1 profile schema remain
+pixel-comparable after route checks, but report `unverified` with a warning.
+Conflicting shared browser/revision, fonts hash, locale, or timezone fields, or
+an explicit foreign engine on either side, are still incompatible. Malformed
+manifests/profiles and unsupported profile schema versions abort comparison,
+even in `report-only`; refresh rather than editing metadata to force a match.
+
+Local capture now explicitly uses `en-US` and `UTC`; localized text/date changes
+may require recapture after upgrading. Fonts are not fingerprinted, so keep
+installed fonts consistent even when profiles are verified.
+
+---
+
 ## Local directory layout
 
 After running `capture` and `diff` with default paths:
@@ -239,7 +294,7 @@ Add `.snapdrift/` to your `.gitignore` to keep local run output out of version c
 | `0` | Clean — no drift above threshold, `diff.mode` is `report-only`, the command was intentionally skipped under `onUnavailable: "warn-and-skip"` (`diff`, `capture` and `baseline` all exit 0 in that case), or the command was a `capture` / `baseline` / `migrate-baselines --to local` / `init` that completed |
 | `1` | Drift enforced — `diff.mode` caused the run to fail, a required command argument was missing, or the `--to local` engine-name check failed (see [Drift modes](../README.md#drift-modes)) |
 
-Enforcement follows the same `diff.mode` rules as the GitHub Actions workflow. Set `"mode": "report-only"` during local development to always get a report without a failing exit code.
+Enforcement follows the same `diff.mode` rules as the GitHub Actions workflow. Set `"mode": "report-only"` for nonblocking report inspection; capture, input-validation, and other command failures still exit 1 and can prevent report generation.
 
 ---
 
@@ -310,7 +365,7 @@ differ; `fail-on-changes` and `strict` still enforce it.
 
 | Variable | Applies to | Description |
 |:---------|:-----------|:------------|
-| `SNAPDRIFT_CAPTURE_CONCURRENCY` | `capture`, `diff` | Max concurrent route operations (positive integer, default `5`): route captures per viewport context, and per-route resolve/compare during `diff`. Set to `1` to restore serial behavior for apps with shared session or auth state. |
+| `SNAPDRIFT_CAPTURE_CONCURRENCY` | `capture`, `diff` | Max concurrent route operations (positive integer, default `5`): route captures per viewport group, and per-route resolve/compare during `diff`. Each local capture attempt uses isolated browser storage. Set to `1` to serialize captures within each viewport group, without sharing storage. |
 | `SNAPDRIFT_CONFIG_PATH` | `capture`, `diff`, `migrate-baselines` | Override the config file path. Equivalent to `--config`. |
 | `SNAPDRIFT_ROUTE_IDS` | `capture`, `baseline`, `diff` | Comma-separated route ids to scope to. Equivalent to `--routes`; it may not reduce a hosted baseline's complete route set. |
 

package/docs/workflow-templates/refresh-baseline-on-merge.yml

@@ -82,7 +82,7 @@ jobs:
 
       - name: Publish SnapDrift baseline
         if: steps.baseline_candidate.outputs.current == 'true'
-        uses: ranacseruet/snapdrift@v0.11.0
+        uses: ranacseruet/snapdrift@v0.13.0
         with:
           mode: baseline
           repo-config-path: .github/snapdrift.json

package/lib/cli.mjs

@@ -214,6 +214,10 @@ export function printSummary(summary) {
   if (errors > 0) process.stdout.write(`   Errors:   ${errors}\n`);
   if (dimensionChanges > 0) process.stdout.write(`   Dim diff: ${dimensionChanges}\n`);
 
+  if (summary.captureCompatibility?.status === 'unverified' && summary.message) {
+    process.stdout.write(`   Note: ${summary.message}\n`);
+  }
+
   if (summary.changed?.length) {
     process.stdout.write('\n   Changed routes:\n');
     for (const item of summary.changed) {

package/lib/github-requests.mjs

@@ -0,0 +1,134 @@
+// @ts-check
+
+import { selectConfiguredRoutes, selectRoutesForChangedFiles, splitCommaList } from './snapdrift-config.mjs';
+
+/** @typedef {import('../types/visual-diff-types').VisualRegressionConfig} VisualRegressionConfig */
+/** @typedef {{ filename: string, status?: string, previous_filename?: string }} PullRequestFile */
+/** @typedef {ReturnType<typeof selectRoutesForChangedFiles>} ScopeDecision */
+/** @typedef {{ paginate: Function, rest: { pulls: { listFiles: Function } } }} ScopeGitHubClient */
+/**
+ * @typedef {{
+ *   paginate: Function,
+ *   rest: { issues: {
+ *     listComments: Function,
+ *     createComment: Function,
+ *     updateComment: Function,
+ *     deleteComment: Function
+ *   } }
+ * }} CommentGitHubClient
+ */
+
+/**
+ * @param {{ github: ScopeGitHubClient, owner: string, repo: string, pullNumber: number }} options
+ * @returns {Promise<PullRequestFile[]>}
+ */
+export async function fetchPullRequestFiles({ github, owner, repo, pullNumber }) {
+  const files = await github.paginate(github.rest.pulls.listFiles, {
+    owner,
+    repo,
+    pull_number: pullNumber,
+    per_page: 100
+  });
+  if (!Array.isArray(files)) {
+    throw new Error('Malformed GitHub changed-file response: expected an array of file records.');
+  }
+  for (const [index, file] of files.entries()) {
+    if (!file || typeof file !== 'object' || typeof file.filename !== 'string' || file.filename.length === 0) {
+      throw new Error(`Malformed GitHub changed-file response: file record ${index} must include a non-empty string filename.`);
+    }
+  }
+  return files;
+}
+
+/**
+ * @param {{ config: VisualRegressionConfig, files: PullRequestFile[] }} options
+ * @returns {ScopeDecision}
+ */
+export function resolveScopeDecision({ config, files }) {
+  if (files.length >= 3000) {
+    return { shouldRun: true, reason: 'changed_files_truncated', selectedRouteIds: (config.routes || []).map((route) => route.id) };
+  }
+  const changedFiles = [...new Set(files.flatMap((file) => [
+    file.filename,
+    ...(file.status === 'renamed' && typeof file.previous_filename === 'string' && file.previous_filename
+      ? [file.previous_filename]
+      : [])
+  ]))];
+  return selectRoutesForChangedFiles(config, changedFiles);
+}
+
+/**
+ * @param {{
+ *   github: ScopeGitHubClient,
+ *   owner: string,
+ *   repo: string,
+ *   config: VisualRegressionConfig,
+ *   pullNumber: number,
+ *   routeIds?: string,
+ *   forceRun?: boolean,
+ *   forceRunReason?: string,
+ *   warning?: (message: string) => void
+ * }} options
+ * @returns {Promise<ScopeDecision>}
+ */
+export async function resolvePullRequestScope({ github, owner, repo, config, pullNumber, routeIds = '', forceRun = false, forceRunReason = 'forced', warning = (_message) => {} }) {
+  const allRouteIds = (config.routes || []).map((route) => route.id);
+  const explicitRouteIds = splitCommaList(routeIds);
+  if (explicitRouteIds.length > 0) {
+    const selected = selectConfiguredRoutes(config, explicitRouteIds);
+    return { shouldRun: true, reason: 'explicit_route_ids', selectedRouteIds: selected.selectedRouteIds };
+  }
+  if (forceRun) {
+    return { shouldRun: true, reason: forceRunReason || 'forced', selectedRouteIds: allRouteIds };
+  }
+  if (!Number.isFinite(pullNumber) || pullNumber <= 0) {
+    return { shouldRun: true, reason: 'missing_pr_number', selectedRouteIds: allRouteIds };
+  }
+  try {
+    const files = await fetchPullRequestFiles({ github, owner, repo, pullNumber });
+    const scope = resolveScopeDecision({ config, files });
+    if (scope.reason === 'changed_files_truncated') {
+      warning('GitHub returned the maximum 3000 changed-file records; the list may be truncated, so running all configured captures.');
+    }
+    return scope;
+  } catch (error) {
+    warning(`Unable to inspect PR files for SnapDrift scope; running all configured captures instead. ${error.message}`);
+    return { shouldRun: true, reason: 'snapdrift_scope_check_failed', selectedRouteIds: allRouteIds };
+  }
+}
+
+/**
+ * @param {{
+ *   github: CommentGitHubClient,
+ *   owner: string,
+ *   repo: string,
+ *   issueNumber: number,
+ *   body: string,
+ *   markers: readonly string[]
+ * }} options
+ * @returns {Promise<void>}
+ */
+export async function upsertPullRequestReportComment({ github, owner, repo, issueNumber, body, markers }) {
+  const comments = await github.paginate(github.rest.issues.listComments, {
+    owner,
+    repo,
+    issue_number: issueNumber,
+    per_page: 100
+  });
+  const matchingComments = comments
+    .filter((comment) => comment.body && markers.some((marker) => comment.body.includes(marker)))
+    .sort((left, right) => {
+      const leftTime = new Date(left.updated_at || left.created_at).getTime();
+      const rightTime = new Date(right.updated_at || right.created_at).getTime();
+      return rightTime - leftTime;
+    });
+  const existing = matchingComments[0];
+  if (existing) {
+    await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
+  } else {
+    await github.rest.issues.createComment({ owner, repo, issue_number: issueNumber, body });
+  }
+  for (const duplicate of matchingComments.slice(1)) {
+    await github.rest.issues.deleteComment({ owner, repo, comment_id: duplicate.id });
+  }
+}